HELPLIB.HLB  —  SPAWN
    Creates a subprocess of the current process. Portions of the
    current process context are copied to the subprocess.

    The RESOURCE_WAIT state is required to spawn a process.
    Requires TMPMBX (temporary mailbox) or PRMMBX (permanent
    mailbox) privilege. The SPAWN command does not manage terminal
    characteristics. The SPAWN and ATTACH commands cannot be used if
    your terminal has an associated mailbox.

    Format

      SPAWN  [command-string]

1  –  Parameter

 command-string

    Specifies a command string of less than 132 characters that is
    to be executed in the context of the created subprocess. When
    the command completes execution, the subprocess terminates and
    control returns to the parent process. If both a command string
    and the /INPUT qualifier are specified, the specified command
    string executes before additional commands are obtained from the
    /INPUT qualifier.

    If the command string contains apostrophe substitution, the
    apostrophe substitution is performed in the context of the parent
    command line interpreter (CLI); other phases of substitution are
    performed in the context of the subprocess CLI.

2  –  Qualifiers

2.1    /CARRIAGE_CONTROL

       /CARRIAGE_CONTROL
       /NOCARRIAGE_CONTROL

    Determines whether carriage-return and line-feed characters are
    prefixed to the subprocess's prompt string. By default, SPAWN
    copies the current setting of the parent process.

2.2    /CLI

       /CLI=cli-filespec
       /NOCLI

    Specifies the name of a command language interpreter (CLI) to
    be used by the subprocess. The default CLI is the same as the
    parent process (defined in SYSUAF). If you specify the /CLI
    qualifier, the attributes of the parent process are copied to
    the subprocess.

    The CLI you specify must be located in SYS$SYSTEM and have the
    file type .EXE.

2.3    /INPUT

       /INPUT=filespec

    Specifies an input file containing one or more DCL commands to
    be executed by the spawned subprocess. The file type defaults
    to .COM. The asterisk (*)  and the percent sign (%) wildcard
    characters are not allowed in the file specification. Once
    processing of the input file is complete, the subprocess is
    terminated. If both a command string and the /INPUT qualifier
    are specified, the specified command string executes before
    additional commands are obtained from the /INPUT qualifier.
    If neither is specified, SYS$INPUT is assumed (in which case a
    SPAWN/NOWAIT command is aborted if Ctrl/Y is pressed to abort
    something running in your parent process).

    You cannot explicitly specify non-record-oriented, process-
    permanent files (NRO PPFs) with the /INPUT qualifier. The system
    displays an error message when it encounters such a file as the
    value for the /INPUT qualifier.

    Note that when NRO PPFs are used as implicit input (that is, the
    /INPUT qualifier is not specified and SYS$INPUT is a NRO PPF),
    the SPAWN command can succeed, as shown in the following table:

    Process Type     SYS$INPUT  Implicit Input

    Interactive      NRO PPF    SYS$COMMAND

    Noninteractive   NRO PPF    Null device

    Any              Any other  SYS$INPUT

    If SYS$INPUT is a terminal, it cannot have an associated terminal
    mailbox.

2.4    /KERNEL_THREAD_LIMIT

       /KERNEL_THREAD_LIMIT=n

    Sets the limit of the number of kernel threads that can be
    created in the new process. If the value specified is higher than
    the SYSGEN parameter MULTITHREAD, an error message is returned.
    Specifying the value 0 makes the process use the system-wide
    limit set by the MULTITHREAD parameter.

2.5    /KEYPAD

       /KEYPAD (default)
       /NOKEYPAD

    Copies keypad key definitions and the current keypad state from
    the parent process. By default, if you have established key
    definitions or states with the DEFINE/KEY or the SET KEY command,
    these settings are copied to the subprocess. Use the /NOKEYPAD
    qualifier if you do not want the key settings to be copied.

2.6    /LOG

       /LOG (default)
       /NOLOG

    Displays the assigned subprocess name and any messages indicating
    transfer of control between processes.

2.7    /LOGICAL_NAMES

       /LOGICAL_NAMES (default)
       /NOLOGICAL_NAMES

    Copies process logical names and logical name tables to the
    subprocess. By default, all process logical names and logical
    name tables are copied to the subprocess except those explicitly
    marked CONFINE or created in executive or kernel mode.

2.8    /NOTIFY

       /NOTIFY
       /NONOTIFY (default)

    Controls whether a message is broadcast to your terminal
    notifying you that your subprocess has completed or aborted.
    This qualifier should not be used unless you specify the /NOWAIT
    qualifier. The /NOTIFY qualifier cannot be specified when the
    SPAWN command is executed from within a noninteractive process.

    Note that messages broadcast as a result of using the /NOTIFY
    qualifier are considered to be DCL messages. Therefore, if SET
    BROADCAST=NODCL is in effect, all such notification messages are
    suppressed.

2.9    /OUTPUT

       /OUTPUT=filespec

    Specifies the output file to which the results of the SPAWN
    operation are written. The asterisk (*)  and the percent sign (%)
    wildcard characters cannot be used in the file specification.
    (Do not specify SYS$COMMAND as a file specification for the
    /OUTPUT qualifier when using the /NOWAIT qualifier; both parent
    and subprocess output will be displayed simultaneously on your
    terminal.)

                                 CAUTION

       If you include a version number in the filespec argument
       of the /OUTPUT qualifier, and that version of the specified
       file already exists, the existing file is replaced with the
       new output.

    You cannot explicitly specify non-record-oriented, process-
    permanent files (NRO PPFs) with the /OUTPUT qualifier. The system
    displays an error message when it encounters such a file as the
    value for the /OUTPUT qualifier.

    Note that when NRO PPFs are used as implicit output, the SPAWN
    command can succeed, as shown in the following table:

    Process
    Type         SYS$OUTPUT   Implicit Output

    Any          NRO PPF      Mailbox transmitting records for parent
                              to write to its current SYS$OUTPUT
                              device

    Any          Any other    SYS$OUTPUT

    If you omit the /OUTPUT qualifier, output is written to the
    current SYS$OUTPUT device.

