Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$CRF_INS_REF

> The Insert Reference to a Key in the Cross-Reference Table routine inserts a reference to a key in a cross-reference symbol table.

> 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$CRF_INS_REF control-table ,longword-integer-key ,reference-string ,longword-integer-reference ,ref-definition-indicator

### RETURNS

> None.

### Arguments

> #### control-table

> OpenVMS usage: | vector_longword_signed
> type: | longword integer (signed)
> access: | read only
> mechanism: | by reference, array reference

> Control table associated with this cross-reference. The control-table argument is the address of an array containing the control table.

> #### longword-integer-key

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

> Key referred to by LIB$CRF_INS_REF. The longword-integer-key argument is the address of a signed longword integer containing the key. The key is a counted ASCII string that contains a symbol name or an unsigned binary longword. It must be a permanent address in the user's symbol table.

> #### reference-string

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

> Counted ASCII string with a maximum of 31 characters, not including the byte count. The reference-string argument is the address of a descriptor pointing to the counted ASCII string.

> #### longword-integer-reference

> OpenVMS usage: | longword_signed
> type: | longword integer (signed)
> access: | write only
> mechanism: | by reference

> The 16-bit value used in selecting the contents of the REF1 field. The longword-integer-reference argument is the address of a signed longword integer containing this value. When preparing the output line, LIB$CRF_OUTPUT uses longword-integer-reference and the bit mask in the field descriptor table to extract the data. The high-order bit of the word is reserved for LIB$CRF_INS_REF.

> #### ref-definition-indicator

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

> Reference/definition indicator that LIB$CRF_INS_REF uses to distinguish between a reference to a symbol and the definition of the symbol. The ref-definition-indicator argument is the address of a signed longword integer containing this indicator. The only difference between processing a symbol reference and a symbol definition is where LIB$CRF_INS_REF stores the information.

> The reference/definition indicator can have either of the following values:

> Symbolic Name | Description
> --- | ---
> CRF$K_REF | Reference to a symbol
> CRF$K_DEF | Definition of a symbol

### Description

> LIB$CRF_INS_REF inserts a reference to a key in the cross-reference symbol table. If you attempt to insert reference information for a key that was not specified in a call to LIB$CRF_INS_KEY, LIB$CRF_INS_REF uses the address of the key to locate the symbol name and set the KEY1 field. Once set, either as a result of LIB$CRF_INS_KEY or LIB$CRF_INS_REF, the KEY1 field is never changed. A KEY1 field set by LIB$CRF_INS_REF has a space-filled VAL1 field associated with it unless it is overridden by a subsequent call to LIB$CRF_INS_KEY.

> Using LIB$CRF_INS_REF involves the following steps:

> 1. Define a table of control information using the $CRFCTLTABLE macro.
> 2. Define each field of the output line using the $CRFFIELD macro.
> 3. Using the $CRFFIELDEND macro, specify the end of each set of macros that define a field in the output line.

> 4. Provide data by calling LIB$CRF_INS_REF to insert a reference to a key in the specified symbol table. This data is used to build tables in virtual memory.
> 5. Call LIB$CRF_OUTPUT, the cross-reference output routine, to summarize and format the data. Supply a routine that LIB$CRF_OUTPUT calls to print each line in the output file. Because you supply this routine, you can control the number of lines per page and the header lines.

### Condition Values Returned

> None.

## LIB$CRF_OUTPUT

> The Output Cross-Reference Table Information routine extracts the information from the cross-reference tables and formats the output pages.

> 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$CRF_OUTPUT control-table ,output-line-width ,page1 ,page2 ,mode-indicator ,delete-save-indicator

### RETURNS

> None.

### Arguments

> #### control-table

> OpenVMS usage: | vector_longword_signed
> type: | longword integer (signed)
> access: | read only
> mechanism: | by reference, array reference

> Control table associated with the cross-reference. The control-table argument is the address of an array containing the control table. The table contains the address of the user-supplied routine that prints the lines formatted by LIB$CRF_OUTPUT.

> #### output-line-width

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

> Width of the output line. The output-line-width argument is the address of a signed longword integer containing the width.

> #### page1

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

> Number of lines on the first page of the output. The page1 argument is the address of a signed longword integer containing this number. This allows the user to reserve space to print header information on the first page of the cross-reference.

> #### page2

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

