6 Using the Cross-Reference Callable Interface

The cross-reference callable interface described in this chapter enables you to integrate a language scanner or compiler into the FUSE static analysis database.

Using the callable interface, a language scanner or compiler can generate cross-reference data at runtime to store declarations, symbol references, assignments, function definitions, calls, and C++ class and member definitions. This information can then be queried by the FUSE tools that access the static analysis database - for example, the Cross-Referencer, Call Graph Browser, and C++ Class Browser.

The callable interface makes it possible for you to store the cross-reference information provided by a language scanner or compiler into the static analysis database without requiring you to know the actual format of the database.

Section 6.1 describes how to use the cross-reference callable interface. Section 6.2 provides reference information on each cross-reference routine, in alphabetical order.

6.1 Using the Callable Interface

Your main task in using the callable interface is to program your scanner or compiler to issue the appropriate cross-reference calls as it processes source code during a cross-referencing session. (It is up to you to determine at what stage of processing your scanner or compiler should issue cross-reference calls.)

A cross-referencing session consists of scanning the source code of a program, statement by statement, and generating cross-reference calls for each source file, declaration, symbol reference, assignment, call, function definition, and C++ class and member definition.

For example, consider the following declaration at line 37 of a C source file:

int width;

This can be associated with a cross-reference call such as the following:

FUSE_XREF_Declaration(<session_context>,37,"width",DFXREF_CC_VARIABLE,"int",DFXREF_NOMODIFIERS);

The code resulting from this call is written to either stdout or to an intermediate data file, and it is then made available to the FUSE static analysis database.

Table 6-1 lists the cross-reference routines by function, with a summary description of each.

The following sections briefly describe the key points in using these routines. For complete details on each routine, see Section 6.2.

Your scanner or compiler must precede any calls with the following line:

#include "fuse_xref.h"

Table 6-1: Cross-Reference Routines

Routine Description

FUSE_XREF_SessionBegin Starts a cross-referencing session.

FUSE_XREF_FileBegin Marks the start of a file whose contents are to be cross-referenced.

FUSE_XREF_ScopeBegin Marks the start of a new scope for cross-references.

FUSE_XREF_Declaration Creates a declaration cross-reference.

FUSE_XREF_Reference Creates a symbol cross-reference.

FUSE_XREF_Call Creates a call cross-reference.

FUSE_XREF_SubroutineBegin Marks the start of a procedure or function definition.

FUSE_XREF_SubroutineEnd Marks the end of a procedure or function definition.

FUSE_XREF_ClassBegin Marks the start of a C++ class definition.

FUSE_XREF_Member Creates a cross-reference for a C++ class member definition.

FUSE_XREF_ClassEnd Marks the end of a C++ class definition.

FUSE_XREF_ScopeEnd Marks the end of a scope for cross- references.

FUSE_XREF_FileEnd Marks the end of a file whose contents have been cross-referenced.

FUSE_XREF_SessionEnd Ends a cross-referencing session.

Routine	Description
FUSE_XREF_SessionBegin	Starts a cross-referencing session.
FUSE_XREF_FileBegin	Marks the start of a file whose contents are to be cross-referenced.
FUSE_XREF_ScopeBegin	Marks the start of a new scope for cross-references.
FUSE_XREF_Declaration	Creates a declaration cross-reference.
FUSE_XREF_Reference	Creates a symbol cross-reference.
FUSE_XREF_Call	Creates a call cross-reference.
FUSE_XREF_SubroutineBegin	Marks the start of a procedure or function definition.
FUSE_XREF_SubroutineEnd	Marks the end of a procedure or function definition.
FUSE_XREF_ClassBegin	Marks the start of a C++ class definition.
FUSE_XREF_Member	Creates a cross-reference for a C++ class member definition.
FUSE_XREF_ClassEnd	Marks the end of a C++ class definition.
FUSE_XREF_ScopeEnd	Marks the end of a scope for cross- references.
FUSE_XREF_FileEnd	Marks the end of a file whose contents have been cross-referenced.
FUSE_XREF_SessionEnd	Ends a cross-referencing session.

6.1.1 Starting and Ending a Cross-Referencing Session

Before you can generate any cross-reference data from a set of source files, you must start a cross-referencing session with the FUSE_XREF_SessionBegin routine.

The FUSE_XREF_SessionBegin routine initializes context information that is used for all subsequent cross-reference calls for this session. The session_context parameter, which is passed to every call, is a pointer to this context information.

The FUSE_XREF_SessionBegin routine lets you specify whether the cross-reference data generated during the session should be directed to stdout or to an intermediate data file. To ensure compatibility with the FUSE static analysis database, use the file-naming conventions listed in the routine description in Section 6.2.

You end a cross-referencing session using the FUSE_XREF_SessionEnd routine.

6.1.2 Marking the Start and End of Source Files

Use the FUSE_XREF_FileBegin and FUSE_XREF_FileEnd routines to mark the start and end, respectively, of all source files as they are scanned.

