TOC PREV NEXT INDEX DOC LIST MASTER INDEX


CHAPTER 1:

Getting Started

You must have two things to begin executing Ada Analyzer commands:

These items are the minimum requirements to execute Ada Analyzer commands. The remainder of this chapter provides the information necessary to use all features of the Ada Analyzer effectively.

This chapter begins with a short introduction on installation. The next section, "Command Execution", describes the invocation of commands and the expected parameter-option inputs. It describes both standard and nonstandard parameter options and errors that may be reported in command logs.

The section titled "Hypertable Report Output" describes what a hypertable is, how it is used to contain the output of the Ada Analyzer commands, and how you can manipulate the output to get more information.

The section "Online Documentation" describes how to access the online documentation for the Ada Analyzer.

The section"Configuring the Ada Analyzer" explains the configuration options (analysis switches) available within the Ada Analyzer and how to change them to optimize the contents of the output and its format.

Installation

Installation of the Ada Analyzer is a straightforward process that is similar to the installation of layered products offered by Rational. The following steps are required to install the Ada Analyzer:

1. Read the release tape or CD.

2. Execute the installation procedures.

3. Register the Ada Analyzer with the authorization code provided for the machine on which the installation was performed.

These steps are described in detail in a separate section of the Apex installation Guide.

Command Execution

Ada Analyzer commands can be executed either by entering them at the shell command line or through the graphical user interface (GUI) using menus and dialog boxes. Menus offer a convenient way of indicating which command to execute, and dialog boxes offer a convenient method of collecting parameter options for Ada Analyzer commands. When a dialog box is completed, it makes a call to the command-line interface with the options and parameters selected by the user.

Ada Analyzer commands have the following command-line syntax: 

 aa command_name

   -Boolean_Parameter_Option

   -Threshold_Parameter_Option [integer-expression, default = N]

   -String_Parameter_Option [string-expression, default = ""]

   -Sort_By_Subsystem

   -Use_Configuration [string-expression, default = ""]

   -To_Report_Named [string-expression, default =

       <default_output_directory>/collected_metrics]

   <list of units>

The Ada Analyzer main program, named aa, is called to invoke the command-line parser. The name of the Ada Analyzer command must be the first argument, followed by parameter options in any order. All options have a name and are indicated with the hyphen (-) prefix character. The list of units to process appears after all named options have been specified. Multiple unit pathnames should be separated by spaces.

The precise set of options supported by each command is described in Chapter 3. The Sort_By_Subsystem, Use_Configuration, and To_Report_Named options are considered standard parameter options because they appear in almost every Ada Analyzer command. A description of these options is provided in this section and is not repeated in every command description. A general description of Boolean, threshold, and string options is also provided.

Parameter Options

Although the Ada Analyzer is most effective when used interactively through the GUI, it is also useful to create batch-oriented scripts that can be scheduled to collect analysis information at regular intervals. See the section titled "Creating Command-Line Scripts" on page 265 for more information.

Command Execution through the GUI

Most users will find that invocation of Ada Analyzer commands through menus and dialog boxes is more convenient than the command-line form. A set of cascading menus is available to invoke each Ada Analyzer command. The top-level menu is named Analyzer and appears as follows when "Torn off" for continued access. Menus can be pulled down as well.

Each item in this menu has a second-level menu that can be selected by moving the cursor over the triangle on the right side of the top-level menu. Each third-level menu contains a list of Ada Analyzer commands. For example:

The ellipsis (...) indicates that a dialog box will be displayed for collection of command options if that menu item is selected.

The "Recommended Analysis" provides sub-menus offering a recommended list of Ada Analyzer commands to developers, designers, code reviewers, managers, and quality assurance personnel that support their software development activities. In addition, commands are also suggested for the analysis of legacy code and automate generation of supporting documentation.

In order to make commands easier to find by users familiar with the Ada Analyzer, four command locator menus are available in the main Analyzer menu. The sub-menu "Display_ commands" contains all commands whose name begins with "Display_". The sub-menu "Locate_ commands A-N" contains all commands whose name begins with "Locate_A" through commands that begin with "Locate_N". The sub-menu "Locate_ commands O-U" contains all commands whose name begins with "Locate_O" through commands that begin with "Locate_U". The sub-menu "Other commands" contains all commands that do not begin with "Display_" or "Locate_".

All Ada Analyzer commands use the same dialog-box format to collect command options. Two commands, Check_Consistency and Create_New, under the Configuration Policy menu item have their own dialog boxes and are described later in this chapter. See "Configuring the Ada Analyzer" for more information on these commands.

