Google
 

Trailing-Edge - PDP-10 Archives - tops20tools_v6_9-jan-86_dumper - tools/recog3/helpfs.mem
There are 3 other files named helpfs.mem in the archive. Click here to see a list.


                            VMS RECOGNITION PACKAGE
                       (INCREMENTAL HELP AND RECOGNITION)
                            FUNCTIONAL SPECIFICATION
                                   revision 3











1.0  PRODUCT OVERVIEW

The purpose of this product is to provide a tool  for  VMS  users
that  will  allow  them  to  write  code  that  gets input from a
terminal in "help mode".  By "help mode" we mean that the  person
typing  in  the  input  can  get incremental help and can perform
command recognition as he types.

     1.  Incremental help refers to the ability to type a  <HELP>
         key  in  the  middle  of  a  command line and get a help
         message immediately that explains what kind of input  is
         expected.   The  system  then retypes the command up the
         point of interruption and allows the  user  to  continue
         typing the rest of the command.

     2.  Command recognition (also known as  command  completion)
         refers  to  the ability to type a <RECOGNIZE> key in the
         middle of a command line and have the system complete  a
         partially entered field for you automatically.

EXAMPLE 1:

The user types

$ SET <HELP>

and the result he sees on the terminal is:

$ SET ?        Keyword, one of the following
CARD__READER    [NO]CONTROL__Y    DEFAULT         HOST
MAGTAPE        MESSAGE          [NO]ON          PASSWORD
PROCESS        PROTECTION       QUEUE           RMS__DEFAULT
TERMINAL       [NO]VERIFY       WORKING__SET
$ SET

The system tells the user what his legal options are to  the  SET
command and then brings him back to the space after the word SET.
                                                                          Page 2


EXAMPLE 2:

The user types:

$ SET PR<HELP>

and the result he sees on the terminal is:

$ SET PR?     Keyword, one of the following:
PROCESS       PROTECTION
$ SET PR

and he is left positioned immediately after the "PR".  He is told
that  there  are  only  two  keywords that begin with the letters
"PR".

EXAMPLE 3:

The user types

$ INIT<RECOGNIZE>

and the result he sees is:

$ INITIALIZE (DEVICE)

The system has completed the word "INIT"  to  "INITIALIZE"  since
there is only one valid command beginning with the letters "INIT"
and then displays the guideword  "(DEVICE)"  reminding  the  user
what  field  is  to  be  typed  next.  He is then left positioned
immediately after the space after the guideword ready to continue
typing.

EXAMPLE 4:

The user types

$ FORTRAN INV<RECOGNIZE>

and the result he sees is

$ FORTRAN INVERT.FOR;23

since there was only one FORTRAN file in  the  user's  area  that
began  with  the  letters "INV".  He is left positioned after the
space after the filespec, ready to type <RETURN> or  to  continue
entering more data (such as qualifiers).

Note that the routines provided by this product do not constitute
a  general  "parser",  such  as  TPARSE,  but  rather  are  to be
considered a low level tool (down near the QIO level) that can be
used  by  general  parsers  to  parse  primitive elements such as
keywords, numbers, or filespecifications.  The  user  or  general
                                                                          Page 3


parser  would  then write code to combine these primitive parsing
tasks into more complex parsing tasks.

This project does not include interfacing these routines into DCL
or other VMS utilities.



2.0  PRODUCT GOALS

2.1  Background

Most of the code to handle incremental help and  recognition  had
already been written.  It was embedded in SCP, the command parser
for the DECset Integrated Publishing System which  is  a  layered
product  that  runs  under VMS.  This code shipped with DECset V1
and is deeply embedded in the bowels of SCP.  It was the  purpose
of  this  project to remove that code from SCP and turn it into a
nicely packaged set of RTL routines that would  be  user-callable
and easy to use.




2.1.1  Demos -

There are now several demo programs running under VMS  that  have
already  interfaced  to the recognition package.  The easiest one
to get hold of is WHAT.EXE.  The program WHAT.EXE is  a  midnight
hack  that lets you monitor various pieces of system information,
such as processes, devices, open files, mounted volumes,  network
logical  links,  etc.   WHAT  has  a  command mode (just type any
character to get into command mode).   While  entering  commands,
you  may type TAB and "?" to see recognition and incremental help
in action.  Keep in mind that WHAT  is  a  display  program  that
manages  the  screen,  so  that  the  user  interface is slightly
different from what you would get  with  a  normal  program  that
doesn't  do  screen  management.   This is because WHAT traps the
output from the recognition package and places it on  the  screen
where it would like to see it go.




2.2  Specific Goals


High Priority Goals:

     1.  The interface shall be general enough  that  it  can  be
         re-integrated with DECset.
                                                                          Page 4


     2.  The code shall be general enough that it can support the
         DCL  command  language,  should  the VMS group decide to
         integrate this code into DCL.

     3.  Should DCL decide to use these routines,  then  the  DCL
         user  interface  shall  looks  exactly  as it looks now,
         provided  that  the  user  never  types  the  <HELP>  or
         <RECOGNIZE> keys.

     4.  The code should run as quickly as possible, putting  the
         least  amount  of  strain  on  VMS  as possible.  (It is
         expected that sometime in the future, this code will  be
         frequently invoked.)

     5.  The code must react gracefully to CTRL/C and CTRL/Y.  It
         must  not assume that the image will exit on CTRL/Y.  It
         must establish condition handlers,  when  necessary,  to
         react  to an UNWIND signal and to cleanly deallocate any
         virtual memory that has been allocated, close  any  open
         files, release channels, etc.

     6.  The code shall be general enough to handle  the  parsing
         needs  of  most  VMS-supplied  utilities  (such as MAIL,
         DEBUG, SYSGEN, SDA, AUTHORIZE, etc.).

     7.  The code shall be easily invoked from  either  MACRO  or
         BLISS.

     8.  The code shall follow the practices set forth in the VMS
         Guide to Writing Modular Library Routines.

Medium Priority Goals:

     1.  The code shall be general enough to handle  the  parsing
         needs of most user programs.

     2.  To a user at a terminal using this  facility,  the  user
         interface  should look similar to the corresponding user
         interface   on   TOPS-20   (except   with   regard    to
         functionality    explicity    excluded    in   the   VMS
         implementation).

     3.  It shall be as easy as possible  to  interface  to  this
         code  (subject  to the constraint that the high-priority
         goals must be met).

     4.  Any time the code wants a user-specified descriptor, the
         code   shall  accept  any  kind  of  string  descriptor,
         including dynamic string descriptors and varying  string
         descriptors.    The   code   shall  not  assume  that  a
         descriptor fits in a quadword.
                                                                          Page 5


     5.  The code shall be reentrant.

Low Priority Goals (but goals nonetheless):

     1.  To  a  programmer  using  this  facility,  the   program
         interface  should  look  similar  to  the  corresponding
         program interface on TOPS-20 (the COMND JSYS),  wherever
         this  is practical.  <For those people familiar with the
         TOPS-20 implementation, I include notes enclosed  within
         angle  brackets  throughout this document describing the
         correspondence  between  this  implementation  and   the
         TOPS-20 implementation.>

     2.  It should be easy to invoke this  code  from  high-level
         languages.  (This goal may not be easy to attain.)

     3.  The code should work with block mode terminals  that  do
         their   own   handling   of  rubouts  and  other  action
         characters.   (This  is  under  our  control  for  VT173
         terminals  used with DECset, but may not be a realizable
         goal for all block mode terminals supported by  VMS,  if
         any.)

     4.  The programmer should not have to  know  anything  about
         writing condition handlers to do normal things.

     5.  The system should provide as few limits as  possible  on
         the  programmer.   For  example, LIB$GET_INPUT currently
         will not let you read a record from  SYS$INPUT  that  is
         greater  than 256 bytes long if you use a dynamic string
         descriptor.  My code, when  possible,  shall  impose  no
         limits  on the programmer.  He should be able to write a
         program  that  will  take  an  arbitrarily  long   input
         command,  provided  that  he  supplies  a dynamic string
         descriptor to hold the command and that  the  user  does
         not  run  out  of any process quota or exceed any sysgen
         parameter.

     6.  The user shall not get  errors  during  the  recognition
         process.  For example, if while trying to do recognition
         on a field, some system service  returns  with  a  quota
         exceeded  error, the response to the recognition request
         will be a  beep,  meaning  that  the  system  could  not
         perform  recognition  on  that  field  and  the user may
         continue typing.  The response  shall  not  be  a  quota
         exceeded error message.

Specific features that are goals:

     1.  <HELP> key
                                                                          Page 6


     2.  <RECOGNIZE> key

     3.  Guidewords

     4.  Prompting




2.3  Non Goals

The following features are available under TOPS-20  but  are  not
committed  for this product at this time, however hooks are being
left in the code so that these features can be added at  a  later
date:

     1.  Retype of previous line up to  point  of  error.   Under
         TOPS-20, typing CTRL/H at the beginning of a line (after
         an error has occured) causes the system to redisplay the
         previous  command  line,  up  to the point in error, and
         allow the user to continue typing from that point.

     2.  Partial Field recognition.  Under TOPS-20, typing CTRL/F
         in the middle of a file specification causes the current
         subfield of the file specification to be completed,  but
         not  the  entire  specification.   For  example,  typing
         CTRL/F in the middle of a file name would  complete  the
         file  name  but  would  not complete the file type, even
         though a unique (or default) file  type  and/or  version
         number can be determined.

     3.  Automatic   indirect   command   files.    The   TOPS-20
         implementation  handles  "@filespecification" constructs
         automatically.  This is not planned  for  this  release.
         Indirect  command  files  may  still be implemented by a
         user program by specifically allowing  for  this  syntax
         and  then  doing  the  appropriate  thing (as opposed to
         having it happen automatically).

The current code uses a "fake terminal  service"  to  get  around
certain  deficiencies  in  the VMS V  terminal driver.  This code
does it's own input line editing by waking up any time  the  user
types  rubout, CTRL/R or CTRL/U.  This is very inefficient.  This
will be fixed  for  V4  when  better  terminal  support  will  be
available.   This  will entail one change:  the current code uses
CTRL/W to mean rub-word.  Under V4, LINE FEED is used to mean rub
word,   so  this  code  will  be  changed  to  conform  with  VMS
conventions.

Hooks are being left for the following features, but they are not
committed for the initial release:
                                                                          Page 7


     1.  Asynchronous operation and the ability to parse commands
         from multiple terminals simultaneously.

     2.  The ability to read a help library from the middle of  a
         command to aid in the incremental help process.

     3.  The ability to conveniently use these  routines  from  a
         high  level  language.   The reason for this is the same
         reason that RMS, Cross Reference Utilities,  and  TPARSE
         can  not be conveniently used from high level languages.
         Many high level languages,  like  FORTRAN,  just  cannot
         conveniently  create and manipulate the table structures
         needed to use these routines.

The following features are not being  implemented  at  this  time
because  VMS  provides no clean user-interface for getting at the
appropriate data.

     1.  The ability to recognize node names.

     2.  The ability to recognize device names.

     3.  The ability to recognize logical names.

     4.  The ability to  recognize  topics  from  HELP  libraries
         (except perhaps for the top level topic).

     5.  The ability to recognize account names.

     6.  The ability to recognize usernames.

Specific non-goals:

     1.  It is not a goal of this product to provide users with a
         general-purpose high-level parser.

     2.  It is not a goal of this project to  actually  interface
         these  facilities  into various VMS utilities, but it is
         hoped that the VMS  group  will  decide  to  phase  this
         product  into  their  utilities.   We  have had informal
         talks  with  the  VMS  group,  but  they  have  made  no
         commitment at this time.

     3.  It is not a goal of this product to write  the  code  in
         transportable BLISS.
                                                                          Page 8


2.3.1  STATUS -

The code is reasonably complete (for VMS V3) and has already been
used  in  several  demo  programs  and  some  in-house  products.
however, I have had no luck in submitting




3.0  FUNCTIONAL DEFINITION

There are two main interfaces that need to be described, the user
interface and the programmer interface.

Part A describes the user interface which is what a terminal user
sees when he is typing input to a program that makes use of these
facilities.

Part B describes the  programmer  interface  which  includes  the
usage,  calling  sequences,  macros, and table formats associated
with the RTL routines that one must call  in  order  to  write  a
program that makes use of these facilities.

