HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

Specifying varying-AST-argument is meaningful only if the NOWAIT flags bit is set and if AST-address has been specified.

prompt-string

cli

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

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

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

The Return Virtual Memory Statistics routine returns to its caller one of six statistics available from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which formats the values for output and displays them on SYS$OUTPUT, LIB$STAT_VM returns the statistic in the value-argument argument. Only one of the statistics is returned by each call to LIB$STAT_VM.

Note No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$STAT_VM code ,value-argument

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

Code specifying which statistic is to be returned. The code argument contains the address of a signed longword integer that is this code.

Code	Statistic
1	Number of successful calls to LIB$GET_VM
2	Number of successful calls to LIB$FREE_VM
3	Number of bytes allocated by LIB$GET_VM but not yet deallocated by LIB$FREE_VM
5	Number of calls to LIB$GET_VM_PAGE
6	Number of calls to LIB$FREE_VM_PAGE
7	Number of VAX pages or Alpha pagelets allocated by LIB$GET_VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE

Note that it is invalid to omit code or to give a code of 0 or 4.

value-argument

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Value of the statistic returned by LIB$STAT_VM. The value-argument argument contains the address of an unsigned longword integer that is this value.

Description

LIB$STAT_VM returns to its caller one of six available statistics. Unlike LIB$SHOW_VM, which formats the values for output, LIB$STAT_VM returns the value to a location specified as an argument.

Only one of the six statistics can be returned by one call to LIB$STAT_VM. The argument code must be one of six values described for LIB$SHOW_VM. A code value of 0 or 4 is invalid.

Unlike LIB$SHOW_VM, which produces ASCII values for output, LIB$STAT_VM returns the value in binary form to a location specified as an argument.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument. The value of code was not one of the values allowed by LIB$STAT_VM.

The Return Virtual Memory Statistics routine returns to its caller one of six statistics available from calls to LIB$GET_VM_64 and LIB$FREE_VM_64, as well as LIB$GET_VM_PAGE_64 and LIB$FREE_VM_PAGE_64. Unlike LIB$SHOW_VM_64, which formats the values for output and displays them on SYS$OUTPUT, LIB$STAT_VM_64 returns the statistic in the value-argument argument. Only one of the statistics is returned by each call to LIB$STAT_VM_64.

Format

LIB$STAT_VM_64 code ,value-argument

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

code

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	read only
mechanism:	by reference

Code specifying which statistic is to be returned. The code argument contains the address of a signed quadword integer that is this code.

Code	Statistic
1	Number of successful calls to LIB$GET_VM_64
2	Number of successful calls to LIB$FREE_VM_64
3	Number of bytes allocated by LIB$GET_VM_64 but not yet deallocated by LIB$FREE_VM_64
5	Number of calls to LIB$GET_VM_PAGE_64
6	Number of calls to LIB$FREE_VM_PAGE_64
7	Number of Alpha or I64 pagelets allocated by LIB$GET_VM_PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64

Note that it is invalid to omit code or to give a code of 0 or 4.

value-argument

OpenVMS usage:	user_arg
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

Value of the statistic returned by LIB$STAT_VM_64. The value-argument argument contains the address of an unsigned quadword integer that is this value.

Description

LIB$STAT_VM_64 returns to its caller one of six available statistics. Unlike LIB$SHOW_VM_64, which formats the values for output, LIB$STAT_VM_64 returns the value to a location specified as an argument.

Only one of the six statistics can be returned by one call to LIB$STAT_VM_64. The code argument must be one of six values described for LIB$SHOW_VM_64. A code value of 0 or 4 is invalid.

Unlike LIB$SHOW_VM_64, which produces ASCII values for output, LIB$STAT_VM_64 returns the value in binary form to a location specified as an argument.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument. The value of code was not one of the values allowed by LIB$STAT_VM_64.