Some commands that apply only to Ada units or specific declarations within Ada units only appear in menus in Ada unit windows. They do not appear in directory object windows since their analysis cannot be apply to entire Ada units or sets of Ada units.

All Ada Analyzer commands use the following dialog-box format. The example below contains all possible fields in the dialog box. Many commands will not have all these fields in their dialog box. For example, many commands do not have any thresholds, and most will have only one locator for the units to analyze.

The preceding dialog box is divided into seven sections where the user can enter or select command options.

Command Logs

Execution of any Ada Analyzer command generates the following log entries:

If all goes well, each entry is reported as a positive message (+++). An example log follows: 

::: [Version AA_APEX Rev2_1, ASIS 110.2.5.1, Locate_Subprogram_
... Complexities (Units => "/export/projects/ada_analyzer/utilities.ss/rev2.wrk/
... ipc_server/apex_ada_analyzer_server.2.ada",Minimum_Statement_Depth =>  4,
... Minimum_Number_Of_External_Calls =>  5,Minimum_Number_Of_External_Var_Refs 
... =>  5,Minimum_Number_Of_Procedure_Returns =>  0,Minimum_Number_Of_Function_
... Returns =>  1,Minimum_Number_Of_Execution_Paths =>  5,Relationship => OR_
... RELATIONSHIP,Use_Configuration => "",To_Report_Named => "/export/projects/
... ada_analyzer/testing/test_output/subprogram_complexity_analysis",With_Sort_
... Order => DEFAULT_SORT);]
--- Using Ada Analyzer Configuration Policy: /export/home/dhe/
... configuration_policy/default_configuration
--- Opening Asis Libraries
+++ Processing /export/projects/ada_analyzer/utilities.ss/rev2.wrk/
... ipc_server/apex_ada_analyzer_server.2.ada
+++ Traversal Complete
+++ Sorting
+++ Adding table to document
+++ Saved tables in /export/projects/ada_analyzer/testing/test_

... output/subprogram_complexity_analysis.aarpt
::: [end of Locate_Subprogram_Complexities operation -- No errors detected]

Warning and Error Messages

Warning (!!!) or error (***) messages also may appear in the log. Each is explained with an example.

Error: Unit Does Not Resolve

If the <list of units> parameter option does not resolve to a set of directory objects, the following error message will be displayed: 

*** /projects/code.ss/rew3.wrk is not a valid pathname.
::: [end of Locate_Complex_Expressions.Display operation -- 1 error detected].

Note that this error message is impossible if the file locator in the dialog box is used. This message can appear only when the command line is used to invoke Ada Analyzer commands.

Warning: Object Is Not an Ada Unit

If an object specified by the <list of units> option is not of class Ada, the following warning can be expected in the log: 

!!! /local/tools/ada_analyzer/ada_analyzer.ss/rev1.wrk/a_text_File
... is not an Ada unit.

Warning: Object Is Not Installed or Coded

If an object specified by the <list of units> option is of class Ada but is not installed or coded, the following warning can be expected in the log: 

!!! /local/tools/ada_analyzer/ada_analyzer.ss/rev1.wrk/an_ada_unit.1.ada
... is not installed.

Error: Object Is a Subsystem

If an object specified by the <list of units> option is of class Subsystem, the following error can be expected in the log: 

*** /local/tools/ada_analyzer/ada_analyzer.ss is a subsystem, not a 
configuration,
... view, directory, or Ada unit.

Error: Creating Report Files

If a problem is encountered while creating the report file, a message similar to the following is displayed: 

*** EXCEPTION: USE_ERROR raised during report creation.
::: [end of Locate_Complex_Expressions.Display operation -- 1 error detected].

This error message usually implies a naming or access-control problem.

Unexpected Errors

While Ada Analyzer commands are collecting analysis information from Ada units, they may encounter unexpected constructs and raise internal exceptions. To generate as much correct output as possible, these exceptions are caught and reported in the log with the following message. The Ada Analyzer command will continue processing and collecting information, discarding just this construct from the output: 

*** UNEXPECTED ERROR, EXCEPTION: Asis_Execptions.Inappropriate_Program_Element.
*** DIAGNOSIS: Element is not a statement.
*** UNIT: /local/tools/ada_analyzer/ada_analyzer.ss/rev1.wrk/
... software_content/count_ada_constructs.2.ada.
*** On line: 41.

These messages indicate a bug in the Ada Analyzer command and should be reported immediately to Rational Support. Please save the error portion of the log and an image of the Ada context surrounding the reported error line. This will help greatly in resolving the problem.

