


!
! Help File for AUXiliary KeyPad DCL.
! M. Erik Husby
! Project Software & Development, Inc.
! 14 Story st.
! Cambridge, Ma. 02183
! (617)-661-1444
!
! Modifications: 22-Oct-1983, MEH, Include install
instructions.
!
1 AUX
 AUXillary Keypad DCL is a combination of a command procedure and a  program
 which  builds DCL commands from both typed input and from values associated
 with the keypad of a DEC VT100 family terminal.  In  addition,  editing  of
 the current input line and previously issued commands is possible.
2 Setup
 To invoke AUX, the following definitions and files are needed.

      $ DEFINE AUXKEY name_of_key_definition_command_procedure

 This defines a logical name for the command procedure used to define  the
 keypad.

      $ AUX :== @sys$library:aux.com

 This defines a symbol which can then be used to start  the  AUX  program.
 Before  starting  AUX,  the  command  procedure  will  execute the AUXKEY
 command procedure.

 Supplied with AUX is  a  file  SYS$LIBRARY:AUXKEY.COM  which  provides  a
 sample keypad definition file.  It should be used as a starting point for
 a personelized definition file.

 Supplied with AUX is  a  file  SYS$LIBRARY:AUXKEYSTA.COM  which  provides
 basic  key  definitions.   It is recommended that one reference this file
 from their own key definition file.  AUXKEYSTA.COM defines keys for  line
 editing in a mode very similar to EDT.
2 Special_Keys
 Almost all of the keypad keys  and  the  control  keys  are  available  for
 definition.   However, 3 keys have been reserved for use by AUX.  They are:
 Control-Z, Return, and PF1 (The GOLD key).  In addition, the 2 key sequence
 "ESCAPE ESCAPE" is also reserved.
3 Control-Z
 Control-Z causes AUX to generate a DCL  EXIT  command  so  that  the  AUX
 command procedure can be terminated.
3 Return
 The RETURN key signals the end of command input.  If there is anything in
 the command buffer, it will be passed to DCL as a command to be executed.
 If there is nothing in the command buffer, AUX will simply reprompt.
3 PF1_(GOLD)
 As in EDT, the PF1 key is known as the GOLD key.  It is  used  to  modify
 the meaning of the next key.
3 ESCAPE
 The two character sequence  "ESCAPE  ESCAPE"  is  the  generalized  abort
 capablity.   It can be used to cancel any typed input or to cancel a GOLD
 sequence.
2 Key_Definition
 AUX makes use of DCL symbols to define  its  keypad.   There  is  a  simple
 naming  convention  to  be  followed.   All  AUX related symbols start with
 either "AUX_" or "AUG_".  The symbols for the keypad spell out the name  of
 the key.  The symbols for the control keys simply use the one character key
 name.  For example, the symbols associated with the "0" on the keypad would
 be  "AUX_ZERO"  and  "AUG_ZERO"  for  the  value  associated with "GOLD 0".
 Similarly, the symbols for the "-" key would be "AUX_DASH" and  "AUG_DASH".
 The symbols associated with the Control-D key would be "AUX_D" and "AUG_D".

 When AUX is building  a  command  from  the  typed  input  and  the  values
 associated with a key, it will echo the input.  To present a pretty picture
 or to hide the use of command procedures, it is  possible  to  associate  a
 display  value  with  a  key.   The symbol associating a display with a key
 starts with either "AUX_T_" or  "AUG_T_".   For  example,  to  associate  a
 display value with the PF4 key, the symbol would be "AUX_T_PF4".

 The easiest way  of  defining  the  keypad  is  to  place  all  the  symbol
 definitions  in a command procedure and then assign the logical name AUXKEY
 to that file.  The AUX command procedure will then execute  that  procedure
 before invoking AUX.

 Provided with the AUX package is a file of  the  name  AUXKEYSTA.COM  which
 provides  a  standard  set of key definitions.  Most of the keys defined in
 AUXKEYSTA.COM define internal AUX commands for command line  editing.   The
 keypad  layout  was choosen to be as close as possible to that used by EDT.
 Thus one does not have to learn a  new  set  of  keys  to  perform  similar
 editing operations.

 The file AUXKEYSTA.COM is normally found in SYS$LIBRARY:.
