OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$SET_SYMBOL

The Set Value of CLI Symbol routine requests the calling process's command language interpreter (CLI) to define or redefine a CLI symbol.

Format

LIB$SET_SYMBOL symbol ,value-string [,table-type-indicator]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

symbol

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Name of the symbol to be defined or modified by LIB$SET_SYMBOL. The symbol argument is the address of a descriptor pointing to this symbol string. If you redefine a previously defined CLI symbol, the symbol value is modified to the new value that you provide.
The symbol name is converted to uppercase and trailing blanks are removed before use. The symbol argument must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters.
value-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Value to be given to the symbol. The value-string argument is the address of a descriptor pointing to this value string.
Trailing blanks are not removed from the value string before use. The maximum length of value-string is 1024 characters. Integer values are not allowed; LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI symbols.

table-type-indicator

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Indicator of the table that will contain the defined symbol. The table-type-indicator argument is the address of a signed longword integer that is this table indicator.
If omitted, the local symbol table is used. The following are possible values for table-type-indicator:

Symbolic Name Value Table Used

LIB$K_CLI_LOCAL_SYM 1 Local symbol table

LIB$K_CLI_GLOBAL_SYM 2 Global symbol table

Symbolic Name	Value	Table Used
LIB$K_CLI_LOCAL_SYM	1	Local symbol table
LIB$K_CLI_GLOBAL_SYM	2	Global symbol table

Description

LIB$SET_SYMBOL requests the calling process's CLI to define or redefine a CLI symbol.
CLI symbols created using LIB$SET_SYMBOL may be inaccessible by other CLI commands. To avoid this situation, make sure that your symbol names are alphanumeric and that the first character is alphabetic. LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI symbols.
LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined as global symbols and in symbol libraries supplied by Compaq (macro or module name $LIBCLIDEF).
This routine is supported for use with the DCL CLI. If used with the MCR CLI, the error status LIB$_NOCLI will be 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 this case, the error status LIB$_NOCLI is returned.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_AMBSYMDEF Ambiguous symbol definition. The symbol name you want to define is ambiguous when compared with existing symbol names. This condition might arise if abbreviated symbols have been defined previously. See the OpenVMS DCL Dictionary for more information on abbreviated symbols.

LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.

LIB$_INSCLIMEM Insufficient CLI memory. The CLI could not get enough virtual memory to assign another symbol. This condition may be caused by having too many symbols defined; deleting some symbol definitions may make enough room for the new symbol.

LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.

LIB$_INVARG Invalid argument. The value of table-type-indicator was invalid or the length of value-string was greater than 1024 characters.

LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.

LIB$_INVSYMNAM Invalid symbol name. The length of symbol was greater than 255 characters or symbol did not begin with a letter.

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.

LIB$_UNECLIERR Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL command language interpreter, please report the problem to your Compaq support representative.

Example


!+ ! Initialize value and symbol name !- SYMBOL$ = 'MY_SYM' SETVAL$ = 'ON' CALL LIB$SET_SYMBOL (SYMBOL$, SETVAL$) END

The BASIC program above sets the symbol MY_SYM to ON. This value can be displayed after the program is run with SHOW SYMBOL as follows:
$ SHOW SYMBOL MY_SYM "MY_SYM" = "ON" (LNM$PROCESS_TABLE)

LIB$SFREE1_DD

The Free One Dynamic String routine returns the dynamically allocated storage for a dynamic string.

Format

LIB$SFREE1_DD descriptor-address

Corresponding JSB Entry Point
LIB$SFREE1_DD6

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

descriptor-address

OpenVMS usage: descriptor

type: quadword (unsigned)

access: modify

mechanism: by reference

Dynamic descriptor specifying the area to be deallocated. The descriptor-address argument is the address of an unsigned quadword that is this descriptor. The descriptor is assumed to be dynamic and its class field is not checked.

Description

Before a routine deallocates a dynamic descriptor, it must use LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage space specified by the dynamic descriptor. Otherwise, string storage is not deallocated and your program can run out of memory.
This routine deallocates the described string space and flags the descriptor as describing no string at all. The descriptor's POINTER and LENGTH fields contain zero (0).

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB Fatal internal error.

