PARSECMD

Read syntax diagramSkip visual syntax diagram PARSECMD uniqueid (TRANSLCmsTYPE(1Options)
Options
Read syntax diagramSkip visual syntax diagram2TRANSLSameTRANSLYesTRANSLNoTRANSLCmsTYPENOTYPEAPPLIDapplidSTRINGcmdstring
Notes:
  • 1 You can enter Options in any order between the parentheses.
  • 2 The default is TRANSLCms if the STRING option is not specified.

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

  1. 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
  2. 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.
  3. 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.

  4. 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.
  5. PARSECMD is also the name of a CMS macro that calls the parsing facility from an assembler language program.
  6. 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.
  7. 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