3 KeyPad_Symbols
 The names of symbols associated with the keypad are listed below.

 Keypad Symbol          Gold-Symbol     Display         Gold-Display
 ZERO   Aux_ZERO        Aug_ZERO        Aux_T_ZERO      Aug_T_ZERO
 ONE    Aux_ONE         Aug_ONE         Aux_T_ONE       Aug_T_ONE
 TWO    Aux_TWO         Aug_TWO         Aux_T_TWO       Aug_T_TWO
 THREE  Aux_THREE       Aug_THREE       Aux_T_THREE     Aug_T_THREE
 FOUR   Aux_FOUR        Aug_FOUR        Aux_T_FOUR      Aug_T_FOUR
 FIVE   Aux_FIVE        Aug_FIVE        Aux_T_FIVE      Aug_T_FIVE
 SIX    Aux_SIX         Aug_SIX         Aux_T_SIX       Aug_T_SIX
 SEVEN  Aux_SEVEN       Aug_SEVEN       Aux_T_SEVEN     Aug_T_SEVEN
 EIGHT  Aux_EIGHT       Aug_EIGHT       Aux_T_EIGHT     Aug_T_EIGHT
 NINE   Aux_NINE        Aug_NINE        Aux_T_NINE      Aug_T_NINE
 PF2    Aux_PF2         Aug_PF2         Aux_T_PF2       Aug_T_PF2
 PF3    Aux_PF3         Aug_PF3         Aux_T_PF3       Aug_T_PF3
 PF4    Aux_PF4         Aug_PF4         Aux_T_PF4       Aug_T_PF4
 DASH   Aux_DASH        Aug_DASH        Aux_T_DASH      Aug_T_DASH
 COMMA  Aux_COMMA       Aug_COMMA       Aux_T_COMMA     Aug_T_COMMA
 ENTER  Aux_ENTER       Aug_ENTER       Aux_T_ENTER     Aug_T_ENTER
 UP     Aux_UP          Aug_UP          Aux_T_UP        Aug_T_UP
 DOWN   Aux_DOWN        Aug_DOWN        Aux_T_DOWN      Aug_T_DOWN
 RIGHT  Aux_RIGHT       Aug_RIGHT       Aux_T_RIGHT     Aug_T_RIGHT
 LEFT   Aux_LEFT        Aug_LEFT        Aux_T_LEFT      Aug_T_LEFT
 DELETE Aux_DELETE      Aug_DELETE      Aux_T_DELETE    Aug_T_DELETE
3 Control_Keys_Symbols
 The symbols used for the control keys are listed below:

 Control Key    Symbol  Gold Symbol     Display         Gold Display
 A              Aux_A   Aug_A           Aux_T_A         Aug_T_A
 B              Aux_B   Aug_B           Aux_T_B         Aug_T_B
 C - Same as Control-Y
 D              Aux_D   Aug_D           Aux_T_D         Aug_T_D
 E              Aux_E   Aug_E           Aux_T_E         Aug_T_E
 F              Aux_F   Aug_F           Aux_T_F         Aug_T_F
 G (Bell)       Aux_G   Aug_G           Aux_T_G         Aug_T_G
 H (Backspace)  Aux_H   Aug_H           Aux_T_H         Aug_T_H
 I (Tab)        Aux_I   Aug_I           Aux_T_I         Aug_T_I
 J (LineFeed)   Aux_J   Aug_J           Aux_T_J         Aug_T_J
 K              Aux_K   Aug_K           Aux_T_K         Aug_T_K
 L              Aux_L   Aug_L           Aux_T_L         Aug_T_L
 M (Return) - always signals end of input.
 N              Aux_N   Aug_N           Aux_T_N         Aug_T_N
 O - Discard output - not processed by AUX directly.
 P              Aux_P   Aug_P           Aux_T_P         Aug_T_P
 Q - Resume Output - not processed by AUX directly.
 R              Aux_R   Aug_R           Aux_T_R         Aug_T_R
 S - Halt Output - not processed by AUX directly.
 T -            Aux_T   Aug_T           Aux_T_T         Aug_T_T
        Normally the DCL display process statistics command.
 U              Aux_U   Aug_U           Aux_T_U         Aug_T_U
 V              Aux_V   Aug_V           Aux_T_V         Aug_T_V
 W              Aux_W   Aug_W           Aux_T_W         Aug_T_W
 X - Same as Control-U
 Y - Abort execution - not processed by AUX directly
 Z - Always generates the command EXIT.
