.comment
.comment	This document describes the COMMAND routines
.comment	which are used to parse RSX11M command lines.
.comment
.paper size 60,80
.left margin 8
.right margin 72
.spacing 1
.period
.center ;COMMAND
.skip
.center ;Revision Date: 1 September 80
.center ;System Version: 002
.skip 10
.autoparagraph

These routines were created under the combined influence of
the Department of Atmospheric Science at Colorado State
University and the National Center for Atmospheric Research.

Any problems or suggestions should be directed to:
.skip
.center ;Marvin Brown
.center ;NCAR
.center ;P.O.#Box 3000
.center ;Boulder, CO 80307
.skip
.center ;Phone (303)497-0681
.center ;FTS 322-7681

.chapter INTRODUCTION
.title ########INTRODUCTION
.left margin 8
.right margin 72

These routines are written to allow a user to easily
interface a FORTRAN program with the MCR command line
input routines.  This allows users control of their tasks
through command line inputs and subsequently the power
of using the indirect command line processor.

The routines consist of TECO macros which
act as a compiler on a syntax file (.SYN).
From this syntax file, COMMAND generates
a FORTRAN common block for the command
parameters (.DTB), a MACRO routine which does
the actual parsing (.MAC)
and a command file to assemble the parsing
routine and clean up the files
(.CMD).

There are also a set of MACRO-11 macros to perform
basic parameter manipulations during the parsing process.

.chapter OPERATING PROCEDURES
.title ########OPERATING PROCEDURES
.index Operation
.left margin 8
.right margin 72

.comment 1 Executing COMMAND
.test page 20
.headerlevel 1 Executing COMMAND
.subtitle ########Executing COMMAND
.index Execution
.index Compilation

The compilation of a syntax file (.SYN) consists
of two steps.  First, the syntax file must be processed
through the COMMAND routines.  This is done by executing
the MUNG option of TECO giving the macro name, COMMAND (*),
and the syntax file name.  During the execution of
the COMMAND routines, three files are generated.
They are as follows:
.footnote 5
.left margin 8
.right margin 72
.center ;* * * * *
(*)  Before COMMAND can be executed, a file entry must be created
on the UIC on which COMMAND is to be run.  This is accomplished
with the following command:

.center ;>PIP#/EN=[127,100]COMMAND.TEC
!

.list
.test page 10
.listelement Command Database (.DTB)
.index Command Database
.index DTB

This file contains FORTRAN declaration code for the
labelled common block which contains the storage locations
where the parsed values are to be stored.
This is to be compiled with the FORTRAN program
using the INCLUDE feature described in the FORTRAN
manual.   The FORTRAN routines which have these
INCLUDE statements must be compiled after the
syntax file is compiled using the MUNG command.

.test page 10
.listelement MACRO Parsing Routine (.MAC)
.index MACRO Parser
.index MAC

This file contains the MACRO routine which performs
the actual parsing.  This routine is called when ever
a new line is to be parsed.  It handles any file
manipulation and allows command files to be sent
to the task.  This routine also outputs any error messages.

.test page 10
.listelement Command File (.CMD)
.index Command File
.index CMD

This file is executed using the indirect command file
processor (AT.).  It performs two functions.  First,
it calls the MACRO assembler to assemble the
parsing routine (.MAC) linking in any standard action
routines.  Second, it uses PIP to clean up
the files which have been generated.

.endlist

So, the syntax file (.SYN) defining the syntax of the command
line is compiled with the following statements:

.left margin 24
.literal

>MUNG COMMAND,syntax file name
>@syntax file name
.end literal
.left margin 8

Where the syntax file name is just the name of a file
which has a .SYN extention.  The file selected for processing
is always the current version of the
file on the current UIC.
All output files (.DTB, .MAC and .CMD) are generated with
the same name as the syntax file on the current UIC.

.skip 2
.test page 4
.index Examples
.center ;Example
.left margin 24
.literal

>MUNG COMMAND,PROGCMD
>@PROGCMD
.end literal
.left margin 8

.comment 1 Using the Command Line Parser
.test page 20
.headerlevel 1 Using the Command Line Parser
.subtitle ########Using the Command Line Parser
.index Using Command Line Parser
.index INCLUDE
.index Default Parameters
.index EXIT

