.no paging
.nojustify
.nofill
!
! 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.
!
.fill
.justify
1#AUX
.right margin 76
.left margin 1
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.
.Indent -1;2#Setup
.Break;
.right margin 74
To invoke AUX, the following definitions and files are needed.
.Skip;
.Indent 5;$#DEFINE#AUXKEY#name__of__key__definition__command__procedure
.Skip;
This defines a logical name for the command procedure used to define the 
keypad.
.Skip;
.Indent 5;$#AUX#:==#@sys$library:aux.com
.Skip;
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.
.Skip;
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.
.Skip;
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.
.Indent -1;2#Special__Keys
.right margin 76
.Break;
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.
.Indent -1;3#Control-Z
.right margin 74
.Break;
Control-Z causes AUX to generate a DCL EXIT command so that the AUX command 
procedure can be terminated.
.Indent -1;3#Return
.Break;
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.
.Indent -1;3#PF1__(GOLD)
.Break;
As in EDT, the PF1 key is known as the GOLD key.  It is used to modify the 
meaning of the next key.
.Indent -1;3#ESCAPE
.Break;
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.
.Indent -1;2#Key__Definition
.right margin 76
.Break;
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". 
.Skip;
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". 
.Skip;
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.
.Skip;
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.
.Skip;
The file AUXKEYSTA.COM is normally found in SYS$LIBRARY:.
.Indent -1;3#KeyPad__Symbols
.right margin 76
.Break;
The names of symbols associated with the keypad are listed below.
.Skip;
Keypad	Symbol		Gold-Symbol	Display		Gold-Display
.Break;
ZERO	Aux__ZERO	Aug__ZERO	Aux__T__ZERO	Aug__T__ZERO
.Break;
ONE	Aux__ONE		Aug__ONE		Aux__T__ONE	Aug__T__ONE
.Break;
TWO	Aux__TWO		Aug__TWO		Aux__T__TWO	Aug__T__TWO
.Break;
THREE	Aux__THREE	Aug__THREE	Aux__T__THREE	Aug__T__THREE
.Break;
FOUR	Aux__FOUR	Aug__FOUR	Aux__T__FOUR	Aug__T__FOUR
.Break;
FIVE	Aux__FIVE	Aug__FIVE	Aux__T__FIVE	Aug__T__FIVE
.Break;
SIX	Aux__SIX		Aug__SIX		Aux__T__SIX	Aug__T__SIX
.Break;
SEVEN	Aux__SEVEN	Aug__SEVEN	Aux__T__SEVEN	Aug__T__SEVEN
.Break;
EIGHT	Aux__EIGHT	Aug__EIGHT	Aux__T__EIGHT	Aug__T__EIGHT
.Break;
NINE	Aux__NINE	Aug__NINE	Aux__T__NINE	Aug__T__NINE
.Break;
PF2	Aux__PF2		Aug__PF2		Aux__T__PF2	Aug__T__PF2
.Break;
PF3	Aux__PF3		Aug__PF3		Aux__T__PF3	Aug__T__PF3
.Break;
PF4	Aux__PF4		Aug__PF4		Aux__T__PF4	Aug__T__PF4
.Break;
DASH	Aux__DASH	Aug__DASH	Aux__T__DASH	Aug__T__DASH
.Break;
COMMA	Aux__COMMA	Aug__COMMA	Aux__T__COMMA	Aug__T__COMMA
.Break;
ENTER	Aux__ENTER	Aug__ENTER	Aux__T__ENTER	Aug__T__ENTER
.Break;
UP	Aux__UP		Aug__UP		Aux__T__UP	Aug__T__UP
.Break;
DOWN	Aux__DOWN	Aug__DOWN	Aux__T__DOWN	Aug__T__DOWN
.Break;
RIGHT	Aux__RIGHT	Aug__RIGHT	Aux__T__RIGHT	Aug__T__RIGHT
.Break;
LEFT	Aux__LEFT	Aug__LEFT	Aux__T__LEFT	Aug__T__LEFT
.Break;
DELETE	Aux__DELETE	Aug__DELETE	Aux__T__DELETE	Aug__T__DELETE
.Indent -1;3#Control__Keys__Symbols
.Break;
The symbols used for the control keys are listed below:
.Skip;
Control Key	Symbol	Gold Symbol	Display		Gold Display
.Break;
A		Aux__A	Aug__A		Aux__T__A		Aug__T__A
.Break;
B		Aux__B	Aug__B		Aux__T__B		Aug__T__B
.Break;
C - Same as Control-Y
.Break;
D		Aux__D	Aug__D		Aux__T__D		Aug__T__D
.Break;
E		Aux__E	Aug__E		Aux__T__E		Aug__T__E
.Break;
F		Aux__F	Aug__F		Aux__T__F		Aug__T__F
.Break;
G (Bell)	Aux__G	Aug__G		Aux__T__G		Aug__T__G
.Break;
H (Backspace)	Aux__H	Aug__H		Aux__T__H		Aug__T__H
.Break;
I (Tab)	Aux__I	Aug__I		Aux__T__I		Aug__T__I
.Break;
J (LineFeed)	Aux__J	Aug__J		Aux__T__J		Aug__T__J
.Break;
K		Aux__K	Aug__K		Aux__T__K		Aug__T__K
.Break;
L		Aux__L	Aug__L		Aux__T__L		Aug__T__L
.Break;
M (Return) - always signals end of input.
.Break;
N		Aux__N	Aug__N		Aux__T__N		Aug__T__N
.Break;
O - Discard output - not processed by AUX directly.
.Break;
P		Aux__P	Aug__P		Aux__T__P		Aug__T__P
.Break;
Q - Resume Output - not processed by AUX directly.
.Break;
R		Aux__R	Aug__R		Aux__T__R		Aug__T__R
.Break;
S - Halt Output - not processed by AUX directly.
.Break;
T - 		Aux__T	Aug__T		Aux__T__T		Aug__T__T
.Break;
	Normally the DCL display process statistics command.