Storage_Error Exception

Any tool has a capacity limit and can arrive at the maximum storage allowed for execution of that tool. If this occurs, Ada Analyzer commands will attempt to write all information collected up to that processing point into the report file. This will be successful in almost all cases, unless a Storage_Error exception is raised during this process. The following log can be expected in this situation: 

*** Storage limit reached. Attempting to display information collected to
... this point.
+++ Sorting.
+++ Adding table to document.
+++ Completed /project/test_output/expression_complexity_analysis.
::: [end of Locate_Complex_Expressions.Display operation -- 1 error detected].

Writing the table with incomplete information at least allows the user to see the information collected for the units processed to that point. The best way to complete successfully is to limit the number of units processed or to use threshold and Include_* parameters to limit the amount of items in the output.

Authorization Errors

Three errors are possible: 

*** The Ada Analyzer is not registered on this machine.
::: [end of Locate_Expressions.Display operation -- 1 error detected].

or 

*** Ada Analyzer registration on this machine has expired.
::: [end of Locate_Expressions.Display operation -- 1 error detected].

If either error occurs, another authorization code must be obtained from Rational. See the separate guide, Installing Ada Analyzer for Rational Apex, for more information. Another related error is possible: 

*** All licensed usage tokens already in use.
::: [end of Locate_Expressions.Display operation -- 1 error detected].

If this error occurs, a current user must release his or her token before a new user can execute an Ada Analyzer command.

Token Management

As with all layered Rational products, license tokens are used to control simultaneous access to the Ada Analyzer by multiple users. Whenever an Ada Analyzer command is executed or an Ada Analyzer report is viewed by the user, a token is requested from the pool of available tokens. If no tokens are available, an error message is displayed and the command is not executed. If a token is available and taken, it is not returned to the pool until the user exits Apex or executes the Release_Token command. This command must be entered from a shell window (created from the Tools menu) using the command line: aa release_token.

Hypertable Report Output

All analysis commands generate hypertable reports as their output. Hypertable reports are stored in files with a .aarpt suffix. This indicates that their contents should not be accessed with the standard Apex text editor but with the Ada Analyzer report editor. The report editor can be used to browse reports and extract additional information about the analysis contained in the report. Especially important is the report editor's ability to traverse from entries in hypertables to the actual Ada code from which the entry was derived. This capability is described in more detail below. The other function of the report editor is to manipulate the image of the report (that is, format column size, sort column entries, and elide unwanted columns). Reports can then be printed or written to files in other formats for further processing.

An example directory containing Ada Analyzer report files appears below: 

projects/analysis_output
  elaboration_impact_analysis.aarpt
  misspelling_analysis.aarpt
  naming_anomalies_analysis.aarpt

Hypertable reports contain the results of the analysis for a particular Ada Analyzer command. Ada constructs that match the selection criteria for that command appear in the table (one per row) with attributes (information related to each item in the table) appearing in each column of that row. An example of a hypertable follows: 
Table 1 - Unused and Misplaced "with" Clauses

Unused "with" clauses:
  >Unit                       >Unused "with"          Status
  ==========================  ======================  ========================
  Unused_With_Clauses'B       Representation_Clauses  Unused
  Unused_With_Clauses'S       Ada_Program             Movable to body
  Unused_With_Clauses'S       Compilation_Units       Used only for use/rena|
  Unused_With_Clauses'S       Names_And_Expressions   Unused
  Unused_With_Clauses'S       Pragmas                 Unused
  Unused_With_Clauses'S       Type_Information        Repeat "with"
  Unused_With_Clauses'S       Type_Information        Used only for use/rena|
  Unused_With_Clauses.Subun|  Declarations            Repeat "with"
  Unused_With_Clauses.Subun|  Declarations            Unused
  Unused_With_Clauses.Subun|  Type_Decls              Unused
  Unused_With_Clauses.Subun|  What                    Repeat "with"

In this table, the Unit column contains the name of the Ada unit where the problem occurs. The next column is the name of the with clause that is unused or misplaced, and the final column (Status) contains a short description of the problem.

Viewing Hypertable Reports with the Report Editor

Hypertables are located in files with a .aarpt suffix. These files can be viewed by placing the cursor on a report file with this suffix and pressing [Visit] or by double clicking with the left mouse button. The Open command on the File menu can also be used. This will display the contents of the report in a window and enable the report-editor commands to inspect and manipulate the report.

Note that by default, report output will be displayed automatically when execution of an Ada Analyzer command completes. The Boolean analysis switch Auto_Visit_Report can be set to False if this is not desired.