Once the Command Line Parser is generated using COMMAND,
it is integrated into a FORTRAN program.
First, an INCLUDE statement is added to each routine which
wants to use any of the command line parameters.
Next, the call to the parser should be placed in the
program.
It has the name of GETCMD and has one INTEGER*2 parameter
which is the success flag.
Any default parameter initialization is done
before the call.
After the call to the parser, a test should be made for
the success (+1) or failure of the command line parser.
This will test for the end of file condition and normally
call the EXIT routine.  Finally, the program should contain
a loop back to the default parameter initialization.

.test page 25
The following is an example of how the command line
parser might be integrated into a FORTRAN program:

.skip
.index Examples
.left margin 16
.literal
        PROGRAM DOIT
        INCLUDE 'DOITCMD.DTB'
        .
        .        other declaration statements
        .
100     .        default parameter initialization
        CALL GETCMD(IDS)
        IF(IDS .NE. 1) CALL EXIT
        .
        .        do it
        .
        GO TO 100
        END
        SUBROUTINE HELP(IT)
        INCLUDE 'DOITCMD.DTB'
        .
        .        routine that uses the command
        .        parameters
        END
.end literal
.left margin 8

.comment 1 Using the Parser
.test page 20
.headerlevel 1 Using the Parser
.subtitle ########Using the Parser
.index Using Parser

Just the parsing utility of the Command Line Parser
can be used if the syntax file (.SYN) is written as
described in the Parser Variable Section.
This allows the user to input any character string
and then parse parameters.  This is accomplished by
adding the INCLUDE statements as with the Command
Line Parser, adding the parsing routine after the
line is input and then, checking for success (+1)
or a syntax error (0).  The name for the parsing routine
is found in the syntax file after ROUTINE NAME =.
If there is a syntax error, a syntax error message
appears on TI:.

.test page 20
.center ;Sample FORTRAN Routine Using the Parser
.index Examples
.left margin 20
.skip
.literal
    SUBROUTINE PROCESS
    INCLUDE 'PARS.DTB'
    BYTE LINE(100)
    INTEGER*2 LENGTH, IDS
    .
    .        fill the character string in
    .        LINE with LENGTH characters
    .
    CALL PARS(LINE, LENGTH, IDS)
    IF(IDS .NE. 1) GO TO syntax error
    .
    .        process it
    .
    RETURN
    END
.endliteral
.left margin 8

.chapter COMMAND SYNTAX FILE FORMAT
.title ########COMMAND SYNTAX FILE FORMAT
.left margin 8
.right margin 72
.index Syntax File

The syntax file consists of four sections.  Each section 
must be terminated by a single line of code
containing a slash (_/) as the first character of the line.
The four sections are as follows:

.list
.index Parameter Definition Section
.listelement Parameter Definition Section
.index Syntax Section
.listelement Syntax Section
.index Action Routine Section
.listelement Action Routine Section
.index Parser Variable Section
.listelement Parser Variable Section
.end list

.comment 1 Parameter Definition Section
.subtitle ########Parameter Definition Section
.test page 20
.headerlevel 1 Parameter Definition Section
.index Parameter Definition Section

This section defines the storage for the
labeled common block which contains the parsed
parameters.  This section uses a subset of the standard FORTRAN
data type declarations to define the type of value and
optionally the array length.
The allowable data types are as follows:

.test page 14
.left margin 32
.index BYTE
.index INTEGER
.index REAL
.index COMPLEX
.index LOGICAL
.literal

BYTE

INTEGER*2
INTEGER*4

REAL*4
REAL*8

COMPLEX*8

LOGICAL*1
LOGICAL*2
LOGICAL*4
.end literal
.left margin 8

The number of bytes must be explicitly defined
so there is no conflict between COMMAND and any
FORTRAN compilation options.

Comments are entered by a 'C' or ';'
as the first character of a line.
Also, in this section, continuation lines are not allowed.

.skip 2
.test page 6
.center ;Examples
.left margin 32
.index Examples
.literal