LIB$SFREEN_DD

The Free One or More Dynamic Strings routine returns one or more dynamic strings to free storage.

Format

LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array

Corresponding JSB Entry Point
LIB$SFREEN_DD6

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

number-of-descriptors

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

Number of adjacent descriptors freed by LIB$SFREEN_DD. The number-of-descriptors argument contains the address of an unsigned longword that is this number. The deallocated area is returned to free storage.
first-descriptor-array

OpenVMS usage: descriptor_array

type: quadword (unsigned)

access: modify

mechanism: by reference, array reference

First descriptor of an array of descriptors. The first-descriptor-array argument contains the address of this first descriptor. The descriptors are assumed to be dynamic, and their class fields are not checked.
The descriptor array must contain all 32-bit descriptors or all 64-bit descriptors. They cannot be mixed.

Description

Before a routine that allocates space returns to its caller, it must use LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage space specified by any descriptors located in the stack. Otherwise, space is not deallocated and your program could run out of virtual memory.
LIB$SFREEN_DD deallocates the described string space and flags each descriptor as describing no string at all by setting the descriptor's POINTER and LENGTH fields to 0 (zero).

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB Fatal internal error.

LIB$SGET1_DD

The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify.

Format

LIB$SGET1_DD word-integer-length ,descriptor-part

Corresponding JSB Entry Point
LIB$SGET1_DD_R6

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

word-integer-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: read only

mechanism: by reference

Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_DD. The word-integer-length argument is the address of an unsigned word that contains this number. The amount of storage allocated may be rounded up automatically.
descriptor-part

OpenVMS usage: quadword_unsigned

type: quadword (unsigned)

access: write only

mechanism: by reference

Descriptor of the dynamic string to which LIB$SGET1_DD allocates the dynamic virtual memory. The descriptor-part argument contains the address of this descriptor.
The descriptor-part argument must contain the address of a dynamic string descriptor; LIB$SGET1_DD returns an unpredictable result if any other type of descriptor is specified by this argument.
The descriptor CLASS field is not checked but is set to dynamic (2). The LENGTH field is set to word-integer-length, and the POINTER field points to the string area allocated.

Description

LIB$SGET1_DD is similar to LIB$SCOPY_DXDX except that no source string is copied. You can write anything you want in the allocated area.
If descriptor-part already has dynamic memory allocated to it, but the amount allocated is less than word-integer-length, that space is deallocated before LIB$SGET1_DD allocates new space.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.

LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.

LIB$SGET1_DD_64 (Alpha Only)

The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify.

Format

LIB$SGET1_DD_64 quad-integer-length ,descriptor-part

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

quad-integer-length

OpenVMS usage: quadword_unsigned

type: quadword (unsigned)

access: read only

mechanism: by reference

Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_DD_64. The quad-integer-length argument is the address of an unsigned quadword that contains this number. The amount of storage allocated can be rounded up automatically.
descriptor-part

OpenVMS usage: quadword_unsigned

type: quadword (unsigned)

access: write only

mechanism: by reference

Descriptor of the dynamic string to which LIB$SGET1_DD_64 allocates the dynamic virtual memory. The descriptor-part argument contains the address of this descriptor.
The descriptor-part argument must contain the address of a dynamic string descriptor; LIB$SGET1_DD_64 returns an unpredictable result if any other type of descriptor is specified by this argument.
The descriptor CLASS field is not checked but is set to dynamic (2). The LENGTH field is set to quad-integer-length, and the POINTER field points to the string area allocated.

Description

LIB$SGET1_DD_64 is similar to LIB$SCOPY_DXDX except that no source string is copied. You can write anything you want in the allocated area.
If descriptor-part already has dynamic memory allocated to it, but the amount allocated is less than quad-integer-length, that space is deallocated before LIB$SGET1_DD_64 allocates new space.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.

LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.

LIB$SHOW_TIMER

