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

    The Create and Initialize a Subprocess routine creates a DCL
    subprocess and associates it with a virtual display.

    Format

      SMG$CREATE_SUBPROCESS  display-id [,AST-routine]

                             [,AST-argument] [,flags]

1 - Returns

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

2 - Arguments

 display-id

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

    Identifier of the virtual display with which the newly created
    subprocess is associated. The display-id argument is the address
    of an unsigned longword containing this identifier.

 AST-routine

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

    Optional AST routine to be called when the currently executing
    command completes. The AST-routine argument is the routine's
    procedure value.

    The AST routine is called with five parameters. The first
    parameter is a pointer to a data structure that contains the
    display-id, AST-argument, and the command-status values. The
    remaining four parameters for the AST routine are R0, R1, PC, and
    PSL. The following figure illustrates the AST-routine parameters
    and the data structure pointed to by the first parameter.

             Parameters to AST Routine               data structure
         +--------------------------------+       +------------------+
         |   address of data structure    |------>|    display-id    |
         +--------------------------------+       +------------------+
         |             R0                 |       |   AST-argument   |
         +--------------------------------+       +------------------+
         |             R1                 |       |  command-status  |
         +--------------------------------+       +------------------+
         |             PC                 |
         +--------------------------------+
         |            PSL                 |
         +--------------------------------+

    If the AST-routine argument is specified, the routine
    SMG$EXECUTE_COMMAND buffers any commands passed to it and
    executes them in order, calling the specified AST routine when
    each command completes. If the AST-routine argument is not
    specified, SMG$EXECUTE_COMMAND waits until the specified command
    completes before returning control to the user.

 AST-argument

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

    Optional argument you supply to the AST routine. The AST-argument
    parameter is an unsigned longword that contains the value to be
    passed to the AST routine.

 flags

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

    Optional argument you supply to SMG$CREATE_SUBPROCESS.
    SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess.
    The flags argument lets you control some of the flags used in
    that call. Flags available to SMG$CREATE_SUBPROCESS correspond to
    flags in LIB$SPAWN as follows:

    SMG$CREATE_        LIB$SPAWN
    SUBPROCESS Flag    Flag       Function

    SMG$M_TRUSTED      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 the user.
                                  SPAWN commands originating from
                                  users are disallowed in captive
                                  accounts (DCL).
    SMG$M_AUTHPRIV     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.
    SMG$M_SUBSYSTEM    SUBSYSTEM  If this bit is set, a spawned
                                  process inherits protected
                                  subsystem IDs for the duration
                                  of LOGINOUT.EXE (used to map the
                                  command line interpreter). The IDs
                                  will be removed in the process of
                                  transferring control to the command
                                  language interpreter (CLI) (as a
                                  user mode $RUNDWN is performed).
                                  If this bit is clear, LOGINOUT does
                                  not execute under the subsystem
                                  IDs.

    The default is that none of these bits is set. See online Help or
    the OpenVMS RTL Library (LIB$) Manual for a complete description
    of LIB$SPAWN, these flags, and the security consideration
    surrounding their use.