This chapter describes how you perform queries, which ask the Static Analyzer for specific information about the source code files included in the fileset. This chapter covers the following topics:
For examples of using queries, refer to “Applying the Static Analyzer to Scanned Files” in Chapter 2, and “Applying the Static Analyzer to Parsed C++ Files” in Chapter 2.
The Static Analyzer has two types of queries: comprehensive queries (such as List All Functions and List Global Symbols) that do not require a query target and specific queries (such as Who Is Called By? and List Methods In Class) that do require a query target. Specific query selections in the Queries menu are grayed unless you supply target text in the Query Target field.
To enter text in the Query Target field, put the pointer in the text area and type. You can also click an element in the query results area and the Static Analyzer pastes it into the text area. For example, you can click a function name displayed in the query results area to enter the function name in the Query Target field.
To make a query based on target text, choose a query from the Queries menu. The Static Analyzer returns all elements matching the query parameters and the target text. You can also make a query by pressing the Enter key while the pointer is in the Query Target field. The Static Analyzer repeats the last type of query you made, using the contents of the Query Target field as target text.
The Static Analyzer reads target text in the Query Target field as a regular expression, which is a system of string constructions used by the UNIX ed(1) command to construct literal strings or wild card strings. Regular expression syntax is described in the man page for ed(1).
If you enter target text without using any of the following special characters, the Static Analyzer reads the text as a literal string and searches only for that text:
\ . * ( ) [ ^ $ + |
If you use special characters to create a wild card expression, the Static Analyzer searches for a variety of target text in a single query, a useful tool for expanding the scope of a specific query.
 | Note: Do not confuse regular expressions with the shell expressions you use to create a fileset. They are different systems. |
The Static Analyzer is case-sensitive and recognizes the difference between uppercase and lowercase characters in target text during queries. However, if you want to ignore case in target text during a query (useful for case-insensitive Fortran code), choose General Options from the Admin menu to open the General Options dialog box. Click the Ignore Case In Searches button to turn it on, then click the Close button to close the dialog box.
To make a query, choose a query type from the Queries menu.
The Static Analyzer displays the results in the query results area of the main window. The following sections describe the queries that you can make from the submenus of the Queries menu.
The General submenu contains a variety of general purpose queries designed to find strings or nonspecific program elements. Several of these queries find symbols, which are programmatic tokens sent to the compiler such as macro names, functions, variables, and other source code elements. The following general queries are available:
List Global Symbols: returns all global symbols found in the files defined by the fileset and ignores any target text. Global symbols are standard elements of code including functions, macros, variables, classes, and so forth.
List All Constants: returns all constants in the source code including enums,named constants, and Fortran 77 parameters.
Where Symbol Used: expects a symbol name in the Query Target field. Returns the source code locations of all references to the symbol.
Where Defined?: expects a symbol name in the Query Target field. Finds all symbols that match the target text and returns the source code locations where those symbols are defined.
Find String: expects a literal string in the Query Target field. Returns source code locations of all strings that match the target text. When you use this query, you ask the Static Analyzer not to interpret the target text as a regular expression, which allows you to use regular expression special characters as part of a literal text string.
Find Regular Expression: expects a general expression in the Query Target field. Returns source code locations of all strings that match the target text.
The Macros submenu contains queries that deal with macros. The following queries are available:
List All Macros: returns all macros found in files defined by the fileset. Ignores any target text.
Where Defined?: expects a macro name in the Query Target field. Finds all macros that match the target text and returns the source code locations where the macros are defined.
Where Undefined?: expects a macro name in the Query Target field. Finds all macros that match the target text and returns source code locations where the macros are undefined (by using #undef).
Who Uses?: finds all locations where the macro entered in the Query Target field is used.
The Variables submenu contains queries dealing with variables. In performing a variable query, you typically list variables first and then select an individual variable for further information. Figure 4-1 shows the results of the List All Global Variables selection with the _lastCmd variable selected. Notice that the variable list has five columns: Name, Function, File, Line, and Source. These identify the variable, its function or the notation of global, the file in which the variable is defined or declared, the line number at which it is first defined or declared, and the actual source line.
From the list resulting from List All Global Variables, you can select individual variables for specific queries. You do this by clicking the variable name. Figure 4-2 shows the results of a Who References? query.
The column headings in the Who References? results are the same as for List All Global Variables. In this case, however, the Line and Source fields refer to the line where the reference took place.
The Variables submenu offers the following types of queries:
List All Global Variables: returns all global variables found in files defined by the fileset. Ignores any target text.
Where Defined?: finds the locations where the variable was defined.
Who References?: expects a variable name in the Query Target field. Finds all variables that match the target text and returns all references to those variables.
Who Sets?: expects a variable name in the Query Target field. Finds all variables that match the target text and returns all source code locations where the values of the variables are set.
Where Address Taken: finds all locations where the address of the variable is taken.
List Unused Variables: lists all variables that have been defined or declared but not otherwise used in the source code.
Where Allocated: lists all locations where memory was allocated for the selected variable.
Where Deallocated: lists all locations where memory was deallocated for the selected variable.
The Functions submenu contains queries that deal with functions. It operates in similar fashion to the variable queries; that is, you create a list of functions and select individual functions for detailed queries. The following selections are available:
List All Functions: returns all functions it finds implemented in the fileset. Ignores any target text.
Where Defined?: returns all source code locations where those functions are defined.
Where Function Used: returns all source code locations where the function appears.
Who Calls?: returns all source code locations where the function is called.
Who Is Called By?: returns names of all functions called by the selected (or entered) function, including the line number and source code where the call is made.
List Undefined: returns all functions called but not implemented in the fileset (usually library functions).
List Unused Function: returns functions that were declared or defined but not otherwise used in the source code.
List Local Declarations: returns all local variables and arguments in the source code and the line and source code in which the declaration is made.
The Files submenu contains queries that deal with files. The following selections are available:
List All Files: returns all files included in the fileset as well as any included files specified by files within the fileset (such as header files). Ignores any target text.
List All Header Files: returns all header (filename.h) files in the fileset.
List Matching Files: expects either a file name in the Query Target field or no target text at all. If it finds target text, it returns all file names that match the regular expression. If it finds no target text, it returns the same results as the List All Files query.
Who Includes?: expects a filename in the Query Target field or a selected filename. Returns the names of all files that include the files specified by the target text.
Who is Included By?: expects a file name in the Query Target field or a selected file name. Returns the names of all files that are included by the specified files.
The Classes submenu contains queries that deal with C++ classes. The following queries are available:
List All Classes: returns all classes it finds in files defined by the fileset. Ignores any target text.
Where Defined?: expects a class name in the Query Target field. Finds all classes that match the target text and returns the source code locations where those classes are defined.
List Subclasses: expects a class name in the Query Target field. Returns the immediate subclasses of the classes matching the target text.
List Superclasses: expects a class name in the Query Target field. Returns the immediate superclasses of the classes that match the target text.
List Methods In Class: expects a class name in the Query Target field. Returns those methods defined within the classes that match the target text.
The Methods submenu contains queries that deal with C++ member functions, also called methods. The following queries are available:
List All Methods: returns all methods in the fileset. Ignores any target text.
Where Defined?: expects a method name in the Query Target field. Finds all methods that match the target text and returns all source code locations where those methods are defined.
Where Declared?: expects a method in the Query Target field. Returns source code locations of all class declarations that include methods that match the target text.
The Common Blocks submenu applies to Fortran source code only. The following queries are available:
List All Common Blocks: lists all common blocks in the fileset.
List All Symbols in Common Block: lists all symbols used in common blocks in the fileset.
Where Common Block Defined: expects a common block in the Query Target field. Finds all common blocks that match the target text and returns the source code locations where the common blocks are defined.
Where Common Block Referenced: returns all source code locations where the common block appears.
The Types submenu helps you get type information. The following queries are available:
Where Type Defined: expects a type in the Query Target field. Finds all types that match the target text and returns the source code locations where the types are defined.
List Functions Of Type: returns all functions of the given type and the source code locations where they are declared or defined.
List Data Of Type: returns all data declarations and definitions using the given type and the source code locations where they are declared or defined.
Where Type Used: returns all source code locations where the type and where functions and data items using the type appear.
When the Static Analyzer returns query results, you can look at each element's source code. To do this, double-click an element in the query results area, or single-click an element and then choose Edit from the Admin menu. Either of these actions opens up the Source View window.
The Source View window opens the file containing the element and highlights the source line. Although this window is set by default to be read only, you can edit text if you wish. If you have a configuration management tool installed, you can use the Versioning selection from the File menu to check out the file for editing.
If you prefer to view source code in a text editor window, choose General Options from the Admin menu to open the General Options dialog box, which offers the Use Source View selection. Turn this option off to select vi as your text editor for source code. To set a different alternate text editor, add the following line to your .Xdefaults file, where editor is the command for the editor you want to use:
*editorCommand: editor |
The next time you use the Static Analyzer with the Source View option turned off, the editor you specified will appear when you view source code.
The Static Analyzer retains a list of your 15 most recent queries and presents them in the History menu. You can choose any of the queries listed in this menu to repeat the query. The Static Analyzer remembers the query type and the target text it used; it does not remember any view settings, such as the view type, view options, or Scope Manager settings. If you change view settings and then choose a query from the History menu to repeat the query, the Static Analyzer will return the same query results but will display them differently.
You can save query results by choosing Save Query from the Admin menu to open the Save Query File Browser window shown in Figure 4-3.
To save query results, move to the directory in which you want to make the save. To specify a directory, you can use the path navigation bar, enter a path in the text field, or drag a folder into the drop pocket. Then click the OK button to save the query results and close the Save Query File Browser window.
The Static Analyzer saves the contents of the query results area to the file you named in the Browser. If you are in Text View, the Static Analyzer saves the results in text format. If you are looking at a graphical view, the graph is saved in PostScript format. The Static Analyzer adds a heading to the text that lists the query type and the target text that specified the query. It also includes field headings that match those at the top of the query results area in the main window.