 |
HP OpenVMS RTL Library (LIB$) Manual
HP OpenVMS RTL Library (LIB$) Manual
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:
- Define a table of control information using the $CRFCTLTABLE macro.
- Define each field of the output line using the $CRFFIELD macro.
- Using the $CRFFIELDEND macro, specify the end of each set of macros
that define a field in the output line.
- 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.
- 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 HP 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$CVTS_FROM_INTERNAL_TIME (Alpha and I64 Only)
The Convert Internal Time to External Time (IEEE S-Floating-Point
Value) routine converts a delta internal OpenVMS system time into an
external IEEE S-floating time.
Format
LIB$CVTS_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: |
IEEE S_floating |
| access: |
write only |
| mechanism: |
by reference |
The external time that results from the conversion. The
resultant-time argument is the address of an IEEE
S-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$CVTS_FROM_INTERNAL_TIME converts a delta internal OpenVMS system
time into an external IEEE S-floating-point time. The
operation argument specifies the conversion.
LIB$CVTS_FROM_INTERNAL_TIME converts the value of
input-time into one of the external formats listed in
the operation argument description.
LIB$CVTS_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.
|