2 Input_Processing

 Input to AUX can come from both typed input and from values associated with
 a  special  key.  Typed input will overlay any previous input (or extend it
 if the cursor is at the end of the line).  The value associated with a  key
 will be prefixed to the typed input (Sort of a reverse polish input).  Thus
 one usually types in the operators to a DCL command and then terminates the
 input  with  the  key associated with the DCL command.  AUX also recognizes
 the dash "-" at the end  of  input  as  a  continuation  command  and  will
 reprompt replacing the dash with a blank.

 For example, assume that keypad key ONE has been  defined  as  "DIRECTORY".
 Then  to get a directory with no arguments, simply strike the ONE key.  AUX
 will echo the word DIRECTORY and then request DCL to execute  the  command.
 If  one wanted a directory of all FORTRAN files, one would type "*.FOR" and
 then use the  ONE  key  to  terminate  the  input.   AUX  would  then  echo
 "DIRECTORY *.FOR" and then request DCL to execute the command.

 If the value associated with a special key is an internal AUX command,  AUX
 will  first  overlay  any  typed  input  on  top of previous input and then
 execute the internal command.  When the internal command is  complete,  AUX
 will  reprompt,  preserving the previous input for futher processing.  Thus
 one can use the internal commands to list the key definitions or to  define
 a key without disturbing what has already been typed.
2 Internal_Commands
 All internal AUX commands must be associated with a key, typing an internal
 command  will  not  work.   An  internal AUX command is identified by the 3
 character sequence "$$ " (The blank is required).  Thereafter, the shortest
 unambiguous  abreviation may be used;  however, since internal AUX commands
 are usually defined in the key definition command file  it  is  recommended
 that  the  commands  be spelled out.  Internal AUX commands are not echoed,
 they are simply executed.  However, to make the keypad diagram displayed by
 the  "HELP  KEYPAD"  command look nice it is possible to use the associated
 text display feature.  See the supplied key definition  file  AUXKEYSTA.COM
 for examples.

 An example of an internal command is "$$ Delete To_End_Of Line".

 Internal AUX commands  perform  the  following  functions:   line  editing,
 screen  clears  and  width  changes,  key  definitions  and display, symbol
 definitions and display, and setting of an alarm.
3 CLEAR
 The CLEAR command clears lines 2-23 of the screen.
3 DEFINE
 The DEFINE command is used to define keys and DCL symbols.