Traversal and Explanation

Most hypertable entries are connected to the original Ada constructs from which the information was derived, which is why they are called hypertables. Placing the cursor on the item in the column of interest and pressing [Visit] results in traversal to the Ada construct connected to this table element. Some columns have no connection to the code, to save space and improve the execution time of Ada Analyzer commands. A "greater-than" (>) character in the column header indicates that a traversal connection is present and that [Visit] can be used. The following diagram illustrates this concept:

Associated with each column is additional text that more fully describes the contents of each column. Placing the cursor on any column of the hypertable and pressing [Explain] displays the explanatory text in the message window. Each table title also has explanatory information that describes the contents of the table. To see this concept more concretely, look again at the hypertable containing unused with clauses below: 
Table 1 - Unused and Misplaced "with" Clauses

Unused "with" clauses:
  >Unit                       >Unused "with"          Status
  ==========================  ======================  ========================
  Unused_With_Clauses'B       Representation_Clauses  Unused
  Unused_With_Clauses'S       Ada_Program             Movable to body
  Unused_With_Clauses'S       Compilation_Units       Used only for use/rena|
  Unused_With_Clauses'S       Names_And_Expressions   Unused
  Unused_With_Clauses'S       Pragmas                 Unused
  Unused_With_Clauses'S       Type_Information        Repeat "with"
  Unused_With_Clauses'S       Type_Information        Used only for use/rena|
  Unused_With_Clauses.Subun|  Declarations            Repeat "with"
  Unused_With_Clauses.Subun|  Declarations            Unused
  Unused_With_Clauses.Subun|  Type_Decls              Unused
  Unused_With_Clauses.Subun|  What                    Repeat "with"

By pressing [Visit] on any entry in the Unit column, you traverse to that Ada unit. Pressing [Visit] on any entry in the second column (Unused "with") displays the unit and highlights the with clause. Since the clause is unused, the Ada object editor can be used to delete it. The Status column is informational only and is not connected to any construct. Columns in other tables are often not connected because connections are expensive in terms of time and memory or there are no unique constructs (not already connected to some other item) to connect them to.

Note that it is possible for the Ada unit to have been changed since the report was generated. The report editor will detect this and display a message in the message window. Visiting the unit with highlighting of the referenced construct will be attempted, but the selected item may not be correct because of the changes made to that unit. If the referenced unit has been deleted, the user will be notified.

In the preceding table, pressing [Explain] on the header of each column displays the following information in the message window:

In Chapter 3, "Command Descriptions," each sample output hypertable is accompanied by a description of the [Explain] and [Visit] operations for each table column.

Note: It is possible to customize report and table explanation text as described in "Customized Titles Explanation Text"

Image Manipulation with the Report Editor

The contents of an Ada Analyzer report cannot be modified by the user. It is not possible, for example, to delete or add entries to a report. For this reason, the Edit option has been removed from the File menu.The image of hypertables in an Ada Analyzer report can be manipulated with the report editor. The following changes can be made:

Operations to perform these image transformations are located on the View menu. Several also appear on the button bar for easy access. Specific operations are described below.

Expanding and Contracting Columns

The Expand Column operation increases the width of the column in which the cursor is located by one character. The Contract Column operation decreases the width of the column in which the cursor is located by one character. If the cursor is located between tables or is otherwise not located in a column, an error message to that effect is displayed in the message window. If the size of a column is reduced below the number of characters required to display the entire image, the image is abbreviated with a vertical bar (|) appended.

Eliding and Uneliding Columns

The Elide Column operation removes the image of the column in which the cursor is located, replacing it with a vertical line. If the report is then written to a file in another format (see "Alternative File Formats"), this column will not be included in the output. The Unelide Column operation restores the image of the column to the table. The cursor should be placed immediately before the vertical line indicating the elided column for this operation to have effect. The following diagrams illustrate this capability.

Before column 2 is elided: 
Table 1 - Unused and Misplaced "with" Clauses

Unused "with" clauses:
  >Unit                       >Unused "with"          Status
  ==========================  ======================  ========================
  Unused_With_Clauses'B       Representation_Clauses  Unused
  Unused_With_Clauses'S       Ada_Program             Movable to body
  Unused_With_Clauses'S       Compilation_Units       Used only for use/rena|

After column 2 is elided: 
Table 1 - Unused and Misplaced "with" Clauses

Unused "with" clauses:
  >Unit                      |  Status
  ========================== |  ========================
  Unused_With_Clauses'B      |  Unused
  Unused_With_Clauses'S      |  Movable to body
  Unused_With_Clauses'S      |  Used only for use/rena|