The Show Accumulated Times and Counts routine returns times and counts accumulated since the last call to LIB$INIT_TIMER and displays them on SYS$OUTPUT. (LIB$INIT_TIMER must be called prior to invoking this routine.) A user-supplied action routine may change this default behavior.

Format

LIB$SHOW_TIMER [handle-address] [,code] [,user-action-procedure] [,user-argument-value]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

handle-address

OpenVMS usage: address

type: longword (unsigned)

access: read only

mechanism: by reference

Block of storage containing the value returned by a previous call to LIB$INIT_TIMER. The handle-address argument is the address of an unsigned longword integer containing that value.

If specified, the pointer must be the same value returned by a previous call to LIB$INIT_TIMER.
If omitted, LIB$SHOW_TIMER will use a block of memory allocated by LIB$INIT_TIMER.
If handle-address is omitted and LIB$INIT_TIMER has not been called previously, the error LIB$_INVARG is returned. LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_TIMER.

LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously called, and that the results of that call are stored either in a block pointed to by handle-address, or in the memory allocated by LIB$INIT_TIMER.
code

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Integer specifying the statistic you want; if it is omitted or zero, all five statistics are returned on one line. The code argument is the address of a signed longword integer containing the statistic code.
The following values are allowed for the code argument:

Value Description

1 Elapsed time

2 CPU time

3 Buffered I/O

4 Direct I/O

5 Page faults

user-action-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied action routine called by LIB$SHOW_TIMER. The default action of LIB$SHOW_TIMER is to write the results to SYS$OUTPUT. An action routine is useful if you want to write the results to a file or, in general, anywhere other than SYS$OUTPUT.
The action routine returns either a success or failure condition value; this status is returned to the calling program as the value of LIB$SHOW_TIMER.
user-argument-value

OpenVMS usage: user-arg

type: longword (unsigned) (on VAX systems)
quadword (unsigned) (on Alpha systems)

access: read only

mechanism: by value

A value to be passed to the action routine without interpretation. If omitted, LIB$SHOW_TIMER passes a zero by value to the user routine.

Value	Description
1	Elapsed time
2	CPU time
3	Buffered I/O
4	Direct I/O
5	Page faults

Description

LIB$SHOW_TIMER returns the times and counts accumulated since the last call to LIB$INIT_TIMER. By default, when neither code nor user-action-procedure is specified in the call, LIB$SHOW_TIMER writes to SYS$OUTPUT a line giving the following information:

Shown on Line Description

ELAPSED = dddd hh:mm:ss.cc Elapsed real time

CPU = hhhh:mm:ss.cc Elapsed CPU time

BUFIO = nnnn Count of buffered I/O operations

DIRIO = nnnn Count of direct I/O operations

PAGEFAULTS = nnnn Count of page faults

Any one or all five statistics can be written to SYS$OUTPUT or passed to your user-supplied action routine for other processing.
Call Format for an Action Routine

Action routine is a user-supplied routine called by LIB$SHOW_TIMER. The action routine is used when you want to write results to anywhere other than SYS$OUTPUT. The action routine is called only when you specify the user-action-procedure argument in the call to LIB$SHOW_TIMER.
LIB$SHOW_TIMER calls the action routine using this format:

user-action-procedure out-str [,user-argument-value]

out-str

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Fixed-length string containing the statistics requested. The string is formatted exactly as it would be if written to SYS$OUTPUT. The leading character is blank.
user-argument-value

OpenVMS usage: user-arg

type: longword (unsigned) (on VAX systems)
quadword (unsigned) (on Alpha systems)

access: read only

mechanism: by value

A value passed to LIB$SHOW_TIMER. The user argument is passed without interpretation to the action routine.

Shown on Line	Description
ELAPSED = dddd hh:mm:ss.cc	Elapsed real time
CPU = hhhh:mm:ss.cc	Elapsed CPU time
BUFIO = nnnn	Count of buffered I/O operations
DIRIO = nnnn	Count of direct I/O operations
PAGEFAULTS = nnnn	Count of page faults

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_INVARG Invalid argument. Either code or handle-address was invalid.