4 KEY
 The "DEFINE KEY" command will issue three prompts  in  the  process  of
 defining  a  key.  The first prompt will request the key to be defined,
 simply strike the appropriate key.  The second prompt will ask for  the
 value  to  be  associated with the key.  All of AUX's input capablities
 may be used.  Striking ESCAPE ESCAPE in response to the first or second
 questions will abort the definition.  The third prompt will ask for the
 value to be displayed in response to the key.  Again all of AUX's input
 capablities  may be used to answer this prompt.  If no display value is
 needed, simply strike ESCAPE ESCAPE.

 For example, assume that key Control-K is the "$$ DEFINE KEY"  command.
 Then to define the key DownArrow as "Directory *.TXT" one would proceed
 as follows:


  o  Strike Control-K.  AUX responds with the "Enter Key to be  defined"
     prompt.

  o  Strike the DownArrow key.  AUX responds with the "Enter  definition
     for key Down:".

  o  Enter "Directory *.TXT" followed by a return.   AUX  responds  with
     "Enter value to be displayed for key Down:".

  o  Enter ESCAPE ESCAPE to indicate that no special value is needed.

  o  AUX will then setup the appropriate DCL symbols  so  that  striking
     the DownArrow key will result in the DCL command "Directory *.TXT".

4 SYMBOL
 The "DEFINE SYMBOL" command will be available in a future major release
 of AUX.  Until then, please use the DCL define symbol command.
3 DELETE
 The DELETE commands are used for line editing.  As in EDT, one can delete
 either  backwards  from  the current cursor position or forwards from the
 cursor.  After  a  delete,  the  entity  deleted  is  saved  and  may  be
 "UNDELETED" at any spot on the line.

 Since AUX, for reasons of efficency, uses typeover instead of insert, the
 affect  of  inserting  can be accomplished by using the "Delete To_End_Of
 Line" command.  First position the cursor to the point where insertion is
 desired.   Then  issue the "Delete To_End_Of Line" command.  Then type in
 the desired characters and terminate the input with the  "UnDelete  Line"
 command.

 AUX does not do insert like EDT bcause one character reads would need  to
 be  used.  Instead AUX has tried to exploit the power of the VMS terminal
 driver whereby additional characters such as the control  characters  and
 escape  sequences can be defined as line terminators.  In most cases, the
 AUX method is a much more efficent use of the VMS terminal driver.
4 Character
 The command  "Delete  Character"  command  will  delete  the  character
 covered  by  the  cursor.  The command "Delete Previous Character" will
 delete the character to the left of the cursor.
4 Line There are three forms of the "Delete Line" command.  The  "Delete
 Line"  command  deletes  the  complete  line  reqardless  of the cursor
 position.  The  "Delete  To_Start_Of  Line"  command  will  delete  all
 characters  to  the  left  of  the cursor.  The "Delete To_End_Of Line"
 command will delete all characters to the right of the cursor including
 the character covered by the cursor.
4 Word
 Like the "Delete Character" command, the "Delete Word" command has  two
 formats.   The  command  "Delete  Word"  will  delete  starting  at the
 character covered by the cursor upto and including the  word  delimiter
 to  the  right  of the cursor.  The command "Delete Previous Word" will
 delete the word to the left of the cursor position.

 The delimiters used by the "Delete Word" command are ".;/:,[]<>()=" and
 the  space  character.   (Note:   not  the double quote or single quote
 characters.) These are the delimiters most commonly encountered in  DCL
 phrases.
3 FLIPWIDTH
 The FLIPWIDTH command changes an 80 character screen to  132  and  a  132
 character screen to 80.  The screen is cleared as a side effect.
3 HELP
 The HELP command will display the values associated with the  keypad  and
 the control keys.
