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

    The Get Foreign Command Line routine requests the calling image's
    command language interpreter (CLI) to return the contents of the
    "foreign command" line that activated the current image.

    Format

      LIB$GET_FOREIGN  resultant-string [,prompt-string]

                       [,resultant-length] [,flags]

1 - Returns

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

2 - Arguments

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String that LIB$GET_FOREIGN uses to receive the foreign
    command line. The resultant-string argument is the address of
    a descriptor pointing to this string. If the foreign command
    text returned was obtained by a prompt to SYS$INPUT (see the
    description of flags), the text is translated to uppercase so as
    to be more consistent with text returned from the CLI.

 prompt-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional user-supplied prompt for text that LIB$GET_FOREIGN uses
    if no command-line text is available. The prompt-string argument
    is the address of a descriptor pointing to the user prompt.
    If omitted, no prompting is performed. It is recommended that
    prompt-string be specified. If prompt-string is omitted and if
    no command-line text is available, a zero-length string will be
    returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes written into resultant-string by LIB$GET_FOREIGN,
    not counting padding in the case of a fixed-length resultant-
    string. The resultant-length argument is the address of an
    unsigned word into which LIB$GET_FOREIGN writes the number of
    bytes.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference

    Value that LIB$GET_FOREIGN uses to control whether or not
    prompting is to be performed. The flags argument is the address
    of an unsigned longword integer containing this value. If the low
    bit of flags is zero, or if flags is omitted, prompting is done
    only if the CLI does not return a command line. If the low bit is
    1, prompting is done unconditionally. If specified, flags is set
    to 1 before returning to the caller.

    The primary use of flags is to allow a utility program to be
    invoked once with subcommand text on the command line, and then
    to repeatedly prompt for further subcommands from SYS$INPUT. This
    is accomplished by calling LIB$GET_FOREIGN repeatedly, specifying
    in the call a prompt-string string and a flags variable that
    is initialized to zero at the beginning of the program. The
    first call gets the subcommand text from the command line, after
    which flags will be set to 1, causing further subcommands to be
    requested through prompts to SYS$INPUT.