10 Cross-Referencer

This chapter provides an overview of the Cross-Referencer's features and capabilities. For more detailed information on how to use this tool, choose Help: On Cross-Referencer. You can print Help topics using the HyperHelp Viewer.

The Cross-Referencer queries a target for a specified program symbol and displays the source file name and line number of each occurrence along with other information about the symbol. You can use the Cross-Referencer to:

Locate the lines of source code that declare or use specified program symbols and bring up the Editor focused on one of these lines

Find the type and attributes of specified program symbols

Figure Figure 10-1 shows the Cross-Referencer main window.

Figure 10-1: Cross-Referencer Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area: Displays the current project and data directory from which the program symbol information is derived.
Query definition area: Presents fields that you can use to specify your query and to filter query results. The filters available depend on the query type that you selected.
Query results area: Lists programming symbols of the type selected that match filter information.
Information area: Displays information messages and Quick Help on menu items when you press and hold MB1 on the item.

10.1 Summary of Features

You can use the Cross-Referencer to:

Access source location information for program symbols

Specify names as literals, regular expressions, or identifiers

Constrain query based on file, declaration class, declaration type, or caller

See the active query results area
- Click once to see lines
- Double click to see source

Recall queries for reissue or refinement

Provide integration with the Call Graph Browser and editors

10.2 Requirements for Using the Cross-Referencer

The Cross-Referencer generates query results based on information in a static analysis database. The Database Manager (see Chapter 11) creates and maintains the static analysis database using static analysis data files generated by the Builder. See Section Section 4.8 and the online Help topic Generating Static Analysis Data as Part of the Build for information on creating a static analysis database.

Before using the Cross-Referencer, make sure of the following:

All the files are available.

All disks containing source and intermediate files are mounted and available.

You have configured the browser tools using the Project Manager dialog box (Browser Tools Settings Category). Note that, because of the existence of default settings, this is not an absolute requirement. However, you will likely want to edit the defaults to customize the static analysis database generation and to make sure the compiler macros are consistent with your environment.
See Chapters Chapter 9 and Chapter 11 for more information on configuring a project and the browser tools.

You used the Builder (or some other build mechanism) to generate static analysis data during a build of your target application.

10.3 Starting the Cross-Referencer

You can start the Cross-Referencer tool in several ways:

Use the command line.

If you have CDE installed, use the Cross-Referencer icon.

Use the FUSE Control Panel once FUSE is running.

Use the Tools menu from most FUSE tools.

10.3.1 Use the Command Line

You can start the Cross-Referencer from the command line using the following command:

% fusexref [Xt-Options]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the Cross-Referencer is placed in the current project. Whenever you start a browser tool, you minimally need a working directory specified for the project. The browser inherits its working directory from the project.

Until you have a static analysis database, the Cross-Referencer cannot show any data. You can specify a Data Directory to contain the static analysis database and associated files. You also should check the default properties in the Project Manager dialog box (Browser Tools Settings Category) before you generate static analysis data from your source files. See the online Help topic Generating Static Analysis Data as Part of the Build for details on creating a static analysis database.

10.3.2 Use the Cross-Referencer Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To invoke the Cross-Referencer:

Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

Double click on the FUSE application group icon to display the icons in the FUSE application group.

Double click on the Cross-Referencer icon to start the tool.

10.3.3 Use the FUSE Control Panel

To start Cross-Referencer from the FUSE Control Panel, select Cross-Referencer from the Tools menu.

10.3.4 Use the Tools Menu from Most FUSE Tools

Most FUSE tools have a Tools menu. To start a tool, select the tool from the Tools menu.

10.4 Updating the Cross-Referencer Data

If the underlying static analysis data files change, most likely as a result of a new build, you can update the data in the Cross-Referencer by choosing Database: Update.

When you modify the source code for the application currently displayed in the Cross-Referencer, you can update the graph only after regenerating new static analysis data files, typically using features in the Builder.

For example, suppose you changed a source file while viewing cross reference data for your program. You can update the data only by rebuilding the application, typically in the Builder with the Generate Static Analysis Data button toggled on (or using some other build mechanism that generates the static analysis data). You can then choose Update from the Database menu.