BYTE      NAME(20)
INTEGER*2 NLENG, SWITCH
REAL*4    RATE
.end literal
.left margin 8

.comment 1 Syntax Section
.subtitle ########Syntax Section
.test page 20
.headerlevel 1 Syntax Section
.index Syntax Section

This section defines the form of the command line
and what actions are to be performed during the
line parsing.
The syntax is defined by a set of statements.
An statement takes the form of:

.index Syntax Statement
.skip
.index Syntax Label
.index Syntax Expression
.indent +16
label = expression

Where the label is a symbol with a maximum of
six alpha-numeric characters.

Each expression may be associated with an action routine.
This is achieved by having the expression followed
by a colon (:) and the name of the action routine
which appears in the Action Routine Section.
This passes the string that matched the expression
along with any values associated with the string
to the action routine.

Continuation of a statement is allowed if there is a plus
as the first character of the line.  There is no limit
on the number of continuation lines other than
the logical length for comprehension and the memory
limitations fo MUNG.

A colon (;) as the first character of a line or a blank
line constitute comments in the Syntax Section.

.comment 2 Syntax Expressions
.test page 20
.index Syntax Expression
.headerlevel 2 Syntax Expressions

The expression part of a syntax statement can be any of the following:

.list
.test page 6
.listelement label

References a label which has another expression associated with
it.

.test page 6
.listelement constant
.index Syntax Constant

A constant matches a given character or set of characters.

.test page 6
.listelement element
.index Syntax Element

An element is a string matching command which matches a
set of characters which conform to the individual element's
requirements.

.test page 6
.listelement expression#expression
.index Syntax Concatenation

Two expressions can be concatenated by listing them one
after another.  This requires that the string matching
the second expression immediately follows the first.

.test page 6
.listelement expression#!#expression
.index Syntax Or

Two expressions can be tested for by having a (!) between
them.  If the first expression does not match the
string, the second is tested.

.test page 6
.listelement (expression)
.index Syntax Grouping

An expression can be isolated from other operations such
as concatenation or (!) by enclosing it in parenthesis.

.test page 6
.listelement [expression]
.index Optional Expression

An optional expression is an
expression enclosed in brackets. This means that if the
expression does not match the string, then the null
string is matched.

.test page 6
.listelement [*expression]
.index Repeating Expressions


An optional expression preceded with a (*) means that
the expression may occur repeatedly or the null string
is matched.
.test page 6
.listelement [+expression]

An optional expression preceded with a (+) means that
the expression may occur repeatedly but it must
occur at least once.

.endlist

.comment 2 Syntax Constants
.test page 20
.index Syntax Constant
.headerlevel 2 Syntax Constants

A constant matches either a single character or a string
of given characters.

