The SCA query facilities let you obtain information about symbols in your source code. You can specify a cross-reference query to display specific symbol, file, or module information. You can determine declarations of program symbols, references to the symbols, and references to source files. You can also determine the call relationships between routines by displaying call tree information. Within the editing environment, you can navigate through the complexities of an entire system and, as necessary, inspect and edit related source files.

With LSE editing features, you can move through an unfamiliar system without regard for module or file boundaries. For example, given the task of modifying the characteristics of a variable, you can locate all of the uses of the variable across the system and make your changes without leaving LSE.

Help is available for SCA within LSE, as well as for SCA at the DCL or subsystem level.

LSE> HELP SCA_TOPICS SCA_EXAMPLE

The DECwindows SCA user interface provides context-sensitive online help for all window items, menu items, commands, and graph displays.

SCA displays context-sensitive help on that item. However, if the input focus is in a dialog box and you press the Help key, you receive an overview of the entire dialog box and not just the selected item.

The SCA Main window is the starting point for using all the SCA interactive features. It lets you perform library management functions and provides access to the name browser and query windows, from which you interactively analyze your source code.

The SCA Main window, shown in Figure 1.1, “SCA Main Window”, is composed of screen objects used in all the SCA graphical windows. These objects include the menu bar, options region, display region,and selection buttons.

The options region allows you to enter information and select one or several options. In the SCA Main window, for example,you can enter the name of an SCA library in the box labeled “Enter library directory specification to replace current library list:”. Other windows, like the query windows, allow you to click on any of several options from a list.

The display region complements the options region. In the SCA Main window, a list of active SCA libraries appears in the Current Library List: box.

For more information on these commands, as well as other SCA commands, see the VSI DECset for OpenVMS Language-Sensitive Editor/Source Code Analyzer Reference Manual.

SCA query windows let you specify query attributes and view query results. When you use SCA to browse names in your source code (see Section 2.3.2, “Browsing for Names”), you specify your query and view the result in the same Name Browser window. When you use SCA to get cross-reference information, or to create call graphs or type trees, you specify your query in one window (the query window) and view the results in another window (the result window).

For example, if you want to see all calls to the routine build_table, specify the query in the Call Graph Query window. SCA then displays the call graph in the Call Graph Query Result window.

When you specify subsequent queries, SCA reuses the same two windows. SCA keeps a list of previous query specifications and results that you can use (see Section 4.5, “Using Multiple Queries”).

It is easy to navigate from one query to another. From any query window or query result window, you use the Query pull-down menu and choose the type of query you want to perform next.

The following sections get you started using the SCA query windows.

The SCA name browser lets you specify wildcard expressions from which SCA displays a list of symbols matching that string. The name browser helps you find symbols when you are not quite sure of their names.

Suppose that you know of a procedure in the system that might be useful in new code that you are writing, but you cannot remember its name. You only remember that it begins with build.

SCA displays all the symbol names that match the wildcard expression.

As you can see in Figure 2.1, “Name Browser Dialog Box”, SCA found four names that match the wildcard string.(Note that the first item in the list is selected.)

SCA displays the Cross-Reference Results window, as shown in Figure 2.2, “Cross-Reference Results Window”. As you can see, buildtable is a module. Section 2.3.4, “Cross Referencing Information” describes how to perform a cross-reference query on the last item from the name browser list, build_table.

The following sections describe how to perform a class structure query and manipulate the results.

2.3.3.1. Specifying a Class Browser Query

To specify a class browser query, do the following:

1. From any SCA query window (for example, the Call Graph Query window ), pull down the Query menu. (You can also click the Class Browser... selection button from the SCA main window. )

2. Choose the Class Browser... menu item. SCA displays the Class Browser Query window, shown in Figure 2.3, “The Class Browser Query Window”.

To ask SCA, “What is the class structure for all relationships used by "eagle"?”, do the following:

1. Position the pointer in the specification box (upper right) for the Used by query attribute and press MB1 to activate it.

2. Enter eagle in the specification box. By leaving the To and Depth query attributes blank, SCA interprets this query as, “Find the first level of all classes used by "eagle"”. The Depth query attribute specifies how many levels SCA should display.

3. Click on OK. SCA graphically displays the class structure.

2.3.3.2. Viewing Class Browser Query Results

Figure 2.4, “The Class Browser Results Window” shows the query result from Section 2.3.3.1, “Specifying a Class Browser Query”.