10.5 Issuing a Query

To issue a query with the Cross-Referencer:

Step	Action
1	Choose a query type.
2	Fill in the fields in the query definition area to refine the search.
3	Click on the Issue Query button.

When you issue the query, each occurrence of the symbols that match the search criteria is listed in the query results area.

As soon as you issue the first query, the Recall... button is activated. As long as you do not exit the Cross-Referencer, you can recall any query and reissue it.

Each time you issue a query, the Cross-Referencer accumulates the results in the query results area. You can clear all previous query results by clicking on the Clear button near the bottom of the Cross-Referencer window.

10.5.1 Choosing a Query Type

The Query options menu allows you to choose the type of query you want to issue. The Cross-Referencer modifies the fields presented in the query definition area, depending on the type you choose. If you do not fill in any of the fields in the query definition area, no filtering is done and all occurrences of the specified query type are displayed.

Table Table 10-1 lists and briefly describes query types.

Table 10-1: Query Types

This type... Searches for...

Declaration

Declarations of any symbol (variable, language type, macro, or routine).

Reference

References to any symbol (variable, language type, macros, or routine). References that are also assignments are marked with an asterisk in the Line # column.

Assignment

Assignments to variables.

Function

Definitions of routines.

Call

Calls to routines.

This type...	Searches for...
Declaration	Declarations of any symbol (variable, language type, macro, or routine).
Reference	References to any symbol (variable, language type, macros, or routine). References that are also assignments are marked with an asterisk in the Line # column.
Assignment	Assignments to variables.
Function	Definitions of routines.
Call	Calls to routines.

10.5.2 Specifying Search Patterns for Symbol Names

You can filter names by specifying a search pattern in the Name field and setting the accompanying options menu to the appropriate pattern type, as summarized in Table Table 10-2.

Table 10-2: Search Pattern Types

When options menu is set to...

Search pattern in Name field is interpreted as...

Expression

A regular expression. Use any syntax valid for the egrep(1) command.

Identifier

An expression type that improves searching for identifiers in C++ programs. Results vary by query type. For example, a Reference query using the search patternfoo.* would find foo::member, class::foo, foo(), and class::foo(arglist), but a Declaration query using the same search pattern would not find foo::member (which is a declaration of member, not of foo).

Literal

A literal string. Only exact matches (including case) are found.

Any Case

A case-insensitive literal string.

When options menu is set to...	Search pattern in Name field is interpreted as...
Expression	A regular expression. Use any syntax valid for the `egrep(1)` command.
Identifier	An expression type that improves searching for identifiers in C++ programs. Results vary by query type. For example, a Reference query using the search pattern`foo.*` would find `foo::member`, `class::foo, foo(),` and `class::foo(arglist)`, but a Declaration query using the same search pattern would not find `foo::member` (which is a declaration of member, not of `foo`).
Literal	A literal string. Only exact matches (including case) are found.
Any Case	A case-insensitive literal string.

Figure Figure 10-2 compares the results of two declaration queries. In the one on the left, Animal was used as an expression; on the right, Animal was used as an identifier.

Figure 10-2: Comparison of Declaration Queries in a C++ Program

10.6 Issuing a Declaration Query

To issue a Declaration query to search for the declaration of any symbol (for example, a variable name, language type, macro, or routine):

Step	Action
1	Choose Declaration from the Query: options menu.
2	In the query definition area, click on the Name: field and enter a search pattern. Use the accompanying options menu to specify the search pattern type (see Table Table 10-2).
3	To see declarations from a specific file, click on the File: field and enter the name of the file.
4	To restrict the query to a specific line of a file, click on the Line: field and enter the line number.
5	To restrict the query to a particular data type, click on the Type: field and enter a search pattern. Set the options menu to one of the search pattern types, summarized in Table Table 10-2.
6	You can further refine which declaration class to search for by using the Language and Classification options menus. The class options vary depending on the language option you choose. If you choose the default, All Languages, only classes common to all languages supported by FUSE are available. Table Table 10-3 shows how the common classes map to declaration classes in the languages supported by FUSE. You can further refine which declaration class to search for by using the Language and Classification options menus.
7	Click on Issue Query to issue the query and start the search.