These routine calls can be nested, as in the case of a C include file. For example:

/********    Start of file test.c at line 1  ********/
FUSE_XREF_FileBegin(session_context, "/usr/users/demo/test.c")
   .
   .
   .
#include "symb.h"     /*    Jump to file symb.h  */
              /********   Start of file symb.h at line 1  ********/
FUSE_XREF_FileBegin(session_context, "usr/users/demo/symb.h")
   .
   .
   .
/*    End of file symb.h at line 23    */
FUSE_XREF_FileEnd(session_context, 23)
              /********    Return to file test.c  ********/
   .
   .
   .
/********    End of file test.c at line 143  ********/
FUSE_XREF_FileEnd(session_context, 143)

The FUSE_XREF_FileBegin routine marks a file as the current default file for subsequent cross-reference calls. When a nested file is closed, the nesting (outer) file becomes the current default file.

6.1.3 Marking the Start and End of Definitions and Scopes

Use the following cross-reference routines to mark the start and end of various definitions and scopes:

Routine	Description
FUSE_XREF_ScopeBegin	Marks the start of a new scope, such as a block, for cross-references.
FUSE_XREF_ScopeEnd	Marks the end of a scope for cross- references.
FUSE_XREF_SubroutineBegin	Marks the start of a procedure or function definition.
FUSE_XREF_SubroutineEnd	Marks the end of a procedure or function definition.
FUSE_XREF_ClassBegin	Marks the start of a C++ class definition.
FUSE_XREF_ClassEnd	Marks the end of a C++ class definition.

These routines serve two functions:

Like the FUSE_XREF_FileBegin and FUSE_XREF_FileEnd routines, they provide context information for any contained symbol declarations, references, and class member definitions.

They also mark each function definition, scope, and C++ class definition as a symbol (reference-type) cross-reference in the context information. This is equivalent to also issuing a FUSE_XREF_Reference call automatically for each scope, function definition, and class definition. See Section 6.1.5.2.

6.1.4 Terminating Definitions, Scopes, and Files

Follow these conventions for using the routines that terminate definitions, scopes, and files:

You must start and close a definition or scope within the same file. For example, a FUSE_XREF_SubroutineBegin must be followed by the corresponding FUSE_XREF_SubroutineEnd within the same file. Similarly with ..._ ScopeBegin and ..._ScopeEnd, ..._ClassBegin and ..._ ClassEnd. Thus, a definition must not extend into an included file.

A FUSE_XREF_FileEnd call implicitly performs a FUSE_XREF_SubroutineEnd, FUSE_XREF_ScopeEnd, or FUSE_XREF_ClassEnd call if necessary to close any definition or scope that was not closed explicitly. However, you should not rely on this feature.

6.1.5 Marking Declarations and Symbol References

Use the following routines to create cross-reference information for declarations, symbol references, calls, and C++ class member definitions:

Routine	Description
FUSE_XREF_Declaration	Creates a declaration cross-reference.
FUSE_XREF_Reference	Creates a symbol cross-reference.
FUSE_XREF_Call	Creates a call cross-reference.
FUSE_XREF_Member	Creates a cross-reference for a C++ class member definition.

6.1.5.1 Using the FUSE_XREF_Declaration Routine

Use the FUSE_XREF_Declaration routine to create a declaration cross-reference.

For example, consider the following function declaration at line 29 of a C source file:

int switch(i,j);

This can be associated with the following declaration cross-reference call:

FUSE_XREF_Declaration(<session_context>,29,"switch",DFXREF_CC_FUNCTION,"int",DFXREF_NOMODIFIERS);

The FUSE_XREF_Declaration routine automatically creates a symbol reference in addition to the declaration cross- reference.

For complete information about the FUSE_XREF_Declaration routine parameters, see the routine description in Section 6.2.

6.1.5.2 Using the FUSE_XREF_Reference Routine

Use the FUSE_XREF_Reference routine to create a symbol (reference-type) cross-reference.

For example, consider the following reference to the variable x at line 43 of a C source file:

y = x + 9

This can be associated with the following cross-reference call:

FUSE_XREF_Reference(<session_context>,43,"x",DFXREF_NOMODIFIERS);

On that same source line, the reference to the variable y, which is an assignment, can be associated with the following cross-reference call:

FUSE_XREF_Reference(<session_context>,43,"y",DFXREF_ASSIGNMENT);

If a symbol reference is within a function or procedure, the FUSE_XREF_Reference call must be preceded by a FUSE_XREF_SubroutineBegin call to set the current default function or procedure.

Note that several routines (for example, FUSE_XREF_Call) implicitly issue a FUSE_XREF_Reference call to automatically create a symbol reference in addition to the explicit cross-reference (for example, a routine call).

6.1.5.3 Using the FUSE_XREF_Call Routine

Use the FUSE_XREF_Call routine to create a routine call cross-reference.

For example, consider the following call at line 76 of a C source file:

count_letters(buf);

This can be associated with the following cross-reference call:

FUSE_XREF_Call(<session_context>,76,"count_letters",DFXREF_NOMODIFIERS);

The FUSE_XREF_Call routine automatically creates a symbol reference in addition to the call cross-reference.

6.1.5.4 Using the FUSE_XREF_Member Routine

Use the FUSE_XREF_Member routine to create a cross-reference for a C++ class member definition.

For example, consider the following member definition at line 45 of a C source file:

protected: char *planet;

This can be associated with the following cross-reference call:

FUSE_XREF_Member(<session_context>,45,"planet",DFXREF_PROTECTED,DFXREF_DATA,DFXREF_NOMODIFIERS);

The FUSE_XREF_Member routine automatically creates a symbol reference in addition to the member definition cross-reference.

6.1.6 Allocating Memory for the Context Data

The FUSE_XREF_SessionBegin routine allocates memory automatically for the session. If additional memory is required for a specific call, that call allocates additional memory automatically.

The FUSE_XREF_SessionEnd routine frees the memory allocated during the session automatically.

Any string passed as a parameter during a call to a cross-reference routine is copied for internal use. Therefore, the caller can free the memory allocated for the string after the call.

6.1.7 Error Handling

The cross-reference callable interface does not provide any error handling beyond returning success or failure codes for each call. Therefore, note the following points:

A syntactically incorrect source can cause errors in the resulting cross-reference code and context information. Therefore, it is recommended that you use the routines only with source code that is syntactically error free; that is, the souce code can be compiled without error.

Each cross-reference routine returns success and error status codes as defined in Section 6.2. The cross- reference callable interface does not act on any returned error codes, so it is up to your scanner or compiler to do so.

In general, when your scanner or compiler encounters errors during a cross-reference session, it is safest to close the session (with the FUSE_XREF_SessionEnd routine).

6.2 Callable Interface Reference Section

This section describes the cross-reference routines. The routines are listed in alphabetical order.

Your scanner or compiler must precede any calls with the following line:

#include "fuse_xref.h"

6.2.1 FUSE_XREF_Call

Creates a call cross-reference.

int FUSE_XREF_Call(FUSE_XREF_SessionPtr session_context, unsigned line_number,
      char *subr_name, unsigned modifiers );

Description

The FUSE_XREF_Call routine adds a (procedure or function) call cross-reference to the context information in the current scope. The call is also added as a symbol reference.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file being scanned where the call occurs.
`subr_name`	Name of the procedure or function being called.
`modifiers`	Type of call. This parameter is reserved for future use. For this version of the product, always specify DFXREF_ NOMODIFIERS.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.

6.2.2 FUSE_XREF_ClassBegin

Marks the start of a C++ class definition.

int FUSE_XREF_ClassBegin(FUSE_XREF_SessionPtr session_context, unsigned line_number,
     char *class_name, char *parent_name, unsigned access_type, unsigned modifiers,);

Description

The FUSE_XREF_ClassBegin routine marks the start of a C++ class definition in the context information of the current scope. The class definition is also added as a symbol reference.

Use the FUSE_XREF_Member routine to create cross-references for class members. Then use the FUSE_XREF_ClassEnd routine to mark the end of the class definition.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file being scanned where the class definition starts.
`class_name`	Name of the class.
`parent_name`	This is optional and is the name of the parent class. If not applicable, specify NULL.
`access_type`	Access type of the class. Can be one of the following: DFXREF_PUBLIC: Public access DFXREF_PRIVATE: Private access DFXREF_PROTECTED: Protected access
`modifiers`	These are optional and are the Data types of the class. If applicable, specify one of the following: DFXREF_VIRTUAL: Virtual DFXREF_FRIEND: Friend If not applicable, specify DFXREF_NOMODIFIERS.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross-reference is in effect.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.

6.2.3 FUSE_XREF_ClassEnd

Marks the end of a C++ class definition.

int FUSE_XREF_ClassEnd(FUSE_XREF_SessionPtr session_context, unsigned line_number );

Description

The FUSE_XREF_ClassEnd routine marks the end of a C++ class definition in the context information of the current scope. This is the end of the class definition cross-reference that was started by the last FUSE_XREF_ClassBegin routine call.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DXREF_NOCLASS: No current class definition is in effect.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.
        DFXREF_NOWRITE - Failure to access the intermediate file for output.

6.2.4 FUSE_XREF_Declaration

Creates a declaration cross-reference.

int FUSE_XREF_Declaration(FUSE_XREF_SessionPtr session_context, unsigned line_number,
     char *decl_name, unsigned decl_type, char *data_type, unsigned modifiers, );

Description

