PARSECMD
Authorization
General User
Purpose
Use the PARSECMD command to call the parsing facility from within an exec. The CMS parsing facility parses and translates command arguments.
Operands
- uniqueid
- is the unique identifier for a command syntax definition in a file containing Definition Language for Command Syntax (DLCS) statements. The uniqueid may be up to 16 characters in length.
Options
- TRANSLSame
- specifies the parsing facility should determine translation status from the first keyword found
whose nl-name and sl-name DLCS definitions are different. In other words, the status is TRANSLNO if
this keyword is the sl-name and TRANSLYES if this keyword is the nl-name. If all the nl-names and
sl-names for the command are the same, the translation status cannot be determined.
The default is TRANSLSAME when STRING is specified. The translation status is returned from the MESSAGE.1 variable if TRANSLSAME is explicitly specified and the parsing facility has successfully completed. MESSAGE.1 will contain message 8160 with the string
TRANSLSAME
if a translation status cannot be determined. - TRANSLYes
- specifies all keywords should be translated by the parsing facility. In other words, only keywords defined as nl-names in the DLCS syntax definition are recognized.
- TRANSLNo
- specifies keywords should not be translated by the parsing facility. In other words, only keywords defined as sl-names in the DLCS syntax definition are recognized.
- TRANSLCms
- specifies CMS determines translation status according to how the exec issuing PARSECMD was
invoked. When CMS determines translation status, it uses:
- TRANSLYES if the specified exec name is a translation (or a synonym or abbreviation of a translation) of the exec invoked.
- TRANSLNO if the specified exec is a synonym (or an abbreviation of a synonym) set with the SYNONYM command of the exec invoked.
- TRANSLSAME if the exec is invoked using the same name by which the exec is specified.
For more information on how and when CMS translates or creates a synonym of a command name, For more information, see SYNONYM. The default is TRANSLCMS when STRING is not specified. The translation status is returned in the MESSAGE.1 variable if TRANSLCMS is explicitly specified and the parsing facility has successfully completed. MESSAGE.1 will contain message 8160 with the string TRANSLYES or TRANSLNO if a translation status can be determined. It will contain message 8160 with the string TRANSLSAME if a translation status cannot be determined.
- TYPE
- displays error messages at the terminal for syntax errors that are found while parsing the exec arguments or cmdstring. The default is TYPE.
- NOTYPE
- returns the text of syntax error messages for exec arguments or
cmdstring in a REXX or EXEC2 variable called
MESSAGE.n
. MESSAGE.0 contains the number of lines in the message. Variables MESSAGE.1 to MESSAGE.n (where n is the value in MESSAGE.0) contain the lines of the error message text. MESSAGE.0 is 0 if there are no errors. - APPLID applid
- is an application identifier. The applid must be three alphanumeric
characters, and the first character must be alphabetic. For example,
DMS
is the applid for CMS, the default application. - STRING cmdstring
- parses the cmdstring rather than the exec's arguments usually obtained from EXECCOMM. This must be the last option specified. Specify a complete command definition, including the command name, as if it were entered from the command line.
Usage Notes
- PARSECMD returns parsing information to the exec in a series of REXX (or EXEC 2) variables in
the form
- token.n and code.n
where n is a subscript that distinguishes the different values returned. The variables are in the following format:- token.0
- number of tokens returned
- code.0
- number of validation codes returned
- token.1
- command name from the DLCS definition
- code.1
- validation code for command name
- token.2
- second token in the command string
- code.2
- validation code for the second token
- .
- .
- .
- .
- token.n
- nth token in the command string
- code.n
- validation code for the nth token
- Possible code.n values are:
- ALPHANUM
- Alphanumeric string
- APPLID
- Any three character alphanumeric string with first alphabetic
- ARBMODIF
- Arbitrary modifier consisting of any string not defined by command syntax
- COMMAND
- Command name
- COMMENT
- Comment (everything following OPTEND)
- CHAR
- A single character
- CSLPATH
- The path number for a loaded CSL routine. It is a string consisting of two substrings separated by a period. Each substring is either an unsigned integer or an asterisk.
- CUU
- A 3-digit device address
- DIGITS
- Any unsigned number made up of digits 0-9
- EFN
- File name with ‘*’ or ‘%’ valid also
- EFT
- File type with ‘*’ or ‘%’ valid also
- EXECNAME
- Executable program name
- EXECTYPE
- Executable program type
- FN
- File name
- FT
- File type
- FM
- File mode
- FPOOLID
- File pool name, less than or equal to nine characters, with the first alphabetic, and the rest alphanumeric
- HEX
- Hexadecimal number
- INTEGER
- Integer: ..., -2, -1, 0, +1,+ 2, ...
- KEYWORD
- Keyword
- MODE
- Uppercase alphabetic character
- NAMEDEF
- A name definition, 16 characters or less, with the first character alphabetic, and the rest alphanumeric
- NINTEGER
- Negative integer: ..., -2, -1
- OPTEND
- Option end )
- OPTSTART
- Option start (
- PINTEGER
- Positive integer: +1, +2, ...
- PN
- Path name
- STRING
- Any character string (no blanks)
- TEXT
- Any string
- usercode
- A user-supplied validation code between 128 and 255 that describes the corresponding token returned by the parsing facility.
- VDEV
- A 4-digit device address
The validation codes that can be returned for the DIRID validation routine in the DLCS are:- DIRID
- fully-qualified directory name, with file pool ID, user ID, and subdirectory name
- DIRPOOL
- directory name specified with file pool ID and subdirectory name
- DIRUSER
- directory name specified with user ID and subdirectory name
- DIRSUB
- subdirectory name
- DIRMINUS
- directory name specified with minus sign notation, for example:
-fm.subdirectory
. - DIRPLUS
- directory name specified with plus sign notation, for example:
+fm.subdirectory
.
The validation codes that can be returned for the DIRIDN validation routine in the DLCS are:- FDIRNICK
- full directory name, with file pool ID and nickname
- DIRPOOL
- directory name specified with file pool ID and subdirectory name
- DIRNICK
- directory name specified with nickname and user ID
- DIRSUB
- subdirectory name
- DIRMINUS
- directory name specified with minus sign notation, for example:
-fm.subdirectory
. - DIRPLUS
- directory name specified with plus sign notation, for example:
+fm.subdirectory
.
- The TYPE and NOTYPE options apply while parsing the syntax of
cmdstring or EXEC arguments. Output with the TYPE option depends on the
EMSG setting of the CP SET command. With the NOTYPE option, the complete message is copied into the
variable MESSAGE, with the first line in
MESSAGE.1, the second line in MESSAGE.2, and so
forth.
Syntax errors produced when calling PARSECMD are displayed at the terminal regardless of the TYPE and NOTYPE option.
- The uniqueid you specify in the PARSECMD command is matched to the uniqueid specified in the DLCS file. For more information on unique IDs, see z/VM: CMS Application Development Guide.
- PARSECMD is also the name of a CMS macro that calls the parsing facility from an assembler language program.
- Keywords are uppercased according to the National Language Uppercase Table for the active application. If the table is not found, the CMS National Language Table is used.
- The parser will do translation for TRANSLCMS only when called from an exec invoked from the command line or with the CMS subcommand environment (ADDRESS CMS). The translation is assumed to have been done by the caller when the parser is invoked from an exec that was invoked CMSCALL (ADDRESS COMMAND).
Messages and Return Codes
- DMS407E Invalid unique ID uniqueid [RC=24]
- DMS622E Insufficient free storage [RC=104]
- DMS631E cmdname can only be executed from an EXEC-2 or REXX EXEC [RC=40]
- DMS639E Error in routine routine; return code was retcode [RC=256]
Additional system messages may be issued by this command. The reasons for these messages and their location are:
Reason | Location |
---|---|
Errors in command syntax | Command Syntax Error Messages |