environment at  the  reparse  point.    If  this   value   is
           non-NULL,   then  if  a  reparse  is  required,  a  longjmp()
           operation is performed using this setjmp buffer.

         o CSB_INP is the address  of  the  input-character  routine  to
           use.   If this value is non-NULL, then this routine is called
           to get each character of input.  No line editing  or  special
           interactive  characters are recognized in this mode, since it
           is assumed that this will be  used  for  file  input.    Note




           especially:   this  facility  is not yet implemented, however
           the definition is provided for future expansion.  Thou  shalt
           always leave this NULL, or write the facility thyself.

         o  CSB_OUT is the inverse correspondent to the previous element
           (CSB_INP).  It is the address of a routine to process  output
           from the  command  library.    Please  see the warning in the
           CSB_INP description about not being implemented.

         o CSB_PMT is the address  of  the  prompt  string  to  use  for
           command parsing.      The   command  library  takes  care  of
           prompting, so make sure this is filled in.

         o CSB_BUF is the address of the buffer to put user  input  into
           as s/he is typing it in.

         o  CSB_BSZ,  an int, is the number of bytes which can be stored
           in CSB_BUF;  i.e., it is the buffer size.

         o CSB_ABF is the address of an atom buffer.  Some (if not  all)
           parsing   functions   involve   extracting   some  number  of
           characters from the input buffer and interpreting  or  simply
           returning this  extracted  string.   This buffer is necessary
           for those operations.  It should probably be as large as  the
           input buffer (CSB_BUF), but it is really up to you.

         o  CSB_ASZ,  an  int,  is the number of characters which can be
           stored in CSB_ABF;  i.e., it is the size of that buffer.

           ** Note ** CSB elements from here to the end do not  have  to
           be initialized  by  the  calling  program.   They are used to
           store state information and are initialized  as  required  by
           the library.

         o CSB_PRS,  an  int,  contains  the  parse  index.  This is the
           point in the command buffer up  to  which  parsing  has  been
           achieved.

         o  CSB_FLN,  an  int,  is  the  filled  length  of  the command
           buffer.  This is the number of  characters  which  have  been
           typed by the user.

         o CSB_RCD,  an int, is a result code of the parse.  This is the
           same value which is returned as the  result  of  the  COMND()
           procedure call.

         o  CSB_RVL is a union which is used to contain either an int or
           an address value.  The  names  of  the  union  elements  are:
           _INT  for  int, _ADR for address (note that a typecast should
           be used  for  proper  address  assignment).    This   element
           contains  a  value  returned  from some parse functions which
           return values which are single values.  For  example,  if  an




           integer is parsed, its value is returned here.

         o  CSB_CFB is the address of a command function block for which
           a parse was successful.  This is significant in  cases  where
           there  are  alternative  possible interpretations of the next
           command line field.




        The parse of each element in a command line  involves,  as  well
        as  the  Command  State Block just described, a Command Function
        Block which identifies the sort of thing to  be  parsed.    This
        block  is  defined  in  a  structure  named  "CFBs", which has a
        corresponding typedef named "CFB".  Elements of the  CFB,  named
        "CFB_xxx",  are  as  follows  (in  the  order they appear in the
        structure):



         o CFB_FNC, a BYTE, is the function  code.    This  defines  the
           function to  be  performed.    The function codes are listed,
           and their actions described, a little later.

         o CFB_FLG, a BYTE, contains flags which  the  caller  specifies
           to the  library.    These  are  very significant, and in most
           cases affect the presentation to the user.    The  flag  bits
           are:


            o _CFHPP:    A  help  string has been supplied and should be
              given when the user types the help character ("?").

            o _CFDPP:  A default string has been supplied, and shall  be
              used  if  the  user  does  not type anything at this point
              (typing  nothing  means  typing  a  return  or  requesting
              command completion).     Note  that  this  flag  (and  the
              default string) is ONLY significant for the CFB passed  in
              the  call  to  the COMND() routine, and not for any others
              referenced as alternatives by  that  CFB.    Note  further
              that  a  default  specified by the first CFB is applied to
              the input stream, and not to the parsing function.    That
              means  that  the  default  is subject to interpretation by
              alternate CFBs, and in fact, does  not  even  have  to  be
              appropriate for the CFB which contains it.

            o _CFSDH:    The default help message should be supressed if
              the user  types  the  help  character  ("?").    This   is
              normally   used  in  conjunction  with  the  _CFHPP  flag.
              However, if this flag is present and  the  _CFHPP  is  not
              selected,  then  the  help operation is inhibited, and the
              help character becomes insignificant (just like any  other




              character).

            o _CFCC:      A  character  characteristic  table  has  been
              provided.  A CC table identifies which characters  may  be
              part of  the  element being recognized.  Not all functions
              support this table (for example, it does  not  make  sense
              to   re-specify   which  characters  may  compose  decimal
              numbers).  This table also specifies which characters  are
              break  characters,  causing  the  parser  to "wake up" the
              calling program when one of them is typed.   If  this  bit
              is  not  set  (as is usually the case), a default table is
              associated according to the function code.

            o _CFDTD:  For parsing date and  time,  specifies  that  the
              date should be parsed.

            o _CFDTT:    For  parsing  date and time, specifies that the
              time should be parsed.


         o CFB_CFB is the address of another CFB which  may  be  invoked
           if the  user  input  does  not satisfy this CFB.  CFBs may be
           chained in this manner at will.    Recognize,  however,  that
           the  ORDER  of the chain plays an important part in how input
           is handled, particularly in disambiguation of  input.    Note
           also  that  only  the  first  CFB  of  the  chain is used for
           specifying  a  default  string  and  CC  table  for   command
           wake-up.

           CFB  chaining  is  a very important part of parsing with this
           library.

         o CFB_DAT is defined as a long, since it  is  used  to  contain
           address or   int   values.    It  should  be  referenced  via
           typecast.  It is  not  defined  as  a  union  because  it  is
           inconvenient  or  impossible  to initialize unions at compile
           time with most (all?)  C  compilers,  and  initialization  of
           these blocks  at  compile  time  is  very  desirable.    This
           element contains data used in  parsing  of  a  field  in  the
           command line.    For  instance,  in  parsing  an integer, the
           caller specifies the default radix of the integer here.

         o CFB_HLP is the address  of  a  caller-supplied  help  string.
           This  is  only  significant  if the flag bit _CFHPP is set in
           the CFB_FLG byte.

         o CFB_DEF is the address of a caller-supplied  default  string.
           This  is  only  significant  if the flag bit _CFDPP is set in
           the CFB_FLG byte, and only for  the  first  CFB  in  the  CFB
           chain.

         o  CFB_CC  is the address of a character characteristics table.




           This is only significant if the flag bit _CFCC is set in  the
           CFB_FLG byte.    This is the address of a 16-word table, each
           word containing 16 bits which  are  interpreted  as  8  2-bit
           characteristic entries.       The   most   significant   bits
           correspond to the lower ASCII values, etc.  The 2-bit  binary
           value has the following meaning, per character:


            o 00:    Character  may  not  be  part  of the element being
              parsed.

            o 01:  Character may be part of the element only  if  it  is
              not the first character of that element.

            o 10:  Character may be part of the element.

            o 11:      Character   may  not  be  part  of  the  element;
              furthermore, when it is typed, it  will  case  parsing  to
              begin immediately (a  wake-up  character).  Note:  wake-up
              via this mechanism is not implemented.



                Don't hesitate to use CC tables;  they only take  up  16
           bytes apiece.




             The  function  code  in  the  CFB_FC element of the command
        function block  specifies  the  operation  to  be  performed  on
        behalf of that function block.  Functions are described now.



        CFB function _CMINI:  Initialize

             Every   parse   of  a  command  line  must  begin  with  an
        initialization call.  This tells the command  library  to  reset
        its indexes,  that the user must be prompted, etc.  There may be
        NO other CFBs chained to this one, because  if  they  are,  they
        are ignored.




             The reparse  point  is the point right after this call.  If
        the setjmp method is used, then the  setjmp  environment  should
        be defined  here.    After  the reparse point, any variables etc
        which may be the  victims  of  parsing  side-effects  should  be
        initialized.



        CFB function _CMKEY:  Keyword parse

             _CMKEY parses  a  keyword  from  a given list.  The CFB_DAT
        element of the function block should point to a table of  string
        pointers, ending  with  a  NULL  pointer.  The user may type any
        unique abbreviation of a keyword,  and  may  use  completion  to
        fill out  the rest of a known match.  The address of the pointer
        to the matching string is returned in  the  CSB_RVL  element  of
        the command  state  block.    The  value is returned this way so
        that the index can be  easily  calculated,  and  because  it  is
        consistent   with   the   general   keyword   parsing  mechanism
        (_CMGSK).

             The incremental help associated  with  keyword  parsing  is
        somewhat special.    The  default  help  string is "Keyword, one
        of:" followed  by  a  list  of  keywords  which  match  anything
        already typed.    If  a help string has been supplied (indicated
        by _CFHPP) and no suppression of the default help is  specified,
        then  the  initial  part  ("Keyword,  ")  is  replaced  with the
        supplied help string and the help is otherwise the same.   If  a
        help   string  has  been  supplied  and  the  default  has  been
        supressed, then the given help string is presented unaltered.



        CFB function _CMNUM:  number

             This parses a number.  The caller supplies a radix  in  the
        CFB_DAT element  of  the  function  block.  The number parsed is
        returned (as an  int)  in  the  CSB_RVL  element  of  the  state
        block.




        CFB function _CMNOI:  guide word string