.Break;
U		Aux__U	Aug__U		Aux__T__U		Aug__T__U
.Break;
V		Aux__V	Aug__V		Aux__T__V		Aug__T__V
.Break;
W		Aux__W	Aug__W		Aux__T__W		Aug__T__W
.Break;
X - Same as Control-U
.Break;
Y - Abort execution - not processed by AUX directly
.Break;
Z - Always generates the command EXIT.
.Indent -1;2#Input__Processing
.Skip;
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.
.Skip;
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.
.Skip;
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.
.Indent -1;2#Internal__Commands
.right margin 76
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. 
.Skip;
An example of an internal command is "$$ Delete To__End__Of Line".
.Skip;
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.
.Indent -1;3#CLEAR
.Right Margin 74
The CLEAR command clears lines 2-23 of the screen.
.Indent -1;3#DEFINE
.Right Margin 74
The DEFINE command is used to define keys and DCL symbols.
.Indent -1;4#KEY
.RIght Margin 72
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. 
.Skip;
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:
.Skip;
.List 1"o";
.list element;Strike Control-K.  AUX responds with the "Enter Key to be 
defined" prompt.
.List Element;Strike the DownArrow key.  AUX responds with the "Enter 
definition for key Down:".
.List Element;Enter "Directory *.TXT" followed by a return.  AUX responds with 
"Enter value to be displayed for key Down:".
.List Element;Enter ESCAPE ESCAPE to indicate that no special value is needed. 
.List Element;AUX will then setup the appropriate DCL symbols so that striking
the DownArrow key will result in the DCL command "Directory *.TXT". 
.end list
.Indent -1;4#SYMBOL
.Right Margin 72
The "DEFINE SYMBOL" command will be available in a future major release of 
AUX.  Until then, please use the DCL define symbol command.
.Indent -1;3#DELETE
.Right Margin 74
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.  
.Skip;
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.
.Skip;
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. 
.Indent -1;4#Character
.Right Margin 72
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.
.Indent -1;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. 
.Indent -1;4#Word
.Right Margin 72
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.
.Skip;
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.
.Indent -1;3#FLIPWIDTH
.Right Margin 74
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.
.Indent -1;3#HELP
.Right Margin 74
The HELP command will display the values associated with the keypad and the 
control keys.
.Indent -1;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.
.Indent -1;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. 
.Indent -1;3#LASTCOMMAND
.Right Margin 74
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. 
.Indent -1;3#MOVE
.Right Margin 74
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.
.Indent -1;4#CHARACTER
.Right Margin 72
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.
.Indent -1;4#LINE
.Right Margin 72
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.
.Indent -1;4#WORD
.Right Margin 72
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. 
.Indent -1;3#SHOW
.Right Margin 74
The SHOW command is used to display the values of symbols and keys.
.Indent -1;4#KEY
.Right Margin 72
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.
.Indent -1;4#SYMBOL
.Right Margin 72
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.
.Indent -1;3#SET
.Right Margin 74
The SET command is used to modify AUX parameters.  Currently the only option 
is the Alarm.
.Indent -1;4#ALARM
.Right Margin 72
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.
.Indent -1;3#UNDELETE
.Right Margin 74
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.
.Indent -1;4#Character
Inserts the most recently deleted character at the current cursor position.
.Indent -1;4#Line
Inserts the most recently deleted line at the current cursor position.
.Indent -1;4#Word
Inserts the most recently deleted word at the current cursor position.
.Indent -1;2#Author
.right margin 76
AUX was the orginal idea of Vince Graham, the current version is the product 
of:
.Indent 10;M. Erik Husby
.Indent 10;Project Software _& Development, Inc.
.Indent 10;14 Story Street
.Indent 10;Cambridge, Ma. 02138
.Indent 10;617-661-1444
.Skip;
Please report any problems or suggestions to Erik.
.Indent -1;2#Bugs
.Break;
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.
.Indent -1;2#Restrictions
.Right Margin 76
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.
.List ;
.List Element;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. 
.List Element;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). 
.List Element;LIB$DO__COMMAND limits the command lines to 128 characters. 
.List Element;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. 
.List Element;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.
.end list
.Indent -1;2#Installation
.Right Margin 76
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. 
.List ;
.list element;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.
.List Element;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:
.break
MCR#INSTALL#SYS$SYSTEM:AUX.EXE/OPEN/HEADER/SHARE/PRIVILEGE=PRMMBX
.skip;
The  install  command  should  be placed in the system startup procedure so
that AUX is installed every time the machine is booted.
.List Element;Insert the file HELPAUX.HLP into SYS$HELP:HELPLIB.HLB.
.List Element;In the appropriate login command procedure, insert the 
following.
.Break;
$#AUX#:==#@SYS$LIBRARY:AUX
.Break;
$#AUXCMD#:==#$SYS$SYSTEM:AUX
.Break;
$#DEFINE#AUXKEY#PersonalAuxkeyFileSpec
.List Element;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.
.end list
.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.
.end note