The FUSE_XREF_Declaration routine adds a declaration cross- reference to the context information in the current scope. The declaration is also added as a symbol reference.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the declaration occurs.
`data_type`	This is optional. Data type of the declaration. This is in the syntax of the language being scanned. Spaces and punctuation are allowed. You can specify this parameter as NULL in two cases: If the classification type (`decl_type`) does not include more specific data types (for example, if the classification type is DFXREF_GEN_MACRO_DEF). If the classification type does include more specific data types, but you do not wish to make the declaration more specific (for example, if the classification type is DFXREF_CC_VARIABLE).
`modifiers`	This is optional. Subtype of the declaration. If applicable, specify the following: DFXREF_TEMPLATE (declaration is a C++ template declaration. If not applicable, specify the following: DFXREF_NOMODIFIERS.
`decl_name`	Name of the declaration.
`decl_type`	Classification type of the declaration. Table Table 6-2 lists the recognized classification types. You can specify a general, language-independent classification type or a more restrictive language- dependent type. The choice depends on the desired behavior of the FUSE query tool. Moreover, for certain classification types (for example, variables or user-defined types) you can specify the type even more by providing a data type with the `data_type` parameter.

Table 6-2: Declaration Types

Type Definition

General (Language-Independent) Classification Types

DFXREF_GEN_CONSTANT

General constant

DFXREF_GEN_MACRO_DEF

General macro definition

DFXREF_GEN_ROUTINE

General function or procedure

DFXREF_GEN_ROUTINE_PARAM

General routine parameter

DFXREF_GEN_TYPE

General user-defined type

DFXREF_GEN_VARIABLE

General variable

Ada Classification Types

DFXREF_ADA_ACCEPT

Ada accept statements

DFXREF_ADA_COMPIL_UNIT

Ada accept statements

DFXREF_ADA_COMPIL_UNIT

Ada compilation unit

DFXREF_ADA_ENTRY

Ada task entry

DFXREF_ADA_ENUM_LITERAL

Ada enumeration literal

DFXREF_ADA_EXCEPTION

Ada exception

DFXREF_ADA_FUNCTION

Ada function

DFXREF_ADA_GENERIC

Ada generic unit

DFXREF_ADA_LABEL

Ada label

DFXREF_ADA_NAMED_NUMBER

Ada named number

DFXREF_ADA_PACKAGE

Ada package

DFXREF_ADA_PARAMETER

Ada routine parameter

DFXREF_ADA_PROCEDURE

Ada procedure

DFXREF_ADA_RECORD_COMP

Ada record component

DFXREF_ADA_TASK

Ada task

DFXREF_ADA_TYPE

Ada user-defined type

DFXREF_ADA_VARIABLE

Ada variable

C Classification Types

DFXREF_CC_ENUM_CONSTANT

C enumeration constant

DFXREF_CC_FUNCTION

C function

DFXREF_CC_LABEL

C label

DFXREF_CC_PARAMETER

C function parameter

DFXREF_CC_NAMED_CONSTANT

C named constant

DFXREF_CC_STRUCT_FIELD

C structure field

DFXREF_CC_TYPE

C user-defined type (struct, union, enum)

DFXREF_CC_TYPEDEF

C typedef

DFXREF_CC_VARIABLE

C variable

C++ Classification Types

DFXREF_CXX_CB_CLASS

C++ class browser class entity

DFXREF_CXX_CLASS_MEMBER

C++ class, struct, union member

DFXREF_CXX_ENUM_CONSTANT

C++ enumeration constant

DFXREF_CXX_EXCEPTION

C++ exception

DFXREF_CXX_FRIEND

C++ friend

DFXREF_CXX_FUNCTION

C++ function

DFXREF_CXX_PARAMETER

C++ function parameter

DFXREF_CXX_NAMED_CONSTANT

C++ named constant

DFXREF_CXX_TEMPLATE

C++ template

DFXREF_CXX_TYPE

C++ user-defined type (class, struct, union, enum)

DFXREF_CXX_TYPEDEF

C++ typedef

DFXREF_CXX_VARIABLE

C++ variable

Fortran 77 Classification Types

DFXREF_F77_COMMON_BLOCK

FORTRAN-77 common block

DFXREF_F77_ENTRY_POINT

FORTRAN-77 entry point

DFXREF_F77_EQUIV_ENTITY

FORTRAN-77 equivalence entity

DFXREF_F77_FUNCTION

FORTRAN-77 function subprogram

DFXREF_F77_LABEL

FORTRAN-77 label

DFXREF_F77_NAMELIST_GROUP

FORTRAN-77 namelist group

DFXREF_F77_PARAM_CONSTANT

FORTRAN-77 parameter constant

DFXREF_F77_PROGRAM

FORTRAN-77 program

DFXREF_F77_RECORD_FIELD

FORTRAN-77 record field

DFXREF_F77_STMT_FUNCTION

FORTRAN-77 statement function

DFXREF_F77_SUBP_ARGUMENT

FORTRAN-77 subprogram argument

DFXREF_F77_SUBROUTINE

FORTRAN-77 subroutine

DFXREF_F77_TYPE

FORTRAN-77 user-defined type (structure)

DFXREF_F77_VARIABLE

FORTRAN-77 variable

Pascal Classification Types

DFXREF_PASCAL_COMPIL_UNIT

Pascal compilation unit (program, module)

DFXREF_PASCAL_DISCRIM

Pascal discriminant

DFXREF_PASCAL_ENUM_LITERAL

Pascal enumeration literal

DFXREF_PASCAL_FUNCTION

Pascal function

DFXREF_PASCAL_LABEL

Pascal label

DFXREF_PASCAL_PARAMETER

Pascal routine parameter

DFXREF_PASCAL_PROCEDURE

Pascal procedure

DFXREF_PASCAL_RECORD_FIELD

Pascal record field

DFXREF_PASCAL_SYMB_CONST

Pascal symbolic constant

DFXREF_PASCAL_TYPE

Pascal user-defined type

DFXREF_PASCAL_VARIABLE

Pascal variable

Cobol Classification Types

DFXREF_COBOL_ALPHABET

COBOL alphabet

DFXREF_COBOL_ARGUMENT

COBOL argument

DFXREF_COBOL_CLASS

COBOL class

DFXREF_COBOL_CONDITION_NAME

COBOL condition name

DFXREF_COBOL_FILE

COBOL file

DFXREF_COBOL_FUNCTION

COBOL function

DFXREF_COBOL_GROUP

COBOL group

DFXREF_COBOL_GROUP_ITEM

COBOL group item

DFXREF_COBOL_ITEM

COBOL item

DFXREF_COBOL_PARAGRAPH

COBOL paragraph

DFXREF_COBOL_PROGRAM

COBOL program

DFXREF_COBOL_SWITCH

COBOL switch

DFXREF_COBOL_SYMBOLIC_CHAR

COBOL symbolic character

Fortran 90 Classification Types

DFXREF_F90_BLOCK_DATA

FORTRAN-90 Block Data

DFXREF_F90_COMMON_BLOCK

FORTRAN-90 Common Block

DFXREF_F90_ENTRY_POINT

FORTRAN-90 Entry Point

DFXREF_F90_EQUIV_ENTITY

FORTRAN-90 Equivalence Entity

DFXREF_F90_FUNCTION

FORTRAN-90 Function Subprogram

DFXREF_F90_GENERIC_NAME

FORTRAN-90 Generic Name

DFXREF_F90_LABEL

FORTRAN-90 label

DFXREF_F90_MODULE

FORTRAN-90 Module

DFXREF_F90_NAMELIST_GROUP

FORTRAN-90 Namelist Group

DFXREF_F90_PARAM_CONSTANT

FORTRAN-90 PARAMETER Constant

DFXREF_F90_PROGRAM

FORTRAN-90 Program

DFXREF_F90_RECORD_FIELD

FORTRAN-90 Record Field

DFXREF_F90_STMT_FUNCTION

FORTRAN-90 Statement Function

DFXREF_F90_SUBP_ARGUMENT

FORTRAN-90 Subprogram Argument

DFXREF_F90_SUBROUTINE

FORTRAN-90 Subroutine

DFXREF_F90_TYPE

FORTRAN-90 User-Defined Type (structure)

DFXREF_F90_VARIABLE

FORTRAN-90 Variable

Return Value

Type	Definition
General (Language-Independent) Classification Types
DFXREF_GEN_CONSTANT	General constant
DFXREF_GEN_MACRO_DEF	General macro definition
DFXREF_GEN_ROUTINE	General function or procedure
DFXREF_GEN_ROUTINE_PARAM	General routine parameter
DFXREF_GEN_TYPE	General user-defined type
DFXREF_GEN_VARIABLE	General variable
Ada Classification Types
DFXREF_ADA_ACCEPT	Ada accept statements
DFXREF_ADA_COMPIL_UNIT	Ada accept statements
DFXREF_ADA_COMPIL_UNIT	Ada compilation unit
DFXREF_ADA_ENTRY	Ada task entry
DFXREF_ADA_ENUM_LITERAL	Ada enumeration literal
DFXREF_ADA_EXCEPTION	Ada exception
DFXREF_ADA_FUNCTION	Ada function
DFXREF_ADA_GENERIC	Ada generic unit
DFXREF_ADA_LABEL	Ada label
DFXREF_ADA_NAMED_NUMBER	Ada named number
DFXREF_ADA_PACKAGE	Ada package
DFXREF_ADA_PARAMETER	Ada routine parameter
DFXREF_ADA_PROCEDURE	Ada procedure
DFXREF_ADA_RECORD_COMP	Ada record component
DFXREF_ADA_TASK	Ada task
DFXREF_ADA_TYPE	Ada user-defined type
DFXREF_ADA_VARIABLE	Ada variable
C Classification Types
DFXREF_CC_ENUM_CONSTANT	C enumeration constant
DFXREF_CC_FUNCTION	C function
DFXREF_CC_LABEL	C label
DFXREF_CC_PARAMETER	C function parameter
DFXREF_CC_NAMED_CONSTANT	C named constant
DFXREF_CC_STRUCT_FIELD	C structure field
DFXREF_CC_TYPE	C user-defined type (struct, union, enum)
DFXREF_CC_TYPEDEF	C typedef
DFXREF_CC_VARIABLE	C variable
C++ Classification Types
DFXREF_CXX_CB_CLASS	C++ class browser class entity
DFXREF_CXX_CLASS_MEMBER	C++ class, struct, union member
DFXREF_CXX_ENUM_CONSTANT	C++ enumeration constant
DFXREF_CXX_EXCEPTION	C++ exception
DFXREF_CXX_FRIEND	C++ friend
DFXREF_CXX_FUNCTION	C++ function
DFXREF_CXX_PARAMETER	C++ function parameter
DFXREF_CXX_NAMED_CONSTANT	C++ named constant
DFXREF_CXX_TEMPLATE	C++ template
DFXREF_CXX_TYPE	C++ user-defined type (class, struct, union, enum)
DFXREF_CXX_TYPEDEF	C++ typedef
DFXREF_CXX_VARIABLE	C++ variable
Fortran 77 Classification Types
DFXREF_F77_COMMON_BLOCK	FORTRAN-77 common block
DFXREF_F77_ENTRY_POINT	FORTRAN-77 entry point
DFXREF_F77_EQUIV_ENTITY	FORTRAN-77 equivalence entity
DFXREF_F77_FUNCTION	FORTRAN-77 function subprogram
DFXREF_F77_LABEL	FORTRAN-77 label
DFXREF_F77_NAMELIST_GROUP	FORTRAN-77 namelist group
DFXREF_F77_PARAM_CONSTANT	FORTRAN-77 parameter constant
DFXREF_F77_PROGRAM	FORTRAN-77 program
DFXREF_F77_RECORD_FIELD	FORTRAN-77 record field
DFXREF_F77_STMT_FUNCTION	FORTRAN-77 statement function
DFXREF_F77_SUBP_ARGUMENT	FORTRAN-77 subprogram argument
DFXREF_F77_SUBROUTINE	FORTRAN-77 subroutine
DFXREF_F77_TYPE	FORTRAN-77 user-defined type (structure)
DFXREF_F77_VARIABLE	FORTRAN-77 variable
Pascal Classification Types
DFXREF_PASCAL_COMPIL_UNIT	Pascal compilation unit (program, module)
DFXREF_PASCAL_DISCRIM	Pascal discriminant
DFXREF_PASCAL_ENUM_LITERAL	Pascal enumeration literal
DFXREF_PASCAL_FUNCTION	Pascal function
DFXREF_PASCAL_LABEL	Pascal label
DFXREF_PASCAL_PARAMETER	Pascal routine parameter
DFXREF_PASCAL_PROCEDURE	Pascal procedure
DFXREF_PASCAL_RECORD_FIELD	Pascal record field
DFXREF_PASCAL_SYMB_CONST	Pascal symbolic constant
DFXREF_PASCAL_TYPE	Pascal user-defined type
DFXREF_PASCAL_VARIABLE	Pascal variable
Cobol Classification Types
DFXREF_COBOL_ALPHABET	COBOL alphabet
DFXREF_COBOL_ARGUMENT	COBOL argument
DFXREF_COBOL_CLASS	COBOL class
DFXREF_COBOL_CONDITION_NAME	COBOL condition name
DFXREF_COBOL_FILE	COBOL file
DFXREF_COBOL_FUNCTION	COBOL function
DFXREF_COBOL_GROUP	COBOL group
DFXREF_COBOL_GROUP_ITEM	COBOL group item
DFXREF_COBOL_ITEM	COBOL item
DFXREF_COBOL_PARAGRAPH	COBOL paragraph
DFXREF_COBOL_PROGRAM	COBOL program
DFXREF_COBOL_SWITCH	COBOL switch
DFXREF_COBOL_SYMBOLIC_CHAR	COBOL symbolic character
Fortran 90 Classification Types
DFXREF_F90_BLOCK_DATA	FORTRAN-90 Block Data
DFXREF_F90_COMMON_BLOCK	FORTRAN-90 Common Block
DFXREF_F90_ENTRY_POINT	FORTRAN-90 Entry Point
DFXREF_F90_EQUIV_ENTITY	FORTRAN-90 Equivalence Entity
DFXREF_F90_FUNCTION	FORTRAN-90 Function Subprogram
DFXREF_F90_GENERIC_NAME	FORTRAN-90 Generic Name
DFXREF_F90_LABEL	FORTRAN-90 label
DFXREF_F90_MODULE	FORTRAN-90 Module
DFXREF_F90_NAMELIST_GROUP	FORTRAN-90 Namelist Group
DFXREF_F90_PARAM_CONSTANT	FORTRAN-90 PARAMETER Constant
DFXREF_F90_PROGRAM	FORTRAN-90 Program
DFXREF_F90_RECORD_FIELD	FORTRAN-90 Record Field
DFXREF_F90_STMT_FUNCTION	FORTRAN-90 Statement Function
DFXREF_F90_SUBP_ARGUMENT	FORTRAN-90 Subprogram Argument
DFXREF_F90_SUBROUTINE	FORTRAN-90 Subroutine
DFXREF_F90_TYPE	FORTRAN-90 User-Defined Type (structure)
DFXREF_F90_VARIABLE	FORTRAN-90 Variable

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross-reference is in effect.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.
        DFXREF_NOSCOPE: No current scope for this cross-reference is in effect.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.

6.2.5 FUSE_XREF_FileBegin

Marks the start of a source file whose contents are to be scanned and cross-referenced.

int FUSE_XREF_FileBegin(FUSE_XREF_SessionPtr session_context, char *filename );

Description

The FUSE_XREF_FileBegin routine marks the start of a file in the context information. This call also marks the file as the current default file for subsequent cross-reference calls until the scanner issues either another FUSE_XREF_FileBegin call or a FUSE_XREF_FileEnd call.

If the scanner reaches a nested file, such as a C include file, it must issue another FUSE_XREF_FileBegin call. This marks the nested file as the current default file.

When the scanner reaches the end of a file, it must issue a FUSE_XREF_FileEnd call to mark the end of the file. If that was a nested file, the call also marks the nesting (outer) file as the current default file.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`file_name`	Absolute pathname of the file being scanned.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.

6.2.6 FUSE_XREF_FileEnd

Marks the end of a source file whose contents have been cross-referenced.

int FUSE_XREF_FileEnd(FUSE_XREF_SessionPtr session_context, unsigned line_number );

Description

The FUSE_XREF_FileEnd routine marks the end of a file in the context information. If this is a nested file, such as a C include file, the nesting (outer) file becomes the current default file for subsequent cross-reference calls during the session.

A FUSE_XREF_FileEnd call implicitly performs a FUSE_XREF_SubroutineEnd, FUSE_XREF_ScopeEnd, or FUSE_XREF_ClassEnd call, if necessary to close any definition or scope that was not closed explicitly.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file being scanned where the class definition ends.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.

6.2.7 FUSE_XREF_Member

Creates a cross-reference for a C++ class member definition.

int FUSE_XREF_Member(FUSE_XREF_SessionPtr session_context, unsigned line_number,
     char *member_name, unsigned access_type, unsigned member_type, unsigned modifiers);

Description

The FUSE_XREF_Member routine adds a member definition cross-reference to the current class definition in the context information in the current scope. The member definition is also added as a symbol reference.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.
`member_name`	Name of the member.
`access_type`	Access type of the member. Can be one of the following: DFXREF_PUBLIC: Public access DFXREF_PRIVATE: Private access DFXREF_PROTECTED: Proctected access.
`member_type`	Data type of the member. Can be one of the following: DFXREF_CONST: Constant data DFXREF_DATA: Data DFXREF_INLINED: Inlined data DFXREF_FUNCTION: Function
`modifiers`	(Optional). Subtype of the member. If applicable, specify one or more of the following subtypes, separated by the OR operator ( \| ) in C: DFXREF_FRIEND: Friend DFXREF_STATIC: Static DFXREF_PURE: Pure DFXREF_VIRTUAL: Virtual If not applicable, specify DFXREF_NOMODIFIERS.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOCLASS: No current class definition for this cross-reference is in effect.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.

6.2.8 FUSE_XREF_Reference

Creates a symbol cross-reference.

int FUSE_XREF_Reference(FUSE_XREF_SessionPtr session_context, unsigned line_number,
      char *ref_name, unsigned modifiers);

Description

The FUSE_XREF_Reference routine adds a symbol (reference- type) cross-reference to the context information in the current scope. If the symbol reference is within a function or procedure, the FUSE_XREF_Reference call must be preceded by a FUSE_XREF_SubroutineBegin call to set the current default function or procedure.

Note that the following routines implicitly issue a FUSE_XREF_Reference call to automatically create a symbol reference in addition to the explicit cross-reference (for example, a routine call):

FUSE_XREF_Call
FUSE_XREF_ClassBegin
FUSE_XREF_Declaration
FUSE_XREF_Member
FUSE_XREF_SubroutineBegin

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.
`ref_name`	Name of the reference.
`modifiers`	This is optional and is the type of reference. If applicable, specify the following: DFXREF_ASSIGNMENT: Symbol assignment ("write" rather than "read-only" symbol reference) If not applicable (if "read-only" reference), specify DFXREF_NOMODIFIERS.

Return Value

The return value can be one of the following:

6.2.9 FUSE_XREF_ScopeBegin

Marks the start of a new scope for cross-references.

int FUSE_XREF_ScopeBegin(FUSE_XREF_SessionPtr session_context, unsigned line_number );

Description

The FUSE_XREF_ScopeBegin routine marks the start of a new scope in the context information. This sets the default scope that is used for subsequent cross-reference calls. You can nest this call, as in the case of a local block scope nested within a procedure.

When the scanner reaches the end of a scope, it must issue a call to FUSE_XREF_ScopeEnd to mark the end of the scope. If that was a nested scope, the call also marks the nesting (outer) scope as the current default scope.

Use the FUSE_XREF_ScopeBegin and FUSE_XREF_ScopeEnd routines to resolve ambiguities in referencing symbols when the program contains multiple declarations of the same symbol. A declarations that appears in the same scope as a reference is presumed to be the declaration type of the reference.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.

Return Value

The return value can be one of the following:

6.2.10 FUSE_XREF_ScopeEnd

Marks the end of a scope for cross-references.

int FUSE_XREF_ScopeEnd(FUSE_XREF_SessionPtr session_context, unsigned line_number ););

