Chapter 4. Static Analyzer: Queries

Chapter 4. Static Analyzer: Queries
Prev		Next

This chapter covers queries, which ask the Static Analyzer for specific information about the source code files included in the fileset. You'll find these topics here:

For examples of using queries, refer to "Tutorial 1: Applying the Static Analyzer to Scanned Files" and "Tutorial 2: Applying the Static Analyzer to Parsed C++ Files."

Defining the Scope of a Query

The Static Analyzer has two types of queries: comprehensive queries, such as "List All Functions" and "List Global Symbols," that don't require a query target; and specific queries, such as "Who Is Called By?" and "List Methods In Class," that require a query target. Specific queries are grayed in the Queries menu 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; 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 that match the parameters of the query and the target text. You can also make a query by pressing <Enter> 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. Use this convenient keyboard shortcut to repeat a query with a new target text each time—for example, if you're following a thread of function calls.

Target Text as a Regular Expression

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 command to construct literal strings or wild card strings. Regular expression syntax is described in the reference (man) pages for ed; you'll also find the same description on the Static Analyzer's Help screen for regular expressions.

If you enter target text without using any regular expression special characters (which are \, ., *, (, ), [, ^, $, and +), the Static Analyzer reads the text as a literal string (without wild cards) 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: Don't confuse regular expressions with the shell expressions you use to create a fileset. They're completely different systems. For example, the regular expression "q.*" matches strings that begin with "q," while the shell expression "q.*" matches strings that begin with "q."

Case Sensitivity

The Static Analyzer normally recognizes the difference between uppercase and lowercase characters in target text during queries. If you want to ignore case in target text during a query (useful for Fortran code, which is case-insensitive), choose "General Options" from the Admin menu to open the General Options dialog box shown in Figure 4-1. Click the "Ignore Case In Searches" button to turn it on, then click the Close button to close the dialog box. You can return to the dialog box to turn off the option when you want to recognize case in queries.

Figure 4-1. The General Options Dialog Box

Making a Query

To make a query, choose a query type from the Queries menu, which organizes queries in submenus of related queries (see Figure 4-2). The Static Analyzer shows the results in the query results area of its main window, using the view that is turned on. If the view isn't appropriate for the query (file dependency view for a function query, for example), the Static Analyzer informs you; no elements are listed in the query results area.

Figure 4-2. Static Analyzer Queries Menu with Submenus

General Queries

Figure 4-3. Queries Submenu: "General"

The "General" submenu (see Figure 4-3) 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—macro names, functions, variables, and other source code elements. The general queries are:

"List Global Symbols"		returns all global symbols it finds in the files defined by the fileset. It ignores any target text. (Global symbols are standard elements of code: functions, macros, variables, classes, and so forth.)
"List All Constants"		returns all constants in the source code (includes `enums`, named constants, and Fortran 77 parameters).
"Where Symbol Used?"		expects a symbol name in the Query Target field. It returns the source code locations of all references to the symbol.
"Where Defined?"		expects a symbol name in the Query Target field. It 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. It returns the 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. It returns the source code locations of all strings that match the target text.

Macro Queries

Figure 4-4. Queries Submenu: "Macros"

The "Macros" submenu (see Figure 4-4) contains queries that deal with macros:

"List All Macros"		returns all macros it finds in the files defined by the fileset. It ignores any target text.
"Where Defined?"		expects a macro name in the Query Target field. It finds all the macros that match the target text and returns the source code locations where those macros are defined.
"Where Undefined?"		expects a macro name in the Query Target field. It finds all the macros that match the target text and returns the source code locations where those macros are undefined (using `#undef`).
"Where Used?"		finds all locations where the macro entered in the Query Target field is used.
"List Unused Macros"		lists macros defined but never used.

Variable Queries

The "Variables" submenu contains queries that deal with variables. In performing a variable query, you typically list variables first and then select an individual variable for further information. Figure 4-5 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 <global> if no function, the file in which it is defined or declared, the line number at which it is first defined or declared, and the actual source line.

Figure 4-5. "List All Global Variables" Results with Variable Selected

From a 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-6 shows the results of a "Who References?" query.

Figure 4-6. "Who References?" Results

The column headings are the same as for the "List All Global Variables" query results. In this case, the Line and Source fields refer to the line where the reference took place.

Figure 4-7. Queries Submenu: "Variables"

The "Variables submenu" appears in Figure 4-7 and offers these selections:

"List All Global Variables"		returns the global variables it finds in files defined by the fileset. It ignores any target text.
"Where Declared?"		finds the location where the selected variable was declared.
"Where Defined?"		finds the location(s) where the variable was defined.
"Who References?"		expects a variable name in the Query Target field. It 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. It finds all variables that match the target text and returns all source code locations where the values of those 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.

Function Queries

Figure 4-8. Queries Submenu: "Functions"

The "Functions" submenu (see Figure 4-8)contains queries that deal with functions. It operates in similar fashion to the variable queries—you create a list of functions and select individual functions for detailed queries. The selections are:

"List All Functions"		returns all functions it finds implemented in the fileset. It ignores any target text.
"Where Function Declared"		returns the location where the function was declared.
"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 the 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.

Files Queries

Figure 4-9. Queries Submenu: "Files"

The "Files" submenu (see Figure 4-10) contains queries that deal with files.

"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). It ignores any target text.
"List All Header Files"		returns all header (`<filename>.h`) files in the fileset.
"List Matching Files"		expects either a filename in the Query Target field or no target text at all. If it finds target text, it returns all filenames 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. It returns the names of all files that include the file(s) specified by the target text.
"Who is Included By?"		expects a filename in the Query Target field or a selected filename. It returns the names of all files that are included by the specified file(s).

Class Queries

Figure 4-10. Queries Submenu: "Classes"

The "Classes" submenu (see Figure 4-11) contains queries that deal with C++ classes:

"List All Classes"		returns all classes it finds in the files defined by the fileset. It ignores any target text.
"Where Defined?"		expects a class name in the Query Target field. It 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. It returns the immediate subclasses of the classes matching the target text.
"List Superclasses"		expects a class name in the Query Target field. It 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. It returns those methods defined within the classes that match the target text.

Method Queries

Figure 4-11. Queries Submenu: "Methods"

The "Methods" submenu (see Figure 4-12) contains queries that deal with C++ member functions, also called methods:

"List All Methods"		returns all methods in the fileset. It ignores any target text.
"Where Defined?"		expects a method name in the Query Target field. It 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. It returns source code locations of all class declarations that include methods that match the target text.

Common Blocks Queries

Figure 4-12. Queries Submenu: "Common Blocks"

The "Common Blocks" submenu (see Figure 4-13) applies to Fortran source code only. It contains these selections:

"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. It 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.

Types Queries

Figure 4-13. Queries Submenu: "Types"

The "Types" submenu (see Figure 4-14) helps you get type information. It contains the following choices:

"List All Types"		returns all types used in the source code.
"Where Type Defined"		expects a type in the Query Target field. It 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 functions and data items using the type appear.

Directories Queries

Figure 4-14. Queries Submenu: "Directories"

The "Directories" submenu (see Figure 4-15) helps you determine the organization of the current fileset. It contains these selections:

"List Directories"		lists all directories in the fileset.
"List Files"		lists all files in the fileset.

Packages Queries

Note: The "Packages" submenu is only available if you have purchased the ProDev Ada package.

Figure 4-15. Queries Submenu: "Packages"

The "Packages" submenu helps you get package information when you are analyzing programs written in Ada. It contains

"List All Packages"		lists all packages in the fileset
"Which Package Defines"		expects a package name in the Query Target field. It finds all package that match the target text and returns all source code locations where those packages are defined.
"List Functions"		expects a package name in the Query Target field and returns all functions declared in the package spec and the body.
"List Data"		expects a package name in the Query Target field and returns data declared in the package spec and body.
"Where Withed"		expects a package name in the Query Target field and returns all packages that with the given package.

Tagged Types Queries

Note: The "Tagged Types" submenu is only available if you have purchased the ProDev Ada package.

Figure 4-16. Queries Submenu: "Tagged Types"

The "Tagged Types" submenu

"List All Tagged Types"		lists all tagged types in the fileset.
"Where Tagged Types Defined"		expects a tagged type name in the Query Target field and returns all tagged types that match the target text and returns all source code locations where those tagged types are defined.
"List Parent Types"		lists the parent types for the tagged type entered in the Query Target field.
"List Derived Types"		lists the derived types for the tagged type entered in the Query Target field.
"List Primitive Operations"		lists the primitive operations for the tagged type entered in the Query Target field.
"List Components"		lists the parent types for the tagged type entered in the Query Target field.
"Where Type Used"		returns all declarations of functions and data of this type. as well as sites where other types derive from this one or refer to it.

Task Types Queries

Note: The "Task Types" submenu is only available if you have purchased the ProDev Ada package.

Figure 4-17. Queries Submenu: "Directories"

The "Task Types" submenu

"List All Task Types"		lists all task types in the fileset.
"Where Task Type Defined"		expects a task type name in the Query Target field and returns all task types that match the target text and returns all source code locations where those task types are defined.
"List Entries"
"List Body Data"		lists the data local to the body for the given task type.
"List Body Functions"		lists all non-entry functions local to the task body.
"List Body Types"		lists all types declared that are local to the task body.
"Where Type Used"		lists all tasks of this type, as well as other types that derive from this type or refer to it.

Viewing Source Code

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 as shown in Figure 4-18.

The Source View window opens the file containing the element and highlights the source line. Although the Source View 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.

Figure 4-18. The Source View Window With Highlighted Source Code

Alternate Text Editors

If you prefer to view source code in a text editor other than Source View, you can choose "General Options" from the Admin menu to open the General Options dialog box, which offers the option Use Source View. Turn this option off to use the default alternate text editor, vi, whenever you double-click to see source code. To set a different alternate text editor, add the line

*editorCommand: <editor>

to your .Xdefaults file, where <editor> is the command for the editor you wish to use. 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.

Repeating Recent Queries

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 doesn't 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.

Saving Query Results

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-19. This is the standard Save File Browser.

Figure 4-19. The Save Query File Browser Window

To save query results, move to a 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're in Text View, the Static Analyzer saves the results in text format; if you're looking at a graphical view, the graph is saved in PostScript format. It adds a heading to the text that lists query type and the target text that specified the query. It also includes field headings (such as Function, File, and so on) to match those at the top of the query results area in the main window.

Prev	Table of Contents	Next
Chapter 3. Static Analyzer: Creating a Fileset and Generating a Database		Chapter 5. Static Analyzer: Views