HP OpenVMS DCL Dictionary

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]

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.

Description

The SPAWN command creates a subprocess of your current process with the following attributes copied from the parent process:

All global symbols except $RESTART, $SEVERITY, $STATUS
All local symbols defined for the current command procedure level
Key definitions
The current keypad state
The current prompt string
All process logical names and logical name tables except those explicitly marked CONFINE or those created in executive or kernel mode
Default disk and directory
Current SET MESSAGE settings
Current process privileges
Control and verification states

Note that some attributes, such as the process's current command tables, are not copied.
When the subprocess is created, the process-permanent open files and any image or procedure context are not copied from the parent process. The subprocess is set to command level 0 (DCL level with the current prompt).
If you do not specify the /PROCESS qualifier, the name of this subprocess is composed of a portion of the parent process name and a unique number. For example, if the parent process name is SKONETSKI, the subprocess names can be SKONETSKI_123, SKONETSKI_4732, and so on.
The LOGIN.COM file of the parent process is not executed for the subprocess because the context is copied separately, allowing quicker initialization of the subprocess. When the /WAIT qualifier is in effect, the parent process remains in hibernation until the subprocess terminates or returns control to the parent by way of the ATTACH command.
More than one process simultaneously attempts to use the same input or output stream in the following circumstances:

When several processes share that stream and you terminate a subprocess to which you are not currently attached
When you terminate a process that is not spawned from the process to which you are currently attached

You should use the LOGOUT command to terminate the subprocess and return to the parent process. You can also use the ATTACH command to transfer control of the terminal to another process in the subprocess tree, including the parent process. (The SHOW PROCESS/SUBPROCESSES command displays the processes in the subprocess tree and points to the current process.)

Note
Because a tree of subprocesses can be established using the SPAWN command, you must be careful when terminating any process in the tree. When a process is terminated, all subprocesses below that point in the tree are terminated automatically.

Qualifiers used with the SPAWN command must directly follow the command verb. The command string parameter begins after the last qualifier and continues to the end of the command line.

Qualifiers

/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.
/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.
/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.
/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 systemwide limit set by the MULTITHREAD parameter.
/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.
/LOG (default)

/NOLOG
Displays the assigned subprocess name and any messages indicating transfer of control between processes.
/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.
/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.
/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.
/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.
/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 HP OpenVMS System Management Utilities Reference Manual for more information.

/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.
/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.
/TABLE=command-table
Specifies the name of an alternate command table to be used by the subprocess.
/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 HP OpenVMS Guide to System Security.
/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:.

Process Type	SYS$INPUT	Implicit Input
Interactive	NRO PPF	SYS$COMMAND
Noninteractive	NRO PPF	Null device
Any	Any other	SYS$INPUT

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

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

$ 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.

Contents

Index