> Number of lines per page for the other pages. The page2 argument is the address of a signed longword integer containing this number.

> #### mode-indicator

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

> Output mode indicator. The mode-indicator argument is the address of a signed longword integer containing the mode indicator.

> This indicator allows the user to select which of three output modes is desired.

> Output Mode | Description
> --- | ---
> CRF$K_VALUES | Only the value and key fields are to be printed. LIB$CRF_OUTPUT creates multiple columns across the page. Each column consists of the KEY1, KEY2, VAL1, and VAL2 fields. A minimum of one space between each column is guaranteed.
> CRF$K_VALS_REFS | Requests a cross-reference summary that has no column space saved for a defining reference. If the user inserted a reference with the CRF$K_DEF indicator, the entry is ignored.
> CRF$K_DEFS_REFS | Requests a cross-reference summary with the first REF1 and REF2 fields used only for definition references. If no definition reference is provided, the fields are filled with spaces.

> #### delete-save-indicator

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

> Delete/save indicator, which LIB$CRF_OUTPUT uses to determine whether the table's built-in accumulating symbol information is to be saved or deleted once the cross-reference is produced. The delete-save-indicator argument is the address of a signed longword integer containing the delete/save indicator.

> The indicator can be either of the following:

> CRF$K_SAVE | To preserve the tables for subsequent processing
> CRF$K_DELETE | To delete the tables

### Description

> LIB$CRF_OUTPUT can format output lines for three types of cross-reference listings:
> - A summary of symbol names and their values, as shown in Figure lib-2.
> - A summary of symbol names, their values, and the names of modules that refer to each symbol, as shown in Figure lib-3.
> - A summary of symbol names, their values, the names of the defining modules, and the names of those modules that refer to each symbol, as shown in Figure lib-4.

> Figure lib-2 Summary of Symbol Names and Values

Figure lib-3 Summary of Symbol Names, Values, and Names of Referring Modules

Figure lib-4 Summary Indicating Defining Modules

Regardless of the format of the output, LIB$CRF_OUTPUT considers the output line as consisting of six different field types:

KEY1 | Is the first field in the line. It contains a symbol name.
KEY2 | Is the second field in the line. It contains a set of flags (for example, -R) that provide information about the symbol.
VAL1 | Is the third field in the line. It contains the value of the symbol.
VAL2 | Is the fourth field in the line. It contains a set of flags describing VAL1.
REF1 and REF2 fields | Within each REF1 and REF2 pair, REF1 provides a set of flags, and REF2 provides the name of a module that references the symbol.

Any of these fields can be omitted from the output.

For example:

    Symbol        Value           Symbol          Value
    ------        -----           ------          -----
    BAS$INSTR     000020B0-RU     BAS$SCRATCH     00002308-RU

    KEY1          VAL1    VAL2     KEY1           VAL1    VAL2

    Symbol          Value          Defined By     Referenced By ...
    ------          -----          ----------     -----------------
    LIB$FREE_VM     0001E185-R     LIB$VM         ALLGBL

    KEY1            VAL1   VAL2     REF2           REF2
                                    (CRF$K_DEF)    (CRF$K_REF)

### Condition Values Returned

> None.

## LIB$CURRENCY

> The Get System Currency Symbol routine returns the system's currency symbol.

### Format

> LIB$CURRENCY currency-string [,resultant-length]

### RETURNS

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

### Arguments

> #### currency-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Currency symbol. The currency-string argument is the address of a descriptor pointing to the currency symbol.

> #### resultant-length

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> Number of characters that LIB$CURRENCY has written into the currency-string argument, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word containing the length of the currency symbol. If the input string is truncated to the size specified in the currency-string argument, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of currency-string.

### Description

> LIB$CURRENCY attempts to translate the logical name SYS$CURRENCY as a process, group, or system logical name, in that order. If the translation fails, the routine returns the United States currency symbol ($). If the translation succeeds, the text produced is returned. Thus, a system manager can define SYS$CURRENCY as a systemwide logical name to provide a default for all users, and an individual user with a special need can define SYS$CURRENCY as a process logical name to override the system default.

> For example, if you want to use the British pound sign (£) as the currency symbol within your process but you want to leave the dollar sign as the system's default, define SYS$CURRENCY to be the pound sign in your process logical name table. After this, any call to LIB$CURRENCY within your process returns the pound sign (£), while any call outside your process returns the dollar sign ($).