2.10    /PRIVILEGES

       /PRIVILEGES={CURRENT|AUTHORIZED}

    Determines whether the spawned process inherits the current
    process' current or authorized privileges as its authorized
    privileges. By default, the authorized privilege mask for
    the subprocess is taken from the current privileges of its
    creator. (This corresponds to /PRIVILEGES=CURRENT.) If the
    /PRIVILEGES=AUTHORIZED qualifier is specified, the subprocess'
    authorized privileges will be taken from the caller's authorized
    privileges.

2.11    /PROCESS

       /PROCESS=subprocess-name

    Specifies the name of the subprocess to be created. If you omit
    the /PROCESS qualifier, a unique process name is assigned with
    the same base name as the parent process and a unique number.

    The default subprocess name format is username_n. If you
    specify a process name that already exists, an error message is
    displayed. If the /LOG qualifier has been specified, the assigned
    name of the subprocess is displayed.

                                   NOTE

       Prior to OpenVMS Version 7.3-1, if no process name was
       supplied, the system constructed a name by appending _n to
       the user name, where n was the next available nonduplicate
       integer for any process currently in the system. For
       example, the first spawned process from user SYSTEM would
       be called SYSTEM_1, the second, SYSTEM_2, and so on. The
       next available number was chosen as soon as a gap was found.

       Starting with OpenVMS Alpha Version 7.3-1, a random number
       is chosen to append to the user name. In addition, starting
       with OpenVMS Version 8.3, the chosen number has, by default,
       a maximum value of 65535 instead of the former maximum value
       of 255. Therefore, the first processes that are spawned from
       user SYSTEM might be SYSTEM_7376, SYSTEM_9, SYSTEM_47124,
       and so on.

       Some applications might rely on the prior methods of
       assigning subprocess names. The DCL_CTLFLAGS system
       parameter allows you to configure the system as necessary.

       The rationale for changing from sequential to random
       number generation is that determining the next available
       open sequential number slot is very expensive in terms of
       performance. The mechanism attempts to create the process by
       incrementing names until it finds one that is unique. When
       several subprocesses already exist, the cost of creating the
       subprocess in the same OpenVMS group, the cost multiplies
       because process names must be unique throughout the group.

       The use of random number generation results in a very high
       probability of finding a unique name on the first try,
       because it is unlikely that the same number is already in
       use. This greatly reduces the cost of process creation, and
       applications that rely on spawned subprocesses might see a
       dramatic performance improvement as a result of this change.

       For more information, see the VSI OpenVMS System Management
       Utilities Reference Manual for more information.

2.12    /PROMPT

       /PROMPT[=string]

    Specifies the prompt string for DCL to use in the subprocess. The
    default is the prompt of the parent process.

    The string can consist of more than one character. All valid
    ASCII characters can be used in the string. The string must be
    enclosed in quotation marks (" ")  if it contains spaces, special
    characters, or lowercase characters. Otherwise, letters are
    automatically converted to uppercase, and leading and trailing
    spaces are removed.

    If no string is specified, the dollar sign ($)  DCL default
    prompt string is used for the subprocess.

2.13    /SYMBOLS

       /SYMBOLS (default)
       /NOSYMBOLS

    Determines whether global and local symbols (except $RESTART,
    $SEVERITY, and $STATUS) are passed to the subprocess. $RESTART,
    $SEVERITY, and $STATUS symbols are never passed to the
    subprocess.

2.14    /TABLE

       /TABLE=command-table

    Specifies the name of an alternate command table to be used by
    the subprocess.

2.15    /TRUSTED

       /TRUSTED
       /NOTRUSTED

    Indicates that the SPAWN command input originates in a trusted
    command procedure. SPAWN commands are not allowed in CAPTIVE
    accounts. The /TRUSTED qualifier provides a way for properly
    written captive command procedures to perform SPAWN operations
    when the command input originates in the captive command
    procedure where it can be trusted. For more information about
    trusted command procedures, see the VSI OpenVMS Guide to System
    Security.

2.16    /WAIT

       /WAIT (default)
       /NOWAIT

    Requires that you wait for the subprocess to terminate before
    you enter another DCL command. The /NOWAIT qualifier allows
    you to enter new commands while the subprocess is running.
    (Use the /OUTPUT qualifier with the /NOWAIT qualifier to avoid
    displaying both parent and subprocess output on the terminal
    simultaneously.)

    Note that specifying the /NOWAIT qualifier causes both input and
    output to be shared with the parent process. If the input device
    is a terminal, control characters, such as Ctrl/T or Ctrl/Y,
    also affect all subprocesses sharing the input device. The Ctrl/Y
    control character, for example, interrupts all such subprocesses.

    This problem may be avoided by specifying /INPUT=NL:.

3  –  Example

  $ RUN MYPROG
        .
        .
        .

  $ <Ctrl/Y>
  $ SPAWN MAIL
  %DCL-S-SPAWNED, process SKONETSKI_272 spawned
  %DCL-S-ATTACHED, terminal now attached to process SKONETSKI_272
  MAIL> READ
     .
     .
     .
  MAIL> EXIT
  %DCL-S-RETURNED, control returned to process SKONETSKI
  $ CONTINUE

      The SPAWN command in this example allows you to enter the
      OpenVMS Mail utility (MAIL) without terminating the currently
      running program. After you exit from Mail, control is returned
      to the parent process.
Close Help