Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Programming Concepts Manual


Previous Contents Index


Chapter 8
Using Cross-Reference Routines

The cross-reference routines are contained in a separate, shareable image capable of creating a cross-reference analysis of symbols. They accept cross-reference data, summarize it, and format it for output. Two facilities that use the cross-reference routines are the VMS Linker and the MACRO assembler. They are sufficiently general, however, to be used by any native-mode utility.

Table 8-1 lists the entry points and functions of the cross-reference routines.

Table 8-1 Cross-Reference Routines
Entry Point Function
LIB$CRF_INS_KEY Insert key information
LIB$CRF_INS_REF Insert reference information
LIB$CRF_OUTPUT Summarize and format 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.

8.1 How to Use the Cross-Reference Routines

Using the cross-reference routines 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. Specify the end of each set of macros that define a field in the output line, using the $CRFFIELDEND macro.
  4. Provide data by calling one of the two following cross-reference entry points:
  5. Call LIB$CRF_OUTPUT, the cross-reference output routine, to summarize and format the data.
  6. Supply a routine that the output routine 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.

Figure 8-1 illustrates the steps required in using the cross-reference routines.

Figure 8-1 Using Cross-Reference Routines


The Run-Time Library provides three macros to initialize the data structures used by the cross-reference routines:

  1. $CRFCTLTABLE defines a table of control information.
  2. $CRFFIELD defines each field of the output format definition table. Multiple $CRFFIELD macro instructions can be issued in defining one particular field.
  3. $CRFFIELDEND ends a set of $CRFFIELD macro instructions (a format table).

8.2 $CRFCTLTABLE Macro

$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 

label

The address of the control table. You must specify a control table address in all calls to the cross-reference routines.

keytype

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

output

The address of the routine that you supply to print a formatted output line. The output line is passed to the output routine by descriptor.

error

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

memexp

The number of pages by which to expand region when needed. The default is 50.

key1table

The 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 $CRFCTLTABLE macro.

8.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 VMS System Services Reference Manual. The $CRFFIELD macro has the following format:

label: $CRFFIELD   bit_mask, fao_string, field_width, 
                set_clear 

label

The 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_mask

A 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_string

The $FAO command string. LIB$CRF_OUTPUT uses this string to determine the $FAO format when formatting this field for output.

field_width

The maximum width of the output field.

set_clear

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

8.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:

$CRFFIELDEND 

8.5 Cross-Reference Output

LIB$CRF_OUTPUT can format output lines for three types of cross-reference listings:

  1. A summary of symbol names and their values, as illustrated in Figure 8-2.
  2. A summary of symbol names, their values, and the names of modules that refer to the symbol, as illustrated in Figure 8-3.
  3. A summary of symbol names, their values, the name of the defining module, and the names of those modules that refer to the symbol, as illustrated in Figure 8-4.

Figure 8-2 Summary of Symbol Names and Values


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


Figure 8-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:

  1. KEY1 is the first field in the line. It contains a symbol name.
  2. KEY2 is the second field in the line. It contains a set of flags (for example,--R) providing information about the symbol.
  3. VAL1 is the third field in the line. It contains the value of the symbol.
  4. VAL2 is the fourth field in the line. It contains a set of flags describing VAL1.
  5. 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.

Figure 8-5 shows that any of these fields can be omitted from the output.

Figure 8-5 Output Line for LIB$CRF_OUTPUT


8.6 Example

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.

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

8.6.2 Inserting Table Information

After initializing the format data for the symbol tables, the linker enters data into the cross-reference tables by calling LIB$CRF_INS_KEY.

As the linker processes the first object module, MAPINITIAL, it encounters a symbol definition for $MAPFLG. The following is an example of a call to enter the symbol MAPINITIAL as a key in the cross-reference symbol table:


        PUSHAB    VALUE_FLAGS 
        PUSHAB    VALUE_ADDR 
        PUSHAB    SYMBOL_ADDR 
        PUSHAB    LNK$NAMTAB 
        CALLS     #4,G^LIB$CRF_INS_KEY 
LNK$NAMTAB Is the address of the control table
SYMBOL_ADDR Is the address of the counted ASCII string $MAPFLG
VALUE_ADDR Is the address of the symbol value
VALUE_FLAGS Is the address of a word whose bits are used to select special characters to print beside the value

The linker then calls LIB$CRF_INS_REF to process the defining reference indicator:


DEF:    .LONG     CRF$K_DEF 
        PUSHAB    DEF 
        PUSHAB    REF_FLAGS 
        PUSHAB    REF_ADDR 
        PUSHAB    SYMBOL_ADDR 
        PUSHAB    LNK$NAMTAB 
        CALLS     #5,G^LIB$CRF_INS_REF 
