HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
24.7.4 Inserting an Entry into a Balanced Binary Tree
The following BLISS example illustrates all three routines. The program prompts for input from SYS$INPUT and stores each data line as an entry in a binary tree. When the user enters the end-of-file character (Ctrl/Z), the tree is printed in sorted order. The program includes three subroutines:
|LIB$CRF_INS_KEY||Inserts key information|
|LIB$CRF_INS_REF||Inserts reference information|
|LIB$CRF_OUTPUT||Summarizes and formats cross-reference information|
The interface to the cross-reference routines is by way of a set of
control blocks, format definition tables, and a set of callable entry
points. Macros are provided for assembly language and BLISS
initialization of the control blocks and format definition tables.
25.1 How to Use the Cross-Reference Routines
Figure 25-1 illustrates the steps required in using the cross-reference routines.
Figure 25-1 Using Cross-Reference Routines
The Run-Time Library provides three macros to initialize the data structures used by the cross-reference routines:
$CRFCTLTABLE initializes a cross-reference control table. Your program must issue one $CRFCTLTABLE macro for each cross-reference table you build. You can accumulate information for more than one cross-reference table at a time. For this reason, you must define a table for each set of cross-references, and include the address of that table each time you call a cross-reference routine to insert data.
The $CRFCTLTABLE macro instruction has the following format:
label: $CRFCTLTABLE keytype, output, error, memexp, key1table, key2table, val1table, val2table, ref1table, ref2table
labelThe address of the control table. You must specify a control table address in all calls to the cross-reference routines.
keytypeThe type of key to enter into the table. The following key types are defined:
ASCIC Keys are counted ASCII strings, with a maximum of 31 characters (symbol name). BIN_U32 Keys are 32-bit unsigned binary values. The binary-to-ASCII conversion is done by $FAO using the format string for the KEY1 field.
outputThe address of the routine that you supply to print a formatted output line. The output line is passed to the output routine by descriptor.
errorThe address of an error routine to execute if the called cross-reference routine encounters an error. The error code (longword) is passed to the error routine by value. In other words, it is a copy of the constant on the stack. A value of zero indicates that no error routine is supplied.
memexpThe number of pages by which to expand region when needed. The default is 50.
key1tableThe address of the field descriptor table for the KEY1 field. A value of zero indicates that the field is not to be included in the output line.
The remaining arguments provide the address of the field descriptor
tables for the KEY2, VAL1, VAL2, REF1, and REF2 fields, respectively,
of the output line. You can use these argument names as keywords in the
macros. For example, you can use KEYTYPE as a keyword when issuing the
25.3 $CRFFIELD Macro
For each field in the output line, you must issue a $CRFFIELD instruction to identify the field, supply an $FAO command string to control the printing of the field, and provide flag information. See the program example and the description of $FAO (formatted ASCII output) in the OpenVMS System Services Reference Manual. The $CRFFIELD macro has the following format:
label: $CRFFIELD bit_mask, fao_string, field_width, set_clear
labelThe address of the field descriptor table generated as a result of this set of $CRFFIELD macro instructions. The label field can be omitted after the first macro of the set. These addresses correspond to the field descriptor table addresses in the $CRFCTLTABLE macro.
bit_maskA 16-bit mask. When the user enters a key or reference, the cross-reference routine stores flag information with the entry. When preparing the output line, LIB$CRF_OUTPUT performs an AND operation on the 16-bit mask in the field descriptor table with the flag stored with the entry. Any number of bit masks can be defined for a field. $CRFFIELD macro instructions are used to define multiple bit patterns for a flag field. The high-order bit is reserved to the cross-reference routines.
fao_stringThe $FAO command string. LIB$CRF_OUTPUT uses this string to determine the $FAO format when formatting this field for output.
field_widthThe maximum width of the output field.
set_clearThe indicator used to determine whether the bit mask is to be tested as set or clear when determining which flag to use. SET indicates test for set; CLEAR indicates test for clear.
You can use the argument names shown here as keywords in your program.
In the following example, one bit pattern is defined twice; once indicating a string that is to be printed if the pattern is set, and once indicating that spaces are to appear if the pattern is clear.
$CRFFIELD BIT_MASK=SYM$M_REL, FAO_STRING=3_\##_\,- SET_CLEAR=CLEAR, FIELD_WIDTH=2 $CRFFIELD BIT_MASK=SYM$M_REL, FAO_STRING=_\-R_\,- SET_CLEAR=SET, FIELD_WIDTH=2
If more than one set of flags is defined for a field, each FAO string must print the same number of characters; otherwise, the output is not aligned in columns.
The fields for the symbol name, symbol value, and references are always
formatted using the first descriptor in the corresponding table.
25.4 $CRFFIELDEND Macro
The $CRFFIELDEND macro instruction marks the end of a set of macros that describe one field of the output line. It is used once to end each set of field descriptors. It has the following format:
LIB$CRF_OUTPUT can format output lines for three types of cross-reference listings:
Figure 25-2 Summary of Symbol Names and Values
Figure 25-3 Summary of Symbol Names, Values, and Name of Referring Modules
Figure 25-4 Summary Indicating Defining Module
Regardless of the format of the output, LIB$CRF_OUTPUT considers the output line to consist of the following six different field types:
Figure 25-5 shows that any of these fields can be omitted from the output.
Figure 25-5 Output Line for LIB$CRF_OUTPUT
The VAX Linker uses the cross-reference routines to generate
cross-reference listings. This section uses the linker's code as an
example of using the cross-reference routines in a MACRO program.
25.6.1 Defining Control Tables
Cross-reference routines use two control tables:
First, the linker uses the $CRFCTLTABLE macro to set up the characteristics and fields of the symbol-by-name table. This table will list symbols by name and provide a cross-reference synopsis. The table is set up as follows:
LNK$NAMTAB: $CRFCTLTABLE KEYTYPE=ASCIC,ERROR=LNK$ERR_RTN,_ OUTPUT=LNK$MAPOUT,KEY1TABLE=LNK$KEY1,_ KEY2TABLE=LNK$KEY2,VAL1TABLE=LNK$VAL1,_ VAL2TABLE=LNK$VAL2,REF1TABLE=LNK$REF1,_ REF2TABLE=LNK$REF2
|LNK$NAMTAB||Names the address of the control table|
|KEYTYPE=ASCIC||Specifies that the keys are counted ASCII strings (that is, symbol names)|
|ERROR=LNK$ERR_RTN||Indicates that LNK$ERR_RTN is the address of the routine to be executed in case of error|
|OUTPUT=LNK$MAPOUT||Names LNK$MAPOUT as the address of the user-supplied routine that prints the formatted table|
The remaining arguments provide the addresses of the field descriptor tables.
After setting up the control tables, the linker defines each field of the cross-reference output line, using the $CRFFIELD macro. After each set of definitions for a field, it calls $CRFFIELDEND to mark the end of the field.
Note particularly the following two features of this set of definitions:
LNK$KEY1: $CRFFIELD BIT_MASK=0, FAO_STRING=\!15AC\,- SET_CLEAR=SET,FIELD_WIDTH=15 $CRFFIELDEND LNK$KEY2: $CRFFIELD BIT_MASK=0,FAO_STRING=\ \,- SET_CLEAR=SET, FIELD_WIDTH=1 $CRFFIELDEND LNK$VAL1: $CRFFIELD BIT_MASK=0,FAO_STRING=\!XL\,- SET_CLEAR=SET,FIELD_WIDTH=8 $CRFFIELDEND LNK$VAL2: $CRFFIELD BIT_MASK=0, FAO_STRING=\!2* \,- SET_CLEAR=SET,FIELD_WIDTH=2 $CRFFIELD BIT_MASK=SYM$M_REL,FAO_STRING=\-R\,- SET_CLEAR=SET,FIELD_WIDTH=2 $CRFFIELD BIT_MASK=SYM$M_DEF, FAO_STRING=\-*\,- SET_CLEAR=CLEAR,FIELD_WIDTH=2 $CRFFIELDEND LNK$REF1: $CRFFIELD BIT_MASK=0,FAO_STRING=\!6* \,- SET_CLEAR=SET,FIELD_WIDTH=6 $CRFFIELD BIT_MASK=SYM$M_WEAK,FAO_STRING=\!3* WK-\,- SET_CLEAR=SET,FIELD_WIDTH=6 $CRFFIELDEND LNK$REF2: $CRFFIELD BIT_MASK=0,FAO_STRING=\!16AC\,- SET_CLEAR=SET,FIELD_WIDTH=16 $CRFFIELDEND
After initializing the symbol-by-name table, the linker sets up a second control table. This table defines the output for a symbol-by-value synopsis. For this output, the value fields are eliminated. The symbols having this value are entered as reference indicators. None is specified as the defining reference. The control table uses the field descriptors set up previously. The following macro instructions are used:
LNK$VALTAB: $CRFCTLTABLE KEYTYPE=BIN_U32, ERROR=LNK$ERR_RTN,- OUTPUT=LNK$MAPOUT,KEY1TABLE=LNK$VAL1,- KEY2TABLE=LNK$VAL2,VAL1TABLE=0,- VAL2TABLE=0,REF1TABLE=LNK$REF1,- REF2TABLE=LNK$REF2