A single character is represented by a (') followed by a
character (eg.#'A or '?). There is a set of characters
which will not work under this form and must be handled
in a separate form.  They are the following:

.skip
.test page 5
.index Special Characters
.left margin 32
.literal
Semi-colon     <';>
Comma          <',>
.endliteral
.left margin 8

Character strings may only contain alpha-numeric characters
and are enclosed in double quotes (").

For example, "ALPHANUMERIC" is a character string.

.comment 2 Syntax Elements
.test page 25
.index Syntax Element
.headerlevel 2 Syntax Elements

A syntax element matches a set of characters which conform
to the rules of the element.  The following is the set of
legal syntax elements.

.list
.test page 5
.listelement $ANY
.index $ANY

Matches any single character.

.test page 5
.listelement $ALPHA
.index $ALPHA

Matches any single alphabetic character (A-Z).

.test page 5
.listelement $DIGIT
.index $DIGIT

Matches any single digit (0-9).

.test page 5
.listelement $LAMDA
.index $LAMDA

Matches an empty string.  This element always matches.  They are
useful for calling action routines without having to match
characters.

.test page 5
.listelement $NUMBR
.index $NUMBR

Matches an octal number.  If a string of numbers is followed
by a period, the number is interpreted as a decimal number
with the period also being matched.

.test page 5
.listelement $DNUMB
.index $DNUMB

Matches a decimal number without a decimal point.

.test page 5
.listelement $STRNG
.index $STRNG

Matches any alpha-numeric character string (0-9, A-Z).
The string will not be null.

.test page 5
.listelement $RAD50
.index $RAD50

Matches any legal RADIX-50 string, that is, any string
containing alpha-numeric characters and/or the
period (.) and dollars sign ($) characters.

.test page 5
.listelement $BLANK
.index $BLANK

Matches a string of blank and/or tab characters.

.test page 5
.listelement $EOS
.index $EOS

Matches the end of the line.

.end list

.comment 2 Internal Syntax Expressions
.test page 25
.index Internal Syntax Expression
.headerlevel 2 Internal Syntax Expressions

An internal syntax expression is similar to a syntax
element except that it matches a complex string.  It is
associated with a specific standard action.
This means that a specific standard action routine contains the
internal syntax expression and the action routine must
be invoked in the action routine section.

.list
.test page 5
.listelement FPN
.index FPN
.index RVAL

Matches a free form floating point number which conforms to
the FORTRAN syntax of a floating point number.  FPN is associated
with the standard action routine RVAL.

.test page 5
.listelement FILE
.index FILE
.index FFILE

Matches RSX11M filespecs.  FILE is associated with the
standard action routine FFILE.

.test page 5
.listelement CLRFIL
.index CLRFIL
.index FFILE

This internal syntax expression matches the null string.
It is used to clear the internal file storage which is retained
between successive FILE matches.

.end list

.comment 2 Syntax Examples
.test page 20
.index Syntax Examples
.headerlevel 2 Syntax Examples
.index Examples

.skip
.center ;Sample Syntax Section
.left margin 24
.literal

LINE  = $STRNG:SETS [*OPTS]
OPTS  = SWTCH ! RATE
SWTCH = '/ "SWITCH" '= $NUMBR:SETSW
RATE  = '/ "RATE"   '= FPN:SETR
.endliteral
.left margin 8

.comment 1 Action Routine Section
.subtitle ########Action Routine Section
.test page 20
.headerlevel 1 Action Routine Section
.index Action Routine Section

This section contains the action routines which process
the strings which are matched by the syntax expressions
in the Syntax Section.
The standard form of this section is a line defining
the standard action routines which are to be used
followed by the action routines.
The following shows the standard form of this section:

.skip
.test page 5
.left margin 16
.literal
        .MCALL  action1,action2, ... actionN
alabel: action  action parameters
        .
        .
        .
.endliteral
.left margin 8

Where action1 through actionN is a list of the
standard action routines used
in this section, alabel is the label
referenced in the Syntax Section, action is the
standard action associated with alabel and action
parameters are the parameters used by the standard
action.

.index TPARS

For users who have special requirements of the
action routines and who know how to program in
MACRO-11, specialized action routines can be coded
in MACRO-11 following the guide lines of DEC's
Table-Driven Parser (TPARS).  This is written
up in RSX-11M Version 3.2, I/O Operations
Reference Manual, Chapter 7.

Comments are the standard MACRO-11 form where anything
on a line after a semi-colon (;) is considered
as a comment.

.comment 2 Standard Actions
.test page 20
.index Standard Action
.headerlevel 2 Standard Actions

The following is a list of the currently available
standard action routines:

.list
.test page 10
.listelement SVAL####storage location, value
.index SVAL

This sets a given value into an INTEGER*2 storage location.
(eg.####SVAL####SWITCH,5)

.test page 10
.listelement FVAL####storage location, maximum
.index FVAL

This sets a parsed value into an INTEGER*2 storage location.
If the value is greater than the maximum value given, a
syntax error is generated. (eg.####FVAL####SWITCH,99.)

.test page 10
.listelement FVALS###array, stored, max store, maximum
.index FVALS

This sets parsed values into an INTEGER*2 array.
Each time this action routine is called, it checks
the currently matched value against the maximum
value and stores it in the array.  Then FVAL
increments the position pointer to the array which
is the second argument.  If the
position is greater than max store, the action
causes a syntax error.
(eg.####FVALS###IBUF,NBUF,6,10000.)

.test page 10
.listelement FSTRG###string length, max length, string
.index FSTRG

This sets a parsed string into a buffer along with
the string length.  If the string is longer than max
length characters long, there is a syntax error.
(eg.####FSTRG###NLENG,20.,NAME)

.test page 10
.listelement RVAL####storage location
.index RVAL
.index FPN

This action routine takes a string that is in
the form of a floating point number and stores the
value in a REAL*4 storage location.
The syntax for a floating point number is
an internal syntax statement called FPN.
(eg.####RVAL####RATE)

.test page 20
.listelement FFILE###count, max, file, dev, uic, name, ext, vers
.index FFILE
.index FILE

This action routine takes the parsed RSX11M filespec
which has been parsed by the internal syntax expression FILE.
It then
adds in any default values and stores the string in file
which has count characters.  The maximum number of characters
is given in max.  The defaults are given and must have the
following forms:

.list
.listelement dev#####ddnn:#######(eg. LB:)
.listelement uic#####<[ggg,uuu]>#(eg. <[1,2]>)
.listelement name####nnnnnnnnn###(eg. INPUT)
.listelement ext#####.eee########(eg. .CMD)
.listelement vers####<;vvvvv>####(eg. <;23>)
.end list

(eg.####FFILE###LEN,40.,FIL,,<[1,54]>,TEMP,.DAT)

.endlist

.comment 2 Action Examples
.test page 20
.index Examples
.index Action Examples
.headerlevel 2 Action Examples

.center ;Standard Action Routine Examples
.skip
.left margin 24
.literal
        .MCALL  FVAL,FSTRG,RVAL
SETS:   FSTRG   NLENG,20.,NAME
SETSW:  FVAL    SWITCH,74.
SETR:   RVAL    RATE
.endliteral
.left margin 8

.comment 1 Parser Variable Section
.subtitle ########Parser Variable Section
.test page 30
.headerlevel 1 Parser Variable Section
.index Parser Variable Section

This section contains the options which are included
in the command parser.  They are of the form:

.skip
.indent +16
parser variable = parser constant

Where parser variable must be given exactly
and the parser constant is used
as shown below.  The following is a list
of all the required variables for the command line parser:

.list
.test page 10
.listelement CHARACTERS TO MATCH = number
.index CHARACTERS TO MATCH
.index Abbreviation

This variable number sets the abbreviation length of
character string constants (those enclosed in double-quotes (")).
If it is zero, the characters in the command must match
exactly to the string constant without any trailing
alpha-numeric characters.  If this variable is greater than zero,
then the characters in the command string may be abbreviated
to the given number of characters.  If the command string is not
abbreviated, then the characters must match exactly for the entire
length of the command's alpha-numeric string.

.skip
.test page 10
.index Examples
.center ;Example
.skip
.center ;Given: CHARACTERS TO MATCH = 2
.skip
.left margin 32
.literal
ABCDE    matches   "ABCDE"
ABC      matches   "ABCDE"
AB       matches   "ABCDE"
ABCE  no match to  "ABCDE"
A     no match to  "ABCDE"
ABCD  no match to  "ABC"
.endliteral
.left margin 17

.test page 10
.listelement SYNTAX = syntax label
.index SYNTAX

This variable defines which syntax statement is
to be used as the first syntax statement.  All
other syntax statements should be referenced directly
or indirectly from this statement.
(eg.#SYNTAX#=#LINE)

.test page 10
.listelement LOGICAL UNIT = logical unit number
.index LOGICAL UNIT

This variable number sets which logical unit number
will be used by the process which retrieves the command
line.  During this task build, this logical unit must
be set to TI:. (eg.#LOGICAL#UNIT#=#6 has ASG#TI:6 during
task build)

.test page 10
.listelement PROMPT = prompt character string
.index PROMPT

This variable string is the string which is output
when the task is prompting for terminal input of a
command line.  (eg.#PROMPT#=#CMD#LINE will prompt
CMD#LINE># on TI:)

.endlist

.index ROUTINE NAME

If just the parsing feature of command is going to be
used, then CHARACTERS TO MATCH and SYNTAX are the
only required variables of the above set. The others
will be ignored.  To allow for the definition of
the name of the parsing routine, the ROUTINE#NAME
line must be entered.
(eg.#ROUTINE#NAME#=#PARS)

In this section, comments are not allowed.

.appendix SYNTAX FILE EXAMPLE
.title ########SYNTAX FILE EXAMPLE
.left margin 8
.right margin 72
.index Syntax File
.index Examples
.literal
C
C               This section defines the four variables which
C               will be set by the action routines.
C
C                 NAME is a string (max length of 20)
C                 NLENG is the number of characters in NAME
C                 SWITCH is an integer switch number
C                 RATE is a floating point rate
C
        BYTE      NAME(20)
        INTEGER*2 NLENG, SWITCH
        REAL*4    RATE
/
;       This syntax statement matches a string, and calls SETS.
;       Then it matches any and all OPTS.
        LINE  = $STRNG:SETS [*OPTS]
;
;       This statement matches SWTCH or RATE
        OPTS  = SWTCH ! RATE
;
;       This statement matches /SWITCH=n
        SWTCH = '/ "SWITCH" '= $NUMBR:SETSW
;
;       This statement matches /RATE=floating point number
        RATE  = '/ "RATE"   '= FPN:SETR
/
        .MCALL  FVAL,FSTRG,RVAL  ;Set up for Standard Actions
SETS:   FSTRG   NLENG,20.,NAME   ;Set string and length 
SETSW:  FVAL    SWITCH,74.       ;Set value < 74. in SWITCH
SETR:   RVAL    RATE             ;Set real value in RATE
/
CHARACTERS TO MATCH = 2
SYNTAX          = LINE
LOGICAL UNIT    = 6
PROMPT          = CMD LINE
/
.endliteral

.appendix COMMAND FILES
.title ########COMMAND FILES
.left margin 8
.right margin 72
.index COMMAND Files

The following is a list of the COMMAND files which reside on
the UIC [127,100].

.list

.test page 6
.listelement CMDDTB.TEC
.index CMDDTB.TEC
.index Command Database
.index DTB
.index Parameter Definition Section

This file contains the TECO macro which takes the
Parameter Definition Section of the Syntax File (.SYN)
and generates the Command Database File (.DTB).

.test page 6
.listelement CMDLINE.TEC
.index CMDLINE.TEC
.index TPARS
.index PARSER.TEC
.index Syntax Statement

This file contains the TECO macro which
extracts one syntax statement from the Syntax
File and generates TPARS macro calls using
PARSER.TEC.

.test page 6
.listelement COMMAND.TEC
.index COMMAND.TEC
.index Syntax File

This is the main TECO macro which compiles
a Syntax File.

.test page 6
.listelement MACCOM.TEC
.index MACCOM.TEC
.index Parameter Definition Section
.index MACRO Parser
.index Command Database

This file contains the TECO macro which takes
the Parameter Definition Section of the Syntax File (.SYN)
and generates the labelled common block storage for the
MACRO Parsing Routine.

.test page 6
.listelement PARSER.TEC
.index PARSER.TEC
.index Syntax Expression
.index TPARS

This file contains the TECO macro which takes
a Syntax Expression and generates the TPARS macro
calls.

.test page 6
.listelement CMDMACROS.MAC
.index CMDMACROS.MAC
.index Standard Action

This file contains the Standard Actions coded
in MACRO-11.

.test page 6
.listelement COMMAND.MAC
.index COMMAND.MAC
.index MACRO Parser

This file contains the raw MACRO-11 code for the
Command Line Parser.  The Command Database, the
TPARS commands and the Parser Variables are added
on to this file to create the MACRO Parsing Routine.

.test page 6
.listelement PARSER.MAC
.index PARSER.MAC

This file contains the raw MACRO-11 code for just
the parsing utility of the Command Line Parser.

.test page 6
.listelement COMMAND.MLB
.index COMMAND.MLB
.index Command File
.index CMD
.index Standard Action

This file contains the MACRO-11 library containing the
Standard Actions.
It is linked into the MACRO Parsing Routine during
its assembly through the Command File (.CMD).

.test page 6
.listelement COMMAND.RNO
.index COMMAND.RNO

This file.

.endlist

.appendix INDEX
.title ########INDEX
.left margin 8
.right margin 72
.print index
.comment end of COMMAND rno file