10.7 Issuing a Reference Query

To issue a Reference query to search for references to any symbol:

Step	Action
1	Choose Reference from the Query: options menu.
2	In the query definition area, click on the Name: field and enter a search pattern. Use the accompanying options menu to specify the search pattern type (see Table Table 10-2).
3	To see references from a specified file, click on the File: field and enter the name of the file.
4	To see references on a specific line of a file, click on the Line: field and enter the line number.
5	Click on Issue Query to issue the query and start the search.

References to assignments are marked with an asterisk (*) in the Line # column.

Table 10-3: Common Classifications Mapped to Supported Languages

Classification

Language

Declaration

C

Enumeration constant, named constant

COBOL

Alphabet, class, condition name, switch, symbolic character

FORTRAN-77

Parameter constant

FORTRAN-90

Parameter constant

Pascal

Enumeration literal, symbolic constant

C++

Enumeration constant, named constant

Ada

Enumeration literal, named number

Macro definition

C

cpp macro definition

C

Function

COBOL

Intrinsic function, program

FORTRAN-77

Statement function, subroutine, function

FORTRAN-90

Statement function, subroutine, function

Pascal

Function, procedure

C++

Function

Ada

Function, procedure

C

Parameter

COBOL

Argument

FORTRAN-77

Subprogram argument

FORTRAN-90

Subprogram argument

Pascal

Routine parameter

C++

Function parameter

Ada

Routine parameter

C

Auto, extern, register, static

COBOL

File, group, elementary item

FORTRAN-77

Variable

FORTRAN-90

Variable

Pascal

Variable (declarations in the VAR section)

C++

Auto, extern, register, static

Ada

Object

C

User-defined types (for example, struct, enum, union declarations)

FORTRAN-77

User-defined types (for example, structure declarations)

FORTRAN-90

User-defined types (for example, structure declarations)

Pascal

User-defined types (declarations in the TYPE section)

C++

User-defined types (for example, class, struct, enum, union declarations)

Ada

User-defined types (for example, type and subtype declarations)

Classification	Language	Declaration
C	Enumeration constant, named constant
COBOL	Alphabet, class, condition name, switch, symbolic character
FORTRAN-77	Parameter constant
FORTRAN-90	Parameter constant
Pascal	Enumeration literal, symbolic constant
C++	Enumeration constant, named constant
Ada	Enumeration literal, named number
Macro definition	C	`cpp` macro definition
C	Function
COBOL	Intrinsic function, program
FORTRAN-77	Statement function, subroutine, function
FORTRAN-90	Statement function, subroutine, function
Pascal	Function, procedure
C++	Function
Ada	Function, procedure
C	Parameter
COBOL	Argument
FORTRAN-77	Subprogram argument
FORTRAN-90	Subprogram argument
Pascal	Routine parameter
C++	Function parameter
Ada	Routine parameter
C	Auto, extern, register, static
COBOL	File, group, elementary item
FORTRAN-77	Variable
FORTRAN-90	Variable
Pascal	Variable (declarations in the VAR section)
C++	Auto, extern, register, static
Ada	Object
	C	User-defined types (for example, struct, enum, union declarations)
FORTRAN-77	User-defined types (for example, structure declarations)
FORTRAN-90	User-defined types (for example, structure declarations)
Pascal	User-defined types (declarations in the TYPE section)
C++	User-defined types (for example, class, struct, enum, union declarations)
Ada	User-defined types (for example, type and subtype declarations)

10.8 Issuing an Assignment Query

To issue an Assignment query to search variable assignments:

Step	Action
1	Choose Assignment from the Query: options menu.
2	Click on the Name: field and enter the name of the variable or a search pattern. Use the accompanying options menu to specify the search pattern type (see Table Table 10-2).
3	To see references from a specific file, click on the File: field and enter the name of the file.
4	To see references in a specific line of a file, click on the Line: field and enter the line number.
5	Click on Issue Query to issue the query and start the search.

10.9 Issuing a Function Query

To issue a Function query to search for routine definitions:

Step	Action
1	Choose Function from the Query: options menu.
2	Click on the Name: field and enter the name of the routine or a search pattern. Use the accompanying options menu to specify the search pattern type (see Table Table 10-2).
3	To see references from a specific file, click on the File: field and enter the name of the file.
4	To see references in a specific line of a file, click on the Line: field and enter the line number.
5	Click on Issue Query to issue the query and start the search.

10.10 Issuing a Call Query

To issue a Call query to search for calls to routines:

Step	Action
1	Choose Function from the Query: options menu.
2	Click on the Name: field and enter the name of the routine or a search pattern. Use the accompanying options menu to specify the search pattern type (see Table Table 10-2).
3	Click on the From Name: field and enter the name of the routine from which the call is made, or enter a search pattern. Use the associated options menu to specify the type of search pattern you entered in the From Name: field.
4	To see references from a specific file, click on the File: field and enter the name of the file.
5	To see references in a specific line of a file, click on the Line: field and enter the line number.
6	Click on Issue Query to issue the query and start the search.

10.11 Reviewing Query Results

Located below the query definition area is the Cross-Referencer query results area, which displays the results of queries. After you issue a search for a symbol, the Cross-Referencer displays each occurrence of the symbol (if any are found) in the query results area. For each occurrence, it displays the name of the symbol, the use of that symbol, the name of the source file, and the source code line number where the symbol occurs.

The query results area contains two lists. The wide list on the left displays the:

Symbol name

Symbol's declaration, parameters, or caller, depending on the query type

Name of the source file containing the symbol

The List # column displays the source file line numbers where the currently highlighted symbol exists. As you select different symbols, each symbol's line numbers are displayed in the list on the right.

To view the source code associated with a particular symbol occurrence, double click on the symbol or the line number. The relevant source file is brought up in the FUSE Editor or Emacs (after starting up the editor, if necessary). The editor's focus is brought to the specific line shown by the Cross-Referencer, and the line is marked with a colored icon.

10.12 Reissuing Previous Queries

You can reissue a previously issued query by using the Recall Query dialog box, as shown in Figure Figure 10-3.

Figure 10-3: Recall Query Dialog Box

To reissue a query you issued during the current session:

Step	Action
1	Click on the Recall... button in the Cross-Referencer main window.
2	Select the query you want to reissue by clicking on its definition in the Recall Query dialog box.
3	Click on OK to set the fields in the query definition area and to remove the Recall query dialog box.
4	Click on Issue Query in the Cross-Referencer main window.

10.13 Finding Occurrences of a String in the Query Results Area

To find occurrences of a particular string in the query results area:

Step	Action
1	Click on Find... at the bottom of the query results area. The Find dialog box appears.
2	Enter a string in the Search For: field. The options menu under this field allows you to specify whether the string to search for is a regular expression, a literal string, or a case-insensitive literal string. When you specify Regular Expression, the search pattern can contain any syntax valid for the `egrep(1)` command.
3	Click on Forward or Backward, depending on the direction in which you want to conduct the search, then click on Find Next. The search begins at the currently highlighted symbol in the query results area and continues backward or forward until the beginning or end of the display. When the Wrap Around check button is on, the search continues until the starting point is reached. If the specified string is found, the symbol is highlighted and is visible in the query results area. If the string is not found, you hear a beep.
4	Click on Find Again (in the Cross-Referencer main window) or Find Next (in the Find dialog box) to find the next occurrence of the specified string in the query results area.

10.14 Resetting the Query Definition Area

To empty all fields in the query definition area, click on the Reset button.

10.15 Using the Cross-Referencer with Other Tools

The Cross-Referencer works with the Call Graph Browser, the FUSE Editor, and Emacs.

To view the source code for a symbol listed in the query results area, double click on that symbol to display the associated source code in the FUSE Editor or Emacs. (The editor is invoked if it is not already running.)

If the Call Graph Browser is running in the same project, when you double click on a symbol in the Cross-Referencer query results area, the corresponding node is displayed in the call graph.

When editing a file with the FUSE Editor or Emacs, you can select a symbol in the editor's buffer and invoke the Cross-Referencer to locate the declaration of or references to the selected symbol. See Sections Section 13.5.11 and Section 13.5.12 for information on invoking the Cross-Referencer from an editor.