Sorting on a Column

The Sort on Column operation resorts the table based on the entries in the column in which the cursor is located. The switches Sort_Ascending on page 28 and Sort_Case_Sensitive also on page 29 govern the sort order.

Searching for Text

The standard Apex text search mechanism can be used in report images to find text strings.

Note: Text replacement is not possible since reports cannot be modified.

Reformatting a Hypertable

The format of a hypertable can be specified with the Format operation. The operation creates a dialog box similar to the following:

The dialog box will display the current elided state and size for each column in the table. The elided state of a column can be changed by pressing the radio button for that column. The size of each column can be changed from the current value to the number of desired characters. The sort order is initially displayed as all zeros indicating no sorting. Sort _Order values can be changed to indicate sorting precedence. The column with a 1 will have the highest precedence in the sort, the column with a 2 will have the next highest precedence, and so on. Columns with zeros do not participate in the sort. Analysis switches govern case sensitivity and whether the result should be displayed in ascending or descending order.

Fitting Tables to 80 Columns

The Fit to 80 Cols operation expands or contracts columns so that the table fits into 80 columns. This can be convenient for printing purposes. No column is made smaller than 3 characters or larger than 32 characters. The relative size of all columns is preserved whenever possible.

Expanding Table Columns to Maximum Width

The Expand to Max operation expands each column in a table to the maximum width required to display all characters in the column items. This allows the user to see all table data with no abbreviated columns.

Eliding and Uneliding Tables

The Elide Table operation removes the image of the table in which the cursor is located, replacing it with a single line saying that the table is elided. If the report is then written to a file in another format (see "Alternative File Formats" below), this table will not be included. The Unelide Table operation restores the image of the table to the report. The cursor should be placed immediately in the line indicating the elided table for this operation to have effect.

Marking and Unmarking Rows

Operations are available to mark rows in a report, unmark them if necessary, and save only marked or unmarked rows into a report file. The save can overwrite the same permanent report file or be written to a new named report. It is also possible to elide (hide) and unelide all marked or all unmarked rows in a report. These mechanisms provide the capability to select and save only those report row entries of interest and discard or elide all others.

The operation MarkRow will place a `+' sign in front of a table row on which the cursor is placed or on all selected rows in a table. The operation UnmarkRow will similarly remove the `+' sign, thus unmarking those rows. The operation ElideMarked will remove all marked entries from the displayed image of the report. The operation UnelideMarked will add back or display all marked entries. The operations ElideUnmarked and UnelideUnmarked work similarly for unmarked table entries. Note that if both the ElideMarked and ElideUnmarked operations are performed, the image of all tables in the report will be empty.

Two format options Marked_Rows_Only and Unmarked_Rows_Only of the SaveAs operation (page 20) allow only marked rows or only unmarked rows in tables to be written to the specified report filename.

Saving Changes

When changes are made to the image of the report with the report editor, the Save operation on the File menu and corresponding Save button will be ungreyed. This indicates that the image is not the same as the permanent representation of the report in the .aarpt file. The Save or SaveAs operations can be used to store changes permanently in the report file. If the Close operation from the File menu is executed before a Save, then all changes are abandoned and the report file will revert to its former image. The Close operation also removes the window from the screen. In contrast, the Motif close operation in the upper left corner of the window will save changes before removing the window.

Merging and Comparing Reports

When the software under analysis is so large that a single invocation of the Ada Analyzer takes too long or does not complete, analysis can be performed on sections of the code (that is, each subsystem or subdirectory). Separate reports containing analysis of that subset can be generated and later merged into a single report with the Merge_Reports command.

Two reports generated with the same Ada Analyzer command at different times can also be compared for differences with the Compare_Reports command. The output report will contain table entries marked with a "1" if they appear in the first report and not in the second. Output entries will be marked with a "2" if the appears in the second report and not in the first. If the option Include_Matches is enabled and the entry appear in both reports, then the output entry will be marked with a "1/2". This can be used to identify differences between two versions or releases of software. Both commands can be found under the Report Management menu item.

Acceptable Report Entries

The following mechanism defines a list of "acceptable" items reported by the Ada Analyzer. Some coding violations or other reported problems may be deemed acceptable to the software development team for a variety of reasons. It is then tedious when these same items are reported in subsequent runs of Ada Analyzer commands. This mechanism offers a method of defining acceptable entries and filtering out those entries from newly generated reports.