Any condition values returned by LIB$PUT_OUTPUT or your action routine.

Example


PROGRAM SHOW_TIMER(INPUT,OUTPUT); {+} { This Pascal example demonstrates how to use LIB$SHOW_TIMER. {-} VAR RETURNED_STATUS : INTEGER; [EXTERNAL] FUNCTION LIB$INIT_TIMER( HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0 ) : INTEGER; EXTERNAL; [EXTERNAL] FUNCTION LIB$SHOW_TIMER( HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0; CODE : INTEGER; [IMMEDIATE,UNBOUND] ROUTINE ACTION_RTN( OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; USER_ARG : INTEGER) := %IMMED 0; USER_ARG : INTEGER := %IMMED 0 ) : INTEGER; EXTERNAL; [EXTERNAL] FUNCTION LIB$STOP( CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED ) : INTEGER; EXTERNAL; ROUTINE USER_ACTION_RTN( OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; USER_ARG : INTEGER); BEGIN WRITELN('User argument is ',USER_ARG:1); WRITELN(OUT_STR); END; 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$SHOW_TIMER to display counters. {-} RETURNED_STATUS := LIB$SHOW_TIMER(,0,USER_ACTION_RTN,5); END.

PROGRAM SHOW_TIMER(INPUT,OUTPUT); 
 
{+} 
{ This Pascal example demonstrates how to use LIB$SHOW_TIMER. 
{-} 
 
    VAR 
        RETURNED_STATUS : INTEGER; 
 
    [EXTERNAL] FUNCTION LIB$INIT_TIMER( 
          HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0 
          ) : INTEGER; EXTERNAL; 
 
    [EXTERNAL] FUNCTION LIB$SHOW_TIMER( 
          HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0; 
          CODE       : INTEGER; 
          [IMMEDIATE,UNBOUND] 
            ROUTINE ACTION_RTN( OUT_STR  : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
                                  USER_ARG : INTEGER) := %IMMED 0; 
          USER_ARG   : INTEGER := %IMMED 0 
          ) : INTEGER; EXTERNAL; 
 
    [EXTERNAL] FUNCTION LIB$STOP( 
          CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
          FAO_ARGS         : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 
          ) : INTEGER; EXTERNAL; 
 
    ROUTINE USER_ACTION_RTN( 
          OUT_STR  : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
          USER_ARG : INTEGER); 
 
          BEGIN 
          WRITELN('User argument is ',USER_ARG:1); 
          WRITELN(OUT_STR); 
          END; 
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$SHOW_TIMER to display counters. 
{-} 
 
RETURNED_STATUS := LIB$SHOW_TIMER(,0,USER_ACTION_RTN,5); 
END.

Previous Next Contents Index

privacy and legal statement

5932PRO_038.HTML

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

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_AMBSYMDEF	Ambiguous symbol definition. The symbol name you want to define is ambiguous when compared with existing symbol names. This condition might arise if abbreviated symbols have been defined previously. See the OpenVMS DCL Dictionary for more information on abbreviated symbols.
LIB$_FATERRLIB	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.
LIB$_INSCLIMEM	Insufficient CLI memory. The CLI could not get enough virtual memory to assign another symbol. This condition may be caused by having too many symbols defined; deleting some symbol definitions may make enough room for the new symbol.
LIB$_INSVIRMEM	Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.
LIB$_INVARG	Invalid argument. The value of table-type-indicator was invalid or the length of value-string was greater than 1024 characters.
LIB$_INVSTRDES	Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
LIB$_INVSYMNAM	Invalid symbol name. The length of symbol was greater than 255 characters or symbol did not begin with a letter.
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.
LIB$_UNECLIERR	Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL command language interpreter, please report the problem to your Compaq support representative.

OpenVMS usage:	descriptor
type:	quadword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	descriptor_array
type:	quadword (unsigned)
access:	modify
mechanism:	by reference, array reference

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

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

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

OpenVMS usage:	user-arg
type:	longword (unsigned) (on VAX systems) quadword (unsigned) (on Alpha systems)
access:	read only
mechanism:	by value