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 VSI
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.
The DCL_CTLFLAGS is a bitmask used to alter default behavior
for certain commands on a systemwide basis. Currently, only
the low bit of the bitmask is defined. The low bit controls the
default process-name assignment for a subprocess created using
the LIB$SPAWN routine.
Prior to OpenVMS Version 7.3-1, if no process name was supplied,
the system constructed a name by appending _n to the username,
where n was the next available non-duplicate 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.
Beginning in OpenVMS Version 7.3-1, the default constructed
process name for subprocesses has changed. Instead of
incrementally searching for the next unique number, a random
number is chosen to append to the username. Therefore, the first
processes that are spawned from user SYSTEM might be SYSTEM_154,
SYSTEM_42, SYSTEM_87, and so on. This procedure results in a
very high probability of finding a unique number on the first try
since it is unlikely the same number is already in use.
However, some applications might rely on the previous method
of assigning subprocess names. The DCL_CTLFLAGS parameter is
available to allow you to configure the system as necessary.
Bit 0 of DCL_CTLFLAGS selects the behavior for assigning default
subprocess names, as explained in the following:
o If clear, the new behavior is used. If the process name is
not specified, it will be the username with a random number
suffix. This is the default setting.
o If set, the previous behavior is used. If the process name is
not specified, it will be the username with the next available
number suffix.
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.