Description

The FUSE_XREF_ScopeEnd routine marks the end of a scope that was started by a FUSE_XREF_ScopeBegin call in the context information. If that was a nested scope, the call also marks the nesting (outer) scope as the current default scope.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.
        DFXREF_NOSCOPE: No current scope for this cross-reference is in effect.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.

6.2.11 FUSE_XREF_SessionBegin

Starts a cross-referencing session.

int FUSE_XREF_SessionBegin(FUSE_XREF_SessionPtr *session_context, unsigned API_version,
     char *output_filename );

Description

The FUSE_XREF_SessionBegin routine initializes context information that is used for all subsequent cross-reference calls for this session.

This call must be the first one issued, before any other calls except another FUSE_XREF_SessionBegin call. More than one session can be active simultaneously in a multithreaded application, but one session is usually sufficient because a single session can handle multiple file cross-reference operations.

Parameters

session_context

Address of the session context pointer that will contain the newly initialized context for this cross-reference session. This pointer is a required parameter for all subsequent cross-reference calls.

API_version

Version of the cross-reference callable interface (API) that is being referenced. The value is contained in the definition DFXREF_API_VERSION. It is increased whenever a change is made to the API.

output_filename

Name of an output intermediate data file to store the cross-reference data. A value of NULL indicates that stdout should be used.

