Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

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

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

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

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

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5932PRO_038.HTML