Note that there are really two types of users  of  this  package.
There  is  the  person  that  writes  code that interfaces to the
recognition package.  We shall  refer  to  this  person  as  "the
programmer"  throughout this spec.  There is also the person that
sits at a keyboard and enters commands  to  a  program  that  was
coded  to  use  the  recognition package.  We shall refer to this
person as "the user" throughout this spec.

Throughout this spec, we give examples of command lines that come
from  DCL  and  other  VMS utilities.  This in no way is meant to
imply that the recognition package is being interfaced  into  DCL
at  this time;  we use DCL commands as examples because they will
be familiar to the readers of this spec.
                                                                          Page 9


                          PART A - THE USER INTERFACE




3.1  Keys Used For Help And Recognition

The keys chosen to do  help  and  recognition  are  "?"  and  TAB
respectively.

"?" has long  been  reserved  by  the  Digital  Command  Language
Standard for this purpose.

The reason that ESCAPE was not  chosen  to  do  recognition,  was
because  the  VMS  group  and  the terminals group felt that they
wanted to reserve  ESCAPE  for  the  purpose  of  sending  escape
sequences  to  the  host.  In V4 of VMS, the terminal driver will
normally use  escape  sequences  to  handle  input  command  line
editing.  Also, new terminals are being built that have no ESCAPE
key.

The key used to do recognition must be  easy  to  type  since  it
turns out that this key will be typed a lot, once people get used
to doing recognition.  In fact, it will probably  be  typed  even
more  than  "space".   The reason for this is that by ending each
field typed by <RECOGNIZE> rather than by <SPACE>, the user  gets
an  immediate feedback about whether what he has typed is correct
or not.  In this way, he doesn't have  to  wait  until  he  types
carriage  return at the end of the command to see if he gets some
sort of error message.  This is not  just  a  feature  that  only
novices will use - even experts find it very convenient.

The <TAB> key turns out to be  very  easy  to  touch-type;   even
easier than the ESCAPE key.



3.2  Other Keys Used

In the current implementation (using my  fake  terminal  service)
the  CTRL/W  key is used to mean "rub word".  This will change to
LINE FEED once the recognition package is upgraded for  use  with
V4  of  VMS.   LINE  FEED  is  the  character V4 is using to mean
rub-word.



3.3  Incremental Help

At any time while entering a command, the user can  type  "?"  to
find  out  what  type  of field the computer is expecting at that
point.  He will  get  back  either  a  canned  message  from  the
recognition  package  (such  as  "filespec"  or  "number")  or  a
                                                                         Page 10


tailored message if the programmer  has  supplied  one  (such  as
"FORTRAN source file" or "number of copies to print").

If the current field is an explicit quoted string, then  the  "?"
character  is  a valid data character and can be entered directly
into the command line.  No incremental help occurs.  This  allows
a user to type a command such as

MAIL (FILE) ABC.TXT (TO) JOE /SUBJECT="How are you?"

and have the "?" be used as valid text in the subject string.

If the current field is a keyword field  (including  a  qualifier
field),  then the incremental help message will give the user the
valid list of keywords (or qualifiers) that can be typed at  that
time.  All valid keywords will be listed, although the programmer
has the option of suppressing selected  keywords  from  the  help
display  (such  as  obsolete  keywords) if desired.  If a partial
keyword has already been entered,  then  the  system  only  lists
those keywords that begin with the letters typed.  If the keyword
or qualifier takes a value, the system will display an "=" at the
end  of  the  keyword in the help frame to remind the user that a
value can be supplied.  If the keyword is negatable, and "?"  was
typed  at the beginning of the field, the keyword will be printed
with  the  negation  prefix  enclosed  in  square  brackets,  e.g
/[NO]LIST reminding the user that the keyword can be negated.




3.4  Recognition

If TAB is typed at the beginning of a  field,  then  the  default
value for that field will be recognized, if there was one.  If no
default value was specified by the programmer, or if TAB is typed
in  the  middle of a field, normal recognition as described below
is attempted.

When TAB is typed, the system looks at the partial field  already
entered  by  the  user  and tries to complete it.  If the current
field is a keyword field (including a qualifier  field),  and  if
there  is  a unique qualifier beginning with the letters typed so
far, then the remainder of the keyword is recognized.   If  there
are  multiple  keywords  beginning with the letters typed so far,
the system recognizes as many as it can and  then  beeps  at  the
user telling him that further recognition was not possible.

If the current field is a filespec field, the system will try  to
complete this field too.  No attempt will be made to check to see
if a name is a node name, logical name, or device name;  the name
will  be  assumed  to  be  a filename unless the syntax precludes
this.  Recognition can occur within the  file  name,  file  type,
file  version, or directory portion of the filespecification.  If
                                                                         Page 11


multiple  choices  are  possible,  the  system  will  attempt  to
complete  as much of the partial filespecification as it can, and
then  it  will  beep  at  the  user  telling  him  that   further
recognition was not possible.  After completing a directory name,
the closing "]" (or ">") will be  recognized,  unless  there  are
subdirectories  present  for  that  directory,  in which case the
system will beep indicating that the user may either type "]"  or
"." to specify a subdirectory.

Note that the  programmer  is  permitted  to  include  a  default
filespec  and  a  related  filespec when coding a filespec parse.
These  will  be  taken   into   consideration   when   performing
recognition.   For  example, suppose a default filespec of ".FOR"
is associated with the filespec parse of the first  parameter  in
the DCL FORTRAN command.  Then if a user types FORTRAN A and then
types <RECOGNIZE> and he has only one FORTRAN file beginning with
the  letter  "A", that filename will be recognized, including the
filetype and the latest version number.  This is true even though
he  might have some .OBJ or .EXE files in his area also beginning
with the letter "A".  If the default filetype of ".FOR"  had  not
been  specified  to  the  recognition package, then when the user
typed <RECOGNIZE>, the system  would  complete  the  filename  to
"ABCDEF.",  say,  and  then  beep him since the filespec could be
completed with .OBJ or .FOR.



3.5  Guidewords

The  programmer  can  specify  guidewords  for  any  field.    If
recognition  is  successful  on the previous field, the guideword
for the next field will be displayed in parentheses, as a helpful
reminder  to  the  user of what is expected next.  The guidewords
for a command can be designed to make the command read more  like
English,  rather than computerese.  The guideword can be typed in
directly by the user, but never needs to be typed in.   If  typed
in,  it  must  be  correct.   Help  and recognition work within a
guideword field.



3.6  Choices For Fields

The programmer can specify that there is a list of choices for  a
given  field, for example, the field can be either a keyword or a
number.  In such cases, when the user types "?", he will be  told
about each possible choice.  The choices will be separated by the
word "or" and will be listed in the order that  the  system  will
attempt  matching.   Note  that  if there is a set of choices and
recongition is  requested  by  the  user,  the  recognition  will
proceed choice by choice.  If partial recognition occurs with any
choice, that will determine which characters get recognized.
                                                                         Page 12


3.7  Miscellaneous

If help or recognition is requested by the user  and  the  system
cannot  figure  out  what  type of field is being entered because
some earlier part of the command line is  totally  erroneous,  an
immediate  error  message  will result.  For example, if the user
types SHOW PRICESS /Q?  wanting to know about all the  qualifiers
beginning  with  the  letter  Q  in the SHOW PROCESS command, the
system will not know that  he  wants  the  SHOW  PROCESS  command
because  the  word  "PROCESS" was misspelled.  An immediate error
message results.  In all other cases, if any sort of error occurs
during  the  recognition process itself, no error message will be
given.  The system will mereley beep at the user telling him that
recognition  could  not  be  accomplished.   For example, if when
trying to recognize a filename, the  recognition  package  should
get  a  protection  violation  reading a directory, or run out of
quota, or some other system type error, this error  will  not  be
printed,  but  the package will beep at the user telling him that
it was unable to recognize the filename.
                                                                         Page 13


                       PART B - THE PROGRAMMER INTERFACE




3.7.1  OVERVIEW -

The parsing routines are very closely tied in with  the  terminal
service.   For  example,  the  interface  could  not  be that the
programmer calls LIB$GET_INPUT to read a command  line  and  then
calls  the  recognition  package to parse that line;  for by that
time it is too late.  The <HELP> and <RECOGNIZE> characters  must
be  processed  by  the routine that is reading the input from the
terminal.  In that sense, these routines can be considered to  be
a  replacement  for  the  standard LIB$GET_INPUT routine, or more
generally, a replacement for the $INPUT macro call.




3.7.2  Background Information -

We have seen that the parsing routines must be very closely  tied
in with the terminal input service.  If in the middle of typing a
filespecification, in the middle of  a  command  line,  the  user
types  <RECOGNIZE>, the code must know that a filespec is desired
by the program, so that filespec-recognition  can  occur.   Thus,
the programmer's parsing routine must be invoked at this point.

Consider the following scenario:

A user begins typing a command line, say

$ DELETE ABCD

and then types <RECOGNIZE>.  The  program's  parsing  routine  is
called.   It specifies that the first parameter in the command is
to be a keyword.  The  recognition  package  then  hands  it  the
keyword  "DELETE"  and  the  user's program notes the fact that a
DELETE command has been entered, say by setting  a  bit  in  some
table.   Then  the program's parsing routine says that it wants a
filespecification.   All  well  and  good.   We  see  a   partial
filespecification ("ABCD") and go to try to complete it.  Suppose
partial completion occurs;   we  type  out  "E."  and  leave  the
terminal looking like

$ DELETE ABCDE.

and we await more input, allowing the user to type in a filetype.
At  this  point,  instead  of  typing  further,  the user deletes
characters in his command line back to the "D" at  the  beginning
and  then  types  "IR",  having  changed  his  mind about doing a
DELETE.  He now wishes to issue the  DIRECTORY  command  instead.
                                                                         Page 14


His terminal looks like:

$ DIR

and he types <RECOGNIZE> expecting  "DIR"  to  get  completed  to
"DIRECTORY".   At  this point, we must again invoke the program's
parsing routine to find out  what  kind  of  field  is  expected.
However,  when we last left the program's parsing routine, it was
waiting for a return from a request to read  a  filespecification
from the terminal, preparatory to performing the DELETE command.