4 KEYPAD The HELP KEYPAD command will display  a  picture  of  the  keypad
 (similar  to  EDT's  display) showing the value associated with each key.
 The primary vaule will be displayed on the top and the GOLD value will be
 displayed  in  reverse video on the bottom.  If the key has an associated
 text display value, that value will be used.  Only 13 characters  of  the
 key  value  will  be displayed.  For a more complete display, the command
 "$$ HELP KEYPAD DETAILED" can be used to list both the command  and  text
 display  values.   This  command procduces a display similar to the "HELP
 CONTROL_KEYS" command.
4 CONTROL_KEYS The HELP CONTROL_KEYS command will display, on two screens,
 the  command  and  text display values defined for the control keys.  The
 first screen shows the values associated  with  the  control  keys.   The
 second  screen  shows  the  values associated with the GOLD control keys.
 After the display of the first screen, entering a return will  cause  the
 next screen to be displayed.
3 LASTCOMMAND
 The LASTCOMMAND command fetches the last DCL command executed.   Actually
 it  does  more than just the last command.  AUX maintains a circular list
 of the last N commands executed and repeated execution of the LASTCOMMAND
 command  will  fetch  subsiquent  entries from the list.  The size of the
 list is determined by the value of the symbol AUX_LIMIT.  If  the  symbol
 AUX_LIMIT  is  not defined at the start of the AUX command procedure, AUX
 will set it to 10.  The limit may be changed at any time.   AUX's  memory
 of the last commands consists of local DCL symbols;  thus the memory will
 be lost if one exits from the AUX command procedure.  It  is  recommended
 that  the  symbol AUX_LIMIT be defined in the AUXKEY command procedure if
 the value of 10 is not sufficient.
3 MOVE
 The MOVE commands allows one  to  move  the  cursor  around  the  current
 command  line.   One can move backwards and forwards.  The MOVE CHARACTER
 and MOVE WORD commands will wrap around the command line if the cursor is
 at one end of the line.
4 CHARACTER
 The "MOVE CHARACTER" command moves the cursor one character position to
 the  right.   The  "MOVE  BACKWARDS  CHARACTER"  moves  the  cursor one
 character position to the left.  When at either end of the input  line,
 AUX will wrap around.
4 LINE
 The "MOVE To_End_Of LINE" command moves the cursor  to  the  right-hand
 end  of  the  command.   The  "MOVE To_Start_Of LINE" command moves the
 cursor to the left-hand end of the command.
4 WORD
 The "MOVE WORD" command will move the cursor to  the  right  one  word.
 The  "MOVE BACKWARDS WORD" command will move the cursor to the left one
 word.  The word delimiters are ".;/:,[]<>()=" and the space  character.
 (Note:  not the double quote or single quote characters.) These are the
 delimiters most commonly encountered in DCL phrases.
3 SHOW
 The SHOW command is used to display the values of symbols and keys.
4 KEY
 The "SHOW KEY" will prompt for the key to be shown.  Simply strike  the
 key in question.  AUX will then display both values associated with the
 key.
4 SYMBOL
 The "SHOW SYMBOL" will prompt for the symbol to be shown.  Simply enter
 the name of the symbol.  AUX will then display the value of the symbol.
3 SET
 The SET command is used to modify AUX  parameters.   Currently  the  only
 option is the Alarm.
4 ALARM
 The SET ALARM command defines a DCL symbol which will cause AUX to ring
 the  bell  the next time AUX is executed.  This could be usefull if one
 was preparing to execute a DCL command which  might  take  a  while  to
 execute.   Before  executing  the DCL command one would tell AUX to set
 the alarm.  (You will notice that the clock in  the  upper  right  hand
 corner  of  the  screen  will start to blink.) Then one would enter the
 appropriate command and let the VAX go to work.  You  could  then  turn
 away  from  the  terminal  confident that AUX will notify you when your
 command was done.  Simple but effective.
3 UNDELETE
 The UNDELETE command inserts the specified entity at the  current  cursor
 position.  If the specified entity is null, no action or message is taken
 or displayed.
4 Character Inserts the most recently deleted  character  at  the  current
 cursor position.
4 Line Inserts the most  recently  deleted  line  at  the  current  cursor
 position.
4 Word Inserts the most  recently  deleted  word  at  the  current  cursor
 position.
2 Author
 AUX was the orginal idea of  Vince  Graham,  the  current  version  is  the
 product of:
           M.  Erik Husby
           Project Software & Development, Inc.
           14 Story Street
           Cambridge, Ma.  02138
           617-661-1444

 Please report any problems or suggestions to Erik.
2 Bugs
 Bug 1.  Under unknown conditions, AUX will not respond to the keyboard  but
 continues  to  update the clock.  The workaround for this problem is to hit
 Control-Y several times and to enter some characters into  the  type  ahead
 buffer before AUX prompts.  This appears to clear the problem.
2 Restrictions
 Every attempt has been made to make the use of AUX the same as the straight
 use  of  DCL.  However, because of the nature of AUX and DCL somethings can
 not be done.

 1.  The major restriction imposed by AUX is that the  ASSIGN/USER_MODE  and
     the DEFINE/USER_MODE DCL commands can not be used.  This is because AUX
     is an image that is run  between  each  DCL  command.   The  /USER_MODE
     logical names are removed after an image is run.  Thus one needs to use
     explicit ASSIGN command or to use a command procedure  to  execute  the
     program.

 2.  Explicit symbol substitution (i.e.  symbols inside single  quotes)  can
     not  be  done.   This restriction is imposed by the method used to pass
     the commands to DCL.  AUX uses the routine  LIB$DO_COMMAND  which  does
     not do explicit symbol substitution.  Implicit symbol substitution does
     work (i.e.  defining a symbol which appears to be a DCL command).

 3.  LIB$DO_COMMAND limits the command lines to 128 characters.

 4.  Certain  commands  do  not  do  cause  a  linefeed  on  their   initial
     prompt/read  thus  overwriting  the  command line left on the screen by
     AUX.  The two programs that I encountered with  this  problem  are  the
     $CREATE  command  and  the INSTALL utility.  This is not a very serious
     problem.

 5.  Type ahead from the keyboard is allowed.  However, because AUX needs to
     enable  the VT100's keypad with a command sent to the terminal, one can
     not type ahead from the keypad.

2 Installation
 Installation of AUX requires the following steps.  The copying of files  is
 accomplished  through  the  use  of  the  VMSUPDATE procedure.  Consult the
 system manager's  guide  for  information  on  the  use  of  the  VMSUPDATE
 procedure.

 1.  Copy the files AUX.COM, AUXKEY.COM, AUXKEYSTA.COM to SYS$LIBRARY.   The
     file  AUXKEY.COM is provided as a starting point for a personalized key
     definition file.

 2.  Copy the file AUX.EXE to SYS$SYSTEM.  It is  recommended  that  AUX  be
     installed  because  it  is  used between every DCL command.  AUX uses a
     mailbox to handle broadcast  messages  and  terminal  type  ahead.   If
     possible,  a  permanent mailbox is setup once and then used every time.
     Otherwise, a temporary mailbox is created each time AUX.  Therefore, by
     installing   AUX   with  PRMMBX  privilege,  one  can  say  significant
     processing time.  The recommended command to install AUX is:
     MCR INSTALL SYS$SYSTEM:AUX.EXE/OPEN/HEADER/SHARE/PRIVILEGE=PRMMBX

     The install command should be placed in the system startup procedure so
     that AUX is installed every time the machine is booted.

 3.  Insert the file HELPAUX.HLP into SYS$HELP:HELPLIB.HLB.

 4.  In the appropriate login command procedure, insert the following.
     $ AUX :== @SYS$LIBRARY:AUX
     $ AUXCMD :== $SYS$SYSTEM:AUX
     $ DEFINE AUXKEY PersonalAuxkeyFileSpec

 5.  Thereafter AUX may be started simply by using the command AUX.   It  is
     also possible to invoke AUX directly from one's login command procedure
     if one always wants to use AUX.



                                    NOTE

     When AUX display's its help screen, it  apparently  uses  a  larger
     buffer  than is allowed on standard VMS systems.  It is a simple to
     change the parameter MAXBUF from the default of 1024 bytes to  2048
     bytes.   MAXBUF  is a dynamic parameter that can be altered without
     having to boot the machine.   Use  the  SYSGEN  utility  to  change
     MAXBUF to 2048 bytes.


