VMS Help CLI Routines, CLI$DCL_PARSE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The CLI$DCL_PARSE routine supplies a command string to DCL for
    parsing. DCL separates the command string into its individual
    elements according to the syntax specified in the command table.

    Format

      CLI$DCL_PARSE  [command_string] ,table [,param_routine]

                     [,prompt_routine] [,prompt_string]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 command_string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor-fixed length
    Character string containing the command to be parsed. The
    command_string argument is the address of a descriptor specifying
    the command string to be parsed. If the command string includes
    a comment (delimited by an exclamation mark), DCL ignores the
    comment.

    If the command string contains a hyphen to indicate that the
    string is being continued, DCL uses the routine specified in
    the prompt_routine argument to obtain the rest of the string.
    The command string is limited to 256 characters. However, if the
    string is continued with a hyphen, CLI$DCL_PARSE can prompt for
    additional input until the total number of characters is 1024.

    If you specify the command_string argument as zero and specify a
    prompt routine, then DCL prompts for the entire command string.
    However, if you specify the command_string argument as zero and
    also specify the prompt_routine argument as zero, DCL restores
    the parse state of the command string that originally invoked the
    image.

    CLI$DCL_PARSE does not perform DCL-style symbol substitution on
    the command string.

 table

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by value
    Address of the compiled command tables to be used for command
    parsing. The command tables are compiled separately by
    the Command Definition Utility using the DCL command SET
    COMMAND/OBJECT and are then linked with your program. A global
    symbol is defined by the Command Definition Utility that provides
    the address of the tables. The global symbol's name is taken
    from the module name given on the MODULE statement in the command
    definition file, or from the file name if no MODULE statement is
    present.

 param_routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Name of a routine to obtain a required parameter not supplied in
    the command text. The param_routine argument is the address of a
    routine containing a required parameter that was not specified in
    the command_string argument.

    To specify the parameter routine, use the address of LIB$GET_
    INPUT or the address of a routine of your own that has the
    same three-argument calling format as LIB$GET_INPUT. See the
    description of LIB$GET_INPUT in the OpenVMS RTL Library (LIB$)
    Manual for information about the calling format. If LIB$GET_
    INPUT returns error status, CLI$DCL_PARSE propagates the error
    status outward or signals RMS$_EOF in the cases listed in the
    Description section.

    You can obtain the prompt string for a required parameter from
    the command table specified in the table argument.

 prompt_routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Name of a routine to obtain all or part of the text of a command.
    The prompt_routine argument is the address of a routine to obtain
    the text or the remaining text of the command depending on the
    command_string argument. If you specify a zero in the command_
    string argument, DCL uses this routine to obtain an entire
    command line. DCL uses this routine to obtain a continued command
    line if the command string (obtained from the command_string
    argument) contains a hyphen to indicate that the string is being
    continued.

    To specify the prompt routine, use the address of LIB$GET_INPUT
    or the address of a routine of your own that has the same three-
    argument calling format as LIB$GET_INPUT. See the description
    of LIB$GET_INPUT in the OpenVMS RTL Library (LIB$) Manual for
    information about the calling format.

    If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates
    the error status outward or signals RMS$_EOF in the cases listed
    in the Description section.

 prompt_string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Character string containing a prompt. The prompt_string argument
    is the address of a string descriptor pointing to the prompt
    string to be passed as the second argument to the prompt_routine
    argument.

    If DCL is using the prompt routine to obtain a continuation line,
    DCL inserts an underscore character before the first character
    of the prompt string to create the continuation prompt. If DCL is
    using the prompt routine to obtain an entire command line (that
    is, a zero was specified as the command_string argument), DCL
    uses the prompt string exactly as specified.

    The prompt string is limited to 32 characters. The string
    COMMAND> is the default prompt string.

3 - Description

    The CLI$DCL_PARSE routine supplies a command string to DCL for
    parsing. DCL parses the command string according to the syntax in
    the command table specified in the table argument.

    The CLI$DCL_PARSE routine can prompt for required parameters if
    you specify a parameter routine in the routine call. In addition,
    the CLI$DCL_PARSE routine can prompt for entire or continued
    command lines if you supply the address of a prompt routine.

    If you do not specify a command string to parse and the user
    enters a null string in response to the DCL prompt for a command
    string, CLI$DCL_PARSE immediately terminates and returns the
    status CLI$_NOCOMD.

    If DCL prompts for a required parameter and the user presses
    Ctrl/Z, CLI$DCL_PARSE immediately terminates and returns the
    status CLI$_NOCOMD, regardless of whether you specify or do not
    specify a command string to parse. If DCL prompts for a parameter
    that is not required and the user presses Ctrl/Z, CLI$DCL_PARSE
    returns the status CLI$_NORMAL.

    Whenever CLI$DCL_PARSE encounters an error, it both signals and
    returns the error.

4 - Condition Values Returned

    CLI$_INVREQTYP     Calling process did not have a CLI to perform
                       this function, or the CLI did not support the
                       request.
    CLI$_IVVERB        Invalid or missing verb.
    CLI$_NOCOMD        Routine terminated. You entered a null string
                       in response to a prompt from the prompt_
                       routine argument, causing the CLI$DCL_PARSE
                       routine to terminate.
    CLI$_NORMAL        Normal successful completion.
    RMS$_EOF           Routine terminated. You pressed Ctrl/Z in
                       response to a prompt, causing the CLI$DCL_
                       PARSE routine to terminate.