The way we handle this is by the recognition package establishing
a condition handler (behind the programmer's back) and signalling
HLP$_REPARSE when a reparse is necessary.  Our condition  handler
catches  this  signal  and  performs  an  unwind;  then calls the
program's parsing routine over again from the start.   With  this
scheme,  it  is not necessary for the programmer to actually have
to establish any condition handlers of his own.  The programmer's
parsing  routine  must be written so that it can be entered again
should a  reparse  of  the  line  be  necessary.   Normally  this
involves  no extra work on the part of the programmer.  He should
initialize all variables used (not assume they are initially  0).
In  some cases, the programmer may have to test a first-time flag
or some other flag.  For example, if the parsing routine needs to
allocate  virtual  memory,  it  should  first  test to see if the
virtual memory has already been allocated, and only if it has not
yet been allocated, should it allocate it.

In extreme cases, the programmer's parsing routine  may  have  to
establish  a  condition  handler  to  clean up on an unwind;  for
example, if the parsing routine must open a file for some obscure
reason  in the middle of parsing the command line, then it should
establish a condition handler to close the file should an  unwind
occur.



3.7.3  The Programmer Interface -

Two interfaces have been proposed, the general interface and  the
simple  interface.   The  general  programmer  interface  is  the
interface that has been coded and is general enough to handle all
envisioned  parsing  needs.   The simple programmer interface was
envisioned to be simpler to use than the general interface and is
still in the design stage.
                                                                         Page 15


3.7.4  The General Programmer Interface. -

The  general  programmer  interface  consists  of  two  routines,
LIB$PARSE_LINE and LIB$PARSE_FIELD.  LIB$PARSE_LINE initiates the
command line parse.  There are  many  options,  so  it  would  be
inconvenient  to  specify  them  all as actual parameters in this
call.  They are specified in a data block and the address of  the
data  block  is  passed  to LIB$PARSE_LINE.  (Although there is a
large number of options, only a small number  of  them  are  ever
needed, except for incredibly complex programs, such as DCL which
might need about half these options).

The control structure passed  to  LIB$PARSE_LINE  is  called  the
Command  Access  Block  (CAB).   <This corresponds to the command
state table in the TOPS-20 implementation.>  The  format  of  the
call to LIB$PARSE_LINE is:

ret-status.wlc.v =
LIB$PARSE_LINE(cab-adr.ma.v,parse-rtn.flc.rp,parse-arg.rlu.v)

where

cab-adr        is the address of the CAB

parse-rtn      is the address of the  programmer's  routine  that
               will  perform  the  parsing of the line being read
               in.

parse-arg      is an arbitrary longword value  that  gets  passed
               along  to  the programmer's parsing routine.  This
               is an optional argument.  If not  specified,  a  0
               will   be   passed  to  the  programmer's  parsing
               routine.

The programmer specifies the buffer that is to receive  the  line
read in, the prompt string, and other things related to the parse
request, by placing this information in the CAB prior to  issuing
this  call.   To  make  it  easy  to  do  this,  there is a macro
interface to the CAB.  A typical initialization of  a  CAB  might
look like:

$CAB(BUF=IN_BUF,PMT=%ASCID 'FLX> ',OPT=<CVT,COM>)

which specifies the input buffer to receive the command  line,  a
prompt  string  to  be  used ("FLX>"), and two options (CVT means
convert lower case to upper case and COM means allow "!" to  mean
end-of-line comment).

The programmer's parsing routine is called with one argument.

This  argument  is  the   value   of   the   programmer-specified
parse-argument.   This allows the programmer to pass arguments to
his routine.  If more than 32 bits worth of information needs  to
                                                                         Page 16


be  passed,  the  programmer  can  pass the address of a block of
information.  In case the programmer has more than  one  CAB,  he
could specify the address of the CAB as this argument.

It was originally  proposed  that  another  argument  be  passed;
telling  the  parsing  routine  whether this is a reparse or not.
However, it was decided that this is not necessary,  because  the
programmer can set up and test a first-time flag here if he needs
to know whether or not this is a reparse.  (A reparse occurs when
the  recognition  package  calls the programmer's parsing routine
again, after an unwind,  indicating  that  the  user  rubbed  out
fields  that  had  previously  been  parsed,  and  that it is now
necessary for the programmer to parse the line again.)

LIB$PARSE_FIELD is then called once for each field to  be  parsed
by the programmer's parsing routine.  This routine must be passed
the address of a Parameter Block (PAB) containing all the details
about the field to be parsed.

The format of this call is

ret-status.wlc.v = LIB$PARSE_FIELD(pab-adr.ma.v)

where pab-adr is the address of the PAB.

The structure names CAB and PAT have been "signed out"  from  the
VMS  group.   (Originally,  the names CAB and PAB were requested,
however, the name PAB turned out to be in use, so PAT was  chosen
instead.   However,  the  code  currently  uses the prefix "PAB".
Should the VMS group ever accept this code, it will  most  likely
change to PAT.) The prefix "HLP" that you will see below is known
to already be in use and  will  have  to  change  so  as  not  to
conflict  with  other  symbols  appearing  in STARLET;  however I
haven't yet signed out an appropriate replacement prefix.



3.7.5  EXAMPLE -

Before  we  go  into  the  nitty-gritty  of  all  the  bits   and
structures, a simple example would be useful.

Suppose a user  program  wants  to  parse  a  command  line  that
consists  of  a keyword followed by a number.  The valid keywords
are "STOP", "GO", "CONTINUE", and "HALT".  The program  wants  to
prompt for this command using the string "CTRL> " as a prompt.

The programmer starts by writing a standard LIB$LOOKUP_KEY  table
for his four keywords.  Let us say that the address of this table
is USERTAB.  Let us say that when the user is done, he wants  the
keyword  number  1,  2,  3,  or 4 (corresponding to "STOP", "GO",
"CONTINUE", "HALT") stored at address KEYNUM, and  the  value  of
the decimal number stored at address NUMBER.  Let us suppose that
                                                                         Page 17


symbols USERTAB, KEYNUM, and NUMBER are  all  defined  at  module
level, and we omit showing the LIB$LOOKUP_KEY table.

First the programmer  builds  a  CAB  that  contains  his  prompt
string.   Then the programmer calls LIB$PARSE_LINE specifying the
address of this CAB and the address of his parsing routine.   For
example (in BLISS),

LOCAL STATUS,
      PROG__CAB     : $CAB(PMT=%ASCID 'CTRL> ');

STATUS=
   LIB$PARSE__LINE(PROG__CAB,CTRL__PARSER);

The parsing routine, CTRL_PARSER,  specified  by  the  programmer
would look something like this:

ROUTINE CTRL__PARSER =
BEGIN
LOCAL STATUS;

OWN

    KPAB  : $PAB(CAB=PROG__CAB,
                 TYP=KEYWORD,        ! Keyword field
                 ARG=USERTAB,        ! Address of keyword table
                 HLP=%ASCID 'control command'),
                                     ! In-line help message

    NPAB  : $PAB(CAB=PROG__CAB,
                 TYP=NUMBER,         ! Number field
                 HLP=%ASCID 'count', ! in-line help message
                 DEF=%ASCID '1',     ! Default is 1
                 GDW=%ASCID 'WITH'); ! Guideword is "(WITH)"

!+
! Parse keyword.
!-

STATUS = LIB$PARSE__FIELD(KPAB);
IF NOT .STATUS
THEN
    BEGIN
    do whatever you want to tell the user about the error
    and then return.  You could SIGNAL(.STATUS) if desired.
    END;

!+
! Pull the returned value corresponding to
! the keyword that matched
! out of the PAB and store it at KEYNUM.
!-
                                                                         Page 18


KEYNUM = .KPAB[PAB$L__VAL];

!+
! Parse the number.
!-

STATUS = LIB$PARSE__FIELD(NPAB);
IF NOT .STATUS THEN SIGNAL(.STATUS);

!+
! Store away the returned value.
!-

NUMBER = .NPAB[PAB$L__VAL];

RETURN SS$__NORMAL
END;




3.7.6  Types Of Fields -

The type of field to be parsed is specified by the programmer  by
putting  it  in  field  PAB$B_TYPE in the PAB.  The various legal
field types are defined symbolically and will be  made  available
to  the programmer in the same way that the structure offsets for
the CABs and PABs are made available to  the  programmer.   These
names can be distributed through inclusion in STARLET, if the VMS
group wants to do it that way, or through  an  independent  macro
library (MACRO) or require file (BLISS).

HLP$K_KEYWORD

          A keyword is to be parsed.  Field  PAB$L_ARG  specifies
          the  address  of a keyword table containing the list of
          valid keywords.  A standard LIB$LOOKUP_KEY table may be
          specified   or   a   new-style  keyword  table  may  be
          specified.  (See below.)

HLP$K_NUMBER

          A number is to be parsed.  For example,  the  value  of
          the  /COPIES=  qualifier to the DCL PRINT command would
          use  this  type  of  field.   No  range   checking   is
          performed.   That  is  up  to  the  user  program.  Any
          syntactically valid non-null number  is  recognized  as
          being valid.  That is, typing <RECOGNIZE> after a digit
          will cause the system  to  go  on  to  the  next  field
          (normally  a space would print) informing the user that
          a valid number was entered.  Field PAB$L_ARG  specifies
          the radix of the number (2-16).
                                                                         Page 19


HLP$K_QUALIFIER

          A qualifier is to be parsed.  Field PAB$L_ARG specifies
          the  address  of a keyword table containing the list of
          valid aulaifiers.  A standard LIB$LOOKUP_KEY table  may
          be  specified  or  a  new-style  keyword  table  may be
          specified.  The  initial  "/"  is  not  stored  in  the
          keyword table.  If the new style keyword table is used,
          then the programmer can specify which  qualifiers  take
          values,  so  that  the incremental help will inform the
          user of this  fact  by  displaying  an  "="  after  the
          qualifier   name   in   the   help  display.   Obsolete
          qualifiers can  be  marked  by  setting  the  KIT$V_INV
          (invisible)  bit  in  the  KIT.   This  will  allow the
          qualifier to be parsed, but it will not appear  in  the
          incremental   help   text.    For  example,  the  /VT05
          qualifier on the SET TERMINAL command to DCL  has  been
          obsoleted  by  the  qualifier  /DEVICE_TYPE=VT05, so it
          could  be  marked  as  being  invisible,  if   desired.
          Negatable  qualifiers can also be so indicated, so that
          the incremental help text can list them  in  the  form,
          /[NO]FOO, if desired.

HLP$K_INPUT_FILE

          An input filespec is to  be  parsed.   Field  PAB$L_ARG
          specifies  the  address  of  a vector of two longwords.
          The first longword is the address a descriptor for  the
          default  name and the second longword is the address of
          a descriptor for the  related  name.   Either  or  both
          longwords  may be 0.  (((Originally, I had spec'ed that
          this field contained the address of an RMS FAB with  an
          associated NAM block containing the default and related
          strings, however in actual practice, it turned  out  to
          be inconvenient to have to build FABs just to specify a
          default name.)))

HLP$K_OUTPUT_FILE

          An output filespec is to be  parsed.   Field  PAB$L_ARG
          specifies  the address of a vector of two longwords (as
          above) specifying the default and related  names.   The
          difference  between this type of parameter and an input
          file is the way in which recognition works.  For output
          file recognition, the FAB$V_OFP (output file parse) bit
          in the FOP parameter of the FAB structure is  set  whch
          causes   defaults   from   the   related  name  to  act
          differently.  (See the RMS manual  for  more  details).
          Also,  for  input  file  recognition,  the exact vesion
          number (normally the  latest  version)  is  recognized.
          For   output   file   reognition,   ";0"   is  normally
          recognized, indicating that a new version of  the  file
          is to be created.
                                                                         Page 20


HLP$K_GENERAL_FILE

          A general filespec is to be parsed.  (((I  don't  fully
          understand  the  need  for  this  yet,  but the TOPS-20
          people seem to think it is important.)))

HLP$K_PARAM

          An arbitrary parameter terminated by space,  slash,  or
          comma  is to be parsed.  This is useful for fields that
          are not understood  by  the  recognition  package.   No
          recognition is performed on such fields.

HLP$K_END

          The end of the line is expected at  this  point.   This
          field  must eventually be parsed for all command lines.
          The default help text for this field is  "confirm  with
          carriage  return",  but of course this can be overriden
          by specifying explicit  help  text  via  the  PAB$A_HLP
          field  in  the  PAB.  The guidword field (PAB$A_GDW) is
          normally  not  used  with  this  field,  but  could  be
          specified if the programmer wants a guideword to appear
          after the normal termination of  the  command,  say  to
          make  the command read more like English.  For example,
          the WHAT command, SHOW DEVICES (IN  THE  DISPLAY)  uses
          this feature.

HLP$K_DIRECTORY

          A device-directory specification is to  be  parsed.   A
          node  name  is  also optional.  For example, the DECset
          command BUILD DATABASE (ON) DBA3:[FOO] would  use  this
          type   of   field.   Recognition  is  peformed  on  the
          directory portion of this field,  but  not  within  the
          node  name  or  device  name portion.  If the PAB$V_SPO
          (syntax parse only) bit in the PAB is  specified,  then
          the  directory need not exist, i.e., a new directory is
          being created.  In that case,  the  directory  name  is
          only  checked for syntax.  For example, the DCL command
          CREATE/DIRECTORY [FOOBAR] would need to set this bit.

HLP$K_USERNAME

          A username is to be parsed.  For example, the  argument
          to  the  TO>  prompt in the MAIL program would use this
          type of field.  The name  must  be  a  valid  username,
          however, this is not checked for in this release of the
          recognition package because there is no easy way to get
          at  the  list of legal usernames.  Of course, a program
          like AUTHORIZE that has the list of legal names,  could
          put  them  in a keyword table and then parse this field
          as a keyword field, if  desired.   Recognition  is  not
                                                                         Page 21


          performed on this field in this release.  The PAB$V_SPO
          (syntax parse  only)  bit  is  set  to  mean  that  the
          username  need not exist.  For example, the command ADD
          NEUMANN to the AUTHORIZE program would need to set this
          bit.  In that case, the field is only checked for legal
          syntax.

HLP$K_FLOAT

          A  floating  point  constant  is  to  be  parsed.    No
          recognition is performed on this field.

HLP$K_DEVICE

          A device name is to be parsed.  For  example,  the  DCL
          command ALLOCATE DBA2:  would use this type of field to
          parse its parameter.  Partial field recognition is  not
          currently  supported  but  could  be  easily added once
          wildcard  support  is  added  to  the  $GETDVI   system
          service.   Until  then, there is no easy way for a user
          program to get access  to  the  list  of  legal  device
          names.

HLP$K_TEXT

          Arbitrary text is to be  parsed.   All  characters  are
          legal  from  this  point  to the end of the line.  This
          field would be specified when the text to  be  obtained
          is  of  unknown syntax.  It will be accepted and passed
          to  the  user  program   for   further   parsing.    No
          recognition  occurs in such a field.  For example, if a
          user defines the DCL symbol FOO as $SYS$SYSTEM:PROG.EXE
          and  then  types FOO ABC DEF to DCL, he is invoking the
          program PROG through the foreign command  interface  to
          DCL  and  DCL would parse everything after the word FOO
          as a TEXT field.  This text would then be passed to the
          user  program.   (If  a  user wants to invent a new DCL
          command  and  wants  recognition  facilities,  then  he
          should  invoke  his  command  using  the  CLE interface
          rather than the  foreign  command  interface,  assuming
          that recognition services eventually finds its way into
          the CLE.)

HLP$K_TIME

          A  date-time  specification  is  to  be  parsed.    For
          example,  the value of the /AFTER= qualifier on the DCL
          SUBMIT command would use this type of field.  Any legal
          date/time  specification  is  permitted, as well as the
          keywords TODAY, TOMORROW, and YESTERDAY.

HLP$K_QUOTED_STRING
                                                                         Page 22


          A quoted string is to be  parsed.   The  quoted  string
          must  be  enclosed  in  the  quote  character  which is
          specified  in  field  PAB$L_ARG  in  the   PAB.    This
          character   defaults   to   double  quote  (")  if  not
          specified.  The quote character may appear  within  the
          quoted  text by doubling it up.  If the quote character
          is double quote, then the characters "?" and TAB may be
          entered  directly  into  this  field while entering the
          command  line.   They  will  echo  as   "?"   and   tab
          respectively.   In such a case, these characters do not
          signal the start of incremental  help  or  recognition.
          For  example,  the  DCL command A="TEST" would use this
          type of field.  Note that if the surrounding quotes are
          optional,  then  the  next  field  type  should be used
          instead.

HLP$K_STRING

          A string is to be parsed.  The string may  have  double
          quotes around it.  The double quotes are necessary only
          if the string contains special characters such as space
          or  comma.   For  example,  the  value on the /SUBJECT=
          qualifier to the MAIL command to  DCL  would  use  this
          type  of  field.   If  the  first character is a double
          quote, then the field behaves exactly as  the  previous
          type  of  field  (HLP$K_QUOTED_STRING).   If  the first
          character is not a double quote, then the field extends
          to  the  first  valid  separator  (space,  comma, plus,
          slash) or end-of-line.

HLP$K_TOKEN

          An explicit string is to be parsed.  Each character  in
          this  string  must match exactly.  Typically, this is a
          one-character string used to match  syntactic  elements
          like  comma, at-sign, equal sign, etc.  Field PAB$L_ARG
          contains the address of a descriptor  for  the  string.
          For   example,  one  of  the  choices  allowed  at  the
          beginning of a command line to WHAT.EXE is a  construct
          of  the  form  @filespec, telling it to accept commands
          from an indirect command file.  The first character  of
          this   construct  is  parsed  using  a  field  type  of
          HLP$K_TOKEN.

HLP$K_ACCOUNT

          An account name is to  be  parsed.   For  example,  the
          value  of the /ACCOUNT= qualifier to the DCL ACCOUNTING
          command would use this type of field.  The account must
          exist,  however  there is currently no way to check for
          this.  If the bit PAB$V_SPO (syntax parse only) is  set
          in  the PAB, then the account name need not exist, i.e.
          a new account name is being  created.   This  would  be
                                                                         Page 23


          needed  for  the /ACCOUNT= qualifier to the ADD command
          in AUTHORIZE.  Recognition is  not  performed  on  this
          field  in this release of the recognition package;  the
          field is just checked to see  if  it  is  syntactically
          correct.

HLP$K_NODENAME

          A nodename is to be parsed.   For  example,  the  third
          field  in  the  DCL  command SET HOST VAX4::  would use
          this type of field.  The name  must  be  a  valid  node
          name,  however  there is currently no easy way to check
          for this.  If the bit PAB$V_SPO (syntax parse only)  is
          set in the PAB, then the node name need not exist, i.e.
          a new node name is being created.   For  example,  this
          would  be  used to parse field 5 in the NCP command SET
          NODE 23 NAME FOOBAR.  Recognition is not  performed  on
          this  field  in this release of the recognition package
          because  VMS  does  not  provide  an  easy  way  for  a
          user-level   program  to  get  at  the  list  of  valid
          nodenames.  Thus, the field is just checked to  see  if
          it is syntactically correct.

HLP$K_LOGICAL_NAME

          A logical name is to be parsed.  For example, the third
          field in the DCL command SHOW TRANSLATION FOO$BAR would
          use this type of field.   The  name  must  be  a  valid
          logical name.  If the bit PAB$V_SPO (syntax parse only)
          is set in the PAB,  then  the  logical  name  need  not
          already  exist,  i.e.   a  new  logical  name  is being
          created.  For example, this  would  be  used  to  parse
          field  2  in  the  DCL command DEFINE FOO$SYSTEM "XYZ".
          Normally, bit PAB$V_NOWLD (no wildcards) should be  set
          to  prohibit  wildcards in the name.  This bit would be
          clear if wildcards are legal, as  in  the  DCL  command
          SHOW   LOGICAL   ABC*.    Full   field  recognition  is
          performed, however partial  field  recognition  is  not
          implemented  in  this  release because there is no easy
          way to get at the complete list of valid logical names.

HLP$K_UIC

          A UIC of the form [m,n] or <m,n> is to be parsed.   For
          example,  the  third  field  of the DCL command SET UIC
          [23,45] would use this type of field.   No  recognition
          is performed in this field.

HLP$K_TOPIC

          Reserved for future use to allow recognition  of  topic
          names  from  help libraries.  The problem is that there
          is no easy way to get the list of legal subtopic  names
                                                                         Page 24


          (other than the top level topics) from a help library.

HLP$K_NAME

          A name consisting of letters, digits,  and  underscores
          is wanted.  No semantics are involved.  This field type
          is used for names that are unknown to  the  recognition
          package.   If recognition is requested, the system will
          print a space indicating that a  valid  name  has  been
          typed if it is syntactically valid.

HLP$K_CHARACTER

          Any single character is valid.  This field type is used
          as  a  last-ditch  emergency  escape  if the programmer
          wishes  to  perform  parsing  of  some  kind  that   is
          completely out of the scope of the recognition package.
          No  recognition  is  performed  on  this  field.    The
          programmer  can then get as many characters as he wants
          from the command line  and  parse  them  himself.   For
          example, the debugger has a command of the form

          SET BREAK expr DO cmd

          where  "expr"  denotes  any  valid  expression  in  the
          currently  selected language.  The debugger already has
          a large piece of code that parses such expressions, and
          if  they  decide  to  use the recognition package, they
          might not want to  recode  all  this  language-specific
          expression  parsing  code  on  a first pass.  Thus they
          could parse the keyword fields,  SET,  BREAK,  DO,  and
          those  in  "cmd"  via the recognition package and parse
          the "expr" field with their original parser by  getting
          characters    from    the   command   line   with   the
          HLP$K_CHARACTER field type.
                                                                         Page 25


3.7.7  Fields Within The Command Access Block (CAB) -

Fields that are not programmer-initializable:

CAB$W_BLN      Size of CAB in bytes.  This field  is  initialized
               to CAB$K_BLN by the $CAB macro.

CAB$B_BID      Block ID of CAB.  This  field  is  initialized  to
               CAB$K_BID  by  the  $CAB macro.  The value of this
               constant should be assigned by the VMS group.

Common fields set by programmer:

CAB$A_CMD      Address of descriptor for buffer  to  store  final
               command   line  that  was  read.   This  field  is
               actually optional.  If  the  programmer  cares  to
               have  us  parse his line and never really wants to
               see what the line was, he can do that.  Note  that
               if  this  descriptor is a dynamic descriptor, then
               the  recognition  package  will  never  return   a
               "command   line  buffer  overflow"  error  to  the
               programmer.  If the current internal command  line
               buffer  should  fill up, additional virtual memory
               will be obtained, and  the  current  $QIO  request
               will be started again specifying the data typed so
               far as the initial string.   Thus  the  user  will
               never know that the command line buffer filled up.
               He will only get an error if he exceeds some quota
               or runs out of virtual memory.

CAB$A_PMT      Address of  descriptor  for  main  prompt  string.
               <This field corresponds to the .CMRTY field in the
               TOPS-20 implementation.>

CAB$A_ATM      Address of  descriptor  for  atom  buffer.   <This
               field  corresponds to the .CMABP and .CMABC fields
               in the TOPS-20 implementation.> The atom buffer is
               a  buffer to contain the string of characters that
               actually matched the current field specification.

Obscure fields that can be specified by the programmer:

CAB$W_CHN      Channel of input device.  If this word is 0,  then
               it  means  the programmer wants input to come from
               SYS$INPUT.   A  channel   is   assigned   by   the
               recognition  package in this case.  LIB$PARSE_LINE
               will then ASSIGN a channel to SYS$INPUT and  place
               the  channel  number  back  in  this field.  <This
               field corresponds to the left half of  the  .CMIOJ
               field  in the TOPS-20 implementation.  There is no
               field corresponding to the right half of that word
               (the  output  JFN) because no one has been able to
               explain to me the purpose of the  output  JFN.   I
                                                                         Page 26


               can  see  no  reason  why  you  would want to type
               <RECOGNIZE>  on  one   terminal   and   have   the
               recognized characters sent to another device.> For
               example, a program that runs from one terminal but
               wishes  to  take  commands  from one or more other
               terminals would need this ability to  specify  the
               channel  of  the  device from which input is to be
               taken.  If the input device  is  not  a  terminal,
               then  RMS  is  used  to read the command line from
               this device.  In this case, incremental  help  and
               recognition  facilities are not available.  Should
               the   <HELP>   or   <RECOGNIZE>   characters    be
               encountered  in  a  record  read from this device,
               they will be treated as text characters.

CAB$V_CVT      Convert lower  case  to  upper  case.   <This  bit
               corresponds  to  the  CM%RAI  bit  in  the TOPS-20
               implementation.> For example, this  bit  would  be
               set  by  LOGINOUT  when  prompting for a username.
               Note that this  bit  is  actually  passed  to  the
               terminal QIO (via the IO$M_CVTLOW bit) so that the
               characters actually echo  in  uppercase.   If  the
               program  wants the characters to echo in upper and
               lower case but be converted to upper  case  before
               being  passed  back  to  the  program,  that  is a
               different  option  (see  the  description  of  the
               CAB$V_UCA bit).

CAB$V_UCA      Uppercase the atom buffer.   Specifying  this  bit
               causes  the string stored in the atom buffer to be
               up-cased   for   all   field   types   that    are
               case-insignificant,  for example HLP$K_KEYWORD and
               HLP$K_INPUT_FILE.  This bit has no affect  on  the
               atom buffer for fields such as HLP$K_QUOTED_STRING
               where lower case letters are significant.  In that
               case,  the  atom  buffer  gets the exact string as
               typed by the user.  This bit will be useful to DCL
               to  help  implement  the  feature  that  allows  a
               program to call back to DCL to get a copy  of  the
               command  line  in  "normal  form"  with non-quoted
               fields up-cased and  multiple  spaces  reduced  to
               single  spaces.   DCL will simply specify this bit
               and then append together all the atom  buffers  as
               it  parses the line (separating the atomic strings
               by a single space).

CAB$V_COM      Treat "!" as  an  end-of-line  comment  character.
               Only  "!"s  in the proper syntactical context will
               have this meaning.  A "!" found in a quoted string
               or  in  an  access  control string or in a foreign
               filespecification will be considered data and will
               not terminate the command parse.
                                                                         Page 27


CAB$V_CON      Allow continuation lines with hyphen ("-").   Only
               hyphens  found  between  fields will be considered
               continuation  line  indicators.   For  example,  a
               hyphen  found in proper context while scanning for
               a date specification (such as 28-JAN-1982) will be
               considered data and will not terminate the command
               scan.  Similarly, hyphens  within  quoted  strings
               are   considered  to  be  data.   (((This  is  not
               implemented yet.  Should I forgo implementing this
               and  leave  it up to the user program to handle it
               or should I make continuation lines  available  to
               all  user  programs?  It is also unclear to me how
               to handle a request for a continuation line  after
               a (sub) prompt has been issued.)))

CAB$V_IND      Allow indirect command file with "@" (reserved for
               future  use).   <This bit corresponds inversely to
               the CM%XIF bit in the TOPS-20 implementation.>  If
               this feature is allowed at all, it is necessary to
               enable and  disable  it,  because  many  utilities
               allow  "@"  as  part of its normal command syntax.
               For example, the command

               EXAMINE @FOO

               is a  perfectly  valid  command  to  SDA  (meaning
               examine  location  referenced  indirectly  by  the
               symbol FOO) and does not mean invoke  an  indirect
               command  file  at  this point in the command line.
               On the other hand, a  large  number  of  utilities
               already  support  indirect  command files (or want
               to) and it would be wasteful to have each of these
               utilities do it themselves.

CAB$A_LEX      Address of a programmer-suplied lexical processing
               routine.  This routine is called after any wake-up
               character is typed (such as  <HELP>,  <RECOGNIZE>,
               or  <RETURN>)  and  is given the line typed by the
               user.  This routine may perform lexical processing
               on  this  line (such as symbol substitution or any
               other sort of pre-processing, and then return  the
               line  to the recognition package.  The recognition
               package  then  proceeds  to  perform  its   normal
               parsing,  incremental  help,  or  recognition.  If
               this longword is 0,  then  no  pre-processing  has
               been requested by the programmer.  This field will
               be useful to DCL to allow  it  to  perform  symbol
               substitution  with  the  ' (apostrophe character).
               The lexical  processing  routine  is  called  with
               three arguments.  Argument 1 is the address of the
               CAB.  Argument 2 is the address of a descriptor to
               received  the  line  back after lexical processing
               has occurred.  Argument 3  is  the  address  of  a
                                                                         Page 28


               descriptor  for  the line as typed in by the user.
               The lexical processing routine must check the  CAB
               to  determine  if  a  lexical  construct  has been
               interrupted with a request for help or recognition
               and handle such a request.  If the lexical parsing
               routine returns with a FALSE status,  this  aborts
               command  parsing  and  LIB$PARSE_LINE returns with
               the status supplied  by  the  lexical  proceessor.
               (Not yet implemented.)

CAB$V_TMO      Timeout operation.  The timeout time (in  seconds)
               is  specified in the CAB$B_TMO field.  This bit is
               actually passed  to  the  terminal  QIO  (via  the
               IO$M_TIMED bit).  This is useful for programs that
               want to time-out the terminal read operation.  For
               example,   LOGINOUT   would   set  this  bit  when
               prompting for a username.

CAB$B_TMO      Timeout time (in seconds).  This byte is  actually
               passed  to the terminal QIO (via the P3 argument).
               This byte is ignored if the CAB$V_TMO bit  is  not
               set.   Consult  the  VAX/VMS  I/O User's Guide for
               more details.  (((RMS uses a byte  field  for  the
               timeout  time, however the terminal driver appears
               to allow a longword time.  Should  I  change  this
               field to be a word or even a longword?)))

CAB$V_PTA      Purge type-ahead buffer.   This  bit  is  actually
               passed  to  the  terminal  QIO (via the IO$M_PURGE
               bit).  The type-ahead buffer is purged before  the
               initial read.  No type-ahead buffer purging occurs
               later in the  process.   For  example,  type-ahead
               typed   while   the   system   is   displaying  an
               incremental help message will not be  purged.   If
               the  programmer  really  wishes  to  disallow  all
               type-ahead,  he  should  change   the   terminal's
               characteristics to prohibit type-ahead.

CAB$V_RNE      Read with no echo.  This bit is actually passed to
               the  terminal  QIO (via the IO$M_NOECHO bit).  For
               example, this bit would be set  by  LOGINOUT  when
               prompting for a password.

CAB$A_QIOGET   Address  of  a  programmer-supplied   routine   to
               replace   the   normal   read   QIO  used  by  the
               recognition package to  read  the  user's  command
               line.  If this longword is 0, then the recognition
               package uses the standard VMS  terminal  QIO's  to
               get  input  from the terminal.  This address would
               only be needed by  systems  that  have  their  own
               (non-standard)   terminal   driver.    The  DECset
               product needs this field in order to allow  us  to
               support  the  VT173 terminal.  This field could be
                                                                         Page 29


               reserved to DEC if we decided not  to  clutter  up
               user-documentation by explaining how it works.

CAB$A_QIOPUT   Address  of  a  programmer-supplied   routine   to
               replace   the   normal   write  QIO  used  by  the
               recognition package to write text  to  the  user's
               terminal.    If  this  longword  is  0,  then  the
               recognition package uses the standard VMS terminal
               QIO's  to  write  to  the  terminal.  This address
               would only be needed by systems  that  have  their
               own  (non-standard)  terminal  driver.  The DECset
               product needs this field in order to allow  us  to
               support  the  VT173 terminal.  This field could be
               reserved to DEC if we decided not  to  clutter  up
               user-documentation by explaining how it works.

CAB$V_WAK      Wake up and begin parsing after each field.   This
               is   useful   if   you  want  to  change  terminal
               characteristics for some fields, such as turn echo
               off  for a password field.  This feature should be
               used very sparingly since it is quite inefficient.
               <This  bit  corresponds  to  the CM%WKF bit in the
               TOPS-20 implementation.> The recommended method of
               changing terminal characteristics within a command
               is  to  input  the  field  requiring  the  special
               characteristics  on  the  next  line  with its own
               prompt.  For example, if a program is accepting  a
               password  (other than as part of an access control
               string) it  should  perform  a  separate  call  to
               LIB$PARSE_LINE   specifying  a  prompt  string  of
               "PASSWORD:  " and including the CAB$V_RNO  bit  to
               read  that  entire  line  with  no  echo.   A more
               efficient method of  suppressing  the  echoing  of
               passwords within an access control string within a
               filespecification is given later.  This  field  is
               reserved for future use.

CAB$A_GET      The address of a routine that should be called  to
               get  the  command  line  into  the command buffer.
               This is specified when the  programmer  wishes  to
               obtain   the   line   himself  without  using  our
               services.  Our services are merely being  used  to
               parse   the  command  line.   This  feature  would
               typically be used if the programmer implements his
               own indirect command mechanism.  Upon encountering
               an @filespec (or similar command)  the  programmer
               then  gets  subsequent commands from the specified
               file and then merely calls us to use  our  parsing
               facilities.    This   field   is  ignored  if  the
               CAB$V_GOT bit is set.

CAB$V_GOT      The command line has already been gotten and is in
               the  programmer's buffer (specified by CAB$A_CMD).
                                                                         Page 30


               The programmer has already  obtained  the  command
               line  and  only  wants  to make use of our parsing
               services.  This feature would normally be used  to
               execute  a  command  that  is  hard coded into the
               user's program.  In that case, he would just point
               at   the   fixed   command  line.   This  is  more
               convenient than pointing at the fixed command line
               and   then  specifying  a  dummy  routine  in  the
               CAB$A_UCI field that does nothing but return.  For
               example, PHONE could use this feature if CTRL/Z is
               typed;  it would call LIB$PARSE_LINE  pointing  at
               an  "EXIT"  command and the program would continue
               as if the user had typed "EXIT".

CAB$V_ASY      This is an asynchronous operation.  LIB$PARSE_LINE
               returns   immediately   to  the  programmer.   The
               programmer must  explicitly  test  the  associated
               event  flag (specified in field CAB$W_EFN) to find
               out when the line has been  read  in  and  parsed.
               (reserved for future use)

CAB$W_EFN      Event flag to be set when the operation completes.
               This  field is ignored if the CAB$V_ASY bit is not
               set.  (reserved for future use)

CAB$A_ASTADR   Address of AST  routine  to  be  called  when  the
               operation completes.  This field is ignored if the
               CAB$V_ASY bit is not set.  If specified,  the  AST
               routine executes at the access mode from which the
               call to LIB$PARSE_LINE was  made.   (reserved  for
               future use)

CAB$L_ASTPRM   AST parameter to be  passed  to  the  AST  service
               routine.   This  field is ignored if the CAB$V_ASY
               bit is not set.  (reserved for future use)

CAB$A_IOSB     Address of quadword I/O status block  that  is  to
               receive  final  completion  status.  This field is
               valid even if CAB$V_ASY is not  set,  however  the
               data  in the I/O status block is valid only if the
               input device is a  terminal.   Useful  information
               returned  in  the  I/O  status  block is the final
               terminator   character   (the    character    that
               terminated  the  command line read operation), the
               terminator size (if it was  an  escape  sequence),
               and  the offset to the terminator.  This offset is
               relative to the buffer address contained in  field
               CAB$A_CBF.   The terminator is not included in the
               programmer's buffer (specified by  the  descriptor
               at CAB$A_BUF).

CAB$A_ERR      Address of routine to be  called  if  there  is  a
               syntax  error  encountered  in  the  command  line
                                                                         Page 31


               parsed  by  LIB$PARSE_LINE.   This   argument   is
               normally  only useful with asynchronous operation.
               The routine  is  called  with  one  argument,  the
               address of the CAB.  (reserved for future use)

CAB$A_SUC      Address of routine to be  called  if  the  command
               line  parse completes successfully (with no syntax
               error).  This argument  is  normally  only  useful
               with   asynchronous  operation.   The  routine  is
               called with one argument, the address of the  CAB.
               (reserved for future use)

CAB$A_PUT      Address of routine to be  called  to  control  the
               display of the incremental help output.  Normally,
               when the  <HELP>  key  is  depressed,  the  system
               automatically  displays  the incremental help text
               on the terminal in the format it wants.  This  may
               not  be  convenient,  for  example, if the user is
               running on a  scope  terminal  and  is  performing
               screen  management (as is the case with WHAT.EXE).
               In that case, he may want to be under full control
               of  where  the help text prints.  In this case, he
               supplies the address of a routine  in  this  field
               and  that  routine  gets called successively, once
               for each line of help  output  that  is  produced.
               This   action   routine   option  is  provided  in
               conformity to  recommendation  51  of  the  VAX-11
               Modular   Programming  Standard  with  regards  to
               human-readable text output.  (See the VAX-11 Guide
               to  Writing  Modular  Library  Routines  for  more
               details.)   The   action   routine   gets   called
               repeatedly for each line of help text.  The action
               routine is called with three arguments.  The first
               argument  is the type of help line being supplied.
               The second argument is the  address  of  the  PAB.
               The  third  argument  is  programmer-supplied  and
               resides  at  CAB$L_PUT.   If  the  action  routine
               returns   a  status  of  FALSE  (low  bit  clear),
               additional lines of help text are not produced and
               the  system  goes  back  to get more command input
               from the user in the usual manner.

CAB$L_PUT      A context longword whose contents  are  passed  to
               the  action  routine whose address is specified in
               CAB$A_PUT.

CAB$W_WIDTH    Width of the input device.   This  information  is
               necessary  when  deciding  how  to format the help
               output for keywords when there are  more  keywords
               than   will  fit  on  a  single  line.   Normally,
               LIB$PARSE_LINE will determine  the  width  of  the
               input  device  (if  it  is  a terminal) by calling
               $GETDVI and use the actual width of the  terminal.
                                                                         Page 32


               However,  the  program  can override this width by
               setting this field to be  non-0.   This  would  be
               useful   for  programs  that  are  displaying  the
               incremental  help  themselves  (by  specifying   a
               routine  to do so in the CAB$A_HLP field) and wish
               to display the help information in only a  portion
               of   the   screen.    If   not  specified  by  the
               programmer, this field is defaulted  in  from  the
               CAB$W_DEVBUFSIZ field.

Fields containing data returned to programmer:

CAB$W_CLN      Number of characters returned  in  command  buffer
               (specified   by   field  CAB$A_BUF)  not  counting
               padding in the  case  of  a  fixed  length  string
               descriptor.

CAB$W_ALN      Number of characters returned in atom buffer,  not
               counting  padding  in  the  case of a fixed length
               string descriptor.

CAB$V_REC      <RECOGNIZE>  terminated  this  field.   <This  bit
               corresponds  to  the  CM%ESC  bit  in  the TOPS-20
               implementation.>

CAB$V_EOL      Field was terminated by end-of-record  (or  CRLF).
               <This  bit  corresponds  to  the CM%EOC bit in the
               TOPS-20 implementation.>

CAB$V_RPT      A reparse is needed.  Internal use only.

CAB$V_PFR      <RECOGNIZE> terminated previous  field  <This  bit
               corresponds  to  the  CM%PFE  bit  in  the TOPS-20
               implementation.>

CAB$B_TRM      Field terminator character.  This is the character
               that  terminated  the  current  field  (it  is not
               necessarily a wake-up character.) Do  not  confuse
               this   with  the  character  that  terminated  the
               current  QIO  read.   That  character   shall   be
               referred  to as the QIO terminator and is returned
               in the I/O status block.

CAB$V_DEF      This bit gets set if the default string  for  this
               field   was   supplied   because  the  user  typed
               <RECOGNIZE> at the beginning of the  field  or  if
               the field was omitted and the programmer specified
               that he did not want to prompt for this field.

Obscure fields that can be read by the programmer:

CAB$A_CBF      Address of actual command line buffer.   This  may
               or  may  not  be  the  address  specified  by  the
                                                                         Page 33


               programmer  in  the  descriptor  given  at   field
               CAB$A_BUF.   If  the  programmer's  descriptor  is
               static, then we read directly into his buffer.  If
               the  programmer's  descriptor  is dynamic, then we
               use a buffer of our own and then use LIB$SCOPY  to
               copy  the  command line to the programmer's buffer
               when we are done.  <This field corresponds to  the
               .CMBFP field in the TOPS-20 implementation.>

CAB$W_CSZ      Size of command line buffer.

CAB$A_PAB      Address of first Parameter block for  the  current
               field.

CAB$A_CURPAB   Address of the current Parameter  Block  (in  case
               several   were   specified   that   were   chained
               together).  The programmer will sometimes need  to
               check this field to see which PAB actually matched
               what the user typed in.

CAB$A_IND_FAB  Address of  FAB  being  used  to  process  current
               indirect command file.  Reserved for future use.

CAB$A_IND_RAB  Address of  RAB  being  used  to  process  current
               indirect command file.  Reserved for future use.

CAB$W_PTR      Offset to next character to be parsed.

CAB$W_FLD_PTR  Pointer to beginning of current field.   <I  think
               this  field corresponds to the .CMPTR field in the
               TOPS-20  implementation.   There   is   no   field
               corresponding to the .CMCNT or .CMINC fields since
               the  contents  of  these  fields  can  be   easily
               calculated  using  CAB$W_FLD_PTR,  CAB$W_PTR,  and
               CAB$W_CSZ.>

CAB$W_PMT_PTR  Pointer to first field  in  current  (sub)  prompt
               line.

CAB$W_SUB_PTR  Pointer to beginning of current subfield

CAB$W_CNT_PTR  Pointer  to  beginning  of  current  line   of   a
               multi-line  command  (if  continuation  lines  are
               being used).

CAB$L_DEVCHAR  Device characteristics for  the  input  device  as
               returned by $GETDVI.

CAB$B_DEVCLASS Device class for the input device as  returned  by
               $GETDVI.

CAB$B_DEVTYPE  Device type for the input device  as  returned  by
               $GETDVI.
                                                                         Page 34


CAB$W_DEVBUFSIZ Input device buffer size as returned by $GETDVI.

CAB$L_DEVDEPEND Device dependent information for the input device
               as returned by $GETDVI.

CAB$L_DEVDEPND2 Additional device dependent information about the
               input  device  as returned by $GETDVI.  We need to
               know if the  device  is  a  block  mode  terminal,
               because  in that case, editing of the command line
               can  be  performed  even  when  we  didn't   think
               possible, so we must signal HLP$_REPARSE after any
               terminal I/O operation.

CAB$V_HLP      Line ended with "?".

NOTES:

     1.  The following bits are available in $QIO  calls  to  the
         terminal  driver  but  are  not  accessible  through the
         LIB$PARSE_LINE call:

         1.  IO$M_DSABLMBX.  Does not seem applicable.

         2.  IO$M_NOFILTR.  Incremental help and recognition does
             not seem appropriate in NOFILTR mode.

         3.  IO$M_REFRESH.  Under our control.  Always specified.
             Things  would  get  very  confusing without this bit
             set.

         4.  IO$M_TRMNOECHO.    Under   our   control.     Always
             specified.


     2.  The following fields exist in the TOPS-20 implementation
         and have no counterpart here:

         1.  The CM%NOP bit (parse  failed).   This  bit  is  not
             necessary  because  the  programmer can test the low
             order bit of the returned status value.

         2.  The CM%RPT bit (reparse is needed bit).  We  do  not
             use  this  bit because it was felt that there was no
             reason to  ever  let  the  programmer  do  a  manual
             reparse.   Under  our  implementation,  reparses are
             handled automatically as necessary and are invisible
             to  the  programmer.  To explain to a programmer how
             to do the reparse would be very complicated since he
             might  have  to set up a condition handler and do an
             unwind.
                                                                         Page 35


         3.  The CM%SWT bit (switch value  occurred).   This  bit
             appears  to  be  unnecessary.   The  programmer  can
             examine  field  CAB$B_TRM  to  get  the   terminator
             character for the qualifier field.  He can then test
             this character to see if it  is  a  ":"  or  "="  to
             determine  whether  or  not the user has specified a
             value associated with the qualifier.





3.7.8  Fields In The Parameter Block (PAB) -

Fields that are not programmer-initializable:

PAB$W_BLN      Size of PAB in bytes.  This word is initialized to
               PAB$K_BLN by the $PAB macro.

PAB$B_BID      Block ID for the PAB.  This field  is  initialized
               to PAB$K_BID by the $PAB macro.  The value of this
               constant should be assigned by the VMS group.

Common fields supplied by programmer:

PAB$A_CAB      Pointer back to associated CAB

PAB$B_TYP      Field  type.   <This  field  corresponds  to   the
               .CMFNP(CM%FNC)     field     in     the    TOPS-20
               implementation.> For example, this field would  be
               set to HLP$K_KEYWORD if a keyword is to be parsed.
               This field would  be  set  to  HLP$K_NUMBER  if  a
               number  is  to be parsed.  A complete set of valid
               field types is given elsewhere in this document.

PAB$L_ARG      Function-specific    argument.     <This     field
               corresponds  to  the  .CMFNP(CM%DAT)  field in the
               TOPS-20 implementation.> Many field types take  an
               additional  argument.   For  example, if the field
               type were HLP$K_KEYWORD, then this argument  would
               be   the   address  of  the  LIB$LOOKUP_KEY  table
               specifying the list of  valid  keywords.   If  the
               field  type  were HLP$K_NUMBER, then this argument
               would be the radix of the  numeric  string  to  be
               parsed.   If the field type were HLP$K_INPUT_FILE,
               then this argument would be the address of  a  FAB
               specifying  details  about  the file-specification
               wanted (such as what is the default name  and  the
               related name, if any).  A complete list of all the
               different kinds of  field  types  and  what  their
               associated   function-specific  arguments  are  is
               given elsewhere in this document.
                                                                         Page 36


PAB$A_DEF      Address of descriptor for  default  string.   A  0
               longword    indicates    that    there    is    no
               program-supplied default for  this  field.   <This
               field  corresponds  to  the  .CMDEF  field  in the
               TOPS-20 implementation.  There is no necessity for
               a  bit  corresponding to the CM%DPP bit, since the
               presence  of  a  non-0  longword  in  this   field
               specifies that a default string is provided.> This
               string is the string that  is  recognized  if  the
               user  types  <RECOGNIZE>  at  the  beginning  of a
               field.

               Note that <RECOGNIZE>  works  differently  at  the
               beginning  of  a  field  than  in  the middle of a
               field.  For example, if a program  specifies  that
               the default string for a certain filespecification
               field  is  PROG.GLK,  then  if  the   user   types
               <RECOGNIZE>   at  the  beginning  of  that  field,
               "PROG.GLK" will be  recognized.   However,  if  he
               then  types  P followed by <RECOGNIZE>, the system
               would beep at him if he had more than one file  in
               his  area  beginning with the letter "P".  Another
               example:  suppose the default width value  to  the
               /WIDTH=  qualifier in some command were the string
               "80".  If the user typed  <RECOGNIZE>  immediately
               after  the "=", then "80" would be recognized, but
               if he typed "8" and then <RECOGNIZE>, "8" would be
               recognized  as a valid number and the system would
               type a space and go on to the next field.

               The default  string,  if  selected  by  the  above
               mechanism,  is  still  subject  to a syntax check.
               Thus, it is considered a  programming  bug,  if  a
               programmer   specifies   a  syntactically  invalid
               string as the default string for some field.  When
               a  user then types <RECOGNIZE> at the beginning of
               such a field, the faulty default will be displayed
               immediately   followed   by   an   error  message.
               Normally this is not a problem, but  could  happen
               in cases where a program is trying to be fancy and
               peform dynamic  field  defaulting.   For  example,
               suppose  the EDIT command is written to "remember"
               the  filespecification  given  to  it   from   one
               invocation  to  the  next.   If a user types "EDIT
               SRC:FOO.MAC" and then  shortly  later  types  just
               "EDIT",   DCL  could  (if  desired)  remember  the
               previous string "SRC:FOO.MAC" and  specify  it  as
               the   default   string   in  subsequent  calls  to
               LIB$PARSE_FIELD for  this  particular  field.   If
               between one edit and the next, the user deassigned
               the logical name "SRC", then  the  default  string
               would  no longer be syntactically valid.  I do not
               consider  this  to  be   a   problem,   but   this
                                                                         Page 37


               possibility should be noted.

PAB$A_PMT      Address of descriptor for (sub) prompt string.  If
               this  is  omitted, then this means that the system
               should not prompt for this parameter.   Note  that
               some  utilities  like  to prompt for arguments and
               some do not.  For example, NCP prompts for certain
               missing  arguments,  but PHONE does not prompt for
               missing arguments.

PAB$A_GDW      Address of descriptor  for  guideword.   The  $PAB
               macro normally defaults this to be the same as the
               prompt string.  Specifying  an  explicit  0  means
               that  this field has no guideword.  By convention,
               guidewords are used to turn a computerese  command
               into a command that more-closely resembles a valid
               English sentence.  For example, the DEFINE command
               could be set up to have the syntax

               $ DEFINE (LOGICAL NAME) name (TO BE EQUIVALENT TO)
               string

               if desired.  The prompt for the  second  parameter
               could remain "equivalence-name".

               Another example:

               $ SYNCHRONIZE (WITH JOB) name

               reads better than

               $ SYNCHRONIZE (JOB-NAME) name

               In many cases, however, the guideword would be the
               same as the prompt string.

PAB$A_VBF      Address of descriptor to receive  a  string-valued
               result  of  the parse of this field.  For example,
               if the field type were  HLP$K_FILESPEC,  then  the
               expanded  name  string  gets returned through this
               field.  If the field type  is  HLP$K_KEYWORD,  the
               full  keyword  string  gets returned throught this
               field.

Obscure fields that can be supplied by programmer:

PAB$A_NXT      Address of next PAB in chain.   This  is  used  to
               specify   alternatives.    For  example,  the  USE
               command  in  SYSGEN  allows  a  keyword   (ACTIVE,
               DEFAULT)  or  a  filespecification.   <This  field
               corresponds to the  .CMFNP(CM%LST)  field  in  the
               TOPS-20  implementation.>  When  <HELP>  is typed,
               help  about  each  one  of  the  alternatives   is
                                                                         Page 38


               displayed,  in  order.  When <RECOGNIZE> is typed,
               we attempt to perform recognition one  alternative
               at a time and proceed to the next alternative only
               if there  is  no  possible  match  for  the  first
               alternative.    A   partial   completion  prevents
               seeking   alternatives.    For   example,   typing
               <RECOGNIZE> after

               $ DIR

               to DCL will recognize the characters "ECTORY" even
               though the command could legally have been

               $ DIR="ABC"

               or

               $ DIR:  ALLOCATE MTA2:

               We do not beep at the  user  because,  presumably,
               DCL will list the keyword alternative prior to the
               assignment   statement   alternative   and   label
               alternative  when setting up its PAB chain for the
               first field.

PAB$V_SPO      Syntax parse only.  There  are  some  cases  where
               programs  do  not want to check the validity of an
               entity, but only check that  it  is  syntactically
               correct.  For example, the command

               $ SET DEFAULT XYZ:[ABC]

               is perfectly legal to DCL even though there may be
               no  device  called XYZ currently on the system.  A
               similar  situation  exists   with   the   /DEVICE=
               qualifier to AUTHORIZE.  In such cases, the system
               only   checks   that   the   item   specified   is
               syntactically  correct.   <This bit corresponds to
               the CM%PO bit in the TOPS-20 implementation.>

PAB$V_SDH      Suppress  default   help   text.    A   programmer
               specifying  his own help text can either add to or
               replace the  system's  default  text.   <This  bit
               corresponds  to  the  CM%SDH  bit  in  the TOPS-20
               implementation.>

PAB$V_NOS      Field may not be preceded by spaces.  If this  bit
               is not set, then it is presumed that the parameter
               may be preceded by  any  number  of  spaces.   For
               example,  the  /DEVICE=  qualifier on the username
               prompt  to  LOGINOUT  permits  a  device   and   a
               directory  specification.   Either is optional and
               would probably be coded by two successive calls to
                                                                         Page 39


               LIB$PARSE_FIELD;   however  no  space is permitted
               between these two fields.

PAB$A_HLP      Address of descriptor for programmer's help  text.
               This  longword  can  be  0  if  the program is not
               supplying its own help text.  In  that  case,  the
               system's    default    help   text   is   produced
               exclusively.   <This  field  corresponds  to   the
               .CMHLP  field  in  the TOPS-20 implementation.  No
               bit corresponding to the CM%HPP bit  is  necessary
               because   the  presence  of  a  0  in  this  field
               specifies that there is no  program-specific  help
               text for this field.>

PAB$A_HLP_RTN  Address of programmer's routine to  be  called  to
               supply  help.   This  can  be used by a programmer
               that wants to perform a non-standard form of  help
               or  is  parsing  a type of field not understood by
               the supplied help routines.  This field is  needed
               by  DECset  to allow for supplying help for DECset
               specific  fields  such  as  document   names   and
               database names.

PAB$A_REC_RTN  Address of programmer's routine to  be  called  to
               perform  recognition.   This  can  be  used  by  a
               programmer that wants to  perform  a  non-standard
               form  of recognition while parsing a type of field
               not  understood  by   the   supplied   recognition
               routines.  This field is needed by DECset to allow
               for performing  recognition  for  DECset  specific
               fields such as document names and database names.

PAB$Q_BRK      Terminator break mask quadword (not fully designed
               yet).  <This field corresponds to the .CMBRK field
               in the TOPS-20 implementation.>

PAB$L_CTX      Programmer context longword.  The  programmer  may
               put  anything  he  wants in this longword.  When a
               programmer has multiple alternatives for  a  given
               field  and  links  together several PABs, he finds
               out which PAB actually matched  by  examining  the
               CAB$A_CURPAB  field in the CAB.  He can then index
               into this PAB to  retrieve  his  context  longword
               which  is  probably  more  useful  to him than the
               address of the  matching  PAB.   If  a  programmer
               wants more than a longword of context, he can fill
               this field in with a pointer to his context block.

PAB$A_ERR      Address of routine to be  called  if  there  is  a
               syntax  error  encountered  in the parsing of this
               field.   If  there  are  alternative  PABs  linked
               together,  this  routine is only called if all the
               alternatives  fail.   In  that  case,  the   error
                                                                         Page 40


               routines are called in reverse order, that is, the
               one in the last PAB in the chain is called  first.
               Reserved for future use.

PAB$A_SUC      Address of routine to  be  called  if  this  field
               parses successfully.  Reserved for future use.

PAB$L_STS      Error status.  If  an  RMS  error  occurred,  this
               field  is  set  to the RMS status code.  Otherwise
               this field is set to 0.  This field is  useful  to
               programmers  that want to give more complete error
               messages than the standard error messages returned
               by the recognition package.

PAB$L_STV      Error status value.  If  an  RMS  error  occurred,
               this  field  is  set  to  the  RMS  status  value.
               Otherwise this field is set to 0.  This  field  is
               useful  to  programmers  that  want  to  give more
               complete error messages than  the  standard  error
               messages returned by the recognition package.

Fields returned to the programmer:

PAB$W_VLN      Number of characters returned in the  string-value
               buffer   (specified  by  PAB$A_VBF)  not  counting
               padding in the  case  of  a  fixed  length  string
               descriptor.

PAB$L_VAL      Longword value returned  by  a  successful  parse.
               For  example,  if  the field type is HLP$K_NUMBER,
               then the number parsed  is  left  in  this  field.
               (The ATOM buffer gets the string representation of
               the number as actually entered by  the  user.)  If
               the  field  type is HLP$K_KEYWORD, the longword in
               the programmer's LIB$LOOKUP_KEY  table  associated
               with  the  keyword  that  matched  is left in this
               field.

Fields reserved for future use:

PAB$A_FLINK    Reserved for future use (link to next PAB).   This
               could  be  used  if  we  ever  want  to  allow the
               programmer to describe  his  entire  command  line
               with  one  linked  chain of PABs rather than parse
               the fields one at a time.

PAB$A_BLINK    Reserved for future use  (back  link  to  previous
               PAB).

The following 5 fields were rejected as not being necessary in an
earlier  design  review,  they  are  included  here so that other
reviewers will not wonder why it seems that little provision  has
been made for comma lists.  It was felt that the programmer could
                                                                         Page 41


chain his PABs and loop his code in such a manner  as  to  handle
comma  lists  himself  without  the  need  to  have  them handled
automatically by the recognition package.

PAB$V_SEQ      (Reserved for  future  use)  Field  to  be  parsed
               actually  consists  of  a  sequence of fields, all
               alike.  This would be a  convenience  when  it  is
               necessary  to parse off a comma-list of filespecs,
               for example.  It would be easier to set  this  bit
               than  to  write  code  to loop and make successive
               calls to LIB$PARSE_FIELD.   This  concept  is  not
               fully designed yet.

PAB$V_CMA      (Comma list) This bit only has significance if the
               PAB$V_SEQ  bit  is  set.   This bit means that the
               successive copies of the field must  be  separated
               from  each other by commas.  Spaces may optionally
               precede and  follow  the  commas.   (Reserved  for
               future use)

PAB$V_PLS      (Plus list) This bit only has significance if  the
               PAB$V_SEQ  bit  is  set.   This bit means that the
               successive copies of the field must  be  separated
               from   each  other  by  plus  signs.   Spaces  may
               optionally precede  and  follow  the  plus  signs.
               This bit may be combined with the PAB$V_CMA bit to
               mean that the fields may be separated by commas or
               plus  signs.  This is useful when parsing filespec
               lists that allow commas or plus signs to  separate
               them.  (Reserved for future use)

PAB$A_SEQ      (reserved for future use)  Action  routine  to  be
               called each time a field that is one of a sequence
               of  fields  is   found.    This   bit   only   has
               significance  if  the  PAB$V_SEQ  bit is set.  The
               action routine is called with  3  arguments.   The
               first  argument  is  the  address of the PAB.  The
               second argument is a programmer-supplied longword,
               located  at  PAB$L_SEQ_CTX.  The third argument is
               some sort  of  indicator  specifying  whether  the
               field  was  terminated  by a comma or a plus sign.
               This is not adequately designed yet.

PAB$L_SEQ_CTX  Value passed to the action  routine  specified  at
               PAB$A_SEQ, if any.  (reserved for future use)
                                                                         Page 42


3.7.9  Format Of Generalized LIB$LOOKUP_KEYWORD Table. -

For improved efficiency, and more functionality,  the  format  of
the  standard LIB$LOOKUP_KEY table is being extended in an upward
compatible manner.  Anywhere that this spec refers to  a  keyword
table,  the programmer may supply the old format (LIB$LOOKUP_KEY)
table, or the  new  format  table.   It  is  expected  that  many
existing   programs   already  contain  extensive  LIB$LOOKUP_KEY
tables, and the code has been written so that these programs need
not modify those tables.  <The additional functionality needed is
that functionality provided  by  the  TOPS-20  command  table  as
documented  by  the  TBLUK  JSYS,  as further supplemented by the
COMND JSYS.>

Table lookup service is also provided by a  new  routine,  called
LIB$LOOKUP_KEYWORD.   This  routine is upward compatible with the
standard LIB$LOOKUP_KEY RTL routine, and in  fact  could  replace
that  routine if desired;  however, I have temporarily given it a
different name, should we want to  keep  the  routines  separate.
The calling sequence is exactly the same.

Under the new scheme, the high-order bit of the first longword in
the  keyword  table  determines  whether  the  keyword table is a
generalized keyword table or an old-style keyword table.  If this
bit  is  on,  then the structure is a generalized structure.  The
main structural difference in the  new-format  structure  is  the
addition  of  a single new longword as the second longword in the
structure, containing various flag bits.  There  is  also  a  new
structure  associated with each keyword (see below).  This scheme
should provide no incompatibilities for programmers, since it  is
extremely unlikely that any user program has a keyword table with
2**31 longwords in it.

The format of the generalized keyword table thus looks like:

*********************************
*1*                 max-size    *
*********************************
*   flags       *   cur-size    *
*********************************
*          ptr                  *
*********************************
*          value                *
*********************************
*          ptr                  *
*********************************
*          value                *
*********************************
*          ptr                  *
*********************************
*          value                *
*********************************
                                                                         Page 43


      .
      .
      .

*********************************
*          ptr                  *
*********************************
*          value                *
*********************************

The main body of the table still  contains  pairs  of  longwords;
the  first  longword being a pointer to a counted string, and the
second longword being a value that  is  to  be  returned  to  the
programmer  if  that string is the one that matches.  This value,
however, is the address  of  a  structure  called  the  KIT  (the
keyword item table).

The main addition is a new set of flags that can be specified  by
the programmer.  These flags are described below:

KWD$V_ORDERED  If this bit is on, it means that the  keywords  in
               the  table  are in alphabetical order.  If we know
               that this is true, it can significantly  speed  up
               the  performance  for  keyword  recognition  (when
               there are a large number of entries).  To aid  the
               programmer in getting his entries alphabetical (if
               he is dynamically building his keyword table), two
               routines  are provided:  LIB$KEYWORD_TABLE_ADD and
               LIB$KEYWORD_TABLE_DELETE.   <These  correspond  to
               TBADD  and  TBDEL  in the TOPS-20 implementation.>
               One allows you to add a new entry and  one  allows
               you  to  delete an entry.  Two lengths are kept at
               the beginning of the table, the maximum  size  and
               the  current  size.   There  are also two routines
               provided,      LIB$ALLOCATE_KEYWORD_TABLE      and
               LIB$DEALLOCATE_KEYWORD_TABLE that let you allocate
               and deallocate a keyword table dynamically at  run
               time from virtual memory.

KWD$V_CASE     If this bit is off (the default),  it  means  that
               the source string (the one the programmer supplies
               as his first argument) is to be logically up-cased
               before  performing the match.  (We don't upcase it
               in place.) Presumably, the keywords pointed to  by
               the  table  are all in upper case.  If this bit is
               on,  this  means  that  the  programmers   command
               language  contains  case  sensitive  keywords.  In
               that case an exact match must  occur  bewteen  the
               supplied  keyword  and  the entries in the keyword
               table, and lower case does not match upper case.

KWD$B_MAX      A byte field specifying that there is a  limit  on
               the  number of characters that need match.  A 0 in
                                                                         Page 44


               this field is  the  default  and  means  that  all
               characters  must  match.  This field is needed for
               DCL.  DCL has the property that you can type extra
               characters  after  the  first four characters in a
               command keyword and it will not complain (i.e.

                          SET PROCEDURE/PRIVATE=GROUND

               is treated as a valid command to DCL with no error
               message given.  It is equivalent to

                          SET PROCESS/PRIVILEGE=GROUP

               since all the keywords agree up  to  the  first  4
               characters.)   Personally,  I  feel  that  such  a
               command should give an error message, but that  is
               the  way  DCL  is  documented to work;  so if they
               don't want to change it, we need this field.   DCL
               would  set this field to a 4 to indicate that only
               the first 4 characters must match.

The pointer in the first longword of each pair of  table  entries
now  points  to  a  string  descriptor  rather  than to a counted
string.

The second longword in each pair  of  entries  now  points  to  a
structure called the KIT (Keyword Item Table).

The fields within the KIT are described below.

KIT$L_VAL      The value longword.  This is guaranteed to be  the
               first longword in the KIT.  This value is supplied
               by the user and corresponds to the value  that  he
               used  to  place in the keyword table as the second
               longword of each entry pair.

KIT$V_INV      The  keyword  is  to  be  invisible.   <This   bit
               corresponds  to  the  CM%INV  bit  in  the TOPS-20
               implementation.> This bit would be set if you want
               to  hide a keyword so that it does not appear when
               you type the <HELP> key.  This could  be  used  to
               hide  debugging  keywords  from  users.   The more
               common use for this bit is to suppress the listing
               of  obsolete  keywords  from  the incremental help
               message.   For  example,  in  the   SET   TERMINAL
               command,  the  qualifier /VT52 has been superseded
               by the qualifier  /DEVICE_TYPE=VT52.   By  setting
               this  bit for the /VT52 keyword, it would still be
               accepted by the parser, but the user would not  be
               shown this keyword when he typed <HELP>.  This bit
               is used entirely by LIB$PARSE_FIELD and is ignored
               by LIB$PARSE_LOOKUP_KEY.
                                                                         Page 45


KIT$A_ABV      If non-0, this keyword  is  to  be  considered  an
               abbreviation for another keyword in the table (the
               value of this field is the  address  of  a  string
               descriptor  for  the keyword that this entry is an
               abbreviation of.) <This  bit  corresponds  to  the
               CM%ABR  bit  in  the TOPS-20 implementation.> This
               bit allows you to override  the  otherwise  normal
               command   abbreviation  rule.   For  example,  DCL
               allows the R command to be an abbreviation for RUN
               and typing R means RUN even though there are other
               valid DCL commands beginning with  the  letter  R.
               To  make  this  happen,  you would specify in this
               field that R is really an  abbreviation  for  RUN.
               Another  example  is the debugger which allows "E"
               to be a  valid  abbreviation  for  "EXAMINE"  even
               though  "E"  conflicts  with  the  "EXIT" command.
               Similarly, "SE"  in  MAIL  means  "SEND"  and  not
               "SEARCH".

KIT$V_NOR      (No recognize).  Do not  recognize  this  keyword.
               If  an  exact  match  on  this  keyword  is found,
               LIB$LOOKUP_KEYWORD   will   still    return    the
               LIB$_AMBKEY (ambiguous keyword) status.  <This bit
               corresponds to  the  CM%NOR  bit  in  the  TOPS-20
               implementation.>  This  is  useful  if you want to
               insist that certain dangerous keywords have to  be
               spelled  out.  Thus if you wanted the user to have
               to type "DEL" to mean  "DELETE"  even  though  "D"
               might  be  perfectly  unambiguous to your program,
               you would enter the two keywords "D" and "DE" into
               your keyword table with this bit set.

KIT$V_NEG      Keyword  is  negatable.   The  negation  is   also
               entered  elsewhere  in  the  table  in  its normal
               alphabetical  position  (with  the  KIT$V_NOT  bit
               set).   If the <HELP> key is typed when you are at
               the beginning of the keyword field,  this  bit  is
               used  to  enable  the  help message to combine the
               keyword   and   its   negation   in   the   format
               "[NO]KEYWORD"  in  the  incremental  help display.
               This bit is ignored by LIB$LOOKUP_KEYWORD and used
               only  by  LIB$PARSE_FIELD.  Since efficiency calls
               for the  keywords  to  be  entered  in  the  table
               alphabetically,  this  scheme permits keywords and
               their negations to appear together rather than far
               apart.  This is a hack, pure and simple.

KIT$V_NOT      This keyword is the negation of some other keyword
               in  the  table.   The  negation  must  be  entered
               separately   and   in   alphabetical   order   for
               efficiency  reasons (even though it may be alluded
               to be an earlier  entry  with  the  KIT$V_NEG  bit
               set).
                                                                         Page 46


KIT$V_VAL      The keyword takes a  value.   The  user  enters  a
               value  by  specifying  a colon or equal sign after
               the keyword, followed by the  value.   It  is  the
               programmers responsibility to code additional PABs
               to handle the parsing of the keyword value.   This
               bit  just  tells  the  recognition  package that a
               value is legal so that it can display  an  "="  at
               the  end  of  the  keyword in the incremental help
               text.  An example of a keyword that takes a  value
               is the DCL command

                                 SET CONTROL=T

               where the keyword  parameter  "CONTROL"  takes  an
               otpional  value  of  either  "T"  or  "Y".  A more
               frequent use of this field occurs with  qualifiers
               that take values.

KIT$V_REQ      The keyword takes a required value.  Must  be  set
               in  addition  to  the KIB$V_VAL bit.  Reserved for
               future use.

KIT$A_PFX      The address of a counted string for  the  negation
               prefix.   If 0, the standard negation prefix, "NO"
               is  assumed.   This  field  is  ignored   if   the
               KIT$V_NEG bit is not set.  This field is needed by
               DECset for the commands

               DECset> SET COMMAND/[NON]STANDARD

               and

               DECset> PURGE database/[NOT]NOW

               and

               CUSTOM> SHOW parameter/[UN]SCALED

               and could be used by  DCL  in  a  few  places,  if
               desired,  such as the /NOSTANDARD qualifier to the
               PASCAL   command   could   be   changed   to   (or
               supplemented  by)  /NONSTANDARD  which  is  a real
               word.

KIT$A_EXPL     Reserved for use by DECset.  Address of  a  string
               descriptor  containing an explanation of what this
               keyword  means.    DECset   maintains   its   help
               information  about  commands  with  the  commands,
               rather than in a separate help library  which  can
               become  obsolete  when  the commands change or new
               commands get added.

KIB$B_MIN      Minimum number of characters that must match.   If
                                                                         Page 47


               this field is non-0, then this keyword will not be
               matched unless this minimum number  of  characters
               is  found  correctly.  For example, in DCL, if you
               define    a    symbol     with     the     command
               FOO*BAR="TESTING",  then  this means that you have
               created a new symbol FOOBAR and  the  first  three
               characters,  "FOO"  must  match before the keyword
               FOOBAR is found, even though typing one character,
               F,  might  be  enough  to  uniquely  identify this
               keyword.

KIT$B_MAX      If this field is non-0, it overrides the KWD$B_MAX
               field (if there was one) in the keyword table.  It
               specifies the maximum number  of  characters  that
               need  be  checked  for this keyword to be a match.
               All additional characters are  not  checked.   The
               reason  to  have this override is in case you want
               to merge two sets of keywords into one table,  and
               some   are  the  kind  that  want  to  ignore  all
               characters  after  4,  say,  and  some  want   all
               characters  checked.   This  would  be useful, for
               example, if DCL wanted to  merge  it's  verbs  and
               it's  user-defined  symbols into one large keyword
               table instead of two.




3.7.10  Service Routines -

The following routines  are  available  to  programmers  who  are
writing their own help and recognition routines:

     1.  LIB$COLLECT_INIT

     2.  LIB$COLLECT_STORE

     3.  LIB$COLLECT_ABORT

     4.  LIB$COLLECT_OUTPUT


These routines form a sub-package known as "the collector".  They
are  used  to  collect  recognized  characters  and  decide which
characters are common to all  the  strings  recognized.   Calling
sequences  for these routines can be found in the routine headers
of module LIB$COLLECT in file HLPCOLECT.B32.

DECset will use this interface to handle recognition of  database
names and document names.  DCL might use this interface to handle
recognition  of  DCL  symbols.   The  debugger  might  use   this
interface  to  do  recognition  of  user  symbols, since they are
currently hashed and it would not be convenient to put them  into
                                                                         Page 48


the LIB$LOOKUP_KEY table format.



3.7.11  Problems -


     1.  Quoted string problem.   For  example,  DCL  allows  the
         command

         $ MAIL FOO.BAR "STAN"

         yet the STAN field should permit help and recognition as
         a  username  field  not  as  a  quoted  string field.  I
         probably need a new bit to say that an otherwise  normal
         entity is permitted to be enclosed in double quotes.

     2.  Too many keywords problem.  Some commands will  take  an
         inordinate  number  of  keywords,  such  as the debugger
         which could have thousands of choices for certain fields
         (when  a  user symbol is permitted).  We do not want all
         these choices listed when he types "?".  Do we  suppress
         the  list  of choices when there are more than n?  Do we
         let the user customize this?  Do we pick another key  to
         mean "give me lots of help"?

     3.  Many users have suggested to me that "?" when typed to a
         filespec  should actually list all the choices.  The way
         the code is written, this is actually easy to do, but  I
         didn't  do  it  because  of  the  above  problem  - that
         frequently  there  are  too   many   choices   to   list
         conveniently.  Comments?

     4.  Foreign language customization.   Most  of  my  messages
         come  from  message  files  or are specified by the user
         program.  However there are 3 or 4 messages  built  into
         the  program, such as the message "one of the following"
         and the word "or".  This will not be good when we  allow
         switching  to a foreign language, like French.  However,
         I don't relish all the  extra  overhead  that  would  be
         involved  if I had to pick up the "one of the following"
         message from a message file each time a user  typed  "?"
         so I didn't code it that way.  Ideas?

     5.  Terminal driver problem.   The  terminal  driver  change
         that  we  requested did not get into V3A.  It appears to
         be in FT1 of V4, so the current  inefficiencies  can  be
         fixed for V4.

     6.  RMS BUGS.  RMS currently provides no clean way to  abort
         a  long  file operation.  If a user attempts recognition
         of a filespec with  wildcards  in  a  directory  and  it
         starts  taking  too  long  and he types CTRL/C, the only
                                                                         Page 49


         documented way of cleaning up is  to  have  a  condition
         handler  that reacts to an unwind and tries to close any
         open FABS, but it might  get  "file  activity  precludes
         operation" errors.  If it waits for the file activity to
         finish, then the system is not  properly  responding  to
         CTRL/C  (the user should not have to wait 60 seconds for
         his $ prompt to  come  back  after  a  CTRL/C).   If  it
         doesn't wait for the FAB to free up, but resignals, then
         the code could be entered again before the FAB  is  free
         and screw up on the user's next recognition request.

     7.  Simple Interface and ASTs.  I do not see an easy way  to
         make   the   simple   programmer  interface  scheme  AST
         re-entrant.  It builds a CAB and PAB behind  the  user's
         back  and LIB$PARSE_FIELD reaches into this area (in OWN
         storage) instead of us telling the user he has  to  pass
         the  address  of  a  CAB,  which  he has never heard of.
         Another call to LIB$PARSE_INPUT  from  AST  level  would
         wipe  out  the  main-line's  CAB.  The general interface
         does not have this problem because the CAB is passed  as
         an explicit argument on each call.

     8.  ?  to HELP.  For VMS V3A, the VMS  group  used  the  "?"
         character   in   the  HELP  command  to  mean  something
         different (although similar) from what it would mean  if
         DCL were to use this recognition package.  (((I spoke to
         Halvorsen about this, suggesting that the "?"  character
         in  HELP  be changed to something else and he assured me
         that there would be no problem changing its  meaning  to
         "incremental  help"  should  DCL be modified to use this
         recognition package.)))

     9.  Filetype search chains.  Some  commands  allow  multiple
         filetypes  in  a  parameter  field.   For  example,  the
         command BLISS FOO will first  look  for  a  file  called
         FOO.B32 to compile, and if it doesn't find it, will then
         look  for  a  file  call  FOO.BLI   to   compile.    The
         recognition  package  only  lets you specify one default
         file string in the call to parse a filename, so in  this
         case,   ".B32"   would   probably  be  specified.   Thus
         filenames with the .BLI file type would  be  legal,  but
         would not be recognized when the user types <RECOGNIZE>.
         If there are going to be a lot of cases like this,  then
         we  might  want  to  design something in to allow search
         chains of some sort.  It may be able to  use  V4  search
         lists to implement this feature.

    10.  Centralized  Filespec  parsing.   The  VMS   group   has
         (rightly) requested that all filespec parsing be done in
         one centralized spot  (such  as  in  RMS).   This  would
         prevent  user  programs  from having to change in future
         releases of VMS as extensions are made to the syntax  of
         a  filespecification.  The recognition package currently
                                                                         Page 50


         has to know what a filespec looks like because there are
         no  routines  provided  by RMS or VMS that allows a user
         program to analyze partial filespecifications.




4.0  COMPATIBILITY

There should be a minimum adjustment period for users who migrate
from  -20's  to  VAX'es  since  the  user-level interface is very
similar.



5.0  PACKAGING AND SYSTEM GENERATION

Certain macros and structure declarations should be  included  in
STARLET.   If  the  VMS group prefers, these definitions could be
supplied in a completely separate library.

The code does not have to be linked with SYS.STB.



6.0  DOCUMENTATION

This functional specification plus the routine  headers  for  all
the  routines in the package provides all the documentation about
the recognition package that will be turned over to the RTL group
when this package is submitted to them.




7.0  REFERENCES

TOPS-20 Monitor Calls Reference Manual, AA-4166D-TM.