Click on FTP to download from the FTP archives.
![[FTP]](http://www2.encompassus.org/hidedecus/graphics/i_ftp.gif)
SOFTWARE SYSTEMS DESIGN
3627 PADUA AVE. CLAREMONT, CALIFORNIA 91711
(714) 625-6147
ADADL
(Ada-based Documentation And Design Langugae)
User's Guide
This document may be freely reproduced and distributed.
.fo Table of Contents for Release 3.1 5/14/86 page #
Table of Contents
1.Introduction
1.1 Why use ADADL?
1.1.1 Program Design Languages Communicate the Design
1.2 ADADL features
1.2.1 ADADL characteristics
1.2.2 Design reports
1.2.3 Document formatting
1.2.4 ADADL processor controls
1.3 ADADL Design Guidelines
2. Overview of ADADL processing
2.1 Design Statements begin with --|
2.2 Ada code which defines structure
2.3 ADADL processor commands begin with --#
2.4 Dictionary definitions start with --%
2.4.1 Project Management information starts with --*
2.5 ADADL processor ignores source code
2.6 ADADL processor finds undeclared or misspelled identifiers
2.7 Design and code complexity are quantified
3. Ada Code Keywords
3.1 Ada Program Unit Declaration
3.1.1 Program Unit Declaration Errors
3.2 Data Structure Declarations
3.2.1 Type definitions
3.2.1.1 Subtype
3.2.1.2 Derived Type
3.2.1.3 Type definition errors
3.2.2 Object declarations
3.2.2.1 Object declaration errors
3.3 Begin .. exception .. end Keywords
4.0 Design Statement Keyword Recognition
4.1 Loop Statements
4.1.1 Loop statement errors
4.2 If statement
4.2.1 If statement errors
4.3 Case Statement
4.3.1 Case statement errors
4.4 Task related statements
4.5 Execution flow control
4.6 Labelled design statements
5.0 Continuation of Input and output statements
5.1 Continuation of design statements
5.2 Ada code input statement continuation
5.3 Output statement continuation
6.0 Processor Controls
6.1 Page Width, Length, Numbering and Ejection
6.1.1 Page width (--#pagewidth WID)
6.1.2 Page length (--#pagelength LEN)
6.1.3 Next page number (--#pagenum NUMBER)
6.1.4 Pagination of program units (--#pagepu on/off)
6.1.5 Page ejection (--#newpage LINES_REMAINING)
6.2 Adjustment of Indentation Amount (--#indent AMOUNT)
6.2.1 Suppress structure indication (--#structure off)
6.3 Keyword Case and Highlighting
6.3.1 Lower case (--#keyword lower)
6.3.2 Upper Case (--#keyword upper)
6.3.3 Same case as input (--#keyword same)
6.3.4 Underscoring of keywords (--#underscore on/off)
6.3.5 Boldface printing of keywords (--#boldface on/off)
6.4 Output Format of Declared Entities
6.4.1 First character capitalized (--#declared first)
6.4.2 Upper case (--#declared upper)
6.4.3 Lower case (--#declared lower)
6.4.4 Same case as input (--#declared same)
6.5 (--#goodstyle on/off) command no longer applicable
6.6 User Defined Reference Tables (--#mark PUNCT TABLE)
6.6.1 Defining Project Management Reports
6.6.1.1 Tracing Requirements to Program Units
6.6.1.2 Showing Dates of completion of Design
6.6.1.3 Showing Dates of completion of Coding
6.6.1.4 Showing Dates of completion of Testing
6.6.1.5 Referencing Responsible Designers to Program Units
6.6.2 Using mark directives in the design.
6.7 Design Report Suppression
6.7.1 Suppress Object Report (--#noobject)
6.7.2 Suppress Type Report (--#notype)
6.7.3 Suppress Program Unit and Entry Report (--#nounit)
6.7.4 Suppress TBD (to be determined) Report (--#notbd)
6.7.5 Suppress Program Unit Invocation Tree Report (--#notree)
6.7.6 Creates a Smalltree Invocation Report (--#smalltree)
6.7.7 Suppress Dictionary Report(--#nodict)
6.7.8 Suppress Generic Instantiation Report (--#nogeneric)
6.7.9 Suppress Pretty Print Report (--#nopretty)
6.7.10 Suppress Spelling Error Checker (--#nocheck)
6.7.11 Suppress Complexity Report (--#nometric)
6.7.12 Suppress Declaration Tree Report (--#nodectree)
6.7.13 Suppress Printing of Extract Documentation text
on the pretty print output (--#noextract)
6.8 Title Page (--#title .... --#end)
6.9 Design Heading (--#heading ... --#end)
6.10 Text Insertion (--#text .. --#end)
6.11 Creating a Code Prolog Section (--#prolog PROLOG_FILENAME)
6.12 Adding Executable Ada Code
6.13 Ignoring Executable Code (--#ignore begin ..--#ignore end)
6.14 Setting the Maximum Complexity Metric
(--#maxcomp NDES MCODE NEST)
6.15 Declaring program units as utility programs (--#utility)
6.16 Including previously developed designs or command files
(--#include FILENAME)
6.17 Supressing the "pseudo code follows" and "Ada code
follows" boxes (--#noboxes)
6.18 Suppressing the printing of the "extract" documentation
on the pretty print report (--#noextract)
6.19 Importing context clause library information
(--#includlib host-computer-file-name)
7. Design reports
7.1 Object cross reference table
7.2 Type cross reference table
7.3 Program unit and task entry cross reference table
7.4 Design to be determined reference table
7.5 Subprogram and task invocation trees
7.6 Smalltree Invocation Report
7.7 Dictionary Report
7.8 Generic Instantiation Report
7.9 Table of contents
7.10 Error summary information
7.10.1 Design Statement errors
7.10.2 Spelling or Typing errors
7.11 User-defined reference table
7.12 Complexity Report
7.13 Program Unit Declaration Tree Report
7.14 Interrupt Report
8.0 The ADADL Library File
8.1 How to create an ADADL library file
8.2 Deleting Prorgram Units from the library
9.0 Including documenation information in the design
9.1 Creating an intermediate documenation file
9.2 How to format the design to extract different views of
the design.
9.3 An overview of Doc-Gen processing
10.0 Using ADADL to generate Unit Test plans and procedures
10.1 Defining the Test-Gen File
10.2 An overview of Test-Gen processing
Appendix B Installation and use of ADADL processor
B.1 Installation procedure
B.1.1 VAX 11/XXX - VMS
B.1.2 UNIX and Unix derivatives
B.2 Invocation and use
B.2.1 VAX 11/XXX - VMS
B.2.2 UNIX and Unix derivatives
B.3 Printer installation
B.3.1 adadl.prt format
B.3.2 Printer data file *.dat
B.3.3 Deleting a printer from the list of available printers
B.3.4 Changing the "default" printer
B.3.5 Adding a new printer to the system
B.4 Installing the HELP file
.he ADADL User's Manual Software Systems Design, (714) 625-6147
.fo Introduction page 1-#
1.0 Introduction
This document is a User's Guide for the ADADL processor.
The ADADL language is an Ada-based Program Design Language (PDL)
specifically designed to be used to document both the top level
and detailed design phases of the software development
lifecycyle. Designs described using ADADL are able to be compiled
without error on an Ada compiler.
The ADADL processor is designed to interface with the Doc-Gen
tool to provide Mil-Std or DoD-Std documentation by extracting
documentation information directly from the Ada source code.
In addition to automatically generating documentation (in
conjunction with the Doc-Gen tool), the ADADL processor and the
Test-Gen tool will automatically generate Test plans and
procedures for unit testing of all program units.
The ADADL processor consists of over 25 software tools
The ADADL processor is composed of over 25 software tools
written in the C language, which are used to analyze the ADADL
source text in order to produce design reports and documentation
describing the design. The design reports produced by the ADADL
processor provide the designer with information about such things
as program structure, data declarations and use, type
declarations and use, invocation hierarchy, generic utilization,
and design complexity.
A complete list of design reports is given in section 1.2.2.
Examples of the reports are provided in Appendix A.
In addition to the design reports, the design statements (pseudo-
code which shows control flow), are formatted to show the nesting
of the Ada control structures, such as loop..end loop and
if..end if.
This formatting is commonly called "pretty printing". The "pretty
printed" document also highlights keywords and program unit
invocations.
ADADL helps Designers design
Since ADADL is primarily designed to help the Design process, the
user is not expected to have a completely defined design
structure in order to use ADADL. During the early stages of the
design many things may be deferred until later by using the text
"TBD", which stands for To Be Determined. The ADADL processor
will produce a report which shows where all of these TBD items
are to be found. It is a check list of "Things to do" for the
designer.
This document is more than a reference manual for the ADADL
language and processor. It is a "User's Guide", and as a user's
guide it provides guidance as to how the user of ADADL might
effectively use the language and the processor during the design
and maintenance (re-design) stages of the software lifecycle.
Figure 1. shows a program fragment of a design using ADADL.
Figure 1. An Example of an Ada program unit fragment
designed using ADADL.
--..
procedure AT_THE_CORNER is
--* Requirements satisfied : @3.2.2.1
--* Author : $I.M. DeGuy
--%determines what to do when the car
--% is at an intersection.
-- the type and object declarations are shown below
-- these declarations are actual Ada declarations.
type DIRECTION is (NORTH,EAST,SOUTH,WEST);
--% Defines the compass direction
subtype DISTANCE is INTEGER; --% units are feet
subtype STOPPING_DISTANCE is DISTANCE range 0..100;
type LOCATION is (TBD);
type ROAD_OBSTACLE_REPORT is (Clear, Blocked);
type WORKING_TYPE is (Working, Off);
DIST_TO_INTERSECTION : DISTANCE; --% distance
--% to the center of the intersection
INTERSECTION_ERROR : DISTANCE := 6 ;
--% minimum distance which car may be from center of intersection
--% and still be considered at the intersection.
INTERSECTION_LOCATION , CURRENT_LOCATION : LOCATION;
function DIFF_BETWEEN (LEFT,RIGHT : LOCATION) return DISTANCE
is separate;
procedure PROCEED (
SPEED : in SPEED_TYPE;
WAY_TO_GO : out DIRECTION) is separate;
function CHECK_OBSTACLES return ROAD_OBSTACLE_REPORT
is separate;
procedure DIRECTIONS_AT_THE_INTERSECTION is separate;
function STOP_LIGHT return WORKING_TYPE
is separate;
-- Below is the ADADL Structured English pseudo-code
--|check to make sure the car is at the intersection
--|
--|if Dist_to_intersection shows that the car is at the
--| intersection then
--|
--| if the car has reached the intersection but the
--| STOP_LIGHT is not working then
--|
--| The car must look for any obstacles in any
--| direction using CHECK_OBSTACLES before
--| using PROCEED to pass through the intersection
--| at a safe speed
--|
--| else
--|
--| The car uses PROCEED to continue according to
--| instructions supplied by DIRECTIONS_AT_THE_INTERSECTION
--| end if
--| return
--|end if
begin
-- the actual Ada executable code will replace the "null"
-- statement
null;
end AT_THE_CORNER;
separate (AT_THE_CORNER)
-- ...
-- ...
1.1 Why use ADADL?
From the above example, we can understand the designer's intent
easily by reading the ADADL Structured English design
descriptions. We can also see that the declarations of types,
objects, program units are actual Ada language declarations.
The design control flow is expressed in a high level pseudo-code
in the statements following the "--|" token. These pseudo-code
statements are comments to an Ada compiler, but are analyzed by
the ADADL processor, which searches through the pseudo-code to
find any references to the declared Ada entities.
The ADADL processor will also search through the executable code
(between the begin and end keywords) for any references to Ada
entities. This capability allows "experts" to design using only
Ada. This approach is not recommended until the designer has an
expert's view, i.e. an intuitive grasp, of the Ada language since
the design intent is not as clear as it would be if the designer
had used the design statement pseudo-code. However, the
capability to use "pure Ada" exists within the ADADL structure
for those who wish to design in that manner.
1.1.1 Program Design Languages Communicate the Design
Almost all modern software development methodologies, require the
use of Program Design Languages (PDL) to communicate the
designer's intent before any code is actually written.
DoD-STD-2167 requires the use of a PDL to describe the design.
PDL is chosen as the form of communication to enable the designer
to clearly and concisely communicate the design in a more
understandable manner than by using lines of source code.
Moreover, PDL is used rather than flowcharts because a design
described using a PDL must be well structured in order to be
understandable. Some thought must be put into structuring the
design. We want to keep that design structure as visible as
possible throughout the software lifecycle.
The first payoff is during design evaluation
If we use a PDL to describe the design we get a clear picture of
what the designer intends.
The biggest payoff is during maintenance and enhancement
If we keep the PDL description at a high level, i.e. more like
English than like source code, and we keep that high level
description of the design imbedded in (in the same file as) the
source code itself, the maintenance task is simplified; we can
understand what the original designer meant to do.
ADADL is an Ada-based PDL
Being an Ada-based PDL means that Ada constructs are used
wherever appropriate. One of the main reasons for using ADADL is
to use the Ada semantics and the Ada syntax for describing those
portions of the design that should be described using Ada code.
The portions of the design that are well expressed in Ada code
are those which define the structure of the program and the
structure of the data. Specifically, program unit declarations of
packages, tasks, subprograms and generics are strictly Ada.
Similarly, type definitions and object declarations are strictly
Ada. The program control flow, and logic (algorithm definition)
is not Ada code, it is PDL. It should be at a higher level of
abstraction than lines of code; more easily understood.
ADADL was designed with three primary goals in mind:
1. Use Ada to describe the program structure and data
structure.
2. Use a Program Design Language (PDL) pseudo-code to
describe the control flow of the program.
3. Provide for ease of software maintenance and enhancement
by keeping both the PDL portion, which shows the design at a
higher level of abstraction, and the source code as close
together as possible.
A special annotation is used to realize these goals. ADADL uses
a "comment compatible syntax", requiring that all ADADL design
statements (pseudo-code) and ADADL commands start a line with
two hyphens.
A ADADL design statement begins with the symbol --|.
A ADADL processor command begins with --#.
A data dictionary definition begins with --%.
Project Management information starts with --*.
The two hyphens at the start of the line indicate that the
remainder of the line is a comment to the Ada compiler, thereby
allowing the pseudo-code to be compiled (and ignored) by the Ada
compiler. The two hyphens followed by a special character, for
example "--|" or "--#" or "--%" or "--*" indicate that, while the
statement is irrelevant to the Ada compiler, the remainder of
the statement is relevant to the ADADL processor.
.cp 6
One recommendation - Only fully disambiguated names please
Ada provides the use capability to allow the designer to use a
"shorthand" notation to identify entities outside the immediate
scope of the program unit. These entities are made accessible by
using the with clause; identifying the program unit which is to
be accessed. ADADL recognizes both the with and the use clauses,
however, for clarity during the design phase, it is recommended
that the designer fully specify the entity to which he is
referring. The with clause is required in order to make the ADADL
design description compilable by an Ada compiler.
An example ADADL text input
with FOOD ;
procedure EATS is
--% determine if something is edible and either discard or
--% eat it after the correct preparation.
type Thing is (TBD); -- this is a valid Ada type definition
--% this definition for Thing leaves something undefined
A, --% the first possible thing to eat
B : --% another possible thing to eat
Thing; --declare objects A and B and give definitions
-- for the ADADL data dictionary
C : FOOD.Stuff; -- "import" a type from program unit FOOD
-- and use fully disambiguated name.
--% some imported food
--| if the A Thing is smaller than the B Thing then
--| eat it
--| elsif
--| the B Thing is edible and good tasting then
--| mix it with C and subsequently eat it
--| else
--| throw them both out
--| end if;
begin
-- here will be the actual code when it is developed
null;
end EATS;
Since the design descriptions are written in a "comment
compatible" format, making the ADADL design fully compilable, it
is recommended that the design be systematically refined and
expanded using step-wise refinement; adding the executable code
to the design input file (see the discussion of the "prolog"
option in section 6.11).
Different views of design disclosure are available
A technique that may be used in conjunction with the ADADL Doc-
Gen tool is to extract differing levels of design detail, for
different views of the design. One view may be a very high level
view used for management overview, while another view may be a
detailed decription of the algorithm. These different views are
the natural result of using step-wise refinement. They are kept
resident in the source code, but extracted and printed only when
required to show that particular design view.
By keeping the design and the executable code textually close to
one another, and so easy to change, ADADL designs are an aid not
only to program development, by allowing high level design
descriptions, but also to program maintenance, long after the
original designer is gone.
Designers using ADADL can easily develop programs incrementally
using an appropriate "top-down" methodology.
ADADL is an Ada/PDL which consists of two parts, the Ada part and
the PDL part.
The Ada part of ADADL is pure Ada per Mil-Std-1815. The Ada part
is used to define the structure of the proposed solution. The
structure is composed of the program unit declarations, type
(subtype derived type) definitions, object declarations, generic
instantiations, essentially anything outside of the begin..end
block, which is usually used to describe control flow, or some
algorithm.
The PDL part of ADADL is used to describe the control flow at a
higher level of abstraction than would be easily available if one
were to use only lines of executable Ada code.
ADADL allows designers to concentrate on the design.
Designers are allowed and encouraged to express control flow
algorithms, in the Ada framework, using the standard control
constructs, but using a Structured English representation, rather
than executable statements.
The ADADL processor analyzes the Structured English design
statements (the PDL pseudo-code), the actual Ada declarations and
definitions and the executable Ada code in order to produce
valuable design reports. The ADADL processor consists of over 25
software tools which produce these reports. The tool-set is shown
in Table I.
ADADL processor Tool Set
PDL pretty printer - indents text and uses structure bars to highlight the PDL
control structure. Enhances Ada keywords used in the PDL.
Ada code pretty printer - indents and highlights Ada code to show the structure.
Object highlighter - Highlights use of Ada entities in both Ada code and the PDL.
Program Unit Invocation tree generator - graphical representation of the
program unit invocations.
Program Unit Declaration Hierarchy tree generator - graphically shows the
structure of the program unit declarations.
Program Unit Cross Reference generator - shows the location (page and line) of all
program unit declarations and references in both the PDL and the code.
Object Cross reference generator - shows the location (page and line) of all object
declarations and references in both the PDL and the code.
Type Cross Reference generator - shows the location (page and line) of all type
declarations and references in both the PDL and the code.
Subtype and Derived type parent reference generator - shows the base or parent
type for each subtype or derived type
Data Dictionary generator - definitions of all Ada entities as supplied in
the source file by the designer. (Definitions can be in any language.)
Generic Instantiation report - shows the location of each generic instantiation.
Complexity Metric - computes the McCabe and ADADL complexity measures for both
pseudocode and the Ada code for each program unit.
Design Error Checker - shows where the design (PDL) is not properly structured.
Undefined Identifier/Spelling Checker - shows where the user has made a possible
spelling error or omission of a declaration when referring to identifiers.
TBD analyzer - shows where the designer has left items To Be Determined
Interrupt report generator - shows how interrupts are declared and where they are used.
* Ten additional Project Management tools to track such things as: *
Requirements Traceability - provides a method to trace system and/or software
requirements to the program units which satisfy the requirement.
Date of Completion of Design - lists the date of completion of the design of
each program unit.
Date of Completion of Coding- lists the date of completion of the coding of each
program unit.
Date of Completion of Test - lists the date of completion of the testing of each
program unit.
Responsible Engineer - lists the program units assigned to each engineer working
on the project.
Areas of Revision - shows where the design (PDL) or the Code has been revised.
Work Breakdown Structure (WBS) report - provides a cross reference between a
WBS and program units.
******* Others to be specified by the user as required *******
1.2 ADADL processor features
The ADADL processor provides the software designer with a
document to aid him both in communicating his design intent to
others, and in actually designing the relevant modules during
software development. The following sections provide a summary of
the capabilities and characteristics of the processor.
1.2.1 ADADL processor characteristics
recognizes all Ada program units
(subprograms, packages, tasks, generics)
recognizes all Ada executable code segments
(between the "begin" and "end" Ada keywords)
uses Ada compound statements as means of expressing
high level design abstractions, which are not
available, or reasonably expressed in Ada.
(logic structure free-form, in most cases, after leading keyword)
recognizes keywords only at the beginning of input statements
recognizes type, subtype and derived type declarations in Ada
recognizes object declarations in Ada
detects and reports unbalanced design structures
(missing "end" statements)
extracts design information from input file containing
both design statements and Ada code
automatically creates a data dictionary for all Ada entities
recognizes undefined (TBD) items in both the
pseudo-code description and in the Ada declarations.
analyzes and reports on the design complexity
Notifies designer of any spelling or typing errors that are
detected for any Ada entities.
1.2.2 Design reports
Table of contents
Design aids
Object cross reference table
Declared type cross reference table
Subtype, Derived type, Parent type reference table
Program unit and task entry cross reference table
Subprogram and task invocation trees
Design to be determined (TBD) cross reference table
User defined cross reference tables
Data Dictionary
Generic instantiation report
Complexity report for each program unit
Declaration hierarchy report
Page reference numbers on subprogram invocations
and task entry calls
Summary of errors detected in design logic
Summary of errors detected in spelling or typing Ada entity names
Summary of errors when using undeclared identifiers in the design
1.2.3 Document formatting
indentation by structure logic
explicit connection of block structures
flow lines for accentuating structure escapes
flow lines for accentuating subprogram invocations
and task entry calls
special formatting for title pages
special formatting for design heading and text segments
input and output line continuation
keyword enhancement by underlining or boldfacing
enhancement of references to declared Ada entities
1.2.4 ADADL processor controls
adjustment of page width, length, and numbering
user control over page ejection
adjustment of indentation amount
suppression of generation of selected design reports
Ada entity highlighting mode
enable/disable keyword underscoring
enable/disable keyword boldface enhancement
optional title page
optional design heading
optional text sequences
enable/disable checking of spelling of Ada entities
selection of maximum allowable complexity for design
selection of maximum allowable complexity for Ada code
1.3 ADADL Design Guidelines
ADADL may be used with a variety of software development
methodologies.
One such methodology is the Disciplined Software Development
Approach (DSDA) as described in [1]. The following description
is a suggested approach to using ADADL, but is by no means the
only way to use the language.
During the first stage of the refinement the designer defines the
structure of the solution. In Ada terminology, the top level
program units are defined so that, initially, a set of packages
is designed, where each package satisfies a set of requirements
which could be logically grouped together. This initial packaging
of the top level architecture is examined to determine the best
implementation for each package, e.g. a task, subprogram, generic
or package. The top level set of program units is subsequently
expanded and further defined. All "visible" parts of these
program units, i.e. types, objects and program units declared in
the specification part are defined in as much detail as possible.
During this stage, the Ada declarations of program units, types,
and objects are used in ADADL.
In stage two of the DSDA design refinement an Executive Module is
first designed using the ADADL pseudo-code PDL and, after being
reviewed and approved, is coded. The executive module invokes the
visible parts of the packages defined during stage one of the
design process. Design statements (PDL) are used to define the
Executive module control flow.
The ADADL design at the end of stage two consists of the
structure of the program units identified in stage one (Ada
declarations), and the executive module which has been designed
and coded during stage two (Ada declarations as well as
executable invocations of other program units).
The consistency of the interfaces for all visible program units
are tested by compiling the ADADL design. The precedence of
program units invoked by the executive is known. The actual
conditions that would cause those program units to invoke other
program units within the packages has not been identified, that
is, we do not know the control structure yet.
Stage three of the refinement defines the interfaces between
program units, and the control structure of the program units.
The PDL portion of ADADL is used heavily in this stage. The
definition of who calls who, and when is made using PDL
statements at this time. Decisions on type representations and on
design details may be deferred at the start of phase three, by
declaring the items "TBD", (To Be Defined), but these TBD items
must be identified by the end of stage three.
.cp 2
Figure 1
Three stage process of Stepwise Refinement
Using ADADL as a Program Design Language
Design Phase Stage 1 - Architectural Design
Step 1.1: Define the initial top level structure
Package the requirements.
(implement an initial solution using packages.)
A. Group logically cohesive requirements together
B. Allocate specific requirements to a package
(Each requirement is satisfied by some package.)
Step 1.2: Refine initial packages into program units
Identify the subprograms or "sub-packages" that will
satisfy the requirements.
(Determine whether a task, procedure,
function or package should be used to
actually implement the solution.)
Identify available generics where possible.
Step 1.3: Identify the resources available in each
program unit.
Define and write specifications for the subprograms
which are visible in each package.
Define the interfaces of all subprograms.
(the parameters that will be used)
Define the interfaces for all other program units.
Step 1.4: Define all visible types and objects
(or make them private to each package)
Use TBD constructs if necessary.
The Ada part of ADADL documents the design structure
Figure 1 - continued
Three stage process of Stepwise Refinement
Using ADADL as a Program Design Language
Design Phase Stage 2 - Executive Design
Step 2.1: Design the EXECUTIVE module
Define all control flow in the executive.
Define all module invocations to the program units
identified in Stage 1. that the executive will make.
Step 2.2: Code the EXECUTIVE Module
Code and compile the executive and the
program units defined in Stage 1. to check the
interfaces to all top level packages.
The PDL part is used to define any EXECUTIVE module
control flow.
Design Phase Stage 3 - Detailed Design
Step 3.1: Define the controls and interfaces
of subprograms inside the package bodies.
(these subprograms are identified while
designing the body of the package)
Define under what conditions calls
are made (the control flow)
The PDL part of ADADL is used to define the control
flow.
Step 3.2: Define the details and fill in
omissions (define all types and objects)
Define all TBD algorithms
Define all TBD data types and objects
The Ada part of ADADL is used to define
the types and objects.
The PDL part of ADADL is used to
define the TBD algorithms.
.pn 1
.fo Overview of ADADL processing page 2 - #
2.0 Overview of ADADL processing
A ADADL design is always compilable, and consists of two parts;
Ada code which describes the program and data structure, and the
PDL pseudo-code, which describes the control flow algorithms. If
pure Ada is used to describe the algorithms, then the executable
code is placed between the Ada begin and end keywords.
The input text can contain both pseudo-code and real Ada code
The ADADL processor may be used on text which contains both
design statement PDL and executable source code implementations
of the PDL. The executable Ada code should be placed between the
begin and end Ada keywords. The PDL pseudo-code should precede
the begin statement.
The design statements (those starting with --|), the data
dictionary definitions (those starting with --%) the processor
control statements (those starting with --#) and the project
management information (those starting with --*) are ignored by
the Ada compiler, since they are Ada comments.
All valid Ada declarations are processed by the ADADL processor
to define the entity declarations and references.
The processor uses the following rules to determine what
actions to take for each input statement.
2.1 Design Statements begin with --|
All lines beginning with --| are both Ada comments and are also
considered to be design statements. The text which follows
is searched for references to objects, types, and program
units. The text is output (with --| removed) to the "pretty
printed" design document.
An example of a portion of a design is shown below:
--|if the radar detects some Target which exceeds the
--| Threshold_criterion then
--| the Target should be engaged by sending the Target_ID to
--| Engage the Target.
--|else
--| get a new set of Radar_data.
--|end if;
Note that the --| does not need to start in column 1, but it must
be the first non-blank symbol to be considered a design
statement.
.cp4
Design statements may appear anywhere, except in between the
start and end of compound statements, such as accept and do, or
case and when, or if andthen.
An example is shown below:
While the following statement sequence is legal Ada code, it
causes severe problems for the ADADL processor to interrupt a
compound Ada code statement with a design statement.
accept A_thing
--| this ADADL design statement will cause an error here
do
null;
end;
but this code will not cause a ADADL error
accept A_thing
do
--| this ADADL design statement is perfectly fine here
null;
end;
2.2 Ada code which defines structure
The following Ada code is considered to be a part of the
design:
(a) Declarations of program units, objects, types, task
entries and generic parameters.
(b) Lines beginning with the keywords "begin", "end",
"private", "generic", "with", "use", "separate", "for",
"record", "end record", and "declare".
2.3 ADADL processor commands begin with --#
Commands to the ADADL processor all begin with the symbol --#.
These commands are primarily concerned with the format of the
design reports and control such things as, page length, keyword
enhancement, design report generation, etc. A complete
description of ADADL processor commands is given in Section 6.
2.4 Dictionary definitions start with --%
A dictionary of all Ada program units, types and objects is
automatically produced by the ADADL processor. The definitions of
the Ada entities are provided by the user using the special
symbol --% to start a definition of the most recently declared
Ada object, type, task entry or program unit.
There should be at least one space (blank) following the name of
an Ada object and the beginning of the --% dictionary definition.
2.5 Project Management information starts with --*
Project Management information is used to define items of
interest in the design which can facilitate the project
management function.
Examples of project management information are:
Requirements tracacebility.
Dates of completion of the design, coding and testing of program
units.
Identification of the responsible designer, coder and tester for
the program units.
This inforamtion can be kept resident in the source code, and
extracted using the Mark directives (see Section 6.6.).
A special symbol (--*) is used to denote the project management
information. The information is not pseudo-code (--|) or a
definition of an Ada entity (--%), nor is it a ADADL processor
command(--#). Project management information is a different set
of information, and it is therefore started with its own unique
symbol; the "--*" symbol.
2.5 The ADADL processor can also ignore source code
The user can notify the ADADL processor to avoid processing
certain sections of the executable code. The statements to be
ignored should be placed between the "--#ignore begin" and "--
#ignore end" processor commands.
Statements between the "--#ignore begin" and "--#ignore end"
processor commands are not checked for references, and are not
"pretty printed" in the design document. If the "--#prolog"
option is selected, these statements will be printed in the file
named in the "--#prolog" command.
The ignore capability is particularly useful if ADADL is used as
the design language for source languages other than Ada.
.cp 4
2.6 ADADL processor finds undeclared or misspelled identifiers
The ADADL processor can aid designers in finding identifiers
which have been misspelled in the design pseudo-code, or which
have not been declared correctly in the non executable Ada code.
The processor analyzes the pseudo-code to search for any text
that appears to be an identifier (contains an underscore
character or is conected using a period). Once the processor
finds a possible identifier a search is made to see if and where
that identifier was previously declared. If the identifier is
found (has been previously declared) a notation is made in the
appropriate cross reference table. However if the identifier is
not found, a warning message is issued, informing the user that
there is either a misspelling or the identifier is not declared.
The warning messages and the checking for undeclared identifiers
can be suppressed using the "--#nocheck" command.
2.7 Design and code complexity are quantified
The ADADL processor provides a quantification of the complexity
of the design and the code for each program unit.
The McCabe [2] cyclomatic complexity number is calculated and
augmented with a measure of the depth of nesting of the control
constructs to determine the ADADL complexity metric.
The user can select the maximum allowable complexity for both
design and code. A complexity report is generated which will show
the complexity of each program unit. Any program unit whose
design or code exceeds the maximum allowable complexity will be
highlighted, and a warning message will be printed for that
program unit.
.pn 1
.fo Ada code keywords page 3 - #
3.0 Ada Code Keywords
The ADADL processor is "keyword driven". All actions are the
result of successfully finding one or more keywords.
The ADADL processor will recognize both Ada language keywords
which are actually non-executable Ada declarations, and design
statement keywords. In order to enhance and highlight the
keywords, they are printed on the design document using an
enhanced print such as Capital (UPPER CASE) letters, or
underscoring.
Ada keywords are recognized if they are the first non blank
characters on a line.
The Ada keywords which are recognized can be divided into two
categories, Ada program unit declarations, and Ada data structure
definitions.
3.1 Ada Program Unit Declarations
Program units are declared using Ada code. The ADADL processor
will detect both program unit declarations, in the specification
part of other program units and also program unit invocations in
the PDL part of the ADADL design.
Program units are declared by the following keywords:
procedure
function
task
package
generic
These keywords are recognized only in declaration sections of
an Ada program unit. The declaration may be the definition of a
specification part or a body part of a program unit.
The declaration must end either in a semicolon or in the word
"is". If the declaration ends in a semicolon, the declaration
is complete and no further statements describing the program
unit are expected. An example is shown below:
procedure RANDOM_NUMBER --% generates a Random Number
(SEED in out : INTEGER);
If the declaration ended in the word "is", further statements
describing the program unit are expected to follow. In this
case, the next output line will be printed one indentation
level to the right of the declaration statement. It is
recommended practice that an "end" to the program unit be
provided with the name of the program unit explicitly shown in
the "end" statement.
3.1.1 Program Unit Declaration Errors
If the declaration of a program unit ends in the word "is",
further statements describing the program unit are expected to
follow, and an "end" to the program unit is expected.
If no "end" statement is supplied an error message will be
printed.
3.2 Data structure declarations
All objects declared in Ada must have their types previously
defined either by using an Ada pre-defined type such as Integer,
or by defining the type using an Ada type definition statement.
Types and objects are declared using the Ada syntax. The
semicolons and colons are important.
3.2.1 Type definitions
The syntax for a type definition is keyword driven, adhering to
the Ada syntax. The first non blank sequence of characters on the
line must be the keyword "type", followed by the type_name,
followed by the keyword "is", or by a semi-colon ";".
Some examples:
type A_TYPE is range 0..4;
type GARBAGE is (YIJKHGGI,OII,HDYRT,A1,S4,NVJH,IUHJHEO);
type Axces;
type Point is access Axces;
-- or an example using more than one line
type GARBAGE is (
YIJKHGGI,
OII,
HDYRT,
A1,
S4,
NVJH,IUHJHEO);
Type definitions must end in a semicolon.
3.2.1.1 Subtype
The syntax for a subtype definition is keyword driven, adhering
to the Ada syntax. The first non blank sequence of characters on
the line must be the keyword "subtype", followed by the
subtype_name, followed by the keyword "is", followed by the
parent_type_name, followed by the optional range constraint.
Subtype definitions must end in a semicolon.
Some examples:
subtype B_TYPE is A_TYPE range 0..2;
subtype OTHER_GARBAGE is GARBAGE range OII..NVJH;
3.2.1.2 Derived Type
The syntax for a derived type definition is keyword driven,
adhering to the Ada syntax. The first non blank sequence of
characters on the line must be the keyword "type", followed by
the derived_type_name, followed by the keyword "is ", followed by
the keyword "new", followed by the parent_type_name.
Derived type definitions must end in a semicolon.
Some examples:
type C_TYPE is new A_TYPE ;
type NEW_GARBAGE is new GARBAGE ;
3.2.1.3 Type definition errors
All type, subtype and derived type definitions must adhere to
the Ada syntax.
3.2.2 Object declarations
Object declarations must adhere to the Ada syntax.
Objects are created in Ada by declaring the object as being of a
particular type. The object name is followed by a colon, followed
by a previously defined, or pre-defined type.
Object declarations must end in a semicolon.
Examples
A : A_type;
G : Garbage := HDYRT; -- initialization will appear in the
-- object cross reference table.
F: NEW_gARbAgE; -- can mix upper and lower case
3.2.2.1 Object declaration errors
All object declarations must adhere to the Ada syntax.
3.3 Begin .. exception .. end Keywords
The Ada keywords begin, exception and end are recognized. These
keywords will be printed at the proper indentation level to match
the nearest open program unit. The keywords will be emphasized
according to the highlighting specifications (see section 6.3).
.pn 1
.fo Design statements page 4 - #
4.0 Design Statement Keyword Recognition
The flow of execution of a program is generally determined by the
control structures, e.g., if..then..else, case..when, select,
while..loop, which are used to define the algorithm.
Design statements use pseudo-code to provide higher level
descriptions (abstractions) of the conditions and subsequent
actions used to determine the flow of control of the program. A
pseudo-code description provides the designer with a means for
describing the design intent without getting into the details of
exactly how the design is to be implemented in code.
Design statements follow the syntax and semantics of the Ada
language, but rather than implementing the design , as the code
does, the design statements describe the design.
The ADADL processor only recognizes design statement keywords if
two conditions are met:
(1) the first symbol on the line is a --|
and
(2) the next non-blank sequence of characters is a design
statement keyword.
Design statements are useful to represent a high level
description of the detailed control algorithm. They can be used
at any level of detail to describe the design.
It is suggested that the algorithms be developed using a step-
wise refinement technique. The successive views of the algorithm
can be "stored away" in the source code, and may be extracted
later using the "--#extract" command (see Section 9.0).
The following design statement keywords are recognized:
Loop Statements
loop
for
while
end loop
If statement
if
if..then
elsif
elsif..then
else
end if
Case Statement
case
when
end case
Task related statements
accept
accept..do
select
or
end select
Execution flow control
exit
return
goto
raise
The design statements are processed with two goals in mind:
(1) to produce a "pretty print" document explicitly showing
the flow of control and the nesting structure of the program
unit.
(2) to provide cross reference information about the use of
Ada entities (objects, types and program units) in the
design statement.
The pretty printed document will highlight all design statement
keywords by underscoring or capitalizing as described in section
6.3.
The "abnormal" exits from control structures are also flagged
using an exit arrow to draw attention to the point of exit. These
abnormal exits, for example, may be the result of a design
statement raising an exception.
All design statements are scanned for reference to any previously
declared Ada entity, such as an object, type, or program unit.
All references to Ada entities are recorded in the cross
reference design reports.
Design statements are comments to the Ada compiler, and do not
have to end with a semi-colon.
The remainder of this section will discuss the processing of the
design statement keywords.
4.1 Loop Statements
Design statements beginning with the keyword "loop", and design
statements beginning with the keywords "for", or "while" and
ending in the keyword "loop", are printed at the current
indentation level. All subsequent lines are indented one level
until the next "end loop".
The "end loop" will return the indentation level to the same
indentation level as the "while" and "loop" design statements.
An example:
The input text
--| While the Egg is in the Pan
--| loop
--| try to push the Egg out of the Pan
--| put more Water in the Pan
--|end loop
will be printed as
while the Egg is in the Pan
loop
try to push the Egg out of the Pan
put more Water in the Pan
end loop
4.1.1 Loop statement errors
The following errors are reported:
No "end loop" design statement supplied for the outer-most "loop"
design statement.
An "end loop" is supplied without a matching "loop" statement.
4.2 If statement
The keywords "if", "elsif", "else", are used to change the
indentation level of subsequent design statements. Statements
following a design statement following the "if" keyword are
indented one additional level, except the design statement
beginning with the keywords "else" or "elsif". Design statements
beginning with "else" or "elsif" are printed at the same
indentation level as the line containing the "if" keyword. The
keyword "end if" is used to terminate the "if" statement.
Each "if" or "elsif" keyword may have a corresponding "then"
keyword. The "then" keyword, if present must either be the last
word on the line containing the "if" or "elsif", or it must be
the first keyword on a line.
Each "if" must have one corresponding "end if".
The "end if" will return the indentation level to the same
indentation level as the "if" and "else" design statements are
printed.
For example the input text
--|IF THE DOG IS HUNGRY
--|THEN FEED IT
--|ELSIF THE DOG IS THIRSTY THEN
--|GIVE IT SOME WATER
--|ELSE
--|CHECK IF IT IS ALIVE
--|THEN CALL FOR A VET
--|END IF
will be printed as
if THE DOG IS HUNGRY
then FEED IT
elsif THE DOG IS THIRSTY then
GIVE IT SOME WATER
else
CHECK IF IT IS ALIVE
THEN CALL FOR A VET
end if
4.2.1 If statement errors
The following conditions will cause an error message to be
printed:
An "else" or an "elsif" keyword is detected before a
corresponding "if" keyword.
No "end if" is supplied.
4.3 Case Statement
The keywords "case", "when" and "end case" are processed as
follows. After a design statement beginning with the keyword
"case", the subsequent design statement will usually start with
the keyword "when", which will be printed one indentation level
to the right of the "case" statement. All design statements
following the design statement containing the keyword "when" will
be printed one indentation level to the right of the "when"
design statement. The "end case" will be printed at the same
indentation level as the most previous "case" design statement.
for example the input statements
--| case Incoming_target is detected
--| when Foe
--| suggest a Target_engagement
--| when Friend
--| notify operator of Friendly_target
--| when Unknown
--|notify operator of Unknown_target
--|Get_more_information about target
--| when others
--| there are no other cases
--| end case
Will result in the following output:
case Incoming_target is detected
when Foe
suggest a Target_engagement
when Friend
notify operator of Friendly_target
when Unknown
notify operator of Unknown_target
Get_more_information about target
when others
there are no other cases
end case
4.3.1 Case statement errors
The following errors are reported:
No "end case" design statement supplied for the outer-most "case"
design statement.
An "end case" is supplied without a matching "case".
4.4 Task related statements
Tasks are declared using the Ada language. The processing which
is to be accomplished by the task body, and the conditions under
which rendezvous are designed to occur, are all specified using
the ADADL design statements. The following keywords are relevant
to the task related statements: "accept".."do".."end",
"select".."or".."end select", "select".."when", "else".
A design statement starting with the keyword "accept" must either
end in the keyword "do" on the same line, and have a
corresponding "end" statement, or the design statement starting
with the keyword "accept" must not contain any actions to be
performed at rendezvous (no statements between "do" and "end").
All design statements following the keyword "accept" are printed
indented to the right, except for the keyword "or". The word
following the keyword "accept" is a name of a task entry, and
will appear in the task entry cross reference table, (see
section 7.0).
Some examples are shown below.
The input text
task body Try_to_catch_me is
--|select
--|accept Tag do
--| run around like a chicken
--|end;
--|or
--|accept Hide
--|end select
end Try_to_catch_me;
will be printed as
.cp9
task body Try_to_catch_me is
select
accept Tag do
run around like a chicken
end;
or
accept Hide
end select
end Try_to_catch_me;
4.5 Execution flow control
Changes in the flow of control, which would normally proceed in a
top down manner, from one statement to subsequent statements on
the page, are accomplished either by the reference to previously
defined subprograms or tasks in the design statements, or by
design statements starting with the keywords "exit", "return",
"raise" or "goto".
Subprogram and task references which are a part of a design
statement result in the printing of an arrow from the end of the
design statement, to the right margin of the page, where the page
and line number of the subprogram or task declaration is listed.
See the example in Appendix A for further clarification.
The keywords "exit, "return", "raise" and "goto" result in the
printing of "exit arrows" which are arrows which point to the
left margin of the page, denoting a possible "abnormal" exit
from the control structure.
Examples of the two types of arrows are shown below.
The following code fragment
procedure A_proc is begin ... end
-- A_proc is some previously declared procedure
--... (declared on page 23 for example)
--...
--|loop
--|if we can use A_proc to determine the correct
--| strategy then
--| do so before reverting to using any other method
--| else
--| exit and go find another starting point
--| end if
--|end loop
results in the following pretty printed documentation.
loop
if we can use A_proc to determine the correct ----> (23)
strategy then
do so before reverting to using any other method
else
<--- exit and go find another starting point
end if
end loop
The right pointing (invocation) arrow indicates the page number
where the subprogram which is being invoked may be found. The
left pointing (exit) arrow shows that the flow of control may
cause the program to leave the current control structure.
4.6 Labelled design statements
Labels for design statements and names for loops should be input
as a separate line of design text, which contains the prefix
"--|" followed by the label or name, as shown below.
An example of a named loop is:
--| OUTER :
--| loop
An example of a labelled design statement is:
--| << HERE >>
--| return
.pn 1
.fo Continuation statements page 5 - #
5.0 Continuation of Input and output statements
This section describes how the user may continue input statements
beyond the end of a line, and how the ADADL processor denotes the
continuation of output lines.
5.1 Continuation of design statements
Input text for a design statement may extend beyond the end of
a line by placing a continuation directive at the end of each
line of text to be continued. The ampersand character "&" is used
as the continuation directive. It is placed at the end of a line
of input to concatenate that line with the next line of text.
An example:
--| If there is a very long condition I would like to describe &
--| on one line
--| then use an "&" character
--| end if
will result in
If there is a very long condition I would like to describe on one line
then use an "&" character
end if
The user may concatenate as many subsequent input text lines as
desired, but the sum of the number of Ada entities, (either
objects, types, program units, etc.) and keywords contained in
the concatenated lines is limited to 100.
5.2 Ada code input statement continuation
All Ada declarations may continue past the end of a line without
the use of a continuation directive.
The ADADL processor will both indent all lines after the first
line up to end of the declaration, and also start a new line for
each new line of input.
An example:
procedure X(
Y:integer;
Z: out float
) is
begin
will result in the following output:
procedure X(
Y:integer;
Z: out float
)is
begin
5.3 Output statement continuation
Output text which is too long to fit on one line will be
continued on the output page by printing a continuation mark (an
ampersand "&") at the right margin of all lines which have
continuations on the following line.
An example:
--| If there is a very long condition I would like to describe &
--| like something about singing and dancing
--| then use a "&" to character
--| end if
will result in
If there is a very long condition I would like to describe like something about &
singing and dancing
then use an "&" character
end if
.pn 1
.fo Processor Controls page 6 - #
6.0 Processor Controls
Processor controls are the means by which the user can specify
exactly which reports, and their format, he wishes to have
printed.
Processor control commands are recognized only at the beginning
of input lines. The commands are always Ada comments. These
commands always begin with "--#", (note that the quotation marks
are not part of the prefix). If an error is found in a command,
the command is not executed. The erroneous command is printed in
the pretty-print output, along with a warning message. The error
report identifies the line number of the pretty print report on
which the erroneous command may be found.
In the following description, all identifiers shown in UPPER_CASE
must be replaced with an actual parameter name or value when the
command is issued. For example, in the --#pagelength LEN command,
LEN would be replaced by some integer indicating the desired
length.
The table below shows the default values for the ADADL processor.
Default Values
page width 80
page length 62
starting page number 1
program unit paging on
indentation 3
explicit structure on
keyword case lower
keyword underscore on
keyword boldface off
declared entities first (character capitalized only)
maximum allowable
design complexity 7
maximum allowable
code complexity 10
6.1 Page Width, Length, Numbering and Ejection
This section discusses how the user may change the default values
for page formatting.
6.1.1 Page width (--#pagewidth WID)
The user can override default value of the output page width
(WID) for hardcopy printout. To override the default value, the
user must specify the new desired value for the page width.
For example,
--#pagewidth 132
would cause the output document to have 132 columns on each
page.
The minimum and maximum allowable page widths are installation
dependent (see Appendix B). Specification of an unachievable page
width will result in the default value.
6.1.2 Page length (--#pagelength LEN)
The user can override the default value for the number of lines
(LEN) on each hardcopy output page printout. To override the
default value, the user must specify the new desired value for
the page length.
For example,
--#pagelength 55
would cause the output document to have 55 lines on each page.
Specification of a value less than 20 lines will result in the
default value being used.
6.1.3 Next page number (--#pagenum NUMBER)
The user can change the page number of the hardcopy printout at
any time. For example,
--#pagenum 50
would immediately set the page counter to 50, causing the all
subsequent lines on the page to be printed on page 50, and all
subsequent pages to be printed on pages 51, 52,... etc.
The specification of a negative NUMBER, or a NUMBER of 0 will
result in an error, as will the specification of a page number
which is less than the current page being printed.
The "pagenum" command when given may not decrease the page number
of the report below that which would be printed if the "pagenum"
command was not issued. In other words the "NUMBER" must specify
a larger page number than would ordinarily be printed.
Since the "--#pagenum" command forces an immediate change in the
current page number, it should be used only immediately after or
immediately before a "--#newpage" command.
6.1.4 Pagination of program units (--#pagepu on/off)
The default condition (--#pagepu on) causes the ADADL processor
to automatically eject a page at the start of each new program
unit when printing the Pretty Print report. The processor
control command "--#pagepu off" will suppress this automatic
ejection.
6.1.5 Page ejection (--#newpage LINES_REMAINING)
The command "--#newpage" causes an automatic page ejection,
thereby resulting in subsequent output of the Pretty Print report
to start at the top of a new output page.
For example,
--#newpage
causes a page eject to be issued.
If a positive integer (LINES_REMAINING) is given after the
"--#newpage" command, a new page will be started only if less
than (LINES_REMAINING) lines remain on the current page.
For example,
--#newpage 5
will cause a new output page to begin only if less than 5
lines remain on the current page.
6.2 Adjustment of Indentation Amount (--#indent AMOUNT)
The user can override the default of 3 spaces and set the
indentation amount to any desired value within the range 2 to
6.
For example,
--#indent 5
would cause the indentation amount to be 5 spaces. If this
command is used, it must be given before any design text.
6.2.1 Explicit structure indication (--#structure on/off)
By default, a vertical bar is used in the pretty print output of
the pseudo code design statements in order to accentuate the
levels of nested structures.
For example, the input
--|if A is something
--|do this
--| and do that too
--|else
--|loop
--| do something in a loop until you can get out
--| exit when you are ready
--|end loop
--|end if
will result in the following
if A is something
| do this
| and do that too
else
| loop
| | do something in a loop until you can get out
<---------exit when you are ready
| end loop
end if
To suppress printing of the vertical bar nesting indication, use
the command --#structure off.
To enable or to restore the printing of the vertical bar nesting
indication, use the command --#structure on.
6.3 Keyword Case and Highlighting
Keywords in the design statements as specified in section 4.0,
and Ada code keywords described in section 3.0, are, by default,
output in lower case. The user has the ability to change
this and have keywords output in upper case or in the same case
in which they were input. There is also an option to enable or
disable keyword underscoring and boldfaced printing.
6.3.1 Lower Case (--#keyword lower)
In the default case (--#keyword lower) keywords are output in
lower case. The input text
--| If THE BIG DOG IS HUNGRY THEN
--| FEED HIM IMMEDIATELY
--| Else
--| GIVE HIM SOME WATER
--| End if;
would be printed as
--|if THE BIG DOG IS HUNGRY then
--| FEED HIM IMMEDIATELY
--|else
--| GIVE HIM SOME WATER
--|end if;
6.3.2 Upper Case (--#keyword upper)
The command "--#keyword upper" will cause these keywords to be
output in upper case.
The example text would be printed as
--|IF THE BIG DOG IS HUNGRY THEN
--| FEED HIM IMMEDIATELY
--|ELSE
--| GIVE HIM SOME WATER
--|END IF;
6.3.3 Same case as input (--#keyword same)
The command "--#keyword same" will cause the keywords to be
output in the same case in which they were entered.
The example text would be printed as
--|If THE BIG DOG IS HUNGRY THEN
--| FEED HIM IMMEDIATELY
--|Else
--| GIVE HIM SOME WATER
--|End if;
.cp 4
6.3.4 Underscoring of keywords (--#underscore on/off)
The default condition (--#underscore on) will print keywords
underscored.
The command "--#underscore off" will disable keyword
underscoring.
The "--#underscore on/off" command may be combined with either
the default (keyword lower), the keyword upper, the keyword same,
or the boldface on/off modes of keyword printing.
Note: the underscore option is dependent on the printer support
for the particular implementation site. Certain printers may not
provide the ability to underscore the keywords. Please refer to
Appendix B which deals with installation for more detail.
6.3.5 Boldface printing of keywords (--#boldface on/off)
The default condition (--#boldface off) will not print keywords
boldfaced.
The command "--#boldface on" will enable the boldface printing of
keywords.
The "--#boldface on/off" command may be combined with either the
default (keyword lower), the keyword upper, the keyword same, or
the underscore on/off modes of keyword printing.
Note: the boldface option is dependent on the printer support for
the particular implementation site. Certain printers may not
provide the ability to perform the boldface printing of the
keywords. Please refer to Appendix B which deals with
installation for more detail.
6.4 Output Format of Declared Entities
All Ada entities such as objects, types, program units and task
entries may be highlighted and enhanced in the pretty print
listing by either capitalization of all characters, making all
characters lower case characters, or by leaving the input textual
description of each entity unchanged.
6.4.1 First character capitalized (--#declared first)
The default case (--#declared first) will print the names of
declared program units, task entries, types, and objects with
first letters in upper case in both their declarations and in all
references to them in the design. The first character after any
underscore character is also capitalized.
6.4.2 Upper case (--#declared upper)
The command (--#declared upper) will print the names of declared
program units, task entries, types, and objects with all letters
in upper case in both their declarations and in all references to
them in the design.
6.4.3 Lower case (--#declared lower)
The command (--#declared lower) will print the names of declared
program units, task entries, types, and objects with all letters
in lower case in both their declarations and in all references to
them in the design.
6.4.4 Same case as input (--#declared same)
The command (--#declared same) will print the names of declared
program units, task entries, types, and objects with all letters
in the same case as input.
6.5 (--#goodstyle on/off) Command is no longer supported
In earlier versions of the proceesor it was thought that all
object, type, program unit and task entries that are used in the
PDL portion of the design should begin with at least one UPPER
CASE letter. This is no longer required, and therefore, the
command (--#goodstyle on/off) is no longer supported.
This command should be removed from previous versions of the
processor. Failure to remove the command will cause an ADADL
command syntax error.
6.6 User Defined Reference Tables (--#mark PUNCT TABLE)
Mark directives may be used in order to keep track of specific
information which the user can identify with a special character.
The user can specify a punctuation mark (PUNCT) which will cause
all words containing the character PUNCT to be placed in a
cross reference table named (TABLE). For example,
Satements containing the specified Mark PUNCT character are
detected by the ADADL processor when they appear either in a
pseudo-code design statemenent (--|) or in a project management
statement (--*).
--#mark $ revision areas
--#mark @ Requirements Traceability
would cause all words found either in the design statements (statements
starting with --|) or in the project management statements
(statements starting with --*) which contain a dollar sign "$"
to be placed in a cross reference table titled "revision areas",
and those words containing the "@" symbol to be placed in a cross
reference table named "Requirements Traceability".
Omitting the title of the table will result in an error.
If more than one PUNCT mark is encountered in a word, only the
first PUNCT mark is referenced, the other mark is ignored.
The following punctuation marks may be used in the "--#mark"
command:
$, ?, @, [, ], `, ~, ^, {, }
Up to ten "--#mark" commands may be used. Each "--#mark" command
may specify one PUNCT character.
6.6.1 Defining Project Management reports
This section shows how the "--#mark" directives can be used to
generate a sample series of project management reports. Other
types of reports can be generated easily.
6.6.1.1 Tracing requirements to program units
In order to create a report which lists the requirements and also
shows the program units which satisfy the requirement the user
can use a mark directive as shown below:
--#mark @ Software Requirements Traceability
--#mark ? Interface Requirements
In each program unit, the user must then define the requirement
that is being satisfied by that program unit, as in:
procedure Find_likely_targets (
--- ..... ) is
--*Software reqts @3.1.1.2.3 @3.1.1.10.4 Interface reqts ?2.3.3
---
---
end;
More than one requirement can be listed for each program unit.
For "utility" programs, the user can enter the requirement as
text describing the module as a utility:
procedure Sort_array (
--- ..... ) is
--* @a_utility_module
---
---
end;
6.6.1.2 Showing Dates of Completion of Design
In order to create a report which shows the dates that each
program unit design was completed the user can use a mark
directive as shown below:
--#mark [ Dates of Design Completion
In each program unit, the user must then define the date that the
design portion was completed as in:
procedure Find_likely_targets (
--- ..... ) is
--*Software reqts @3.1.1.2.3 @3.1.1.10.4 Interface reqts ?2.3.3
--* Completion Dates: Design [11/21/85
---
end;
.cp6
6.6.1.3 Showing Dates of Completion of Coding
In order to create a report which shows the dates that the coding
of each program unit was completed the user can use a mark
directive as shown below:
--#mark ^ Dates of Coding Completion
In each program unit, the user must then define the date that the
coding was completed as in:
procedure Find_likely_targets (
--- ..... ) is
--*Software reqts @3.1.1.2.3 @3.1.1.10.4 Interface reqts ?2.3.3
--* Completion Dates: Design [11/21/85 Coding: ^02/24/86
---
end;
6.6.1.4 Showing Dates of Completion of Testing
In order to create a report which shows the dates that the
testing of each program unit was completed the user can use a
mark directive as shown below:
--#mark ] Dates of Testing Completion
In each program unit, the user must then define the date that the
testing was completed as in:
procedure Find_likely_targets (
--- ..... ) is
--* Software reqts @3.1.1.2.3 @3.1.1.10.4 Interface reqts ?2.3.3
--* Completion Dates: Design [11/21/85 Coding: ^02/24/86
--* Testing: ]04/15/86
---
end;
6.6.1.5 Referencing Responsible Designers to the design
In order to create a report which shows the name of all
designers, and defines the program units for which each designer
is responsible, the user can use a mark directive as shown below:
--#mark ` Areas of Responsibility for Designers
In each program unit, the user must then define the name of the
resposible designer as in:
procedure Find_likely_targets (
--- ..... ) is
--* Software reqts @3.1.1.2.3 @3.1.1.10.4 Interface reqts ?2.3.3
--* Completion Dates: Design [11/21/85 Coding: ^02/24/86
--* Testing: ]04/15/86
--* Original Designer `Alberts,Frank
--* Modifications `Johnson,James
---
end;
6.6.2 Using mark directives in the pseudio-code design statements
The mark directives may be used in the pseudo-code design
statements as well as in project management statements.
An example using the command
--#mark ~ Revisions to the design
is shown below. The areas of the design that are modified
subsequent to being reviewed and put under configurationa
management are identified with the ~ PUNCT character. Perhaps
showing the date or the revision number.
procedure Radar_control is
--
--| if the Radar_return shows that the target is present
--| and the velocity is greter than minimum ( ~rev_1.3 )
--| then do something
--| ....
--| end if
6.7 Design Report Suppression and Creation
The various design reports are described in section 7.0. This
section describes how printing of any of the design reports may
be suppressed, and how the smalltree invocation report may be
created.
If any of the design report suppression commands are used, they
must appear before any design text.
6.7.1 Suppress Object Report (--#noobject)
The command "--#noobject" will suppress the printing of the
object cross reference table.
6.7.2 Suppress Type Report (--#notype)
The command "--#notype" will suppress the printing of the type
cross reference table.
6.7.3 Suppress Program Unit and Entry Report (--#nounit)
The command "--#nounit" will suppress the printing of the cross
reference table for program units and task entries.
6.7.4 Suppress TBD (to be determined) Report (--#notbd)
The command "--#notbd" will suppress the printing of the cross
reference table for all TBD items.
6.7.5 Suppress Invocation Tree Report (--#notree)
The command "--#notree" suppresses the generation of the
subprogram and task invocation trees.
6.7.6 Create Smalltree Invocation Report (--#smalltree)
The command "--#smalltree" causes the generation of the Smalltree
Invocation Report described in section 7.6.
6.7.7 Suppress Dictionary Report (--#nodict)
The command (--#nodict) will suppress the printing of the
dictionary report.
.cp 5
6.7.8 Suppress Generic Instantiation Report (--#nogeneric)
The command (--#nogeneric) will suppress the printing of the
generic instantiation report.
6.7.9 Suppress Pretty Print Report (--#nopretty)
The command (--#nopretty) will suppress the printing of the
pretty print report, which "pretty prints" all program unit
design and code segments. All other reports will be printed as
usual unless suppressed using the processor commands.
6.7.10 Suppress Spelling Error Checker (--#nocheck)
The command (--#nocheck) will suppress the processor from
checking for possible errors in typing or spelling of any Ada
entities in the design pseudocode or the Ada code.
6.7.11 Suppress Complexity Report (--#nometric)
The command (--#nometric) will suppress the printing of the
complexity report.
6.7.12 Suppress Declaration Tree Report (--#nodectree)
The command (--#nodectree) will suppress the printing of the
declaration hierarchy report, which shows the nesting of the
program unit declarations.
6.8 Title Page (--#title ... --#end)
The design document may be given a title page. For example,
--#title
--# Program Design Language
--# H. Morales
--# September, 1984
--#end
The text on all lines following the "--#title" directive up to
the "--#end" directive is taken as the design title. The title
page text is terminated by "--#end". All lines between the
"--#title" and "--#end" must begin with "--#". If a line is
encountered which does not begin with "--# ", the title page text
is terminated and a warning message is printed. The title
page text is enclosed in a box formed by asterisks. Each line
is centered within the box, and the box is centered on the
page. Lines are truncated if they exceed the box right margin.
The title page is printed as the first cover sheet of the design
document. The title page does not have a page number associated
with it. The title page is not scanned for references to objects,
types, program units, etc.
The title page may not exceed 60 lines. If more than the maximum
allowable number of title lines is specified, a warning message
will be printed.
If more than one "--#title" command is used, only the last one
read by the processor will be recognized.
6.9 Design heading (--#heading ... --#end)
The command "--#heading" signals the beginning of a sequence of
lines which are to be enclosed in a box formed of asterisks
and printed at the top of each page of the design document. The
heading text is terminated by the command "--#end". All lines
in between "--#heading" and "--#end" must begin with "--# ".
If a line is encountered which does not begin with "--# ",
the heading text is terminated and a warning message is printed.
An example design Heading is shown below:
--#heading
--#Computer Systems Design
--#Special Project "Alpha - Star"
--#Contract Number AS-12-444-5Y
--#end
The design heading may not exceed 7 lines in length, (not
including the --#heading and --#end processor commands). A
warning message is printed if the design heading exceeds the
maximum allowable length.
The design heading is not scanned for references to objects,
types, program units, etc.
Instead:
(1) The text is enclosed in a box formed by asterisks.
(2) Each line is centered within the box and the box is centered
across the page width.
(3) The heading is printed at the top of each page of the pretty
print design document.
Lines are truncated if they exceed the box right margin.
The design heading may be changed as often as desired.
Once a design heading is specified, some heading will be printed
on all subsequent pages. There is no way to disable subsequent
printing of the design heading.
6.10 Text Insertion (--#text .. --#end)
The command "--#text" signals the beginning of a sequence of
lines which are to be enclosed in a box formed of asterisks
and printed at the top of each page of the design document. The
text is terminated by the command "--#end". All lines in
between "--#text" and "--#end" must begin with "--# ". If a
line is encountered which does not begin with "--# ", the
text is terminated and a warning message is printed.
An example of a text specification is shown below:
--#text
--#The following section of code describes the
--# Computer Systems Design
--# Approach to solving the spatial distortion
--# problem associated with Special Project "Alpha - Star"
--#end
The text may not exceed 60 lines in length, (not including the
--#heading and --#end processor commands). A warning message is
printed if the text exceeds the maximum allowable length.
The text is not scanned for references to objects, types,
program units, etc.
Instead:
(1) The text, exactly as input, is enclosed in a box formed by
asterisks.
(2) The text is printed on the pretty print design document in
the same place the --#text .. --#end command appears in the input
file.
Lines are truncated if they exceed the box right margin.
The --#text command may be used as often as desired.
.cp 4
6.11 Creating a Code Prolog Section (--#prolog PROLOG_FILENAME)
The ADADL processor may be used to create the prolog section to
the final Ada code. The prolog section of an Ada program consists
of all Ada statements which have been entered, along with a
pretty printed version of the design statements, which show the
design intent. The code and the design statements are output to
the file named (PROLOG_FILENAME). The pretty printed design
statements are output preceded with the --| symbol, which makes
them Ada comments.
Line numbers, page numbers, and headings are not output to the
file (PROLOG_FILENAME) if the "--#prolog" option is selected.
The prolog sections of all program unit bodies will serve as a
description of the designer's intent. The actual executable Ada
code will be developed in the body of the program unit, leaving
the PDL description in the prolog to the body.
If a prolog output is desired, the --#prolog command must be the
first command in the input text.
6.12 Adding Executable Ada Code
Ada executable code may be added to the design at any stage by
delimiting the code using the Ada keyword begin at the start of
the code. The program unit end statement will be the end of the
code.
All Ada statements between the begin and end statements are
scanned for references by the ADADL processor.
The Ada executable code will be reformatted according to the
pretty print format specifications of Sections 6.3 and 6.4. and
will be output on the pretty print document, and the PROLOG_FILE
if the "--#prolog" option is used.
6.13 Ignoring Executable Code (--#ignore begin ... --#ignore end)
Executable code may be added to the design at any stage as
described in Section 6.12. This code will normally be processed
by the ADADL processor. The user may prevent the ADADL processor
from analyzing the executable code, by delimiting the code using
the command "--#ignore begin" at the start of the text to be
ignored, and "--#ignore end" at the end of the text to be
ignored.
Any statements (usually executable code) between the "--#ignore
begin" and "--#ignore end" is ignored by the ADADL processor.
The ignored statements will never be output on the pretty print
document, but all statements between and including the "--#ignore
begin" and --#ignore end" pair will be output to the PROLOG_FILE
exactly as input if the "--#prolog" option is used.
6.14 Setting the Maximum Complexity Metric
(--#maxcomp NDES MCODE NEST)
The pseudocode statements and the executable Ada code are
independently examined to determine the complexity of both the
design (as expressed in the pseudocode) and the code.
The McCabe measure of cyclomatic complexity (see Reference 2 for
more information), quantifies the design and code complexity
through an analysis of the control structures.
The ADADL complexity measure is an augmentation of the McCabe
measure which considers not only the control structure, but also
the depth of nesting of the control structures.
The ADADL complexity measure of each program unit is calculated
as follows:
1. The McCabe cyclomatic complexity is calculated from the
control structure.
2. The number of times the nesting level exceeds the integer
specified by the parameter NEST (default is NEST = 2) within a
given module is calculated.
3. These two figures are added to determine the ADADL
complexity measure.
The maximum allowable complexity for both the design and code is
defined using the command "--#maxcomp NDES MCODE NEST", where
NDES is an integer defining the maximum acceptable complexity of
the design statements, MCODE is an integer defining the maximum
acceptable complexity of the executable code, and NEST is an
integer defining the maximum acceptable nesting level for the
calculation of the ADADL complexity measure as described above.
The default is set to NDES=7, MCODE=10 and NEST=2.
If either the design or the code ADADL complexity exceeds the
maximum specified by the user, a warning message is printed in
the complexity report.
6.15 Declaring Program Units as utility programs (--#utility)
Program units which are utility programs and are therefore
invoked by several different program units throughout the design
may be eliminated from the invocation tree and smalltree report
by using the "--#utility" command after the declaration of either
the specification or the body part of these program units.
Example:
function Sine( Input_angle : Radian_angle) is
--% general purpose sine routine with radian inputs
--#utility
--...
end Sine;
Those program units which contain the "utility" command will
appear under a separate section of the invocation tree report,
and will not appear in the tree as being invoked by other program
units.
However if the utility programs invoke other program units, they
will be shown as invoking those units (unless they also are
utilities) on the invocation tree report.
6.16 Including previously developed designs or command files
(--#include FILENAME)
Previously created text files can can be included anywhere in the
design using the "--#include" command.
The user can specify an unlimited number of files to be textually
inluded (a parameterless "macro" substitution) in the ADADL input
file. The command format is: --#include FILENAME, where FILENAME
is a valid file descriptor of a text file on the host machine.
For example on the VAX/VMS version:
--#include [Direct.adastuff]command.inf
will include the file (command.inf) which is located in directory
(Direct.adastuff).
The "include" capability allows project members to create a
standard header section, or a standard output format for all
project reports, as well as allowing design team members to
create separate source files of design, which can be subsequently
"included" together.
There is no limit on the number of files which may be included
(the number of time the "--#include"command is used in the
design.) Each "included" file may also contain the "--#include"
command in order to include other files, up to a maximum nesting
level of ten (10) "includes" within "includes" within included
files.
6.17 Supressing the "pseudo code follows" and "Ada code
follows" boxes (--#noboxes)
The pretty print output normally delineates the start of pseudo-
code and the start of executable Ada code for each program unit.
These are delineated using "boxes" similar to:
*************************
* Pseudo-code *
* Follows *
*************************
or
*************************
* Ada Code *
* Follows *
*************************
These boxes can be inhibited by using the command "--#noboxes".
6.18 Suppressing the printing of the "extract" documentation
on the pretty print report (--#noextract)
The textual information which is added to the source code in
order to produce documentation using the Doc-Gen tool may be
inhibited from being printed on the pretty print output report by
using the "--#noextract" command.
Any text which appears between the "--#extract xxx" and the
terminating "--#end extract" keywords are extracted and put in
the Intermediate Documenation File, but will not appear in the
pretty print report.
6.19 Importing context clause library information
(--#includlib host-computer-file-name)
The --#include command textually includes another file. This is
desirable to combine several reports into one larger report, but
is not an optimal implementation for an Ada library.
The --#includlib command is used to support the Ada library
concept.
For large projects, when several different designers are working
together, it is desirable to separate the amount of information
printed by the ADADL processor on the pretty print report. The
individual designers may have access to the project library, and
can import library units using the Ada "with" clause.
The ADADL --#includlib command is equivalent to an Ada "with"; it
retrieves and restores the context of the packages found on the
host-computer-file-name specified in the command.
For example if a file named Foo.txt was stored on the system, and
contained the following;
package foo is
type dummy is (aa,bb,cc);
procedure A (innn : dummy);
end foo;
in Ada the instruction "with Foo" will restore the context of
package foo. The ADADL command which is equivalent to the Ada
"with" command is "--#includlib Foo.txt".
The file Foo.txt is retrieved from storage and reprocesssed by
the ADADL processor, just as woulf be done using the "--#include"
command. However, the information which is retrieved from storage
is marked internally by the ADADL processor to be library
information, and is therefore used only so set up the proper
context, and is not printed on the pretty print or prolog files.
The user will have access to all objects in the host-computer-
file-name file, just as he would have if he had "withed" the
package in Ada.
.pn 1
.fo Design Reports page 7 - #
7.0 Design Reports
The processor scans each input design statement for references
to the objects, types, and program units which were previously
declared using the full Ada language syntax, and are visible at
the point of the design statement. Both simple names, within the
scope of their visibility, and the expanded names are recognized.
The processor will produce design reports which aid the
designer/reviewer in analyzing the design. The following sections
describe the various types of reports available.
7.1 Object cross reference table
The object cross reference table provides the following
information:
(1) All objects and formal parameters declared in the program
units using the correct Ada syntax will be listed.
(2) All record components appear in the object cross reference
table.
(3) The location of the declaration of the object is given. (The
"location" consists of the enclosing program unit, and the
page and line numbers). Since a declaration may be made in more
than one place, (for example, the specification part and the body
part of a program unit might be in different locations), all
locations of the declaration is given.
(4) All references to the object will be listed. The name of each
program unit which references the object is printed. The page
number where each of these program units can be found is given
along with a list of the line numbers on which the object was
referenced. The object reference is identified as occuring in the
design pseudo-code, or in the executable code.
(5) The type of the object and any initialization of the object
is also shown.
Note: The type of the object and object initialization is shown
on the object cross reference report by replicating all text
between the colon and the semi-colon used in the object
declaration, including optional definitions. This may be
objectionable in some cases.
A non-objectionable example:
A_thing : Some_type := Initial_value ;
will result in the text " Some_type := Initial_value" to be
listed in the object cross reference table under object A-thing.
But if a definition is given on the same line as the object
declaration, as in:
A_thing : Some_type --% used to do something or another
;
this will result in the text " Some_type --% used to do something
or another" to be listed in the object cross reference table
under object A-thing. This possibly objectionable listing can be
avoided by providing all definitions after the terminating semi-
colon either on the same line, or on the next line as shown
below.
A_thing : Some_type :=Initial_value; --% used for something
or
A_thing : Some_type :=Initial_value;
--% used for something
Both of the above examples will produce the type definition for
object A_thing as "Some_type :=Initial_value", and will also
produce the data dictionary entry for A_thing as "used for
something".
7.2 Type cross reference table
The type cross reference table contains the following
information:
(1) All types, subtypes, derived types declared in program units
being submitted to the processor appear in the type cross
reference table.
(2) The location of the declaration is given.
(3) The location of each reference to the type in a declaration
is given, as well as an identification of whether the type
reference occured in the design pseudo-code, or in the executable
code.
(4) For subtypes and/or derived types, the base/parent type of
the subtype or derived type is listed.
7.3 Program unit and task entry cross reference table
The program unit and task entry cross reference tables contain
the following information:
(1) All program unit and entry declarations appear in the
program unit and entry cross reference table.
For each of these program units and task entries:
(2) The page number on which it is declared is given. Since a
specification may be given in more than one place, two page
numbers may be given.
(3) The name of each program unit that references this program
unit or task entry is printed, along with the page number
where it can be found and the list of line numbers on which the
program unit or entry was referenced, as well as an
identification of whether the reference occured in the design
pseudo-code, or in the executable code.
For all program units which are instantiations of some generic,
the name of the generic program unit is shown along with a
notation that the program unit is an instantiation of that
generic.
7.4 Design TBD (to be determined) reference table
The stepwise refinement methodology for software development,
permits a design to continue definition even though some areas
are not fully defined. These areas are denoted as TBD (to be
determined). They need to be defined before the coding phase
begins. The TBD cross reference table explicitly shows the areas
that need further definition.
The processor searches for "TBD" in the design. The location of
any statement containing "TBD" is printed in the design TBD cross
reference table. (The locations are given by the enclosing
program unit name, the page number, and the line number).
7.5 Program unit invocation trees
Invocation trees show the program unit invocation hierarchy.
The following information about invocations of program units is
shown:
(1) A separate tree is given for each program unit submitted to
the processor which is not invoked by another program unit.
(2) When a task entry is called, the entry is placed on the
invocation tree and the tree continues with any references
made within the accept statement for the entry.
(3) A task will start an invocation tree if it references any
other subprograms or tasks, even if the task's entries are
called by other subprograms and tasks.
(4) When a program unit or task entry appears in an invocation
tree, the page number of its first declaration is given.
(5) If the processor, while tracing a subtree, encounters the
same program unit twice, the second occurrence is printed
preceded by an asterisk to indicate recursion, and the
tracing of the smalltree stops.
7.6 Smalltree invocation report
The smalltree invocation report is similar to the program unit
invocation tree report described in Section 7.5, with the
following exceptions:
(1) Only immediate invocations (not invocations made as the
result of invocations) are shown. Hence each smalltree is at most
two levels deep.
(2) A smalltree is created for each program unit which causes at
least one invocation.
7.7 Dictionary Report
Any Ada entities may be given a definition to appear in the
Dictionary report, by using the symbol "--%" preceding the
definition or description. The definition will be printed in the
dictionary.
Definitions when given always refer to the most recently declared
Ada entity.
example:
A : Thing; --% this definition defines A as something
and
A : Thing;
--% this definition defines A as something
are equivalent definitions, and will result in the same
definition for A to be listed in the dictionary.
Dictionary definitions should be given after the terminating
semi-colon for declarations.
The data dictionary will also provide an indication as to the
nature of the entity, e.g. whether it is an object, type,
package, etc.
.cp 8
7.8 Generic Instantiation
The Generic Instantiation report lists the names of all generic
program units and the names of all instantiations of that
generic.
This report is helpful to see the ramifications of changing a
particular generic.
7.9 Table of Contents
The table of contents lists the name and page number of each
program unit submitted to the processor. In addition, page
numbers of the reference tree and all the cross reference tables
are given.
7.10 Error Summary and Report
The first page of the design document is a summary of all errors
detected by the ADADL processor. The total number of errors and
warning messages which are present in the design document is
listed in the error summary.
If any errors exist, an error report is produced. The error
report is a detailed list of errors, and warning messages ordered
by page number. A description of the error, the page number and
the line number on which the error occurs are listed on the
error report.
7.11 User-defined reference table
One User-defined reference table is created for each named mark
directive (see section 6.6) specified by the user. Each of these
tables lists all words containing the mark directive, and the
location (page number and line number) of all occurrences of each
of the words which contain the user-defined mark directive.
Since the user defined reference tables are usually defined to
satisfy particular reporting needs, the reader is referred to the
Appendix A for example reports.
7.12 Complexity Report
The pseudocode statements and the executable Ada code are
independently examined to determine the complexity of both the
design (as expressed in the pseudocode) and the code.
The McCabe measure of cyclomatic complexity (see Reference 2 for
more information), which quantifies complexity through an
analysis of the control structures, is augmented by considering
the depth of nesting of the control structures.
The ADADL complexity measure is calculated as follows:
1. The cyclomatic complexity is calculated from the control
structure.
2. The number of times the nesting level exceeds the user
defined maximum level (see the NEST parameter of the --#maxcomp
command) within a given module is calculated.
3. These two figures are added to determine the ADADL
complexity measure.
If either the design or the code complexity exceeds the maximum
specified by the user, a warning message is printed in the
Complexity Report.
In addition to a calculation of the complexity as described
above, the Complexity Report lists the number of times that each
type of control structure (e.g. if ...endif, case..end case), is
used in either the design or the code.
7.13 Declaration Tree Report
The declaration tree report shows the hierarchy of all program
unit declarations.
The lexical nesting of program units is shown by indenting
subordinate units under those program units which contain the
subordinate units.
7.14 Interrupt Report
The interrupt report shows the location of all entries which have
been declared as interrupts using the "for .. use at.." represen
tation specification in Ada.
.pn 1
.fo ADADL Library page 8 - #
8.0 The ADADL Library File
The ADADL library file contains the entries for the library units
and the file-name on the host processor which contains that
library unit.
The ADADL library file is called adadl.lib
The format of the file is as follows:
Library_unit_name_1 Host-computer-file-name-1
----
---
---
Library_unit_name_N Host-computer-file-name-N
Each Library_unit_name is the name of an Ada library unit which
can be imported using the "with" clause in an Ada program.
The Host-computer-file-name is the name of the file containing
the source code (or ADADL design) for the Library_unit_name.
The user must supply the file adadl.lib, which describes the
location (the file name) on the host computer where the ADADL
processor can find the information about each library unit that
the user wishes to import using the "with" clause.
An example adadl.lib file is shown below:
standard adadl.std
global_data Globldt.pkg
When the ADADL processor sees a context clause such as "with
library_unit" in the input file, The processor performs the
following actions in order to retrieve the library unit, and to
restore the proper context:
If the library_unit has already been processed in the current
input file, then nothing special is done since the ADADL
processor is already aware of the proper context.
However if the library_unit named in the "with" clause has not
been processed as a part of the current input file, then the
adadl.lib file is searched to find the library_unit name.
If the library_unit is found, then the host-computer-file-name is
read by the ADADL processor, and is processed as if the user
supplied a command "--#includelib host-computer-file-name" (see
6.19).
If the library_unit is not listed in the adadl.lib file, or if
the named file is not available, a warning message is issued
stating that the proper context cannot be established.
.pn 1
.fo Automatic Documentation page 9 - #
9.0 Including documentation information in the design
This section describes how the ADADL language can be used to
store documenation information which can be extracted and
processed by the associated Doc-Gen tool in order to produce Dod-
Std-2167, or other Mil-Std documents.
9.1 Creating an intermediate documenation file
9.2 How to format the design to extract different views of
the design.
.pn 1
.fo Automatic Test Plans page 10 - #
10.0 Using ADADL to generate Unit Test plans and procedures
10.1 Defining the Test-Gen File
.pn 1
.fo Installation and use page B-#
Appendix B
Installation and use of ADADL processor and Printers
This section discusses how the ADADL processor is to be installed
on particular host computer systems, as well as the procedure for
invoking the ADADL processor to process the input text.
The procedure for installing new printers is also discussed.
B.1 Installation procedure
This section discusses the installation procedures necessary to
install the ADADL processor on particular host computer systems.
To install the ADADL processor on any host computer system the
following files must be installed from the distribution tape
supplied:
adadl.err - a text file of error messages used by the ADADL
processor.
adadl.usr - an internally used file
adadl.prt - a text file, which may be modified by the system
manager, listing the printers which are available for
use at any particular installation.
*.DAT - several text files containing the printer data for each
printer listed in adadl.prt
adadl.hlp - a help file to be installed as decribed in
Section B.4.
some other sample input files may also be present, such as
bat.txt or tom.tst
For Vax/VMS and Unix systems, the ADADL processor assumes that
all files (except the input and output text files) are located on
logical directory adadldir.
For all applications, the logical directory adadldir should be
assigned, by the system manager, to a specific physical directory
compatible with the user's installation.
The following sections describe the format of the distribution
tape for the various host computer/operating system combinations.
B.1.1 VAX family - VMS
This section describes the tape format for reading the files on
the ADADL distribution tape for the VAX host, running under the
VMS operating system.
The ADADL distribution tape is written according using the VMS
Copy command. The tape is written at 1600 BPI, is labelled ADADL.
To read the tape on any Vax/VMS system, the mounted tape should
be copied to disk using the Vax/VMS command:
copy MT:*.* *.*
In addition to the files mentioned above, the following files
should be present:
adadl.exe - the executable code for the ADADL processor for
VAX/VMS
After the files are copied successfully, the adadl.* files and
the *.DAT files should be installed on the system.
The ADADL processor assumes that all files are located on logical
directory adadldir. For example the adadl.exe file assumes that
the error file is located at adadldir:adadl.err.
For VMS applications, the logical directory adadldir must be
assigned to a specific physical directory compatible with the
user's installation.
An example assignment if all ADADL system files are stored on
DISK$USER1:[DIRECT.SUBDIRECT] is:
In the SYSTARTUP file:
ASSIGN/SYS DISK$USER1:[DIRECT.SUBDIRECT] adadldir
or
DEFINE/SYS adadldir DISK$USER1:[DIRECT.SUBDIRECT]
In addition the following assignment should be made in SYLOGIN
adadl :== $adadldir:ADADL
B.1.2 UNIX and Unix derivatives
This section describes the tape format for reading the files on
the ADADL distribution tape for all hosts, running under the Unix
or Unix derivative operating systems.
The ADADL distribution tape is written using the Unix tar command
procedure. The tape speed is 1600 BPI.
To load the tape use the "tar -xv" command.
The ADADL processor assumes that all files are located on logical
directory /adadldir. For example the adadl.exe file assumes that
the error file is located at /adadldir/adadl.err.
In addition to the files mentioned in section B.1 the following
files are present on the distribution tape:
adadl - the executable code for the ADADL processor for Unix
and Unix derivative systems.
B.1.2 Data General MV series AOS/VS
The ADADL distribution tape is written using the AOS/VS DUMP
command procedure. The tape speed is 1600 BPI.
To load the tape use the AOS/VS LOAD command.
In addition to the files mentioned in section B.1 the following
files are present on the distribution tape:
adadl.pr - the executable code for the ADADL processor for DG-MV
AOS/VS
rm.cli - a command file to remove the jojo. file
The system manager must create another command file, which may be
called adadl.cli in order to set the search path for the adadl
program and its associated files.
B.2 Invocation and use
This section discusses the protocol for invocation and use of the
ADADL processor on various host systems.
B.2.1 VAX family - VMS
After having created a design input file, which we will call
DESIGN.TXT, to run the ADADL processor to produce design reports
in an output file called DESIGN.OUT type the following:
At the $ prompt type:
$ ADADL <CR> (note the <CR> means the return key)
args: DESIGN.TXT DESIGN.OUT
The format is (input file) followed by the (output file).
Failure to enter both filenames at the args: prompt will cause
the ADADL processor to ask the user for the name of the
appropriate input file or output file.
After the input and output files have been specified by the user,
the printer menu is displayed, and the user is required to select
a printer from the menu.
B.2.2 Unix and Unix derivatives
After having created a design input file, which we will call
DESIGN.TXT, to run the ADADL processor to produce design reports
in an output file called DESIGN.OUT type the following:
At the Unix system prompt "%" type:
% adadl DESIGN.TXT DESIGN.OUT <CR>
(note the <CR> means the return key)
The format is (input file) followed by the (output file).
Failure to enter both filenames will cause the ADADL processor
to ask the user for the name of the appropriate input file or
output file.
After the input and output files have been specified by the user,
the printer menu is displayed, and the user is required to select
a printer from the menu.
B.2.2 Data General AOS/VS
After having created a design input file, which we will call
DESIGN.TXT, to run the ADADL processor to produce design reports
in an output file called DESIGN.OUT type the following:
At the AOS/VS system prompt ")" type:
) adadl.pr DESIGN.TXT DESIGN.OUT <CR>
(note the <CR> means the return key)
The format is (input file) followed by the (output file).
Failure to enter both filenames will cause the ADADL processor
to ask the user for the name of the appropriate input file or
output file.
After the input and output files have been specified by the user,
the printer menu is displayed, and the user is required to select
a printer from the menu.
B.3 Printer installation
The ADADL processor is distributed with a pre-defined set of
printers, and their relevant printer parameters. The set of
printers shown in the adadl.prt file is probably a super-set of
printers that are actually available and supported at any one
particular site. This set should be modified by removing
printers from the set, or by adding new printers which are not in
the distributed set yet are available at the installation site.
The super-set of available printers for a particular installation
is provided in the text file adadl.prt. This file must be
modified to conform to the particular installation of printers
available at the installation site. The modification of the
printer table, adadl.prt should only be done by the host
computer system manager.
B.3.1 adadl.prt format
The text file adadl.prt is organized as follows:
Name_1 File_1.DAT
Name_2 File_2.DAT
Name_3 File_3.DAT
--
- Note: EXACTLY ONE SPACE between the
- two file_name specifications.
--
Name_n File_n.DAT
Each line of text contains two fields, separated by EXACTLY ONE
space. The first field Name_n, is the name of the printer, e.g.
Printronix or EpsonMX_100. The name cannot contain any spaces
(blanks). The second field File_n.DAT, is the full name
(including the logical directory name adadldir: for VMS or
/adadldir/ for Unix) of the file containing the printer data for
that printer, for example, adadldir:PRNTR.DAT or
adadldir:EPSMX.DAT for VMS or /adadldir/PRNTR.DAT for Unix. It is
recommended that any new printers that are added be given the
.DAT extension.
The file File_n.DAT contains information relative to a particular
printer, such as whether the printer supports the BACKSPACE
character, or whether it has a "built-in" capability to perform
boldface or underlining.
An example adadl.prt file for the VAX/VMS system is shown below:
Printronix adadldir:PRNTR.DAT
Versatec adadldir:VERS.DAT
Spinwriter_7720 adadldir:SP7720.DAT
Epson_MX adadldir:EPSMX.DAT
Epson_FX adadldir:EPSFX.DAT
An example adadl.prt file for the Unix system is shown below:
Printronix /adadldir/PRNTR.DAT
Versatec /adadldir/VERS.DAT
Spinwriter_7720 /adadldir/SP7720.DAT
Epson_MX /adadldir/EPSMX.DAT
Epson_FX /adadldir/EPSFX.DAT
An example adadl.prt file for the AOS/VS system is shown below:
Printronix PRNTR.DAT
Versatec VERS.DAT
Spinwriter_7720 SP7720.DAT
Epson_MX EPSMX.DAT
Epson_FX EPSFX.DAT
The first line of the adadl.prt file is used as the "default"
printer. At the start of each ADADL run, the user is shown the
list of available printers for the site. He may select the
default printer or may change the desired printer.
B.3.2 Printer Data file *.DAT
The printer data file contains information relative to a
particular printer, such as whether the printer supports the
BACKSPACE character, or whether it has a "built-in" capability to
perform boldface or underlining.
The printer data file is usually given the .DAT extension,
however this is not mandatory.
The printer data file is organized as seven lines of text as
shown below:
Line 1: Printer supports built-in boldfacing (1=yes 0=no)
Line 2: Sequence of decimal equivalent of ASCII characters to
turn on boldface. Each field separated by exactly one blank.
Line 3: Sequence of decimal equivalent of ASCII characters to
turn off boldface. Each field separated by exactly one blank.
Line 4: Printer supports built-in underlining (1=yes 0=no)
Line 5: Sequence of decimal equivalent of ASCII characters to
turn on underline. Each field separated by exactly one blank.
Line 6: Sequence of decimal equivalent of ASCII characters to
turn off underline. Each field separated by exactly one blank.
Line 7: Printer supports backspace (1=yes 0=no)
an example printer data (.DAT) file is shown below for a
fictional printer.
1
27 12 15 Note: exactly one space (blank) separates
27 11 14 98 the fields.
0
0
0
1
The above example is for a printer which supports a built-in
boldface command. The command to turn on the boldface is
described in ASCII characters as <ESC> <FF> <SI> which have the
decimal equivalent of 27 12 15 respectively. The command to turn
the boldface off is <ESC> <VT> <SO> "b" which have the decimal
equivalents of 27 11 14 98 respectively.
The printer does not support any built-in underline capability
hence line 4 contains 0 and lines 5 - 6 are irrelevant.
The printer does support a Backspace capability so line 7
contains a 1.
B.3.3 Deleting a printer from the list of available printers
To delete a printer from the list of available printers, the
line of text defining the printer name and the printer data file
must be removed from the adadl.prt file using any text editor.
B.3.4 Changing the "default" printer
The first entry (line 1) of the adadl.prt file defines the
"default" printer name and the "default" printer data file
(xxx.DAT). Any printer may be made to be the "default" printer by
editing file adadl.prt and placing the desired printer name and
data file as the first line of adadl.prt .
B.3.5 Adding a new printer to the system
To add an additional printer to the list of available printers,
the adadl.prt file must be modified, and a new file defining the
printer parameters must be created.
The adadl.prt file must be modified to define both the name of
the additional printer and the name of the printer data file for
the additional printer (adadldir:SOMETHING.DAT) The adadl.prt
file is modified by adding one line of text for each additional
printer.
The line of text added to adadl.prt contains the printer name,
e.g. Dataproducts_135 and the printer data filename , e.g.
adadldir:DATAPRD.DAT. As described in Section B.3.1. Any text
editor can be used to add the line of text required.
For each printer added, one new file defining the printer
parameters, such as whether the printer supports the BACKSPACE
character, or whether it has a "built-in" capability to perform
boldface or underlining must be added to the system. The format
for the printer data file is described in Section B.3.2.
The file specification of each .DAT file must start with
adadldir:for VAX/VMS or /adadldir/ for Unix systems or ??? for
Data General MV series AOS/VS systems.
B.4 Installing the HELP File
The ADADL distribution tape contains a file labelled adadl.hlp
which is a "Help" file to be installed on any operating systems
which support the help capability.
The adadl.hlp file may be installed on the VAX/VMS system as
follows:
LIBRARY/HELP/REPLACE library-file-spec adadl.hlp
where library-file-spec is the file specification of the HELP
library file on the host VAX/VMS computer.
.pn 1
.fo References page R - #
References
[1] Radi, Thomas S., "The Disciplined Software Development
Approach (DSD)", M-6-370-TR-058, General Dynamics Pomona
Division, November 1984.
[2] McCabe, Thomas J.,"A Complexity Measure",IEEE Trans. Software
Engineering, December 1976, pp 320.308-
Click on FTP to download from the FTP archives.