TOC PREV NEXT INDEX DOC LIST MASTER INDEX



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:

Each command description has the following format:


Command_Name

The 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:

aa locate_attributes -include_first_attributes -to_report_named attribute_rpt 
/devel/code.ss/rev1.wrk

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:

$AA_HOME/base/ada/test_ada_analyzer.ss

Test input is located in:

$AA_HOME/base/ada/testing/test_input.ss

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

Check_Consistency
  -Create_Missing_Items
  <list of configuration-policy directories>

Nonstandard Parameters

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

Check_Reports_Up_To_Date
  <list of reports>

Nonstandard Parameters

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:

Command-Line Interface

Collect_Metrics
  -Attempt_Collection_In_Uninstalled_Units
  -Compute_Weighted_Average
  -Compute_Horizontal_Totals
  -Compute_Vertical_Totals
  -Sort_By_Subsystem
  -Use_Configuration [string-expression, default = ""]
  -To_Report_Named [string-expression, default =
      <default_output_directory>/collected_metrics]
  <list of units>

Nonstandard Parameters

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

Collect_Statistics
  -Collect_By_Unit
  -Collect_By_Subsystem
  -Collect_By_Column
  -Column_Name
  -Report_By_Table
  -Table_Number
  -Sort_By_Subsystem
  -Use_Configuration = [string-expression, default = ""]
  -To_Report_Named = [string-expression, default =
      <default_output_directory>/statistics_report]
  <list of reports>

Nonstandard Parameters

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

Compare_Metrics
  -Compute_Average
  -Compute_Vertical_Totals
  -Sort_By_Subsystem
  -To_Report_Named [string-expression, default =
      <default_output_directory>/comparison_report]
  <list of reports>

Nonstandard Parameters

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

Compare_Reports
  -Include_Linakge
  -Include_Matches
  -Ignore_Line_Numbers
  -To_Report_Named [string-expression, default =
      <default_output_directory>/data_synchronization_analysis]
  <list of reports>

Nonstandard Parameters

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

Compare_Unit_Construct_Counts
  -Include_Unit_Totals
  -Display_Totals_Only
  -Include_Major_Element_Counts
  -Include_Comp_Unit_Kind_Counts
  -Include_Declaration_Kind_Counts
  -Include_Statement_Kind_Counts
  -Include_Pragma_Kind_Counts
  -Include_Context_Clause_Kind_Counts
  -Include_Rep_Clause_Kind_Counts
  -Include_Length_Clause_Kind_Counts
  -Include_Parameter_Mode_Counts
  -Include_Generic_Parameter_Mode_Counts
  -Include_Loop_Kind_Counts
  -Include_Select_Alternative_Kind_Counts
  -Include_Expression_Kind_Counts
  -Include_Type_Definition_Kind_Counts
  -Use_Configuration [string-expression, default = ""]
  -To_Report_Named [string-expression, default =
      <default_output_directory>/comparison_construct_counts]
  <list of units>

Nonstandard Parameters

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

Count_Lines_Of_Code
  -Sort_By_Subsystem
  -Use_Configuration [string-expression, default = ""]
  -To_Report_Named [string-expression, default =
      <default_output_directory>/line_counts]
  <list of units>

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

Create_New_Configuration_Policy
  -Configuration_Policy [string-expression, default = ""]
  -New_Policy [string-expression, default = "Default_Configuration"]

Nonstandard Parameters

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

Display_Call_Tree
  -To_Depth [positive-expression, default = 999]
  -Display_Flat
  -Full_Expansion
  -Collapse_Multiple_Calls_To_Same_Subprogram
  -Exclude_Decls_Halting_Recursion
  -Walk_Into_Entry_Accept
  -Units_Or_Decls_Halting_Recursion [string-expression, default = ""]
  -Sort_By_Dependency_Order
  -Use_Configuration [string-expression, default = ""]
  -To_Report_Named [string-expression, default =
      <default_output_directory>/call_tree]
  -Of_Subprogram_Or_Task [string-expression, default = ""]

Nonstandard Parameters

Sample Output


Rational Software Corporation  http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2000, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX DOC LIST MASTER INDEX