The class structure shows that eagle is used by several classes. Each class, depicted within a box, is called a node. The arrows showing the class relationships are called arcs.

By default, SCA displays the type tree as a lexical tree. A lexical tree shows all calls for the indicated depth, in the order in which they appear in the source code.

SCA also displays more detail about each node in the type tree. As shown in Figure 2.4, “The Class Browser Results Window”, the lower pane of the Class Browser Results window shows an alphabetic list of the usage. Use the horizontal scroll bar to view all the details about this usage. You can select a class from either the display graph or the list in the lower pane.

As shown in Figure 2.4, “The Class Browser Results Window”, SCA displayed one level of detail from eagle. You could have specified Depth = All to show all levels of detail from eagle.A more efficient way is to use the Extend options. Using these options,you can incrementally expand your class display to show additional levels of detail. For example, to see what calls pet, do the following:

1. Position the pointer on the class pet and click on MB1 to select it.

2. Click on MB3. A pop-up menu is displayed, as shown in Figure 2.4, “The Class Browser Results Window”.

3. Position the pointer on the Extend To menu item and click on MB3. SCA extends the class browse display to pet by one level, as shown in Figure 2.5, “Extending to a Class Node”. (Note that you can choose the Extend To menu item from the Modify menu to get the same result.)

The class browser display now shows all classes that extend to the class pet, including the original class browser result, eagle.

A cross-reference query enables you to find specific occurrences of a symbol and their locations in the source code.

2.3.4.1. Specifying a Cross-Reference Query

To find all occurrences of the symbol build_table, continue these steps from the tutorial in Section 2.3.2, “Browsing for Names”:

1. From the Cross-Reference Results window, pull down the Query menu.

2. Choose the Show Query Window menu item.

   SCA displays the Cross-Reference Query window, as shown in Figure 2.6, “The Cross-Reference Query Window”.

3. Click MB1 on the Reset button to clear the window. Click on the specification box for the Name query attribute.

4. Type build_table in the specification box.

5. Click on OK. (You can also click on Apply or press Return for the same action. Clicking on Apply retains the query window.)

2.3.4.2. Viewing Cross-Reference Query Results

Figure 2.7, “The Cross-Reference Query Result Window” shows the cross-reference query result. This information includes the symbol name, type, and domain. (Use the scroll bar or move the sash to the right to view this information.) In this example, build_table is a procedure.

You can expand the result to display information about occurrences of a symbol. This information includes the usage, module or routine that contains the occurrence, and file where the occurrence resides.

To expand the information, do the following:

1. Position the pointer on the icon next to the symbol name.

2. Double click on MB1. (Alternatively, you can click MB1 anywhere on the line to select the symbol, then choose the Expand menu item from the View menu.) SCA provides information about the occurrences of the selected symbol, as shown in Figure 2.8, “Expanding Information”.

The right-hand pane of the result window now shows the occurrences of build_table. For example, the first occurrence is in the module buildtable in the file buildtable.c on line 117. You can collapse this information by double clicking again on the symbol icon.

SCA also enables you to display full information for a selected symbol or occurrence. See Section 4.1, “Performing Cross-Reference Queries” for more information on cross-reference queries.

With LSE running, you can double click MB1 on a symbol name in the left-hand pane, or an occurrence in the right-hand pane of a query result, and go directly to its location in the source code.

A call graph query enables you to graphically display call relationships between routines in your source code. SCA builds a call graphthat hierarchically shows these relationships. SCA provides you with several options for formatting the call graph display.

2.3.5.1. Specifying a Call Graph Query

In the following example, you specify a call graph query to ask SCA, “What routines does the function copy_file call?” Perform the following steps:

1. From any SCA query window (for example, the Cross-Reference Results window from the last example), pull down the Query menu.

2. Choose the Call Graphs... menu item. The Call Graph Query window is displayed, as shown in Figure 2.9, “The Call Graph Query Window”.

3. Position the pointer in the specification box for the From query attribute and press MB1 to activate it.

4. Enter copy_file in the specification box. By leaving the To and Depth query attributes blank, SCA interprets this query as, “Find the first level of all calls from copy_file”. The Depth query attribute specifies how many levels of calls SCA should display.

5. Click on Apply. SCA displays a Cancel Operation box in case you change your mind. SCA creates a new call graph with a depth of 1.

2.3.5.2. Viewing Call Graph Query Results

