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

    The Spawn Subprocess routine requests the command language
    interpreter (CLI) of the calling process to spawn a subprocess
    for executing CLI commands. LIB$SPAWN provides the same function
    as the DCL command SPAWN.

    Format

      LIB$SPAWN  [command-string] [,input-file]

                 [,output-file] [,flags] [,process-name]

                 [,process-id] [,completion-status-address]

                 [,byte-integer-event-flag-num] [,AST-address]

                 [,varying-AST-argument] [,prompt-string] [,cli]

                 [,table]

1 - Returns

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

2 - Arguments

 command-string

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

    CLI command to be executed by the spawned subprocess. The
    command-string argument is the address of a descriptor pointing
    to this CLI command string. If command-string is omitted,
    commands are taken from the file specified by input-file.

 input-file

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

    Equivalence name to be associated with the logical name SYS$INPUT
    in the logical name table for the subprocess. The input-
    file argument is the address of a descriptor pointing to this
    equivalence string. If input-file is omitted, the default is the
    caller's SYS$INPUT.

 output-file

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

    Equivalence name to be associated with the logical names
    SYS$OUTPUT and SYS$ERROR in the logical name table for the
    subprocess. The output-file argument is the address of a
    descriptor pointing to this equivalence string. If output-file
    is omitted, the default is the caller's SYS$OUTPUT.

 flags

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

    Flag bits that designate optional behavior. The flags argument
    is the address of an unsigned longword that contains these flag
    bits. By default, all flags are clear.

    These flags are defined as follows:

    Bit  Symbol      Meaning

    0    NOWAIT      If this bit is set, the calling process
                     continues executing in parallel with the
                     subprocess. If this bit is clear, the calling
                     process hibernates until the subprocess
                     completes.
    1    NOCLISYM    If this bit is set, the spawned subprocess does
                     not inherit CLI symbols from its caller. If
                     this bit is clear, the subprocess inherits all
                     currently defined CLI symbols. You may want
                     to specify NOCLISYM to help prevent commands
                     redefined by symbol assignments from affecting
                     the spawned commands.
    2    NOLOGNAM    If this bit is set, the spawned subprocess does
                     not inherit process logical names from its
                     caller. If this bit is clear, the subprocess
                     inherits all currently defined process logical
                     names. You may want to specify NOLOGNAM to
                     help prevent commands redefined by logical name
                     assignments from affecting the spawned commands.
    3    NOKEYPAD    If this bit is set, the keypad symbols and state
                     are not passed to the subprocess. If this bit is
                     not set, the keypad settings are passed to the
                     subprocess.
    4    NOTIFY      If this bit is set, a message is broadcast to
                     SYS$OUTPUT when the subprocess completes or
                     aborts. If this bit is not set, no message is
                     broadcast. This bit should not be set unless the
                     NOWAIT bit is also set.
    5    NOCONTROL   If this bit is set, no carriage-return/line-feed
                     is prefixed to any prompt string. If this bit is
                     not set, a carriage-return/line-feed is prefixed
                     to any prompt string specified.
    6    TRUSTED     If this bit is set, it indicates a SPAWN command
                     on behalf of the application. If this bit is
                     not set, it indicates that the SPAWN command
                     originates from user. SPAWN commands originating
                     from users are disallowed in captive accounts
                     (DCL).
    7    AUTHPRIV    If this bit is set, the subprocess inherits the
                     caller's authorized privileges. If this bit is
                     clear, the spawned processes' authorized mask
                     is set equal to the caller's current (active)
                     privilege mask.
    8    SUBSYSTEM   If this bit is set, a spawned process inherits
                     protected subsystem IDs for the duration of
                     LOGINOUT.EXE (used to map the CLI). The IDs
                     will be removed in the process of transferring
                     control to the CLI (as a user mode $RUNDWN is
                     performed). If this bit is clear, LOGINOUT does
                     not execute under the subsystem IDs.

    Bits 9 through 31 are reserved for future expansion and must be
    zero. Symbolic flag names are defined in libraries supplied by
    Compaq in module $CLIDEF. They are CLI$M_NOWAIT, CLI$M_NOCLISYM,
    CLI$M_NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_NOTIFY, CLI$M_NOCONTROL,
    CLI$M_TRUSTED, CLI$M_AUTHPRIV, and CLI$M_SUBSYSTEM.

 process-name

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

    Name defined for the subprocess. The process-name argument is the
    address of a descriptor pointing to this name string. If process-
    name is omitted, a unique process name will be generated. If you
    supply a name and it is not unique, LIB$SPAWN will return the
    condition value SS$_DUPLNAM.

 process-id

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Process identification of the spawned subprocess. The process-id
    argument is the address of an unsigned longword that contains
    this process identification value.

    This process identification value is meaningful only if the
    NOWAIT flags bit is set.

 completion-status-address

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by value

    The final completion status of the subprocess. The completion-
    status-address argument contains the address of the status. The
    system writes the value of the final completion status of the
    subprocess into completion-status-address when the subprocess
    completes. If the subprocess returns a status code of 0, the
    system writes SS$_NORMAL into this address.

    If the NOWAIT flags bit is set, the completion-status-address
    is updated asynchronously when the subprocess completes. Use the
    byte-integer-event-flag-num or AST-address arguments to determine
    when the subprocess has completed. Your program must ensure that
    the address is still valid when the value is written.

 byte-integer-event-flag-num

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The number of a local event flag to be set when the spawned
    subprocess completes. The byte-integer-event-flag-num argument
    is the address of an unsigned byte that contains this event flag
    number. If byte-integer-event-flag-num is omitted, no event flag
    is set.

    Specifying byte-integer-event-flag-num is meaningful only if the
    NOWAIT flags bit is set.

 AST-address

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by value

    Routine to be called by means of an AST when the subprocess
    completes.

    Specifying AST-address is meaningful only if the NOWAIT flags bit
    is set.

 varying-AST-argument

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    A value to be passed to the AST routine. Typically, the varying-
    AST-argument argument is the address of a block of storage the
    AST routine will use.

    Specifying varying-AST-argument is meaningful only if the NOWAIT
    flags bit is set and if AST-address has been specified.

 prompt-string

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

    Prompt string to use in the subprocess. The prompt-string
    argument is the address of a descriptor pointing to this prompt
    string. If prompt-string is omitted, the subprocess uses the same
    prompt string that the parent process uses.

 cli

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

    File specification for the command language interpreter (CLI)
    to be run in the subprocess. The cli argument is the address of
    this file specification string's descriptor. The CLI specified
    must reside in SYS$SYSTEM with a file type of .EXE, and it must
    be installed. No directory or file type may be specified. The cli
    argument must be specified in uppercase characters.

    If cli is omitted, the subprocess uses the same CLI as the
    parent process. If cli is specified, no context is copied to
    the subprocess.

 table

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

    File specification for the command tables to be used by the
    spawned process. The table argument is the address of this file
    specification string's descriptor. The table specified must
    reside in SYS$SHARE with a file type of .EXE, and it must be
    installed.

    If table is omitted, the subprocess uses the same table as the
    parent process.