If you specify a file name, use the following naming conventions for naming intermediate data files in each language that is currently supported by FUSE. These conventions ensure compatibility with the FUSE static analysis database.

        Ada: .sourcefile_name.axref
        C: .sourcefile_name.cxref
        C++: .sourcefile_name.Cxref
        COBOL: .sourcefile_name.cobxref
        FORTRAN: .sourcefile_name.fxref
        Pascal: .sourcefile_name.pxref

For example, if you are scanning a C++ source file calledtest.C, name the intermediate data file .test.C.Cxref.

Return Value

The return value can be one of the following:

6.2.12 FUSE_XREF_SessionEnd

Ends a cross-referencing session.

int FUSE_XREF_SessionEnd(FUSE_XREF_SessionPtr session_context);

Description

The FUSE_XREF_SessionEnd routine closes the session context that was made active by a previous call to the FUSE_XREF_SessionBegin routine. The session context is invalidated and no further cross-reference calls can be made with this context. If an intermediate data file was specified in the FUSE_XREF_SessionBegin call, it is closed.

Parameters

session_context

Address of the session context initiated by FUSE_XREF_SessionBegin.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOCLOSE: Failure to close the intermediate file for output.

6.2.13 FUSE_XREF_SubroutineBegin

Marks the start of a procedure or function definition.