Figure 2.10, “The Call Graph Results Window” shows the query result from Section 2.3.5.1, “Specifying a Call Graph Query”.

The call graph shows that the routine copy_file calls several routines. Each routine, depicted in the call graph by a circle, is called a node. The arrows showing the call relationships are called arcs.

By default, SCA displays a call graph as a lexical tree. A lexical tree shows all calls for the indicated depth, in the order in which they appear in the source code. See Section 4.4, “Modifying the Current Query” for information about other call graph display formats.

SCA also displays more detail about each node in the call graph. As shown in Figure 2.10, “The Call Graph Results Window”, the lower pane of the Call Graph Results window shows an alphabetic list of the routines. For each routine it shows its type, the domain it is part of, its usage, what module or routine it is contained by, the file it resides in, and the line number in that file. You can select a node in the call graph by pointing to a node in the graph, or by pointing to a node name in the list and pressing MB1.

As you can see in Figure 2.10, “The Call Graph Results Window”, SCA displayed one level of detail from copy_file. You could have specified Depth = All to show all levels of detail from copy_file.A more efficient way is to use the Extend options. Using these options,you can incrementally expand your call graph to show additional levels of detail. For example, to see what calls copy_file, do the following:

1. Position the pointer on the node copy_file and click on MB1 to select it.

2. Click on MB3. A pop-up menu is displayed, as shown in Figure 2.11, “Extending to a Node”.

3. Position the pointer on the Extend To menu item and click on MB3. SCA extends the call graph to copy_file by one level. (Note that you can choose the Extend To menu item from the Modify menu to get the same result.)

To extend from a node, do the following:

1. Position the pointer on the node main and click on MB1 to select it.

2. Click on MB3. A pop-up menu is displayed.

3. Choose the Extend From menu item. SCA extends the call graph from main by one level. Figure 2.12, “Extending from a Node” shows the result.

The following sections describe how to perform a data structure query and manipulate the results. For more information on specifying data structure queries, see Section 4.3, “Performing Data Structure Queries”.

2.3.6.1. Specifying a Data Structure Query

To specify a data structure query, do the following:

1. From any SCA query window (for example, the Call Graph Query window), pull down the Query menu.

2. Choose the Data Structures... menu item. SCA displays the Data Structures Query window, shown in Figure 2.13, “The Data Structures Query Window”.

To ask SCA, “What is the data structure for the type trans_table?”, do the following:

1. Position the pointer in the specification box (upper right) for the Type of query attribute and press MB1 to activate it.

2. Enter trans_table in the specification box.

3. Click on OK. SCA graphically displays the data structure.

2.3.6.2. Viewing Data Structure Query Results

Figure 2.14, “The Data Structures Results Window” shows the query result from Section 2.3.6.1, “Specifying a Data Structure Query”.

The data structure result shows that trans_table is an array of records with the components trans_value and compress. trans_value is of type code_value, and compress is of type boolean.

When you position the pointer on a node and press MB1, SCA highlights the corresponding information in the lower pane of the window. For example, when you click on trans_value, SCA highlights the line “trans_value [is of type] code_value.”

As with a call graph, SCA displays a type tree in lexical format by default and lets you manipulate the display of information in several ways from the View menu. SCA allows you to customize the result window so your default display is, for example, a graph instead of a lexical tree. See Section 4.6, “Modifying the Display Options” for information on modifying the display data structure queries, see Section 4.3, “Performing Data Structure Queries”.

SCA lets you maintain more than one query at a time. This feature maximizes the use of SCA by allowing you to perform simultaneous source investigations.

For example, when you specify a cross-reference query, SCA creates a new query by default. If, during the session, you go to the source of a symbol occurrence and find another symbol you want to investigate before returning to your last query, you can specify a new query about the symbol. After inquiries in your new session are completed, you can go back to your previous session.

SCA depends on supporting compilers for the generation of files containing detailed analysis data. These analysis data files contain information about all of the symbols, files, and modules in the source code. You load this information into an SCA library (see Section 3.3, “Loading an SCA Library”). It is then used as a database for the SCA query and analysis features.

Some compilers generate .XREF files that can be converted to .ANA files by means of the SCA IMPORT command. For more information on the IMPORT command, see the VSI Language-Sensitive Editor/Source Code Analyzer for OpenVMS Reference Manual.

For OpenVMS systems, you produce an analysis data file by specifying the /ANALYSIS_DATA qualifier during compilation. This qualifier requests that the compiler generate a file of analysis data information with a default file type of .ANA.

