COMMAND Revision Date: 1 September 80 System Version: 002 These routines were created under the combined influence of the Department of Atmospheric Science at Colorado State Univer- sity and the National Center for Atmospheric Research. Any problems or suggestions should be directed to: Marvin Brown NCAR P.O. Box 3000 Boulder, CO 80307 Phone (303)497-0681 FTS 322-7681 CHAPTER 1 INTRODUCTION These routines are written to allow a user to easily inter- face 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 gener- ates 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 2 OPERATING PROCEDURES 2.1 Executing COMMAND 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: 1. Command Database (.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 state- ments must be compiled after the syntax file is com- piled using the MUNG command. 2. MACRO Parsing Routine (.MAC) This file contains the MACRO routine which per- forms 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. * * * * * (*) 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: >PIP /EN=[127,100]COMMAND.TEC OPERATING PROCEDURES PAGE 2-2 Executing COMMAND 3. Command File (.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. So, the syntax file (.SYN) defining the syntax of the com- mand line is compiled with the following statements: >MUNG COMMAND,syntax file name >@syntax file name Where the syntax file name is just the name of a file which has a .SYN extention. The file selected for processing is al- ways 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. Example >MUNG COMMAND,PROGCMD >@PROGCMD 2.2 Using the Command Line Parser Once the Command Line Parser is generated using COMMAND, it is integrated into a FORTRAN program. First, an INCLUDE state- ment is added to each routine which wants to use any of the com- mand 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 par- ameter initialization is done before the call. After the call to the parser, a test should be made for the success (+1) or fa- ilure 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 ini- tialization. OPERATING PROCEDURES PAGE 2-3 Using the Command Line Parser The following is an example of how the command line parser might be integrated into a FORTRAN program: 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 2.3 Using the 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 accom- plished 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 mes- sage appears on TI:. OPERATING PROCEDURES PAGE 2-4 Using the Parser Sample FORTRAN Routine Using the Parser 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 CHAPTER 3 COMMAND SYNTAX FILE FORMAT 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: 1. Parameter Definition Section 2. Syntax Section 3. Action Routine Section 4. Parser Variable Section 3.1 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 allow- able data types are as follows: BYTE INTEGER*2 INTEGER*4 REAL*4 REAL*8 COMPLEX*8 LOGICAL*1 LOGICAL*2 LOGICAL*4 The number of bytes must be explicitly defined so there is no conflict between COMMAND and any FORTRAN compilation options. COMMAND SYNTAX FILE FORMAT PAGE 3-2 Parameter Definition Section Comments are entered by a 'C' or ';' as the first character of a line. Also, in this section, continuation lines are not allowed. Examples BYTE NAME(20) INTEGER*2 NLENG, SWITCH REAL*4 RATE 3.2 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: 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 Ac- tion 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. COMMAND SYNTAX FILE FORMAT PAGE 3-3 Syntax Section 3.2.1 Syntax Expressions The expression part of a syntax statement can be any of the following: 1. label References a label which has another expression associated with it. 2. constant A constant matches a given character or set of characters. 3. element An element is a string matching command which matches a set of characters which conform to the indi- vidual element's requirements. 4. expression expression Two expressions can be concatenated by listing them one after another. This requires that the string matching the second expression immediately follows the first. 5. expression ! expression Two expressions can be tested for by having a (!) between them. If the first expression does not match the string, the second is tested. 6. (expression) An expression can be isolated from other opera- tions such as concatenation or (!) by enclosing it in parenthesis. 7. [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. 8. [*expression] An optional expression preceded with a (*) means that the expression may occur repeatedly or the null string is matched. COMMAND SYNTAX FILE FORMAT PAGE 3-4 Syntax Section 9. [+expression] An optional expression preceded with a (+) means that the expression may occur repeatedly but it must occur at least once. 3.2.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: Semi-colon <';> Comma <',> Character strings may only contain alpha-numeric characters and are enclosed in double quotes ("). For example, "ALPHANUMERIC" is a character string. 3.2.3 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. 1. $ANY Matches any single character. 2. $ALPHA Matches any single alphabetic character (A-Z). 3. $DIGIT Matches any single digit (0-9). 4. $LAMDA Matches an empty string. This element always matches. They are useful for calling action routines without having to match characters. COMMAND SYNTAX FILE FORMAT PAGE 3-5 Syntax Section 5. $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. 6. $DNUMB Matches a decimal number without a decimal point. 7. $STRNG Matches any alpha-numeric character string (0-9, A-Z). The string will not be null. 8. $RAD50 Matches any legal RADIX-50 string, that is, any string containing alpha-numeric characters and/or the period (.) and dollars sign ($) characters. 9. $BLANK Matches a string of blank and/or tab characters. 10. $EOS Matches the end of the line. 3.2.4 Internal Syntax Expressions An internal syntax expression is similar to a syntax ele- ment 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. 1. FPN 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. 2. FILE Matches RSX11M filespecs. FILE is associated with the standard action routine FFILE. COMMAND SYNTAX FILE FORMAT PAGE 3-6 Syntax Section 3. CLRFIL This internal syntax expression matches the null string. It is used to clear the internal file storage which is retained between successive FILE matches. 3.2.5 Syntax Examples Sample Syntax Section LINE = $STRNG:SETS [*OPTS] OPTS = SWTCH ! RATE SWTCH = '/ "SWITCH" '= $NUMBR:SETSW RATE = '/ "RATE" '= FPN:SETR 3.3 Action Routine Section This section contains the action routines which process the strings which are matched by the syntax expressions in the Syn- tax Section. The standard form of this section is a line defin- ing the standard action routines which are to be used followed by the action routines. The following shows the standard form of this section: .MCALL action1,action2, ... actionN alabel: action action parameters . . . Where action1 through actionN is a list of the standard ac- tion routines used in this section, alabel is the label refer- enced in the Syntax Section, action is the standard action asso- ciated with alabel and action parameters are the parameters used by the standard action. For users who have special requirements of the action rou- tines and who know how to program in MACRO-11, specialized ac- tion 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. COMMAND SYNTAX FILE FORMAT PAGE 3-7 Action Routine Section 3.3.1 Standard Actions The following is a list of the currently available standard action routines: 1. SVAL storage location, value This sets a given value into an INTEGER*2 storage location. (eg. SVAL SWITCH,5) 2. FVAL storage location, maximum 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.) 3. FVALS array, stored, max store, maximum 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 posi- tion 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.) 4. FSTRG string length, max length, string 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) 5. RVAL storage location 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) COMMAND SYNTAX FILE FORMAT PAGE 3-8 Action Routine Section 6. FFILE count, max, file, dev, uic, name, ext, vers This action routine takes the parsed RSX11M files- pec which has been parsed by the internal syntax ex- pression 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: 1. dev ddnn: (eg. LB:) 2. uic <[ggg,uuu]> (eg. <[1,2]>) 3. name nnnnnnnnn (eg. INPUT) 4. ext .eee (eg. .CMD) 5. vers <;vvvvv> (eg. <;23>) (eg. FFILE LEN,40.,FIL,,<[1,54]>,TEMP,.DAT) 3.3.2 Action Examples Standard Action Routine Examples .MCALL FVAL,FSTRG,RVAL SETS: FSTRG NLENG,20.,NAME SETSW: FVAL SWITCH,74. SETR: RVAL RATE COMMAND SYNTAX FILE FORMAT PAGE 3-9 Parser Variable Section 3.4 Parser Variable Section This section contains the options which are included in the command parser. They are of the form: 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: 1. CHARACTERS TO MATCH = number 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 ab- breviated, then the characters must match exactly for the entire length of the command's alpha-numeric string. Example Given: CHARACTERS TO MATCH = 2 ABCDE matches "ABCDE" ABC matches "ABCDE" AB matches "ABCDE" ABCE no match to "ABCDE" A no match to "ABCDE" ABCD no match to "ABC" 2. SYNTAX = syntax label This variable defines which syntax statement is to be used as the first syntax statement. All other syn- tax statements should be referenced directly or indi- rectly from this statement. (eg. SYNTAX = LINE) 3. LOGICAL UNIT = logical unit number 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) COMMAND SYNTAX FILE FORMAT PAGE 3-10 Parser Variable Section 4. PROMPT = prompt character string This variable string is the string which is output when the task is prompting for terminal input of a com- mand line. (eg. PROMPT = CMD LINE will prompt CMD LINE> on TI:) If just the parsing feature of command is going to be used, then CHARACTERS TO MATCH and SYNTAX are the only required vari- ables of the above set. The others will be ignored. To allow for the definition of the name of the parsing routine, the ROU- TINE NAME line must be entered. (eg. ROUTINE NAME = PARS) In this section, comments are not allowed. APPENDIX A SYNTAX FILE EXAMPLE 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 / APPENDIX B COMMAND FILES The following is a list of the COMMAND files which reside on the UIC [127,100]. 1. CMDDTB.TEC This file contains the TECO macro which takes the Parameter Definition Section of the Syntax File (.SYN) and generates the Command Database File (.DTB). 2. CMDLINE.TEC This file contains the TECO macro which extracts one syntax statement from the Syntax File and generates TPARS macro calls using PARSER.TEC. 3. COMMAND.TEC This is the main TECO macro which compiles a Syn- tax File. 4. MACCOM.TEC 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. 5. PARSER.TEC This file contains the TECO macro which takes a Syntax Expression and generates the TPARS macro calls. 6. CMDMACROS.MAC This file contains the Standard Actions coded in MACRO-11. COMMAND FILES PAGE B-2 7. COMMAND.MAC 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. 8. PARSER.MAC This file contains the raw MACRO-11 code for just the parsing utility of the Command Line Parser. 9. COMMAND.MLB 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). 10. COMMAND.RNO This file. APPENDIX C INDEX $ALPHA . . . . . . . . . 3-4 $ANY . . . . . . . . . . 3-4 $BLANK . . . . . . . . . 3-5 $DIGIT . . . . . . . . . 3-4 $DNUMB . . . . . . . . . 3-5 $EOS . . . . . . . . . . 3-5 $LAMDA . . . . . . . . . 3-4 $NUMBR . . . . . . . . . 3-5 $RAD50 . . . . . . . . . 3-5 $STRNG . . . . . . . . . 3-5 Abbreviation . . . . . . 3-9 Action Examples . . . . 3-8 Action Routine Section . 3-1, 3-6 BYTE . . . . . . . . . . 3-1 CHARACTERS TO MATCH . . 3-9 CLRFIL . . . . . . . . . 3-6 CMD . . . . . . . . . . 2-2, B-2 CMDDTB.TEC . . . . . . . B-1 CMDLINE.TEC . . . . . . B-1 CMDMACROS.MAC . . . . . B-1 Command Database . . . . 2-1, B-1 Command File . . . . . . 2-2, B-2 COMMAND Files . . . . . B-1 COMMAND.MAC . . . . . . B-2 COMMAND.MLB . . . . . . B-2 COMMAND.RNO . . . . . . B-2 COMMAND.TEC . . . . . . B-1 Compilation . . . . . . 2-1 COMPLEX . . . . . . . . 3-1 Default Parameters . . . 2-2 DTB . . . . . . . . . . 2-1, B-1 Examples . . . . . . . . 2-2, 2-3, 2-4, 3-2, 3-6, 3-8, 3-9, A-1 Execution . . . . . . . 2-1 EXIT . . . . . . . . . . 2-2 FFILE . . . . . . . . . 3-5, 3-6, 3-8 INDEX PAGE C-2 FILE . . . . . . . . . . 3-5, 3-8 FPN . . . . . . . . . . 3-5, 3-7 FSTRG . . . . . . . . . 3-7 FVAL . . . . . . . . . . 3-7 FVALS . . . . . . . . . 3-7 INCLUDE . . . . . . . . 2-2 INTEGER . . . . . . . . 3-1 Internal Syntax Expression 3-5 LOGICAL . . . . . . . . 3-1 LOGICAL UNIT . . . . . . 3-9 MAC . . . . . . . . . . 2-1 MACCOM.TEC . . . . . . . B-1 MACRO Parser . . . . . . 2-1, B-1, B-2 Operation . . . . . . . 2-1 Optional Expression . . 3-3 Parameter Definition Section 3-1, B-1 Parser Variable Section . 3-1, 3-9 PARSER.MAC . . . . . . . B-2 PARSER.TEC . . . . . . . B-1 PROMPT . . . . . . . . . 3-10 REAL . . . . . . . . . . 3-1 Repeating Expressions . 3-3 ROUTINE NAME . . . . . . 3-10 RVAL . . . . . . . . . . 3-5, 3-7 Special Characters . . . 3-4 Standard Action . . . . 3-7, B-1, B-2 SVAL . . . . . . . . . . 3-7 SYNTAX . . . . . . . . . 3-9 Syntax Concatenation . . 3-3 Syntax Constant . . . . 3-3, 3-4 Syntax Element . . . . . 3-3, 3-4 Syntax Examples . . . . 3-6 Syntax Expression . . . 3-2, 3-3, B-1 Syntax File . . . . . . 3-1, A-1, B-1 Syntax Grouping . . . . 3-3 Syntax Label . . . . . . 3-2 Syntax Or . . . . . . . 3-3 Syntax Section . . . . . 3-1, 3-2 Syntax Statement . . . . 3-2, B-1 TPARS . . . . . . . . . 3-6, B-1 Using Command Line Parser 2-2 Using Parser . . . . . . 2-3