int FUSE_XREF_SubroutineBegin(FUSE_XREF_SessionPtr session_context,
     unsigned line_number, char *subr_name, unsigned modifiers );

Description

The FUSE_XREF_SubroutineBegin routine adds a function or procedure definition cross-reference to the context information in the current scope. The function or procedure definition is also added as a symbol reference.

The routine also marks the start of the function or procedure definition's scope for subsequent cross- references. The end of that scope is marked by a FUSE_XREF_SubroutineEnd call.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.
`subr_name`	Name of the procedure or function being defined.
`modifiers`	This is optional and is the subtype of the subroutine. If applicable, specify the following: DFXREF_TEMPLATE: Definition is a C++ template routine. If not applicable, specify DFXREF_NOMODIFIERS.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOFILE: No current file context for this cross- reference is in effect.
        DFXREF_NOMEMORY: Failure to allocate sufficient memory to store the context data.
        DFXREF_NOSCOPE: No current scope for this cross-reference is in effect.

6.2.14 FUSE_XREF_SubroutineEnd

Marks the end of a procedure or function definition.

int FUSE_XREF_SubroutineEnd(FUSE_XREF_SessionPtr session_context,
    unsigned line_number);

Description

The FUSE_XREF_SubroutineEnd routine closes a function (function or procedure definition) cross-reference in the context information in the current scope. If that was a nested function definition, the call also marks the nesting (outer) function definition as the current function definition.

Parameters

`session_context`	Address of the session context initiated by `FUSE_XREF_SessionBegin`.
`line_number`	Line number within the file beingn scanned where the class definition ends.

Return Value

The return value can be one of the following:

        DFXREF_SUCCESS: Successful completion.
        DFXREF_BADPARAM: A parameter is invalid.
        DFXREF_NOWRITE: Failure to access the intermediate file for output.
        DFXREF_NOSUBROUTINE: No current subroutine definition is in effect.