$ CC/ANALYSIS_DATA PG1,PG2,PG3

Figure 3.1, “Setting Up an SCA Environment” shows these steps.

The /REPLACE qualifier replaces modules in the specified library, if they exist, and adds any newly specified modules. The /NOREPLACE qualifier adds new modules to the library. The default is /REPLACE.

$ SCA LOAD/NOREPLACE  PG1,PG4
%SCA-W-LOADED, module PG1 has already been loaded
%SCA-S-LOADED, module PG4 loaded
%SCA-S-COUNT, 1 module loaded, (1 new, 0 replaced)

The /LIBRARY=library-spec qualifier specifies the SCA library to be updated. The update library must be one of the libraries on the current list. The default is /LIBRARY=primary-library.

$ SCA LOAD/LIBRARY=LIB2 PG1
%SCA-S-LOADED, module PG1 loaded

The /DELETE qualifier deletes an .ANA file from its present location when it is successfully loaded into an SCA library. You can recover deleted .ANA files from SCA libraries using the EXTRACT MODULE command.

Another way to load an analysis data file is to type the file name directly in the Load into Library: box on the bottom of the dialog box and click on Apply. Using this method, you can load several files by entering the file names in a space-separated list, or by specifying a wildcard expression.

$ SCA CREATE LIBRARY/REPLACE [.LIB3]
%SCA-S-NEWLIB, SCA Library created in PROJ:[USER.LIB3]
%SCA-W-NEWLIB, your SCA Library is PROJ:[USER.LIB3]

For DECwindows, the easiest way to open an SCA library is to enter a library specification directly from the SCA Main window. SCA replaces all libraries in the Current Library List: box with the ones you specified. Subsequent SCA functions now use these libraries.

The Current Library List box shows the libraries you opened.

SCA searches for libraries in the order they are listed on library lists. The /BEFORE qualifier adds the libraries specified on the command line to the beginning of the current library list. The /BEFORE=library-spec qualifier inserts the libraries specified on the command line before the library specified by the qualifier.

$ SCA CREATE LIBRARY/BEFORE=[.LIB3] [.LIB2]
%SCA-S-NEWLIB, SCA Library created in PROJ:[USER.LIB2]
%SCA-S-LIB, your SCA Libraries are
-SCA-S-LIB,      PROJ:[USER.LIB1]
-SCA-S-LIB,      PROJ:[USER.LIB2]
-SCA-S-LIB,      PROJ:[USER.LIB3]

The /AFTER qualifier adds the libraries specified on the command line to the end of the current library list. The /AFTER=library-spec qualifier inserts libraries specified on the command line after the library specified by the qualifier.

$ SCA CREATE LIBRARY/AFTER=[.LIB3] [.LIB4]
%SCA-S-NEWLIB, SCA Library created in PROJ:[USER.LIB4]
%SCA-S-LIB, your SCA Libraries are
-SCA-S-LIB,      PROJ:[USER.LIB1]
-SCA-S-LIB,      PROJ:[USER.LIB2]
-SCA-S-LIB,      PROJ:[USER.LIB3]
-SCA-S-LIB,      PROJ:[USER.LIB4]

For DECwindows, another way to open an SCA library is from the Open Library dialog box. Using this method, you can add libraries to the current library list. This method also allows you to position the libraries among other libraries in the list (see Section 3.4.3, “Repositioning Libraries in the Current Library List for DECwindows”). By default, the new library you add becomes the selected library.

Where you position a library in the current library list affects how SCA uses modules of analysis data. Table 3.1, “How SCA Uses Multiple Libraries” shows this concept.

If Module A in LIB1 and Module A in LIB2 were different in content and you want SCA to use Module A in LIB2, position LIB2 before LIB1 in the library list when you open it.

In the previous example, you had to close a library on the current library list to reposition it. The recommended way to use SCA is to first determine the order in which you want to position SCA libraries before you open them. As such, you would have opened LIB2 before LIB1.

When you reorganize SCA libraries, you optimize their size and organization. As a result, query and update operations are faster.

The REORGANIZE command sorts, compresses, and reorders the data structures in an SCA library, freeing up memory space and improving library performance. The result is a smaller, more efficient SCA library.

REORGANIZE [/qualifier...] [library-spec[,...]]

$ SCA
SCA> CREATE LIBRARY/SIZE=8000/MOD=200 library-directory
SCA> LOAD data-file-directory:*.ANA
SCA> REORGANIZE

