| |
|
|
|
|
|
CHAPTER 3:
Command Descriptions This chapter provides complete descriptions of Ada Analyzer analysis commands. All commands are listed in alphabetic order for easy reference. Together with Chapter 2, "Quality-Improvement Objectives," this chapter provides all information necessary to apply the Ada Analyzer to your quality-improvement objectives. Chapter 5, "Command Cross-Reference," provides three cross-reference tables for determining which command best suits your requirements:
- "Construct to Be Located and Command To Use" on page 271
- "Quality-Improvement Objectives and Command to Use" on page 278
- "Command-Line Summary" on page 283
Each command description has the following format:
Command_NameThe first paragraph gives a description of the analysis information collected by each command.
Usage Tip: Tips contain suggestions and examples of how best to use this command or interpret the output it generates.
Command-Line Interface
The UNIX command-line syntax required to invoke the command is provided here. Normally, Ada Analyzer commands are invoked through a menu choice and subsequent modification of a dialog box, but it is also possible to invoke commands directly at the command line. The name of the main command is aa. The name of each command must appear as the first option in the command line. Boolean options appear at the beginning of the option list, although all options can appear in any order. Including a Boolean option in the command line enables that option during command execution. Numeric options appear next and require that an integer value follow immediately as the next token in the command line. The default for each numeric option is included in the description. String options with their defaults appear next.
The standard parameters Sort_By_Subsystem, Use_Configuration, and To_Report_Named generally appear next, followed by the list of units to process. Most commands have the standard parameter options listed above. The list of units to process must appear at the end of the command line. Thus an example command might be:
Nonstandard Parameters
A description of any nonstandard parameters is provided in this section. Standard parameters such as Sort_By_Subsystem, To_Report_Named, Use_Configuration, and the list of Ada units to analyze are not repeated here. See "Parameter Options" on page 2 for more information on these standard command parameters.
Sample Output
Sample hypertable output from the command is provided here. In some cases, commands generate multiple tables. Examples of each are provided when they differ significantly and merit separate explanation.
Following each hypertable is an explanation of each output column, noting which Ada constructs it is connected to and what explanatory text is available. An example of this diagram appears below. Note that a "greater-than" (>) character appears in a column header if [Visit] is enabled for that column. A description of the contents of a table is provided when the [Explain] operation is used on the title of the table. Explanatory text is also available for each column.
Note: All examples given in this chapter have been generated with the Display_Subsystem_Names switch set to False. Thus, the SS column does not appear in any of the sample output sections. This was done to reserve as much space as possible for the other, more important attribute columns.
The Ada Analyzer provides test programs to verify that it is functioning correctly. These also can be used to experiment with command operation, hypertable output, and the traversal and explain connections within each table. These test main programs are located in:
These test programs are delivered in the archived state (uncompiled) to save space. To execute, the test programs must be compiled and linked. The test input must also be compiled.
Check_Consistency
This command verifies that the structure of a configuration-policy directory is correct and that all files are present. An expanded directory image of a configuration-policy directory can be found in "Configuration Structure and Content" on page 21.
Command-Line Interface
Nonstandard Parameters
- Create_Missing_Items: Specifies that any files found to be missing are to be created. New files are created by copying from the default_configuration in $AA_HOME. In addition, this option will add missing analysis switches to the analysis_switch_file, missing rule enforcements to the standards_conformance/rule_enforcement file, and missing metrics collection enforcement to the metrics_collection/metrics_collection_status file. This can be used to automatically add these items to existing configuration-policy directories when new releases are received.
- <list of configuration-policy directories>: Specifies the names of configuration-policy directories to check. The default is the currently active configuration. See "Determining the Currently Active Configuration Policy" on page 25 for more information.
Check_Reports_Up_To_Date
This command will check a set of Ada Analyzer reports (.aarpt files) to determine if the information contained within them is up to date. Each unit that was processed to create the original report is checked to see if it has been modified in the local view or checked out and modified in another view of the subsystem. Log entries are generated for each unit that is not the latest version or has been modified since the creation date of the report.
Usage Tip: This command can be used to verify that the information in an Ada Analyzer report is consistent with the current state of the Ada units under development. Out-of-date reports should be regenerated based on the current set of Ada units.
Command-Line Interface
Nonstandard Parameters
- <list of reports>: Specifies a list of Ada Analyzer reports (.aarpt file) to check. Ada units, views, and/or directory objects are not valid input to this command.
Collect_Metrics
This command traverses the specified list of units and locates each compilation unit and program unit declared within them. As specified by the enabled status for each metric in the metrics library, a count or metric value is obtained for each compilation unit or program unit and placed in the hypertable. Command options determine whether totals and/or weighted averages are computed and added to the hypertable.
The metrics_collection_status file in the metrics_collection directory of the current configuration-policy directory defines which metrics are enabled, the table in which they will appear, and their relative weight. Enabled status values are not_enabled, collect_by_compilation_unit, collect_by_program_unit, collect_by_subprogram_body, and collect_by_subprogram_and_-task_bodies. See "Metrics-Collection Files" on page 34 for a description of each status value. Table names can be any string. Relative weights can be any integer value. The following restrictions apply:
- No more than five metrics can be defined for each table
- All metrics in a table must be enabled with the same status
Usage Tip: Metrics can be used to qualify code against some standard, but they are more useful when they are compared over time. It is thus recommended that metrics be collected at regular intervals, at release points, or on some regular schedule.
Command-Line Interface
Nonstandard Parameters
- Attempt_Collection_In_Uninstalled_Units: Specifies whether to attempt to collect metrics in all units even if they are not installed. If collection of that metric fails because the unit is not installed, a message for that unit will be displayed and a metric of 0 will be listed in the output.
- Compute_Weighted_Average: Specifies that a weighted average of all metrics for a particular compilation unit or program unit should be computed and placed in a column titled "Weighted Average." Weights for each metric are defined in the metrics_collection_status file as described above.
- Compute_Horizontal_Totals: Specifies that all metrics for a particular compilation unit or program unit should be totaled and placed in a new column titled "Total."
- Compute_Vertical_Totals: Specifies that vertical totals (a total of all units) should be computed for each metric and added as a new row in the hypertable.
Sample Output
Collect_Statistics
This command collects statistics on the number of occurrences of names and text values in Ada Analyzer reports. Statistics can be collected on unit names, subsystem names, or entries in named columns. Statistics can be collected in a specific table, on a table by table basis, or for an entire report or set of reports.
Usage Tip: This command can be useful to identify units or subsystems that appear very often in certain reports. If statistics are collected on code-correctness reports in may indicate that a particular unit or subsystem should receive additional scrutiny.
Command-Line Interface
Nonstandard Parameters
- Collect_By_Unit - Specifies that statistics should be collected on all unit names that appear in the analyzed reports.
- Collect_By_Subsystem - Specifies that statistics should be collected on all subsystem names that appear in the analyzed reports.
- Collect_By_Column - Specifies that statistics should be collected on text entries in columns specified by the Column_Name option below.
- Column_Name - Specifies the name of the column from which to collect statistics.
- Report_By_Table - Specifies that statistics should be collected and reported separately for each table in the report.
- Table_Number - Specifies the table number in the report from which to collect statistics. The default, 0, indications that statistics should be collected from all tables in the report.
- <list of reports> - Specifies the list of report (.aarpt) files that should be processed.
Sample Output
Unit Statistics
Compare_Metrics
This command compares metrics collected at different times for the same or a similar set of Ada units. The reports specified are time-ordered, and differences between the current and previous collection are computed.
Usage Tip: Metrics comparison can be very useful in estimating project status and/or completion milestones. Trends, both bad and good, can also be identified from time-line data.
Command-Line Interface
Nonstandard Parameters
- Compute_Average: Specifies that an average of all metrics being compared for each compilation unit or program unit should be computed and placed in the last column of the hypertable.
- Compute_Vertical_Totals: Specifies that vertical totals be computed for each metric.
Note: The last parameter must specify a list of report files to compare, not a list of Ada units.
Sample Output
Compare_Reports
This command takes two reports generated by the same Ada Analyzer command and compares the table entries in those reports. The output report table entries display a "1" if they appear in the first report and not in the second, and a "2" if the appear in the second report and not in the first. If the option Include_Matches is enabled and the entry appears in both reports, then the output entry will display a "1/2".
Usage Tip: This command can be used to compare two analysis reports generated for different software-release versions to determine which constructs have been added or deleted. It can also be used to verify that nothing has changed in a critical area since the last release.
Command-Line Interface
Nonstandard Parameters
- Include_Linkage: Specifies whether or not the linkage information associated with each input report should be transferred to the output report.
- Include_Matches: Specifies whether or not table entries that are identical in both input reports should be listed in the output report.
- Ignore_Line_Numbers: Specifies that line numbers that may appear in the Units column of the report should be ignored during comparison. This is useful when the report information has moved to a new line in the Ada unit but is otherwise the same.
- <list of reports>: Specifies a list of reports (.aarpt files) to compare for differences. Two reports generated from the same Ada Analyzer command must be specified for comparison.
Compare_Unit_Construct_Counts
For each construct kind, this command produces tables that show the number of each construct in each unit processed.
Usage Tip: One specific use of this report is to locate extremely high (or low) numbers of specific constructs. In particular, a high number of with clauses in unit may indicate a structural problem. High use of some pragmas, certain type declarations, and certain expressions may suggest further analysis with other Ada Analyzer commands to provide more detailed information about those constructs.
Command-Line Interface
Nonstandard Parameters
- Include_Unit_Totals: Specifies whether to include summary tables of counts for all constructs in all units.
- Display_Totals_Only: Specifies that only summary totals be included and not counts for each individual unit.
- Include_*: Specifies whether to include counts for the * kind of construct.
Sample Output
Count_Lines_Of_Code
This command selects the line-counting metrics from the metric library and enables them directly rather than through the metrics_collection_status file. This command is a specific instance of the more general Collect_Metrics command. In this instance, a subset of the library metrics have been broken out into their own named command. Chapter 4, "Customization," discusses how to use a template to break out other sets of metrics into separate commands.
Command-Line Interface
Nonstandard Parameters
All parameters are standard parameters.
Sample Output
Note: A description of the meaning of each line-counting metric appears on page 328
Create_New_Configuration_Policy
This command creates a new configuration policy by copying the configuration policy specified in the Configuration_Policy parameter into a new configuration-policy directory specified by the New_Policy parameter. The parent directory, configuration_policy, and the current-_configuration file will be created as necessary. See "Configuring the Ada Analyzer" on page 21 for more information.
Usage Tip: Projects may create several different configuration-policy directories for use at different project times or in different contexts. Users may have their own, separately customizable configuration policy by creating a new configuration policy in their home directory.
Command-Line Interface
Nonstandard Parameters
- Configuration_Policy: Specifies the name of the configuration-policy directory to use as the source for the copy. The default is the currently active configuration policy. See "Determining the Currently Active Configuration Policy" on page 25 for more information.
- New_Policy: Specifies the name of the new configuration-policy directory to create. If the value of this parameter is a simple name, then the new configuration will be created in the user's home directory.
Display_Call_Tree
This command displays the complete call tree for any subprogram, task, or package body with explicit elaboration code. The calling structure is displayed in an indented hierarchy with cross-references when subprograms appear more than once. An option to display all subprogram calls in a flattened format is also available. If the traversal through the call tree arrives at a unit in the source state, further traversal through calls in that unit will not be performed. All objects appear in a hypertable for easy location and traversal. Every attempt is made to walk through calls to generic formal subprograms. For this to work, however, the original call to a subprogram in a generic must be prefixed by the instantiated unit name.
Usage Tip: The output from this command can be used for interactive analysis, to support test generation, or to generate reference information for project use or delivery to the customer. The analysis switch Include_Line_Numbers can be set to True to indicate the line number on which each procedure declaration occurs. This can be used to differentiate calls to overloaded subprograms.
Note: The Of_Subprogram_Or_Task field at the top of the dialog box identifies the subprogram or task for which a call tree should be generated. Use of Ada selection is the best way to fill this field with a valid reference. It is possible to identify an overloaded subprogram by using a nickname attribute.The name attribute `N(1) or `N(2) can be added to select the first or second or Nth (in order of appearance) overloaded subprogram. Name resolution for references with embedded declaration numbers is also supported. Name references can also have the form "Package_Name.5D." This references the fifth declaration in the package named Package_Name. Note that use clauses and representation specifications are not counted as declarations, but pragmas are counted. Apex will often use these name references to specify a particular declaration.
Command-Line Interface
Nonstandard Parameters
- To_Depth: Determines how many levels of the call tree should be displayed.
- Display_Flat: Displays each subprogram in the call tree with only those subprograms that it calls. Cross-references are still maintained.
- Full_Expansion: Specifies whether all subprogram call trees should be fully expanded even if they appear previously in the call hierarchy. This can provide better local understanding without having to follow several references. Only recursive subprograms will not fully expand if this parameter is True. For large call trees, enabling this option may require a very large amount of computation time.
- Collapse_Multiple_Calls_To_Same_Subprogram: Specifies that when a subprogram calls another subprogram multiple times, these calls can be reduced to one table entry.
- Exclude_Decls_Halting_Recursion: Specifies whether or not to exclude a subprogram from the report if it is one specified by the Units_Or_Decls_Halting_Recursion option.
- Walk_Into_Entry_Accept: Specifies whether or not to include subprogram/entry calls within accept statements. Subprogram and entry calls within accept statements will be included when two conditions are met: 1) There is only one accept for the entry, and 2) The accept is implemented as a do block. In this case, single thread semantics are preserved and all calls within the sequence of statements in the do block will be listed in the report.
- Units_Or_Decls_Halting_Recursion: Specifies a set of Ada units or procedure declarations that should halt the recursive computation of the call tree closure. Use of this parameter can bound the closure to some limiting set of procedures. A list of views, directories, Ada units, or specific procedure declarations can be entered for this parameter. The inclusion of Ada units specifies any procedure declaration in that unit.
- Sort_By_Dependency_Order: Sorts all subprograms in call-dependency order when the Display_Flat option is selected. If Sort_By_Dependency_Order is not selected, subprograms will be sorted alphabetically by name.
- Of_Subprogram_Or_Task: Specifies the pathname of the subprogram or task for which the call tree is desired. The syntax of this pathname follows standard UNIX notation up to the compilation-unit name. Ada dot notation is used to select a specific subprogram or task declaration within the compilation unit.
Sample Output
| Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2000, Rational Software Corporation. All rights reserved. |
| |
|
|
|
|
|
 |
 |