A naming convention is used to find the corresponding report containing acceptable entries for a given report. An acceptable report has the same name as the primary report but is appended with an "_acceptable" suffix. Thus if a report is named "coding_violations.aaprt", the report containing acceptable violations will be named "coding_vioaltions_acceptable.aarpt". The analysis switch, Accepted_Output_Directory, is defined to hold the name of the directory where acceptable reports are located. If the value of the Accepted_Output_Directory resolves to a valid directory, then the Ada Analyzer will look in that directory for the acceptable report name. If the value of this switch is the null string or does not resolve, then the Ada Analyzer will look in the same directory containing the primary report for the corresponding acceptable report.

The SaveAs format option (Marked_Rows_As_Acceptable) will save only marked rows to a report file. This operation will also automatically construct the correct "acceptable" output filename, taking the value of the Accepted_Output_Directory switch into account. Note that it is also possible to manually construct the name of the acceptable report with the Marked_Rows_Only or Unmarked_Rows_Only options.

The report editor operation Mark_Accepted will locate the acceptable report and if found will compare the entries in the primary report with those in the acceptable report. Entries that match identically (except for line numbers) will then be automatically marked (as described above on page 17) in the primary report. If the value of the Auto_Incorporate_Accepted switch is True, any new report that is generated will automatically mark rows from an acceptable report if one with the correct name can be located.

Printing Reports

Ada Analyzer reports can be printed in two ways. The Print operation on the File menu will print the image of the report just as it would any other ASCII file. For PostScript®-quality printing, the following steps must be performed:

Saving Reports

The Save operation in the File menu and on the button bar saves all changes made to the image of the report back into the .aarpt file. When the file is next opened, the modified format of all tables will be preserved. If you do not want the changes you make to be permanent, you can use the Close operation without first saving it.

Alternative File Formats

Hypertables can be written to files in the following formats:

Save As

The Save As operation generates the following dialog box:

The name of the report to be saved appears in the Filename section of the dialog box. The Context field defines the directory into which the filename will be saved. The Context field will be prefixed to the Filename field if it is not a fully qualified pathname. The Format field defines which format is used to store the file as described above. The alternatives button allows selection of Normal, FrameMaker MIF, Column Delimited, Interleaf, HTML, and ASCII format values. If the Normal file format is selected, the current image of the report will be saved in the filename selected (as in the Save operation). If the FrameMaker MIF format is selected, the report is saved in FrameMaker MIF format. If the Column-Delimited format is selected, the Delimiter field at the bottom of the dialog box specifies the separator character used to delimit columns. If the Interleaf format is selected, the report is saved in Interleaf IAF format. If the HTML format is selected, the report is saved in HTML format suitable for browsing. If the ASCII format is selected, the ASCII image of the report is saved in the specified filename.