The library-directory parameter specifies the location of the library to be reorganized. The default is the current library directory.

The REORGANIZE commands creates scratch files in SYS$SCRATCH approximately equal in size to the files in the library being reorganized.

DELETE LIBRARY [/qualifier...] directory-spec[,...]

SCA deletes the selected library and removes it from the library list.

The library attributes include the library number, date it was created,date last accessed and by whom, and number of blocks allocated and used. The module attributes include the module type (for example, C), module identifier, compiler name and compile command line used, date compiled, SCA library where the module resides, and date it was loaded into the library.

$ SCA SHOW LIBRARY
%SCA-S-LIB, your current SCA library is PROJ:[USER.SCA]
$ 

3.5.3.2. Displaying Modules and Module Attributes

The SHOW MODULE command selectively displays information about modules in SCA libraries. The SHOW MODULE command has the following form:

SHOW MODULE [/qualifier...] [module-name-expr[,...]]

Complete or partial information about all modules, or selected modules, can be displayed. The terms “visible” and “hidden” refer to the results of the module selection process that occur when multiple libraries are accessed.

If you use a general module query, abbreviated information is displayed. The default qualifier is /BRIEF. For example:

$ SCA SHOW MODULE
   Module             Ident    Language    Compiled
                                                       
BUILD_TABLE          1  01       Pascal   24-Oct-1998 15:43
COPY_FILE            1  01       Pascal   24-Oct-1998 15:44
EXPAND_STRING        1  01       Pascal   24-Oct-1998 15:44
OPEN_FILES           1  01       Pascal   24-Oct-1998 15:43
TRANSLIT             1  01       Pascal   24-Oct-1998 15:44
TYPES                1  01       Pascal   24-Oct-1998 15:43
%SCA-S-MODULES, total of 6 modules

If you use a general module query with the /FULL qualifier, details of all the module information in the library are displayed.

If you type a specific module name, detailed information on the specified module is displayed.

The /VISIBLE qualifier displays only visible modules. The default is /VISIBLE.

The /ALL qualifier displays all modules (both visible and hidden).

For DECwindows, to display a list of modules for any SCA library, position the pointer on a library name in the Current Library List box and double click on MB1.You can also select an SCA library, then choose the Show Modules menu item from the View menu.

SCA displays a list of modules for the selected library. Double click again on the library name to hide the modules, or select a library and choose the Hide Modules menu item from the View menu.

To display attribute information for any module in the library:

1. Position the pointer on a module name and press MB1 to select it.

2. Pull down the View menu.

3. Choose the Show Attributes menu item. SCA displays the attributes for the selected module.

Figure 3.5, “Displaying Attributes” shows the attributes of the sample SCA library and the attributes for the build_table module.

SCA provides a way for you to recover an SCA library. For example, a library may have inconsistencies resulting from the abnormal termination of a LOAD or DELETE MODULE command.

When you recover a library, SCA deletes from the library any module that started to load but had not completed loading, or any module that started to be deleted but had not completed deleting. SCA cannot recover modules waiting to be processed; you will need to load them again.

A name-selection expression selects occurrences that have names that match a specified name expression.

name-selection-exp ::= name-expression |
                       name=name-expression |
                       name=( name-expression,... )

name=( namexp1, namexp2 )
name=namexp1 OR
name=namexp2namexp1 OR namexp2

"one quotation mark ("")"

Enclosing a complex string in quotation marks does not affect the case-sensitivity of matching. String matching is not sensitive to the case of the string specified in the name expression.

Although a hyphen (-) is allowed in a simple name, a command line that ends in a hyphen is a continued command, just as in DCL.

SCA shows all occurrences of the variable codein the right-hand pane (see Figure 4.1, “Cross-Referencing by Symbol Name”).