LNK$NAMTAB Is the address of the control table
SYMBOL_ADDR Is the address of the counted string $MAPFLG
REF_ADDR Is the address of the referrer's counted ASCII string
REF_FLAGS Is the address of a word whose bits are used to select special characters to print beside the reference

Further on in the input module, the linker encounters a global symbol reference to CS$GBL. The call to store data for this reference is as follows:


REF:      .LONG     CRF$K_REF 
          PUSHAB    REF 
          PUSHAB    REF_FLAGS 
          PUSHAB    REF_ADDR 
          PUSHAB    SYMBOL_ADDR 
          PUSHAB    LNK$NAMTAB 
          CALLS     #5,G^LIB$CRF_INS_REF 

The arguments are similar to the previous example, except for CRF$K_REF, which indicates that this is not the defining reference.

After it has performed symbol relocation for the module being linked, the linker calls LIB$CRF_INS_REF to build a table ordered by value.


        PUSHAB    REF 
        PUSHAB    REF_FLAGS 
        PUSHAB    REF_ADDR 
        PUSHAB    VAL_ADDR 
        PUSHAB    LNK$VALTAB 
        CALLS     #5,G^LIB$CRF_INS_REF 
LNK$VALTAB Is the address of the control table for the symbol synopsis by value
VAL_ADDR Is the address of the value (binary longword key)
REF_ADDR Is the address of the symbol name having the value contained in VAL_ADDR
REF_FLAGS Is the address of a word whose bits are used to select special characters to print beside the value
CRF$K_REF Is the indicator that this is not a defining reference

8.6.3 Formatting Information for Output

After all input modules are processed, the linker requests the information for the map. It calls LIB$CRF_OUTPUT once for each type of output. The following MACRO example illustrates a call to list the symbols and their values. Three calls are illustrated here.


LNWID:  .LONG   132 
LNSP1:  .LONG   LINES_PAGE1 
LNSOP:  .LONG   LINES_OTHR_PAGE 
SAVE:   .LONG   CRF$K_SAVE 
VAL:    .LONG   CRF$K_VALUES 
        PUSHAB  VAL 
        PUSHAB  SAVE 
        PUSHAB  LNSOP 
        PUSHAB  LNSP1 
        PUSHAB  LNWID 
        PUSHAB  LNK$NAMTAB 
        CALLS   #6,G^LIB$CRF_OUTPUT 

In this example, CRF$K_VALUES means that no reference indicators are to be printed, while CRF$K_SAVE means that the cross-reference table is to be saved. It is also possible to list all cross-reference data. The type of output produced by this call is shown in Section 8.5, Figure 8-2.

The following call produces such a summary and releases the storage at the same time:


LNWID:  .LONG   132 
LNSP1:  .LONG   LINES_PAGE1 
LNSOP:  .LONG   LINES_OTHR_PAGE 
DELETE: .LONG   CRF$K_DELETE 
DEFREF: .LONG   CRF$K_DEF_REF 
        PUSHAB  DELETE 
        PUSHAB  DEFREF 
        PUSHAB  LNSOP 
        PUSHAB  LNSP1 
        PUSHAB  LNWID 
        PUSHAB  LNK$NAMTAB 
        CALLS   #6,G^LIB$CRF_OUTPUT 

The type of output produced by this call is shown in Section 8.5, Figure 8-4.

CRF$K_DEFS_REFS indicates that the first two reference fields are used for the defining references, and CRF$K_DELETE indicates that the table is deleted.

Another call is made to list the symbol by value synopsis, as follows:


LNWID:      .LONG     132 
LNSP1:      .LONG     LINES_PAGE1 
LNSOP:      .LONG     LINES_OTHR_PAGE 
VALREF:     .LONG     CRF$K_VALS_REF 
DELETE:     .LONG     CRF$K_DELETE 
            PUSHAB    DELETE 
            PUSHAB    VALREF 
            PUSHAB    LNSOP 
            PUSHAB    LNSP1 
            PUSHAB    LNWID 
            PUSHAB    LNK$VALTAB 
            CALLS     #6,G^LIB$CRF_OUTPUT 

This is similar to the previous call in that it produces a complete cross-reference output by value, but it does not have the defining reference fields.

8.7 How to Link to the Cross-Reference Shareable Image

The cross-reference routines are located in a shareable image CRFSHR.EXE. This shareable image is part of the default system shareable image library, SYS$LIBRARY:IMAGELIB.OLB. For this reason, the cross-reference routines are automatically included in your image, unless you specify /NOSYSHR in the LINK command. If you have specified /NOSYSHR and you want to include CRFSHR.EXE, your LINK command must include the following:


SYS$LIBRARY:IMAGELIB/INCLUDE=CRFSHR 


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5841PRO_022.HTML