Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## 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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_042.HTML