occurrence-selection-exp ::= occurrence=occurrence-class |
                             occurrence=( occurrence-class,...

Occurrence is a formal parameter name and occurrence-class is one of the following keywords:

SCA displays the new result. It again keeps items from the previous result, because this option remains active from the last query. Choose the Expand All menu item from the View menu to see more detail. Figure 4.2, “Limiting Queries to Specific Modules” shows the query specification and result.

symbol-class-selection-exp ::= symbol=symbol-class |
                               symbol=( symbol-class,... )

You use one or more of the generic (multilanguage) keywords to request specific classes of symbols. Because different languages use different terminology, several alternatives are provided for some classes of symbols.

A list of symbol classes is equivalent to a union of symbol-class-selection expressions, each having a single symbol class.

In the following example for DECwindows, you specify a cross-reference query by symbol type. There are several symbol types listed in the Selection box, for example: variables, constants, and functions. When you specify a symbol type, SCA lists the names of all symbols of that type.

SCA lists generic symbol types in the Selection box for this attribute. To see what types correspond to these symbol types, look at the language table in SCA help for the language that you are using. For example, the symbol type routine means procedure in Pascal.

A symbol-domain-selection expression selects occurrences whose symbol domain is one of those specified in the symbol-domain-selection expression.

Symbol domain is the range of source code in which a symbol has the potential of being used. For example, a C static declaration creates a symbol that has a module-specific symbol domain; it cannot be used outside of that module. On the other hand, a regular C module-level declaration creates a symbol that has a multimodule symbol domain; it has the potential of being used in more than one module. The symbol domain of a GLOBAL is multimodule, regardless of how many modules there are in which the symbol is used.

symbol-domain-selection-exp ::= domain=symbol-domain |
                                domain=( symbol-domain,... )

A list of symbol domains is equivalent to a union of symbol-domain-selection expressions, each having a single symbol domain.

Figure 4.3, “Cross-Referencing by Symbol Domain” shows the query specification and result.

As with modules, you can limit your cross-reference query results to occurrences located in a particular file. In the Cross Reference Query window, enter the file specification in the specification box for the In File query attribute.

x.c, x.h

From the Cross Reference Results window, position the pointer on the name of a symbol in the left-hand pane, or the name of an occurrence in the right-hand pane of the query result, and double click on MB1. Figure 4.4, “Go-To-Source Feature” shows an occurrence of build_table that has been selected and the cursor positioned to its corresponding location in the source code.

As you examine the cross-reference results, you might also want to see the structure of your code. SCA can graphically display routine calls and data structures. From the Query pull-down menu, you can select menu items to specify call graph and data structure queries.

SCA interprets this query as, "Find all calls from read_command_line". Figure 4.5, “Call Graph Results”shows the resulting display. Note that the default depth is 1.

4.2.1.1. Navigating a Large Display

SCA displays all routines called by read_command_line.Because this is a large display, the entire result (shown as a lexical tree by default) cannot fit in the window's display area. You can use the scroll bars to view various parts of the call graph, or click MB1 on a name in the lower pane to show the graph area that pertains to that node.

SCA also provides a Navigation window that lets you look at a call graph in its entirety. The Navigation window serves two purposes:

• You can determine the part of the graph you want to see and navigate to that location.

• Upon viewing an image of the entire graph, you can decide whether to use this graph, or to respecify your query to limit the results.

To display the Navigation window, click on the navigation button. The navigation button is the small square (icon) in the lower-right corner of the top pane, between the horizontal and vertical scroll bars.

SCA displays the Navigation window, shown in Figure 4.6, “The Navigation Window”. The Navigation window shows an image of the entire graphical display.

As you can see in Figure 4.6, “The Navigation Window”, there is a box within the display outlining part of the graph. This area corresponds to the image currently in the query result display area. To navigate to another part of the graph, do the following:

1. Position the pointer in the Navigation box. A cross-hair cursor appears.

2. Press and hold MB1.

3. Move the box to the part of the call graph you want to see. In this case, move the box up to the top of the graph.

4. Release MB1. The display area of the Call Graph Results window now shows this part of the graph (you should see the routine open_in). The Navigation window stays active until you click MB1 again on the navigation button.

After you specify an SCA query, you can refine it until you arrive at the most meaningful information. This section demonstrates several ways to refine your query.

4.2.2.2. Eliminating Extraneous Information

To limit your query results to only those routines found in your application, SCA provides a feature that lets you modify your query results to remove items not defined in your SCA library. Perform the following steps:

1. From the Call Graph Results window, pull down the Modify menu.

2. Choose the Remove items not defined in the SCA library menu item. This step keeps everything that has primary declarations in the SCA library.

Figure 4.7, “Simplified Call Graph” shows the simplified query result.

4.2.2.4. Extending Information About a Routine

You can ask SCA to display more information about a given routine. Whenever you refine your call graph queries in SCA, you have two basic ways to work:

• By specifying new query attributes for the current query

• By extending your current query display

In the first case, you return to the query window and revise the current query specification (see Section 4.4.3, “Adding Items to the Previous Query Result”).This method is useful when you know several things about your code and want to indicate several conditions in your query. If you want to see what, if anything, calls a given routine or what that routine calls, you can use the Extend options.

To get more information about the node build_table directly from the display of the query result, do the following:

1. In the display of the current query result, position the pointer on the node build_table and click MB1 to select it.

2. Click on MB3. A pop-up menu is displayed.

3. Choose the Extend From menu item. SCA adds calls from build_table. Figure 4.8, “Extending From a Node” shows the result.

In the same way that you extend from a node, you can select the Extend To menu item to extend to a node. Extending to a node finds routines that call the routine corresponding to that node. For example, if you had a call tree from build_table and you selected Extend To build_table, SCA would show the node read_command_line with an arc extending to build_table.

Proc routine1 ( )
        routine2 ( )
Proc routine2 ( )
        routine1 ( )
        routine2 ( )

Figure 4.12, “Recursive Calls” shows the resulting call graph in Lexical format.

As you can see, routine2 calls routine1,which calls routine2 again. In addition, routine2 calls itself.

Recursive calls are shown as dashed circles. If you change your query result to Graph format, SCA displays the arc from routine2 to routine1, then back again to routine2, as well as an arc pointing from routine2 to itself.

SCA creates a .DDIF file of the currently displayed call graph. You can continue displaying the results of other call graph queries and extract them in the same manner.

In the first case, you provide a symbol name for the “Type” of query attribute in the Data Structure Query window. The symbol can be a variable or a type. SCA finds the type of each symbol.

For example, suppose you have the variable X in your code. If you enter X in the specification box, SCA finds the data type of the variable X. In another example, if you have a type named T in your code and you enter T in the “Type of” specification box, SCA graphically displays the structure of T.

When you provide a data type name for the “Of type” query attribute in the Data Structure Query window, SCA finds symbols that are of that type. For example, if you enter “Type of” X and “Of type” INTEGER, SCA finds symbols named X that are of type INTEGER.

The type can be predefined by the programming language, such as INTEGER, or it can be user-defined. For example, if you leave the “Type of” attribute blank and enter user_defined_type for the “Of type” query attribute, SCA finds all symbols that are of type user_defined_type.

The result of a data structure query is a type tree. Type trees give you a graphical overview of the structure of your data types. Like call graphs, type trees contain nodes and arcs. You can click on anode to get “type” information about the structure. Double clicking on a node takes you to that occurrence in your source code.

Another similarity to call graphs is that type trees can be extended,compressed, and in other ways modified to best display the result. You can also extract your final result into a file for printing (see Section 4.2.6, “Printing Call Graph Results” for information).

4.3.2.1. Extending a Type Tree

You can extend your type tree to see more information. The node beginning with window_title is a record containing several fields. Note that window_title and several other fields are marked with squares in the right margin. These indicate that you can further extend the type tree from that item because these fields are also of some user-defined type.

Before you can extend an item, you must select it. SCA lets you select a single item or select the entire node (in this case, all the fields in the record). To select a single item, click MB1 on the name of the item (for example, window_title). To select the entire record, clickMB1 on the border of the node, or on the line between the item names. Selecting globally is useful for extending or removing all items in a node.

To extend the type tree from window_title, do the following:

1. Click MB1 on window_title to select it. Note that the line highlighted in the lower pane of Figure 4.14, “Initial Type Display” shows that window_title is of type string_desc. To see the structure of string_desc, continue with Steps 2 and 3.

2. Click on MB3. A pop-up menu is displayed.

3. Choose the Extend From menu item.

Figure 4.15, “Extended Type Tree” shows the result.

SCA shows that the structure string_desc has four fields (SCA shows the name of a structure outside the node box). When you click on the name of any field, the corresponding information is displayed in the bottom window.

Next, return to the previous node and select q_context. (Again, the square in the right margin next to the name denotes an extendible field, as well as the information in the lower pane.) To extend from q_context, do the following:

1. Click on MB3. A pop-up menu is displayed.

2. Choose the Extend From menu item. Note that the resulting type tree is large and cannot display in its entirety.

3. Click MB1 on the navigation button. SCA displays the Navigation window, which shows an image of the entire graphical display. The outlined area within the Navigation window represents the current display. To navigate to another part of the type tree, go to Step 4.

4. Click and hold MB1 and move the outline box up so you see the top nodes of the tree, then release MB1. The display area of the Data Structure Results window now shows this part of the tree.

The node represented by a broken-line box indicates a recursive structure. The recursive data structure display is similar to a recursive call graph display (see Section 4.2.5, “Displaying Recursive Calls”). In this example, the structure query_context contains a field that is also of type query_context.

You can also reposition nodes in the query result. Position the pointer on a node then click and hold MB2. Drag the node to the desired location and release MB2. Figure 4.16, “Repositioned Type Tree” shows the previous type tree repositioned.

4.3.2.2. Selecting and Removing Nodes from a Type Tree

Suppose you decide that the node string_desc is not important and you want to remove all occurrences of it from the type tree. By selecting the node, SCA selects all nodes with the same name.

To select string_desc, click MB1 on the border of the node box. SCA highlights the selected nodes, as shown in Figure 4.17, “Selecting a Node”.

To remove the selected nodes, do the following:

1. Click on MB3. A pop-up menu is displayed.

2. Choose the Remove Item(s) menu item. SCA removes both nodes for string_desc.

Figure 4.18, “Final Display” shows the modified type tree.

As with cross-reference or call graph queries, you can go to the source code by double clicking MB1 on a node in the display or item in the bottom window. You can also specify additional queries by choosing items from the Query pull-down menu. Choose Show Query Window to specify data structure queries. Choose Call Graphs or Cross Reference to specify call graph and cross-reference queries, respectively.

From the Cross Reference Query window, when you click MB1 on the Keep items from previous result option, SCA keeps the results from the previous query that match the new selection attributes. For example, if you ask SCA to cross reference the symbol build* then modify your query to show only declarations of build*, SCA will update the result to keep only the matching items.

Figure 4.19, “Keeping Items from the Results” shows the query specification and result.

SCA removes the module declaration from the result, as shown in Figure 4.20, “Removing Items from the Results”.

SCA adds information about copy_file to the previous results(see Figure 4.21, “Adding Items to the Results”).

In the previous examples, you performed several steps but modified the same query. SCA shows this as one query in the query result list.

SCA provides a way to navigate to the previous or next query in the query list.

LSE> NEXT QUERY

The NEXT QUERY command moves forward through the query sessions in their order of creation. The window is remapped to the buffer associated with the next query session. If there is no next query session, the previous query session is used.

LSE> PREVIOUS QUERY

The PREVIOUS QUERY command moves backward through the query sessions in the reverse order of their creation. The window is remapped to the buffer associated with the previous query session. If there is no previous query session, the next query session is used.

For DECwindows, from the Query window or Results window, pull down the Query menu and choose the Previous or Next menu item. SCA displays the query specification or result for that query.

After you create several queries, you might want to see a list of those queries and select a query for modification or deletion, or look at the query results again. The following sections describe how to access and select from the query list.

4.5.2.1. Accessing the Query List

The GOTO QUERY command moves the cursor to the specified query session. The command has the following form: GOTO QUERY name

You enter the command as follows:

LSE> GOTO QUERY 1

The GOTO QUERY command causes the query number specified by the name parameter to become the current query session and maps the buffer associated with that query session.

To access the query list in DECwindows, do the following:

1. From a Query window or a Results window, pull down the Query menu.

2. Choose the List … menu item.

The Query List dialog box is displayed. Figure 4.22, “Query List Dialog Box”shows the Query List dialog box with a list of queries.

Use the SAVE QUERY command to save queries made during an SCA session into a command file. The saved query can then be read into any SCA session by using the @file-specification command.

The SAVE QUERY command saves a query session. The command has the following form:

SAVE QUERY [query-name,...] /OUTPUT=output-file-specification

/PREFIX=name-prefix /QUALIFIERS=find-command-qualifiers

LSE> SAVE QUERY

As your list of queries grows, you might want to delete unneeded queries. The SCA delete operation always deletes the current query (the query currently displayed on the screen). You can set the current query by using Previous or Next, or the query list (see Section 4.5.1, “Moving to the Next or Previous Query” and Section 4.5.2, “Navigating Through the List of Queries”).

The DELETE QUERY command deletes a query session. The command has the following form: DELETE QUERY [name]

LSE> DELETE QUERY 1

The DELETE QUERY command deletes the specified query session. If no name is specified, the current query session is deleted. If the current query session is deleted, no current query exists.

SCA deletes the query. If there are more queries, the next query in the list becomes the current query.