If the boolean switch Include_Table_Explanation_Text_In_Ascii_Output is true, the explanation text (either predefined or customized) will be written to the ascii file before the table title. Report header explanation text will also be added. If false (the default, no explanation text will be included. This applies to all ascii output formats including ascii, HTML, Interleaf, RTF, and Framemaker MIF.

Online Documentation

An online version of this document is available through the Help item of the Analyzer menu.This operation will take you to an online copy of this manual, including its own separate index. Pressing the Help button in any Ada Analyzer dialog box or using Help:On Context will take you to the section of the Ada Analyzer User's Guide that describes the specified command or operation.

Configuring the Ada Analyzer

The Ada Analyzer is designed to be configurable. A set of file-based switch values is available to accomplish the following:

Configuration Structure and Content

All Ada Analyzer configuration switches and files are located in directories with the following structure: 

default_configuration/
  ada_repair/
    declaration_mapping
  annotation_collection/
    annotation_collection_status
  compatibility/
    development_libraries
    known_pragmas
    reserved_names
    rule_enforcement
  framemaker_formats/
    listing_formats.mif
    report_formats.mif
  

html_formats/
    listing_formats.html
    report_formats.html
  interleaf_formats/
    listing_formats.iaf
    report_formats.iaf
  metrics_collection/
    cmvc_metrics_description

    halstead_metrics_description
    line_counting_description
    metrics_collection_status
    metrics_explanations_and_titles
    oo_metrics_description
    subprogram_metrics_description
  rtf_formats/
    listing_formats.rtf
    report_formats.rtf

  stack_analysis/

    stack_analysis_parameters

    subprogram_frame_sizing
  standards_conformance/
    allowed_name_abbreviations
    allowed_use_clauses
    annex_d_enforcement
    annex_h_enforcement
    approved_renames
    expression_depth_limit
    maximum_protected_entries
    maximum_select_alternatives
    maximum_subprogram_size
    maximum_task_entries
    maximum_unit_size
    mccabe_complexity_limit
    name_selection_limit
    named_loop_size
    naming_conventions
    package_nesting_limit
    prohibited_attributes
    prohibited_names

    ravenscar_enforcement
    return_type_limit
    rule_enforcement
    rule_enforcement_interactive
    rule_explanations_and_titles
    spark_enforcement
    spc_enforcement

    subprogram_nesting_limit
    subtype_nesting_limit
  analysis_switch_file
  command_table_explain_text
  excluded_units
  type_sizing_file
  type_sizing_name_map

The Check_Consistency command on the Configuration Policy item of the Analyzer menu can be used to verify that the structure of a configuration-policy directory is correct and that all files are present. This command can also be used to add missing files to older configuration-policy directories.

The Check_Consistency command creates the following dialog box:

The locator at the top of the box can be used to specify configuration-policy directories to check. The radio button at the bottom can be pushed to indicate that any missing files should be copied from the default configuration policy into the configuration policy missing the file.

Since all configuration information is stored in the files shown above, it can be updated with the Apex text editor. This is the easiest and most straightforward way to change the configuration of the Ada Analyzer. Required formats are described in each file and in this document. Most files contain lists of simple names, one to a line. Others define the value assigned to a named entity (that is, named_entity => value).

Multiple Configuration Policies

It is possible to have several configuration-policy directories, each with different settings. These can be located at either the project or the user level. The $AA_HOME/configuration_policy directory is the recommended place to store all project-level configuration policies. It is possible, of course, to put configuration-policy directories elsewhere in the directory structure, but that is not recommended. The following is an example of a configuration-policy directory containing several named configurations: 

configuration_policy/
  default_configuration/
  configuration_1_2/
  verification_configuration/
  current_configuration

In this case, there are three configuration policies: the default_configuration supplied with the Ada Analyzer and two project configurations called configuration_1_2 and verification_configuration. Each should have the structure shown in the earlier diagram.

There are two methods available for specifying which configuration-policy directory should be considered the current configuration policy and used for all Ada Analyzer commands. A file called current_configuration within the configuration_policy directory can be used to store the pathname of the configuration-policy directory that should be considered "current". This should be a fully qualified pathname to the desired configuration-policy directory.

An alternative method of specifying the current configuration policy is to use an environment variable. The $AA_CONFIG_POLICY_DIR environment variable can be used to designate the pathname of the configuration-policy directory to use. If $AA_CONFIG_POLICY_DIR contains a valid pathname, its contents takes precedence and it will be used to designate the current configuration policy to use with all commands. If $AA_CONFIG_POLICY_DIR has a null value, then the contents of the current_configuration file will be used. Although use of the environment variables may be more convenient for some users, they can only be set before Apex is initialized. If a user wishes to change the value of the $AA_CONFIG_POLICY_DIR environment variable, they must first exit Apex, set the variable to a new value, and then re-initialize Apex for the change to have an effect.

You can create your own personal configuration by duplicating this structure in your home directory. This can be accomplished easily with the Create_New command on the Configuration Policy item of the Analyzer menu. This command creates a new configuration by copying an existing configuration-policy directory into a new context. If no context parameter is specified, the new configuration is created in the user's home directory including the configuration_policy directory and the current_configuration file if necessary. Note that this command also can be used to create new project-level configurations in any context. The Create_New command has the dialog box on the next page.

The single-object locator (labeled From Configuration) at the top of the dialog box can be used to specify the configuration-policy directory to copy when creating the new configuration policy. The New Configuration field specifies the simple name of the configuration-policy directory to create. The Context field is left empty by default but can be changed to any other directory context. A configuration-policy directory with the name specified in the New Configuration field will be created in the specified context directory.

Determining the Currently Active Configuration Policy

When Ada Analyzer commands are executed, the following algorithm is used to determine which configuration policy to use:

1. If $AA_CONFIG_POLICY_DIR contains a valid pathname, then use its contents to locate the current configuration-policy directory. If $AA_CONFIG_POLICY_DIR contains a null or invalid value, then continue to step 2.

2. If the user's home library contains a directory called configuration_policy, it is used to complete step 3. Otherwise, step 3 is completed with the configuration_policy directory in $AA_HOME.

3. Locate the actual configuration. If a file named current_configuration exists within the configuration_policy directory found in step 1, its contents are read to retrieve the path-name of the actual configuration-policy directory to use for command execution. If this file does not exist, if the pathname does not resolve, or if the resolved object is not a configuration-policy directory, the default_configuration in $AA_HOME is used for command execution.

The selected configuration is always displayed as part of the command log. A command called Visit Current in the Configuration Policy menu is available to traverse to the currently active configuration-policy directory.

Customized Titles Explanation Text

It is possible to customize the table title and explanation text in reports for most Ada Analyzer commands. This allows projects the ability to define their own titles and descriptions of coding violations, metrics, and most other items reported by the Ada Analyzer.

The Ada Analyzer switch, Use_File_Based_Explain_Text (page 29) governs whether this mechanism is used or not. If the value of the switch is false (the default), then predefined titles and explanations will be used. If enabled, the customization files command_table_explain_text (page 40), standards_conformance/rule_explanations (page 39), and metrics_collection/metrics_explanations (page 35) will be consulted for table titles and explanation text. Explanations can be simple text, a reference to a description located in a file, or a reference to a file containing HTML help text(page 41). Title text may only be simple text and will be copied verbatim into the title area of a report table.

Analysis Switches

This section describes the switches that govern general operation of the Ada Analyzer. Each switch name is followed by the kind of input expected (shown in parentheses) and a description of the switch.

Note: This switch should be used only when necessary to resolve overloading since it is somewhat computation intensive.

Editing Analysis Switches

Analysis switches are stored in the file named analysis_switch_file in the configuration-policy directory. They can be edited with the Apex text object editor. The format for entries (one per line) in the file is: 

Switch_Name => Value

These switch values are loaded from the analysis_switch_file into memory each time an Ada Analyzer command executes. Values are checked to see that they have the correct format (Boolean, Integer, String) and in some cases that they resolve to the right kind of objects (Project_Software_Configuration, for example). Errors are reported in the command log before tool execution starts. The following log is an example of the kinds of errors that can occur: 

*** Initializing Analysis_Switches--Had problem interpreting entry:
... UNIT_NAME_ABBREVIATION_POLICY => NO_ABBREV. Must be one of
... No_Abbreviation, First_N_Characters, First_N_That_Differentiate,
... First_N_Of_Each_Segment, First_N_Of_Each_Segment_That_Differentiate.
... Currently using default.
*** Initializing Analysis_Switches--Had problem interpreting entry:
... PROJECT_SOFTWARE_CONFIGURATION => /import/tools/ada_analyzer/
... /activities/my_current does not resolve.

Environment-Variable Switches

It is also possible to set Ada Analyzer analysis switches with an environment variable. The name of the environment variable can be constructed by appending AA_ to the fully uppercase switch name. This alternative allows switches to be set without modifying the analysis_switch_file in the configuration-policy directory

Configuration-Policy Files

The following configuration files are used to modify the behavior of specific Ada Analyzer commands. Each file description includes the commands that use this information to perform their analysis and the expected format of data, if any.

Wildcards

A limited form of name wild-carding can be used to specify names in configuration-policy files. Two wildcard characters are available:

Thus, the wildcard string "*Bob##" would match "Jim Bob L" or "Billy Bob's" but not "Jim Bo's" or "Bill Bobby's". Files allowing wildcards are so specified.

Ada Repair Files

The configuration file in this section support the declaration renaming capability of the Ada Repair command. It use is described in "Specifying Declarations to Rename or Move" on page 340.

Annotation Analysis Files

The configuration file in this section supports the analysis of structured annotations (comments) embedded in software.

Compatibility Files

Configuration files in this section support the checking of code for compatibility with other compilation systems.

FrameMaker Format Files

Configuration files in this section support the generation of code listing and reports in FrameMaker Interchange Format (MIF). These files contain the baseline definitions for the documents generated for FrameMaker or FrameViewer.

HTML Format Files

Configuration files in this section support the generation of code listing and reports in HTML. These files contain the baseline definitions for the documents generated for on-line browsing.

Interleaf Format Files

Configuration files in this section support the generation of code listing and reports in Interleaf ASCII Format (IAF). These files contain the baseline definitions for the documents generated for Interleaf.

Rich Text Format Files

Configuration files in this section support the generation of code listing and reports in Rich Text Format (RTF). These files contain the baseline definitions for the documents generated for word processing programs supporting RTF.

Metrics-Collection Files

Configuration files in this section support the qualification of code with metrics.

Standards-Conformance Files

Configuration files in this section support checking code against project coding standards.

Other Configuration Files

These configuration files appear immediately within the configuration-policy directory and apply to multiple Ada Analyzer commands.

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