 |
OpenVMS RTL Library (LIB$) Manual
LIB$SPAWN
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]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
The subprocess created by LIB$SPAWN inherits the following attributes
from the caller's environment:
- Process logical names
- Global and local CLI symbols
- Default device and directory
- Process privileges
- Process nondeductible quotas
- Current command verification setting
The subprocess does not inherit process-permanent files nor routine or
image context.
Though the subprocess inherits the caller's process privileges as its
own process privileges, the set of authorized privileges in the
subprocess is inherited from the caller's current privileges. If the
calling image is installed with elevated privileges, these privileges
are not available to the the subprocess until a SET PROCESS/PRIVILEGE
command or equivalent $SETPRV call is performed in the subprocess to
enable these privileges.
If the calling image is installed with elevated privileges, it should
disable those privileges around the call to LIB$SPAWN unless the
environment of the subprocess is strictly controlled. Otherwise, there
is a possibility of a security breach due to elevated privileges
accidentally being made available to the user.
If neither command-string nor
input-file is present, command input is taken from the
parent terminal. If both command-string and
input-file are present, the subprocess first executes
command-string and then reads from
input-file. If only command-string is
specified, the command is executed, and the subprocess is terminated.
If input-file is specified, the subprocess is
terminated by either a LOGOUT command or an end-of-file.
The subprocess does not inherit process-permanent files nor routine or
image context. No LOGIN.COM file is executed.
Unless the NOWAIT flags bit is set, the caller's
process is put into hibernation until the subprocess finishes. Because
the caller's process hibernates in supervisor mode, any user-mode ASTs
queued for delivery to the caller are not delivered until the caller
reawakes. Control can also be restored to the caller by means of an
ATTACH command or by a suitable call to LIB$ATTACH from the subprocess.
This routine is supported for use only with the DCL command language
interpreter. If used when the current CLI is MCR, the error status
LIB$_NOCLI is returned.
If an image is run directly as a subprocess or as a detached process,
there is no CLI present to perform this function. In such cases, the
error status LIB$_NOCLI is returned.
Programs depending on embedded DCL commands may not function properly
when run under other command language interpreters that may be
supported by future versions of OpenVMS operating systems.
See the OpenVMS DCL Dictionary for a complete description of the SPAWN command.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_ACCVIO
|
Access violation. One of the string arguments to LIB$SPAWN could not be
read, or
completion-status-address could not be written.
|
|
SS$_DUPLNAM
|
Duplicate process name. If the argument
process-name was specified, it duplicated an existing
process name. If
process-name was omitted, LIB$SPAWN was unable to
create a unique name for the subprocess.
|
|
fac$_xxx
|
Other error trying to create subprocess.
|
|
LIB$_INVARG
|
Invalid argument. The optional argument
flags was specified, and a bit other than bits 0
through 8 was set.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. One of the string arguments had an invalid
descriptor.
|
|
LIB$_NOCLI
|
No CLI present to perform function. The calling process did not have a
CLI to perform the function, or the CLI did not support the request
type. Note that an image run as a subprocess or detached process does
not have a CLI.
|
If an error is encountered during subprocess creation, the status value
for that error is returned by LIB$SPAWN.
Example
|
ISTAT=LIB$SPAWN(,,,CLI$M_NOKEYPAD,,,,,,,'> ')
IF (.NOT. ISTAT) CALL LIB$STOP(%VAL(ISTAT))
|
This Fortran fragment shows a call to LIB$SPAWN from within a Fortran
program. A subprocess is spawned taking input from SYS$INPUT and giving
output to SYS$OUTPUT. The keypad state is not passed to the subprocess.
A prompt string of "> " is specified for the subprocess.
LIB$STAT_TIMER
The Statistics, Return Accumulated Times and Counts routine returns to
its caller one of five available statistics accumulated since the last
call to LIB$INIT_TIMER. Unlike LIB$SHOW_TIMER, which formats the values
for output, LIB$STAT_TIMER returns the value as an unsigned longword or
quadword.
Format
LIB$STAT_TIMER code ,value-argument [,handle-address]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
code
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
The address of a signed longword integer that contains a code to
specify the statistic to be returned. The code specification must be an
integer from 1 to 5.
The following values are allowed for code:
| Value |
Statistic Returned |
|
1
|
Elapsed real time (quadword, in system time format)
|
|
2
|
Elapsed CPU time (longword, in 10 millisecond increments)
|
|
3
|
Count of buffered I/O operations (longword)
|
|
4
|
Count of direct I/O operations (longword)
|
|
5
|
Count of page faults (longword)
|
value-argument
| OpenVMS usage: |
user_arg |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference |
The statistic returned by LIB$STAT_TIMER. The
value-argument argument contains the address of a
longword or quadword that is this statistic. All statistics are
longword integers except elapsed real time, which is a quadword.
See the OpenVMS System Services Reference Manual for more details on the system time format.
handle-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Pointer to a block of storage. The optional
handle-address argument contains the address of an
unsigned longword that is this pointer.
If handle-address is specified, LIB$STAT_TIMER assumes
that LIB$INIT_TIMER has been called with the same value of
handle-address. Handle-address is an
optional argument. If it is not specified, LIB$STAT_TIMER uses internal
storage.
Description
Only one of the five statistics is returned by each call to
LIB$STAT_TIMER. The elapsed time is returned in the system quadword
format. Therefore the receiving area should be eight bytes long. All
other returned values are longwords.
LIB$SHOW_TIMER and LIB$STAT_TIMER are relatively simple tools for
testing the performance of a new application. Note that LIB$INIT_TIMER
must be called prior to any calls to LIB$SHOW_TIMER or LIB$STAT_TIMER.
To obtain more detailed information, use LIB$GETJPI (Get Job/Process
Information) or the system service $GETTIM.
The following summary shows the differences between LIB$SHOW_TIMER and
LIB$STAT_TIMER:
| Code |
Statistic |
Format for
LIB$SHOW_TIMER |
Format for
LIB$STAT_TIMER |
|
1
|
Elapsed real time
|
hhhh:
mm:
ss.
cc
|
Quadword in system time format
|
|
2
|
Elapsed CPU time
|
hhhh:
mm:
ss.
cc
|
Longword in 10-millisecond increments
|
|
3
|
Count of buffered I/O operations
|
nnnn
|
Longword
|
|
4
|
Count of direct I/O operations
|
nnnn
|
Longword
|
|
5
|
Count of page faults
|
nnnn
|
Longword
|
When you call LIB$INIT_TIMER, you must use the optional
handle-address argument only if you want to keep
several sets of statistics simultaneously. This argument points to a
block in heap storage where the statistics are to be stored.
You need to call LIB$FREE_TIMER only if you have specified
handle-address in LIB$INIT_TIMER and you want to
deallocate all heap storage resources. In most cases, the implicit
deallocation at program exit time will be sufficient.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. Either
code or
handle-address is invalid.
|
Example
|
PROGRAM STAT_TIMER(INPUT,OUTPUT);
{+}
{ This Pascal example program demonstrates the use of
{ LIB$STAT_TIMER.
{-}
TYPE
BYTE = [BYTE] 0..255;
WORD = [WORD] 0..65535;
QUADWORD_SYSTEM_TIME = [QUAD] RECORD
FIRST_LONGWORD : UNSIGNED;
SECOND_LONGWORD : UNSIGNED;
END;
VAR
ELAPSED_REAL_TIME : QUADWORD_SYSTEM_TIME;
ELAPSED_STRING : VARYING [32] OF CHAR;
PAGE_FAULT_COUNT : UNSIGNED;
RETURNED_STATUS : UNSIGNED;
[EXTERNAL] FUNCTION LIB$INIT_TIMER(
HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0
) : INTEGER; EXTERNAL;
[EXTERNAL] FUNCTION LIB$STAT_TIMER(
CODE : INTEGER;
VALUE : [UNSAFE,REFERENCE] PACKED ARRAY [L..U:INTEGER] OF BYTE;
HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0
) : INTEGER; EXTERNAL;
[EXTERNAL] FUNCTION LIB$STOP(
CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED;
FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED
) : INTEGER; EXTERNAL;
[EXTERNAL] FUNCTION LIB$SYS_ASCTIM(
OUT_LEN : [REFERENCE] WORD := %IMMED 0;
VAR DST_STR : PACKED ARRAY [L..U:INTEGER] OF CHAR;
USER_TIME : QUADWORD_SYSTEM_TIME := %IMMED 0;
CNV_FLG : UNSIGNED := %IMMED 0
) : INTEGER; EXTERNAL;
BEGIN
{+}
{ Call LIB$INIT_TIMER to initialize RTL internal counters.
{-}
RETURNED_STATUS := LIB$INIT_TIMER;
IF NOT ODD(RETURNED_STATUS)
THEN
LIB$STOP(RETURNED_STATUS);
{+}
{ Print a line of text to waste time.
{-}
WRITELN('Spend time to acquire elapsed real time and page faults');
{+}
{ Call LIB$STAT_TIMER to retrieve statistics values.
{-}
RETURNED_STATUS := LIB$STAT_TIMER(1,ELAPSED_REAL_TIME);
IF NOT ODD(RETURNED_STATUS)
THEN
LIB$STOP(RETURNED_STATUS);
RETURNED_STATUS := LIB$STAT_TIMER(5,PAGE_FAULT_COUNT);
IF NOT ODD(RETURNED_STATUS)
THEN
LIB$STOP(RETURNED_STATUS);
{+}
{ Print the statistics retrieved from LIB$STAT_TIMER.
{-}
WRITELN('Page fault count is ',PAGE_FAULT_COUNT:1);
RETURNED_STATUS := LIB$SYS_ASCTIM(
ELAPSED_STRING.LENGTH,
ELAPSED_STRING.BODY,
ELAPSED_REAL_TIME,
1);
IF NOT ODD(RETURNED_STATUS)
THEN
LIB$STOP(RETURNED_STATUS);
WRITELN('Elapsed real time is ',ELAPSED_STRING);
END.
|
This Pascal program demonstrates the use of LIB$STAT_TIMER. The output
generated by this program is as follows:
Spend time to acquire elapsed real time and page faults
Page fault count is 22
Elapsed real time is 00:00:00.61
|
|