### 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$_INVSTRDES | Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
> LIB$_STRTRU | Successfully completed, but the currency string was truncated.

### Example

    10 !+
       ! This BASIC program uses LIB$CURRENCY to
       ! return the default system currency symbol.
       !-

       OUTLEN = 1
       CALL LIB$CURRENCY (CURR$, OUTLEN)
       PRINT CURR$
    99 END

> This BASIC program uses LIB$CURRENCY to display the system currency symbol default. The output generated by the program is a dollar sign ($).

## LIB$CVTF_FROM_INTERNAL_TIME

> The Convert Internal Time to External Time (F-Floating-Point Value) routine converts a delta internal OpenVMS system time into an external F-floating time.

### Format

> LIB$CVTF_FROM_INTERNAL_TIME operation ,resultant-time ,input-time

### RETURNS

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

### Arguments

> #### operation

> OpenVMS usage: | function_code
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following:

> Operation | Interpretation
> --- | ---
> LIB$K_DELTA_WEEKS_F | Fractional weeks
> LIB$K_DELTA_DAYS_F | Fractional days
> LIB$K_DELTA_HOURS_F | Fractional hours
> LIB$K_DELTA_MINUTES_F | Fractional minutes
> LIB$K_DELTA_SECONDS_F | Fractional seconds

> #### resultant-time

> OpenVMS usage: | floating_point
> type: | F_floating
> access: | write only
> mechanism: | by reference

> The external time that results from the conversion. The resultant-time argument is the address of an F-floating-point value containing the result.

> #### input-time

> OpenVMS usage: | date_time
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> Delta time to be converted. The input-time argument is the address of an unsigned quadword containing the time.

### Description

> LIB$CVTF_FROM_INTERNAL_TIME converts a delta internal OpenVMS system time into an external F-floating-point time. The operation argument specifies the conversion. LIB$_CVTF_FROM_INTERNAL_TIME converts the value of input-time into one of the external formats listed in the operation argument description. LIB$_CVTF_FROM_INTERNAL_TIME then places the result into resultant-time.

### Condition Values Returned

> LIB$_NORMAL | Routine successfully completed.
> LIB$_DELTIMREQ | Delta time required but absolute time supplied.
> LIB$_INVOPER | Invalid operation.
> LIB$_IVTIME | Invalid time.
> LIB$_WRONUMARG | Incorrect number of arguments.

## LIB$CVTF_TO_INTERNAL_TIME

> The Convert External Time to Internal Time (F-Floating-Point Value) routine converts an external time interval into an OpenVMS internal format F-floating delta time.

### Format

> LIB$CVTF_TO_INTERNAL_TIME operation ,input-time ,resultant-time

### RETURNS

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

### Arguments

> #### operation

> OpenVMS usage: | function_code
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following:

> Operation | Interpretation
> --- | ---
> LIB$K_DELTA_WEEKS_F | Fractional weeks
> LIB$K_DELTA_DAYS_F | Fractional days
> LIB$K_DELTA_HOURS_F | Fractional hours
> LIB$K_DELTA_MINUTES_F | Fractional minutes
> LIB$K_DELTA_SECONDS_F | Fractional seconds

> #### input-time

> OpenVMS usage: | varying_arg
> type: | F_floating
> access: | read only
> mechanism: | by reference

> Delta time to be converted. The input-time argument is the address of this input time. The value you supply for input-time must be greater than 0.

> #### resultant-time

> OpenVMS usage: | date_time
> type: | quadword (unsigned)
> access: | write only
> mechanism: | by reference

> The OpenVMS internal format delta time that results from the conversion. The resultant-time argument is the address of an unsigned quadword containing the result.

### Description

> LIB$CVTF_TO_INTERNAL_TIME converts an external time interval, such as 3.5 weeks, into an OpenVMS internal format F-floating delta time. The operation argument specifies the conversion. LIB$_CVTF_TO_INTERNAL_TIME converts the value of input-time into one of the internal format delta times listed in the operation argument description. LIB$_CVTF_TO_INTERNAL_TIME then places the result into resultant-time.

### Condition Values Returned

> LIB$_NORMAL | Routine successfully completed.
> LIB$_INVOPER | Invalid operation.
> LIB$_IVTIME | Invalid time.
> LIB$_WRONUMARG | Incorrect number of arguments.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_007.HTML