QQg^ [?*#,:*_
.At** aM>jfc I "^
UNITED STATES ENVIRONMENTAL PROTECTION AGENO
Research Triangle Park, NC 27711
January 30, 1986
OFFICE OF
ADMINISTRATION
AND RESOURCES
MANAGEMENT
MEMORANDUM -
SUBJECT: Logical Data Base Design Review of the
-;.. - AIRS Stationary Source Emissions Inventory System (AIRS-SSEIS)
FROM: James L. Obenschain, Jr.
Central Data. Base Administator, ADP-OMB, NDPD (MD-34)
TO: Charles L. Marks, Data Administrator
Programs Systems Division, OIRM (PM-218B)
This memorandum will be your official notification of the CDBA Logical
of tne ^IRS Stationary Source, Emissions Inventory""
._-_-
System IAIRS-SSEIS) ADABAS applicati'on.
Attached you will find John Yodsnukis's review of the AIRS-SSEIS .
Logical Data Base Design. I agree with his recommendations on this system and
recommend to you that this L-Ogj.231 Desij?" be accepted for the PROTOTYPE testing
only. All missing and required information must be supplied before this -appli-
cation can be consided for PRODUCTION. I understand this is only a prototype
application, and it will more than likely change during the prototyping.
If you have any questions, please call me at {FTSJ629-2693.
Attachment .
cc: Maureen Johnson
Jim Smith
John Yodsnukis
Sam Colon-Velez
Chris Mason ^
Dave Schnell
Charles Isbell
U.S. Environnental Protection Agency
T-~-^-. Room 2404 PM-211-A
401. >.( Street, S.W.
Washington, DC 20460 .......!-.:-,iV'
-------
•"= -,
:?** : •«
January 21, 1986
To: Jim Smith
From: John M. Yodsnukis
Subject: Stationary Source Emissions Inventory System Logical Design
Copies: Jim Obenschain
This memo is a review of documents prepared by TRC Environmental
Consultants, Incorporated, received January 3, 1986. These documents
include Data Dictionary, reports of file descriptions, a technical ..-.>; '.:... ,.'Sf^^:'
manual dated July 1, 1984 and a letter dated December .20; 1985. " . :;_,... ''*•%?
Collectively these should contain all information necessary for a _ :-. • '•";?.
logical data base design. . . ~v . _ ^
The following is a point by point compliance test of the SSEIS Logical .
JData Base design as defined in the ADABAS Application Development,
Procedures Manual in effect at the time of its draft.
3.2.1 Logical Design Review
o Logical data base design
- Best Estimate of data storage requirements (records counts and
occurrences; repeated in Physical Design).
REVIEWER NOTE: Provided and acceptable.
- Description of each logical record, including a list of all
data items in the logical record and for each data item the
information specified in Appendix B.
REVIEWER NOTE: Provided but incorrect. The logical record definitions
are in fact physical record definitions. Normalization
has not been completed. For example there are occurring
fields defined in the logical record of the DEQ-SEI-
PLANT, DEQ-SEI-STACK and DEQ-SEI-POINT files that are in
fact logical files in themselves. Also there is no
mention of the many tables needed in the application.
- Relationships between logical records, including the data
items(s) on which they are logically related.
REVIEWER NOTE: Provided but incorrect. The logical data base diagram
is incompletely normalized, therefore several relation*
-------
ships are missing.
- General description of access types and estimates of
transaction frequency and volume.
REVIEWER NOTE: Provided and acceptable for the user requirements cur-
rently defined.
o Optional diagram of logical files and relationships between them.
REVIEWER NOTE: Provided but incorrect. See above notes about logical
record definitions.
o Description of all functional units related to ADABAS;
REVIEWER NOTE: Provided and acceptable.
o Data base backup", recovery and restart requirements
REVIEWER NOTE: Not Provided. Normal ADABAS backup and recovery
procedures are assumed for online update. No batch
update is indicated.
o Performance requirements
REVIEWER NOTE: Not Provided. Normal turnaround assumed.
o Security requirements
REVIEWER NOTE: Not provided. If exceptional security requirements
exist, they must be supplied soon.
o Planned development schedule
REVIEWER NOTE: Not provided.
Logical Data Base Design Evaluaton Criteria
o Does the design adhere to established Agency standards?
REVIEWER NOTE:. No. Agency naming conventions must be implemented
before installation in the production environment.
o What is.'the potential for using common data tables?
REVIEWER NOTE: Unknown to this reviewer. Data Administrator is
responsible for this evaluation. Data tables are not
mentioned in the design documents.
o What other data items could potentially be shared by other
systems?
REVIEWER NOTE: Unknown to this reviewer. Data Administrator is
responsible for this evaluation.
-------
o If this structure is planned to eventually link to other data
structures, have the interfaces been planned for the maximum
extent possible?
REVIEWER NOTE: Unknown to this reviewer. Data Administrator is
responsible for this evaluation.
o What are the security requirements?
REVIEWER NOTE: Probably simple Read-only and Canned-update users.
o Who are the users?
. REVIEWER NOTE: Although it is not stated, the initial users will be
'- .. _;, prototype testers. After prototyping the users are
- - '-.'--' yet to be defined.
o Where are the users located?
REVIEWER NOTE: Not found in the documents.
o Are there other potential users of this data whose needs have not
been considered in this design?
REVIEWER NOTE: Unknown to this reviewer. Data Administrator is
responsible for.this evaluation.
o What type(s) of data base access will the users be provided?
REVIEWER NOTE: It appears that interactive online query and canned
batch reporting will be provided.
o What is the anticipated mix between batch and online processing?
REVIEWER NOTE: Not found in the documents.
0 What are the anticipated transaction volumes and frequencies?
REVIEWER NOTE: Without knowing who the users are the developers have
provided a projected relative model of this data. This
model shows expected frequencies between transactions,
but gives no indication of volume of transactions.
o What are the minimum performance requirements?
REVIEWER NOTE: Not found in documents. Normal online and batch
transaction turnarounds assumed.
o Does ODP have sufficient resources to support the functional
requirements?
REVIEWER NOTE: Unknown as much information Is undefined at this time.
-------
Recommendation
It is this reviewer's recommendation that the missing information be
supplied by the developer if prototype testing proves successful and
system development is to continue. .At that time, the missing informa-
tion should be available to the developers as the users and their
requirements should be firmly defined by then. If the missing data is
provided with the same spirit of cooperation as the data supplied until
now, it is expected that the Logical Design and the following Physical
Design and Program Test and Acceptance reviews will find an acceptable
and possibly exceptional ADABAS application. Looking ahead to Physical
Data Base Design and Program Test and Acceptance, there will be many
changes necessary to make the current prototype system acceptable under
current agency physical file definition and performance guidelines.
The developers;appear to be very willing to accept these" changes at •-"
that time .as-it".will lead to a better application for everyone. ';. ^f
, . ,.'::-.r.-,:..~7. "4iM-
-------
; ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
INTRODUCTION
All software development for SDS, National Air Data Branch, will be
developed in two distinct phases: Design and Programming. In both of
these phases, SDS will require the contractor to develop specific products.
In the Design Phase, which must be completed first, the contractor will
'develop system and program specifications from which the actual program-
ming will then be directed. In each phase, the required products are
hierarchical—that is, each product must be developed in the order shown
herein. As each product is developed, it must be submitted to SDS for
approval. After SDS approves each product, that item will become a per-
manent part of the software development documentation package; many of
these products may be used intact as parts of the final system documenta-
tion.
The Design Phase, its required products, and their associated elements
will be discussed in the following paragraphs. The Programming Phase will
be similarly explained in Section 4.4.2 of Volume IV.
DESIGN PHASE PRODUCTS
Four distinct items are required as Design Phase products:
1. System Requirements Statement.
2. Detailed Functional Statements.
3. System Specifications.
4. Detailed Program Specifications.
4.4.1-1
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
2
Since these items are hierarchical, each must be totally developed, sub-
mitted, and approved by SDS before the contractor begins his effort on
the next item. The contractor must submit the items in the order shown.
Within each item, there are specific elements (described in the
following paragraph) required by SDS. Although there is some overlap of
elements between items, each item must be considered separately.
Some of the required elements are not appropriate for Structured
Programming. If the contractor wishes to use Structured Programming
design techniques, he must obtain SDS Project Officer approval before he
substitutes any other element for any element required by this document.
In many cases, the Design Phase will include design of manual
processes integral to the computerized system. In such cases, the
contractor will identify the required manual processes and will prepare
the instruction for the appropriate AEROS Manuals.
The following paragraphs describe the required Design Phase items
and their elements:"
System Requirements Statement.
Detailed Functional Statements.
System Specifications.
Detailed Program Specifications.
4.4.1-2
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION systems Development
Section
CHAPTER standards
SUBJECT Software Design
Standards
SECTION CHA
4 4
DATE
12/20/78
Update IV-2
PTER SUBJECT
1
PAGE
3
A Submittal Cover Sheet (4.4.1. ) must accompany all material submitted to
SDS, NADB. Each item should be submitted in draft form for SDS review and
comments before it is submitted for final approval.
SYSTEM REQUIREMENTS STATEMENT
The System Requirements Statement, which describes in general terms
what a system is required to do, is composed of two parts: System Objec-
tives and System Functions.
A. System Objectives
This first part of the System Requirements Statement can be limited
to one paragraph. The paragraph should describe in general terms what the
system will accomplish once it becomes operational. This description may
list the mechanical or organizational needs, in order, to be satisfied by
the system. This is a sample System Objectives paragraph:
"A system is required to edit incoming transactions, to
produce a list of error diagnostics of data failing edit,
and to update a raw data file with those transactions
passing edit."
B. System Functions
Following the system objectives statement should be a vertical,
numbered list of system functions which specifically change data or infor-
mation from one state (or medium) to another. The general system functions
can usually be described by brief imperative statements beginning with such
4.4.1-3
-------
if,
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NAOB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
4
action words as "prepare, provide, create, update, collect, report, re-
trieve." All of these general systems functions will most probably be
included in the list of functions in the Detailed Functional Statements,
the next item required in the Design Phase. During the Design Phase,;
the contractor may find that system functions will have to be updated.
Whenever this happens, he must resubmit the updated list for approval by
SDS.
DETAILED FUNCTIONAL STATEMENTS
Before the contractor can use system requirements to guide his
system design, he must describe in detail each function defined in the
System Requirements Statement—explaining all data elements, processes,
restrictions, and anticipated data volumes. Regardless of the function-
al technique to be used, each function can be described in such detail.
The format required to describe each function is exhibited on page
4.4.1-5. Each functional statement must be submitted on this form, with
only one detailed functional statement on each form. Following is an
explanation of each of the items on the form.
Function Name. This title identifies the function described on
-^^^~ • * i ^i^^^— «
this form.
1. Trigger. Describes the event which causes this function to
begin its execution. The trigger may be preceding function(s),
manual initiation, scheduled operation cycle, or an unscheduled/
occasional transaction. Include here the estimated timeframe
(if possible) for function execution.
4.4.1-4
-------
'••-> ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE PAGE
12/20/78 5
Update IV-2
FUNCTION HAM?:
1. TRISGr?:
2. KESTRIOTIOSIS :
1. TJATA ELEMENTS:
MTA ELEMENT NAVIES
INPUTS
INTERVALS
OUTPUTS
—
4. PROCESSES:
5.VOLUKE CAPACITY:
Figure 4.4.1-a - Detailed Function Statement
4.4.1-5
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER St&ndards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
6.
2. Restrictions. List here all limitations or restraints—time,
policy, cost, equipment, or other—which must be considered to
develop,' initiate, or execute this function.
3. Data Elements. Include in this matrix all data elements associa-
ted with this function—either as input to, transformed or devel-
oped by, or output from the function. First, start with a list
of all output elements required from this function. Then, identi-
fy a source for each output data element—either input to or in-
ternally developed by this function. Show all data elements used
by this function.
4- Processes. List the major steps required of this function to
change functional inputs to functional outputs. These processes,
described by action words, show all the transformations performed
by this function. These ordered steps will form the basis to pre-
pare a general flowchart of the function.
5- Volume Capacity. Estimate the volume of data to be processed by
this function each time it is performed. Approximate the volume
in number of records, documents, or tables.
SYSTEM SPECIFICATION
Before he develops Detailed Program Specifications, the contractor
must develop System Specifications to ensure that the programs do indeed
properly translate the system requirements and do perform correctly the
required system functions. The System Specifications will directly relate
4.4.1-6
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGI
7
the system functions to specific programs, files, and reports that need to
be developed. The System Specifications must be submitted to and approved
by SDS before the contractor can develop Detailed Program Specifications.
Five elements are included in the System Specification:
1. System Flow. A system-level flowchart which illustrates each of
the programs, files, and reports required of the system.
2. System Description. A narrative explanation of system operation,
describing how the System performs each of the System Functions
included in the Detailed Functional Statements. The System
Description will narrate in chronological order how the System
programs will interact to accept, transform, and/or generate the
required files and reports.
3. Program Abstract. A Program Abstract is required for each pro-
gram included in the System. The format for the Program Abstract
is defined in the AEROS Documentation Standards.
4. AEROS File Description. An AEROS File Description Form is re-
quired for all new permanent files (tape, disk, or cards). The
format for the AEROS File Description is defined in the AEROS
Documentation Standards. If no new files are being developed
by the system, copies of required existing files must be included
with the System Specification. Such copies must be submitted in
the current AEROS Documentation Standards format for File De-
scriptions.
4.4.1-7
-------
ff
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT software Design
Standards
SECTION CHA
4 4
DATE
13/20/78
Update IV-2
PTEH SUBJECT
1
PAGE
8
5. System Output Formats. Illustrate the exact format for all printed
output produced as a function of the system. Use a simulated com-
puter-produced sample printout or a printer spacing chart.
All or parts of the preceding five elements are also required in the
Detailed Program Specifications. As required, the appropriate elements
should be duplicated and submitted with the Detailed Program Specifications.
DETAILED PROGRAM SPECIFICATIONS
Detailed Program Specifications describe the detailed input, logic,
and output of each program included in the System Specifications.
The Detailed Program Specifications for each program will include the
following elements. Each of these elements will begin a new page, identi-
fied as required in the Standards Introduction.
1. System or Sub-system Flowchart. This flowchart depicts the system
or that part of the system to which this program belongs. Show
herein all files and reports which are inputs or outputs for this
program.
2. AEROS File Description. Complete an AEROS File Description Form
for each new or old file shown in element #1, preceding. (Refer
to element #4 of the System Specification.)
3. Printed Output Formats. Illustrate the exact format on all printed
output produced by this program; use a simulated computer-produced
4.4.1-8
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL. AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
9
sample printout or a printout layout form (printer spacing chart).
Include with this element a table showing all sort and selection
options and an exact list of all programmed error messages with a
description of what conditions will produce each (may be included
as part of element 8-Detailed Test Conditions.)
4. AEROS Abstract. For this program only, prepare a Program Abstract
in the format defined in the AEROS Documentation Standards.
5. Detailed Program Narrative. Prepare a Detailed Program Narrative
which describes in detail the logic of this program. Include suf-
ficient definition to specifically identify all input and output
processes (Specific "MOVE" statements need not be detailed.); all
logical decisions and all decision paths; and all generation and
maintenance of all data elements. Include a separate section to
describe any special programming techniques to be used in this
program.
6. Calculations. Except for "N=N+l"-type counters, identify in de-
tail all formulas used in and associated with this program.
Define all such formulas with algebraic notation, standard symbols
where possible. Explain in detail and with examples any devia-
tions from standard notation or any use of non-standard symbols.
7. Detailed Program Flowchart. For each program, prepare a Detailed
Flowchart showing the same detail described in the Detailed Pro-
gram Narrative. Use flowchart symbols which conform to the
4.4.1-9.
-------
y '•• ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION CHA
4 4
DATE
12/20/78
Update IV-2
PTER SUBJECT
\ 1
PAGE
10
International Organization for Standardization (IOS) Recommenda-
tion on Flowchart Symbols for Information Processing; or use
symbols consistent with those adopted by the American National
Standards Institute, Inc. (ANSI).
8. General Test Conditions Table. Using the Detailed Flowchart
and Detailed Program Narrative, design a table which illus-
trates all of the general conditions to be tested during the
testing of this program. Indicate in the table the condition
to be tested, the presentation and format of the test data,
and the decision paths to be followed by this program. Although
it is not usually feasible to test every program option and
decision path, the contractor should include in the General
Test Conditions a list of the most critical and/or the most
frequent decision oath-;.
The format of the General Test Conditions Table will be
as follows:
4.4.1-10
-------
SECTIONSystems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION
4
CHAPTER
4
DATE
12/20/78
Update IV-2
SUBJECT
1
PAGE
11
Table 4.4.1.a - General Test Conditions
Table: Test Conditions
Start
End of Detail
End of Master
Detail vs. Master
Detail is an "Addition"
Rule
01 02 03 04
Y N N N
Y Y N
Y N Y
Y
Number
05 06
N N
N N
N N
Y
07 08
N Else
N
N
Do Error Routine
Move Master to New Master
Move Detail to New Master
Set Addition Switch
Write Master
Read Master
Read Detail
X
On
X
X X
X X
X
On
X
X
X
X
X
Off
etc.
4.4.1-11
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
SUBMITTAL COVER SHEET
The contractor must attach a Submittal Cover Sheet (as shown on the
following page) as the first page of any Design Phase material submitted
to NADB. He must submit each item first in draft form for review and com-
ments before he submits it for final approval. Although any material he
submits for review may be circulated to other NADB personnel for comments,
he must obtain final approval for each item by all of the following:
SDS Project Officer or Project Leader
RIS Systems Manager
Chief, Data Processing Section
Chief, Systems Development Section
To minimize the time for review and final approval, the contractor
should submit each item as soon as it is prepared; and each approving
official should complete his review and approval as promptly as possible.
The Submittal Cover Sheet, a copy of which is attached is in memo-
randum format, addressed to the NADB Project Officer from the contractor's
Lead Systems Analyst for the project. Enter the contract number, task
number, and title of the project or system in the appropriate spaces
under "SUBJECT." Place a check mark in the left margin alongside the
item(s) submitted, and indicate under "VERSION" how many times the item
has been submitted: "1" for the original Submittal, "2" for the second
submittal, and so forth. Indicate with a check mark in the "REVIEW" of
the "APPROVAL" column whether or not the material is being submitted for
review or final approval. When items which have already been approved
4.4.1-12
-------
1
"Jk
•* ••.
ENVIRONMENTAL
PROTECTION AGENCY
/ NATIONAL AIR
] DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
* 1
PAGE
13
are resubmitted as background material with other Items being submitted
for review or approval, place an "F" (Final Version) in the "Version"
column opposite such items. (For such previously-approved, resubmitted
items, the contractor may add the approval date in the "Approval" column
opposite the item, if he wishes.)
An example Submittal Cover Sheet follows for these conditions.
The contractor is submitting the System Description for the second time;
he is also submitting, as background for the System Description, the
previously-approved System Flow, Requirements Statement, and Detailed
Functional. Statements.
EXAMPLE
Name Version
1. Requirements Statement F
2. Detailed Functional Statement F
3. System Specifications
a. System Flow F
b. System Description 2
c. Program Narratives
d. AEROS File Description(s)
e. System Output Formats
\. Detailed Program Spcifications
a. System or Subsystem Flowchart
4.4.1-13
.
-------
? ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE
12/20/78
Update IV-2
PAGE
14
b. AEROS File Descriptions
c. Printed Output Formats
d. AEROS Abstract
e. Detailed Program Narrative
f. Calculations
g. Detailed Program Flowchart
h. General Test Conditions Table
Each item'or element submitted under the Submittal Cover Sheet will
start on a new page. Number this page "1 of pages," and continue page
accounting through the pages for this item or element. Further identify
each page with the item/element name and the version number in the upper
left-hand corner; put the date and pagination in the upper right-hand
corner. (For example, an item name could be "Requirements Statement," an
item/element, "System Specification - Sytem Flow.")
4.4.1-14
-------
• ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Software Design
Standards
SECTION
4
CHAPTER
4
SUBJECT
1
DATE PAGE
12/20/78 15
Update IV-2
TO: See Routing List
FROM:
SUBJECT: Contract Number _
Task Number _
Program or System ID _
The following Items are attached for your approval:
1.
_2.
Name
Requi rements Statement1
Detailed Functional Statement
System Specifications
Version
Routine List:
I. SDS Project Officer
ACTION (NADB USE ONLY)
Reviewed
123
a. System Flow
b. System Description
c. Program Narrative
d. AEROS File Descriptions)
e. System Output Formats
Detailed Program Specifications
a. System or Subsystem Flowchart
b. AEROS File Descriptions
c. Printed Output Formats
d. AEROS Abstract
e. Detailed Program Narrative
f. Calculations
g. Detailed Program Flowchart
h. General Test Conditions Table
•
•
•
2 3 4
Initials
Date
2. RIS System Manager
3. Chief. Data Processing Section
4. Chief,. Systems Development Sec.
5. Return to SDS Project Officer
Note: Please indicate your review (attach comments) or ap'proval under the
column identified with your routing list number.
Figure 4.4.1.b
Software Design Submittal Sheet
4.4.1-15
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT Software Design
Standards
SECTION CHA
4 i
DATE
9/30/81
Update IV-7
PTER SUBJECT
I 1
PAGE
16
System Walkthrough
During the Design Phase of Software Development, there should be at least one
System Walkthrough meeting involving SDS, DPS, RIS, and contractor personnel. The
placement of this meeting within the design sequence will be determined by the
appropriate systems analyst and Chief, DPS. This meeting should appear on the
milestone chart.
The System Walkthrough meeting will be conducted as follows:
1. The systems analyst, systems manager, or the contractor using appropriate
visual aids and handouts will explain the purpose of the software and
will describe the details of the processing to be involved.
2. One person other than the person making the presentation will take
notes on comments.
3. Each person, in turn, will be given an opportunity to make comments
concerning the systems processing. If a person chooses to make a
comment, there must first be a positive observation regarding the
system and then any criticism. Except for clarification, NO response
is permitted to a criticism or suggestion. Each suggestion noted,
if necessary, can be followed up after the meeting with the individual.
4. After the meeting, the SDS System Analyst is responsible for
incorporating appropriate suggestions.
4.4.1-16
-------
Page 3
TECHNICAL NOTE NO. 1
EPA/AIRS MEETING - DURHAM, N.C,
January 16, 1986
Preliminary options of ADABAS file designs for AIRS:
Option I Each State has their own files residing on the same ADABAS
data base.
E.g. 5 files x 50 States - 250 files (Today with SSEIS)
15 files x 20 States = 300 files (Potential)*
'..* ADABAS allows up to 255 logical files. This solution may
not fit into ADABAS depending upon the numbers of.files per
State and states participating.
'/Option II Each State shares the files containing common information.
State rquirements for other data are met through separate
logical files unique to that state. Analysis would be
performed to identify and logically group data elements common
to all states.
E.g. 20 shared files
235 remaining for individual use by states
This scenario allows for additional State/Federal files to be added at a
later date.
Option III Each, State has its own computer, ADABAS/Natural Software,
files and applications software. Data is identified as needed
by the Federal EPA (Core System) or by the State. Data is
batched to the Federal EPA for compilation into the Federal
System.
Requires duplicate copies of data and source programs, all of
which must be kept in sync. Federal system would be updated
in batch. All participating States would need similar
hardware/software/file setups for the core system.
Note: EPA, NCC, DBA, and TRC agree that the system configuration
should not be decided upon until later in the analysis/design
process.
-------
. t
- ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NAOB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
DATE
7/5/77
CHAPTER
4
SUBJECT
3
PAGE
INTRODUCTION
To provide information for the execution and maintenance of all
AEROS Software, Documentation Standards have been developed and are'
described on the following pages. These documentation standards discuss
four levels of documentation defined as follows:
Documentation Level
Definition
1. Subprogram
2. Program
3. Procedure
4. System
Concerns a block of code that is
invoked only by an explicit call
from another program.
Concerns a block of code that is
invoked from Executive Control
Language (ECL) by an 6XQT state-
ment. (The ECL associated with a
single program is called a run-
stream and is documented with the
program level documentation.)
Concerns a block of Executive Con-
trol Language statements that invokes
the execution of two or more pro-
grams.
Concerns a group of closely related
procedures or programs which, while
not invoked within the same runstream,
are closely related and usually pro-
vide a common audit trail.
All elements (subprograms, programs, runstreams and procedures)
are named with a standard alphabetic prefix followed by a 3-digit number.
4.4.3-1
-------
Ls, ENVIRONMENTAL
•? "PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
4 3
PAGE
2
The alphabetic prefix identifies the type of element as well as the sys-
tem in which the element resides. All subprograms have 3-letter prefixes
where the third letter is not R; programs have 2-letter prefixes; run-
streams have 3-letter prefixes with the third letter being R, and proce-
dures have 4-letter prefixes. The standard prefixes are shown in the
figure below. The element name may optionally be followed by a letter to
distinguish closely related elements (e.g., NA252A and NA252B).
System
Subprogram
Program
Runstream
Procedure
AEROS
SAROAD
NEDS
SOTDAT
HATREMS
SIPS
AE*###
NA*###
NE*###
S0*###
HA*###
SI*###
AE###
NA###
NEW
S0###
HA###
SI###
AER###
NAR###
NER###
SOR###
HAR###
SIR###
AERO###
NADB###
NEDS###
SOTDW
HATR##f
SIPSf##
Standard name formats
### indicates a 3-digit number
* indicates a letter other than R
The first two letters of subprogram names are the two letters appro-
priate to the system (e.g., AE, NA, etc.). The next letter is simply a
sequence character to distinguish subprograms. The third letter cannot
be R.
If the subprogram is used by a single program, .it has the same 3-
digit number as the program (e.g., NA034 calls NAA034 and NAB034). If
the subprogram is general purpose, it is numbered 000.
4.4.3-2
-------
ENVIRONMENTAL
v ' PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPE RATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
4 3
PAGE
3
Programs have a 2-letter prefix appropriate to the system and a 3-
digit number. The number identifies the program and gives a general idea
of its purpose: 001 through 025 are general programs; 026 through 199 do
maintenance; 200 through 999 generate reports. A runstream associated
with a program has the same prefix and number as the program but with an
R between the prefix and the number. For example, the runstream for
NA034 is NAR034.
All AEROS documentation will be typed on 8-1/2 x 11-inch bond in
the AEROS Documentation page format (see 4.4.3-9). Blank AEROS Docu-
mentation pages are available from the SDS librarian. Changes to exist-
ing documentation will be made by retyping the necessary portions of
existing documentation to ensure good quality. "Cutting and pasting"
will not be allowed and only the typed originals will be maintained in
the NADB library. In the following sections good quality reproduction
may be submitted subject to the approval of the SDS Systems Analyst:
Maintenance Log Section, AEROS File Descritions, ECL listings and Out-
put Examples.
When submitting documentation for review or approval, a submittal
cover sheet should accompany the documentation prepared in the same way
as the Software Design Submittal Sheet (see 4.4.1-12). A copy of.the
Documentation Submittal Sheet can be found on page 4.4.3-8a.
The following outlines show the organization of the four levels
of documentation and page 4.4.3-8 summarizes these sections and locates
within this chapter where each section is discussed.
4.4.3-3
-------
> ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION
CHAPTER
SUBJECT
Systems Development
Section
Standards
Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
* 3
PAGE
4
Subprogram Documentation
Section
*2.
*3.
*4.
5.
6.
7.
8.
Abstract
System Charts
System Flowchart
Hierarchy Chart
Call Statement Description
Call Statement Format
Argument Descriptions
Options
Error Messages
Environment
Files Accessed Table
Region Size
Timing Estimates
Detailed Subprogram Description
Subprogram Narrative
Subprogram Flowchart
I/O descriptions
Test Descriptions
Maintenance Log
*Distributed to DPS and RO's.
4.4.3-4
-------
ENVIRONMENTAL
'*' PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE
PAGE
12/20/78 5
Update IV-2
Section
*2.
*3.
*4.
*5.
6.
7.
8.
9.
Program Documentation
Abstract
System Charts
System Flowchart
Hierarchy Chart
Control Statements
Execution Deck
User Supplied ECL
Cataloged ECL
Restart Deck (optional)
Operating Instructions
Options
Error Messages
Audit Trail
User Warnings
Environment
Files Accessed Table
Region Size
Timing Estimates
Detailed Program Description
Program Narrative
Program Flowchart
I/O Descriptions
Test Descriptions
Maintenance Log
*Distributed to DPS and RO's.
4.4.3-5
-------
ENVIRONMENTAL
t>J PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER SUBJECT
4 3
DATE PAGE
12/20/78 ,
0
Update IV-2
Section
*2.
*3.
*4.
6.
7.
Procedure Documentation
Abstract
System Charts
System Flowchart
Hierarchy Chart
Control Statements
Execution Deck
User Supplied ECL
Cataloged ECL
Restart Deck (optional)
Operating Instructions
Options
Error Messages
Audit Trail
User Warnings
Environment
Region Size
Timing Estimates
Test Descriptions
Maintenance Log
*Distributed to DPS and RO's
4.4.3-6
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE
PAGE
12/20/78 1
Update IV-2
INTRODUCTION
To provide information for the execution and maintenance of all
AEROS Software, Documentation Standards have been developed and are
described on the following pages. These documentation standards discuss
four levels of documentation defined as follows:
Documentation Level
Definition
1. Subprogram
2. Program
3. Procedure
4. System
Concerns a block of code that is
invoked only by an explicit call
from another program.
Concerns a block of code that is
invoked from Executive Control
Language (ECL) by an @XQT state-
ment. (The ECL associated with a
single program is called a run-
stream and is documented with the
program level documentation.)
Concerns a block of Executive Con-
trol Language statements that invokes
the execution of two or more pro-
grams .
Concerns a group of closely related
procedures or programs which, while
not invoked within the same runstream,
are closely related and usually pro-
vide a common audit trail.
All elements (subprograms, programs, runstreams and procedures)
are named with a standard alphabetic prefix followed by a 3-digit number.
4.4.3-1
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE
12/20/78
Update IV-2
PAGE
Section
*1.
*2.
*3.
*4.
5.
System Documentation
Abstract
System Charts
System Flowchart
Hierarchy Chart
Component Abstracts
Detailed System Description
Detailed System Narrative
System Audit Trail
Maintenance Log
*Distributed to DPS and RO's
4.4.3-7
-------
•, ENVIRONMENTAL
'* PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4 A
DATE
12/20/78
Update IV-2
PTER SUBJECT
t • 3 .
PAGE
8
Table 4.4,3.a
Summary Table
Abstract
System Charts
Control Statements
Call Statement Description
Component Abstracts
Operating Instructions
Environment
Detailed Subprogram Description 5
Detailed Program Description
Detailed System Description
I/O Descriptions
Test Descriptions
Maintenance Log
Sub-
gram
1*
2*
3*
4*
i 5
6
7
8
Program
1*
2*
3*
4*
5*
6
7
8
9
Pro-
cedure
1*
2*
3*
4*
5*
6
7
System Page
1* 4.4.3-10
2* 4.4.3-11
4.4.3-14
4.4.3-17
3* 4.4.3-19
4.4.3-20
4.4.3-22
4.4.3-24
4.4.-3-2B
4* 4.4.3-26
4.4.3-27
4.4.3-30
5 4.4.3-31
*Distributed to DPS and RO's.
4.4.3-8
-------
SECTIONSystems Development
Section
CHAPTER Standards
SUBJECT Documentation
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADS INTERNAL
OPE RATIONS MANUAL
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 8a
Update IV-2
TO: See Routing List
FROM:
SUBJECT: Contract Number _
Task Number _
Program or System ID _
The following items are attached for your approval:
ACTION
(NADB USE ONLY)
Name
Version
5.
6.
_9. Maintenance Log
Abs tract
System Charts
a. System Flowchart
b. Hierarchy Chart
Control Statements
a. Execution Deck
b. Cataloged ECL '
Operating Instructions
a. Options
b. Sample Output
Environment
a. I/O Table _
b. Region Size
Detailed Program Description
a. Program Narrative.
b. Program Flowchart
c. Calculations
I/O Descriptions .
a. AEROS File Descriptors I I
b. Sample Output I [
Test Description-
a.
b.
General Test Conditions
Test Plan
Initials
Date
Routing List:
T7SDS Project Officer
2. RIS System Manager
3. Chief, Data Processing Section
4. Chief, Systems Development Sec.
5. Return to SDS Project Officer
Note: Please indicate your review (attach comments) or approval under the
column identified with your routing 11st number.
Figure 4.4.3.a Documentation Submittal Sheet
4.4.3-8a
-------
.'-.? ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NAOB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHAPTER SUBJECT
443
DATE PAGE
12/20/78 9
Update IV-2
\EROS SOFTWARE
DOCUMENTATION
COMPONENT NAME:
SECTION:
SECTION_
DATE
PAGE
Figure 4.4.3.b
AEROS Software Documentation Header
4.4.3-9
-------
, ENVIRONMENTAL
* PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
* 3
PAGE
10
ABSTRACT
For each level of documentation (System, Procedure, Program or
Subprogram) an abstract will be written. The Abstract will contain the
following two items:
1. Descriptive Name of Component. This name or title will be a
one-line description of the component (e.g., SAROAD Raw
Data Update Program or Post-Editor Inventory Report Program).
This Descriptive Name will be decided upon by the SDS Sys-
tems Analyst.
2. Run Description. This should be a brief narrative of the
component describing what it does. The relationships and
purposes of all the input and output shown in the System
Flowchart should be addressed.
4.4.3-10
-------
' / ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION S>
Se
CHAPTER St
Do
SUBJECT
Section
Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE
PAGE
12/20/78
Update IV-2
SYSTEM CHART
There are two items required in the System Charts section:
1. System Flowchart. The system flowchart should be one or a
series of flowcharts defining how the component fits into
a program (for subprograms) or a runstream. The flowchart(s)
should show the relationships of files and programs in the
runstreams as well as the order of program execution in a
runstream. The program name and brief description should be
shown in rectangular boxes. Symbols for the files should
be representative of the actual storage media. All files
used should be shown including temporary work files. Brief
descriptions of the files should be entered in the symbol
such as: sorted point source subfile. If permanent files
are referenced, the file name should be entered. Both in-
ternal and external names for files should be shown (where
possible, the external and internal file names should be
identical).
For System Flowcharts in System level documentation,
decision blocks should be shown which indicate the flow of
the System under specific conditions.
2. Hierarchy Charts. The Hierarchy Chart is a pictorial repre-
sentation of the relationship between the component (System,
4.4.3-11
-------
' , ENVIRONMENTAL
~ PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4 4
DATE
12/20/78
Update IV-2
PTER SUBJECT
3
PAGE
12
Procedure, Program or Subprogram) and other component levels.
The Hierarchy Chart should show the names of all components
one level above and below the component being documented.
The format of the hierarchy chart should be as follows
based on the level being documented and appear on a separate
page within the System Charts Section:
System
Procedure
Program
i System
! Name
Program Procedure Program
Name Name Name
System
Name
System Procedure
Name Name
Procedure
Name
Program Program
Name Name
Program
Name
Subprogram
Name
Subprogram
Program
Name
Program
Name
Subprogram
Name
The name of the component being documented should appear in a
box with the other component names being shown as appropriate.
4.4.3-12
-------
• ENVIRONMENTAL
PROTtCTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 13
Update IV-2
Where more than one runstream calls exclusively the same pro-
gram (i.e., no other programs are in the runstream), the hierarchy
chart must be expanded to show all the runstreams above the program
and also any Procedures or Systems using the various runstreams.
For example,
NADB034/U-GT
NADB034/U-CD NADB034/U-HD
NAR034/U-GT
:
/
NAR034/U-CD NAR034/U-HD
NA034
LOGSUB
'N,
EXPSUB
Otherwise, the runstream is not shown on the hierarchy chart.
4.4.3-13
-------
'* ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
4 3
PAGE
14
CONTROL STATEMENTS
The Control Statements Section is only required for Procedures
and Programs. It contains four items as follows:
1. Execution Peck- The complete Execution Deck should be
shown. The Run Card and Password Card with their line
numbers should be as follows:
1. @RUN - RUN CARD
2. (3PASSWD - PASSWORD CARD
All user supplied input should be shown in small
type. These optional items will be discussed
immediately following the Execution Deck listing
under User Supplied ECU The Execution Deck
statements should be numbered and the appropriate
number referenced in the discussion (see example
below).
2. User Supplied ECL. Following the execution deck the User
Supplied ECL should be listed. The appropriate line number
from the execution deck should be referenced and the appropri-
ate user specifications discussed.
An example of the Execution Deck and User Supplied ECL
sections is shown below.
4.4.3-14
-------
> ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3 .
DATE PAGE
12/20/78 15
Update IV-2
EXAMPLE
1. Execution Deck
1. (3RUN - RUN CARD
2. @PASSWD^- PASSWORD CARD
3. @ASG,T/W filename, 16N, tape #
4 @USE OUTFILE,filename
etc.
2. User Supplied ECL
LINE 3. Replace 'filename' with any user specified
UNIVAC file name.
LINE 3. Replace 'tape #' with any user supplied tape
number.
LINE 4. Replace 'filename' with the same 'filename1
used in LINE 3.
4.4.3-15
-------
> ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 16
Update IV-2
3> Cataloged ECL. All cataloged ECL invoked by the runstream
should be listed showing the element name of the ECL followed
by a listing of the ECL. Within procedure level documenta-
ton, if a cataloged ECL runstream invokes another cataloged
runstream, only the runstream directly invoked by the execu-
tion deck should be listed. The "secondary" ECL runstream
should be shown under the appropriate program level documenta-
tion. For example:
3. Cataloged ECL
NADB535:
@ASG,A
@COPY,S
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPERATIONS MANUAL
SECTION Systems Development
Section
CHATTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 '16a
Update IV-2
5. Control Elements
A listing of all ECL contained in the NADB*NADB-CONTROL. library
is to be included here.
4.4.3-16a
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 17
Update IV-2
CALL STATEMENT DESCRIPTION
For subprograms a CALL STATEMENT DESCRIPTION must be Included.
The format for this section Is as follows:
1. Call Statement Format. This will be a listing of the actual
Call Statement using ARG-1, ARG-2, etc., for the ARGUMENT
names. For example,
CALL NAK000 (ARG-1, AR6-2)
2. Argument Descri ption. This should be a table showing the
argument name as shown above, whether the argument is input
or output, the data item description and a verbal description
of the argument. For example,
NAME
ARG-1
ARG-2
INPUT/OUTPUT
INPUT
OUTPUT
ITEM DESC
PIC (99)
PIC (99)
DESCRIPTION
Any two digit
whole number
The square root
of ARG-1
Options. Any user options associated with the subprogram
should be discussed here.
Program Messages. The format for each message or condition
code should be discussed as follows:
4.4.3-17
-------
•-, ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Secti on
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
4 3
PAGE
18
a. List the exact message or condition code.
b. A brief explanation of what conditions cause the
message or condition code.
c. A brief explanation of remedial action the user
should take if this message is encountered.
4.4.3-18
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 19
Update IV-2
COMPONENT ABSTRACTS
For system level documentation this section would contain the
individual abstracts for programs and procedures used in the system.
.Where procedure abstracts are included, the individual abstracts for
the programs invoked fay that procedure are not required.
4.4.3-19
-------
•.. ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 20
Update IV-2
OPERATING INSTRUCTIONS
The operating instructions section is required for all Program
and Procedure level documentation. This section outlines user options
(select, sort, etc.), error messages, the audit trail associated with
the procedure or program, and user warnings. The format for this
section will be as follows:
1. Options. A discussion of the options available should be
provided so that the user can utilize the full flexibility
of the procedure or program. Associated control card formats
should be shown. Sample outputs for all reports are included
in this section.
2. Program Messages. The format for each program message should
be as follows:
a. List the exact message.
b. A brief explanation of what conditions cause the message.
c. A brief explanation of what remedial action the user should
take if the message is encountered.
3- Audit Trail. The Audit Trail should describe any statistics
or messages (except normal run termination) which can indicate
to the computer technician executing the run that the program
or procedure accomplished its task satisfactorily. Examples
4.4.3-20
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 21
Update IV-2
include count of input or output records, records selected,
and requests completed.
4. User Warnings. A list of user warnings should be listed.
Examples include the following:
a. This program or procedure must run in sequence with some
other program(s) or procedure(s).
b. File contention situations that would prevent this program
or procedure from being executed at the same time as some
other program or procedure.
c. List the consequences of an abnormal termination. For
example, what recovery steps are necessary in case of a
system "crash" during execution.
4.4.3-21
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4 *
DATE
12/20/78
Update IV-2
PTER SUBJECT
\ 3
PAGE
22
ENVIRONMENT
The Environment section is required for all subprogram, program
and procedure level documentaion. The format for the Environment sec-
tion will be as follows:
1. Table of Files Accessed. This table should include the fol-
lowing information about each file: External file name,
Internal file name, device, classification (permanent or
temporary) and whether file is input or output. For example,
Ext. Name
Int. Name
Device
Class
I/O
1.
2.
3.
4.
NADB*NADB-WD-DISK
NADB*PARMFILE
CARD READER .
SUBFILE
NOWDATA
PARMFILE
CARDIN
SUBFILE
TAPE
DISK
CARD READER
TAPE
PERM
PERM
TEMP
TEMP
INPUT/OUTPUT
INPUT
INPUT
OUTPUT
At the bottom of the table a summary of Devices used should be
given. For example, associated with the above, the summary would be
TAPES « 2
DISK = 1
2. Region Size. Number of words of storage required for execution
should be listed. This should be determined during Program
Testing by using @SETC,0 command in the test ECL. If vary-
ing amounts of core are needed (e.g., for internal sort),
estimates should be given based on volume of data.
4.4.3-22
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 23
Update IV-2
3. Timing Estimates. Based on the type of processing, selection
criteria, and the number of records processed, give SUP time
and clock time estimates for running the subprogram, program
or procedures. For example,
Type of Process inq
Update
Retrieval ONE
Selection
None
STATE/COUNTY
Records
100,000
2,500
Time
SUP(MIN)
30
10
CLOCK(HRS)
1.5
.25
4.4.3-23
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL .
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 24
Update IV-2
DETAILED SUBPROGRAM DESCRIPTION
The Detailed Subprogram Description is required for all subprogram
level documentation and consists of the following three items:
1. Subprogram Narrative. This narrative describes in detail
the logic of the subprogram. Include sufficient definition
to specifically identify all input and output processes
(specific "MOVE" statements need not be detailed), all logi-
cal decisions and decision paths, and all generation and
maintenance of all data items. Include a separate paragraph
to describe any special programming techniques used in the
subprogram.
2. Subprogram Flowchart. This flowchart should show the same
detail as the Subprogram Narrative. Use flowchart symbols
which conform to the International Organization for Standard-
ization (ISO) Recommendation on Flowchart Symbols for Informa-
tion Processing; or use symbols consistent with those adopted
by the American National Standards Institute, Inc. (ANSI).
3. Calculations. Except for "N = N + 1" - type counters, identify
in detail all formulas used in and associated with this pro-
gram. Define all such formulas with algebraic notation using
standard symbols.
4.4.3-24
-------
* ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 25
Update IV-2
DETAILED PROGRAM DESCRIPTION
The Detailed Program Description is required for all Program level
documentation and consists of the following three items:
1. Program Narrative. This narrative describes in detail the
logic of the Program. Include sufficient definition to speci-
fically identify all input and output processes (specific
"MOVE" statements need not be detailed), all logical decisions
.and decision paths, and all generation and maintenance of all
data items. Include a separate paragraph to describe any
special programming techniques used in the Program.
2. Program Flowchart. This flowchart should show the same detail
as the Program Narrative. Use flowchart symbols which conform
to the International Organization for Standardization (ISO)
Recommendation on Flowchart Sumbols for Information Process-
ing; or use symbols consistent with those adopted by the
American National Standards Institute, Inc. (ANSI).
3. Calculations. Except for "N - N + 1" - type counters, identify
in detail all formulas used in and associated wtih this pro-
gram. Define all such formulas with algebraic notation using
standard symbols.
4.4.3-25
-------
. ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4 i\
DATE
12/20/78
Update IV-2
PTER SUBJECT
\ 3
PAGE
26
DETAILED SYSTEM DESCRIPTION
The Detailed System Description is required for all system level
documentation. The format for the section will be as follows:
1. Detailed System Narrative. The detailed system narrative
should describe the total process involved in the system,
the interrelationship between the various programs, the normal
order of execution, the decisions which must be made as the
system's parts are executed and finally, all the manual pro-
cesses which are required.
2. System Audit Trail. The system audit trail section is a
specific description of the audit trail which will be given
by the system. Specific examples should be given for relating
such things as input and output totals, record counts and
error counts. When the counts given by one program should
total the counts given by another program this should be
explicitly discussed. The output formats for these counts
and summary statistics, should be illustrated and circled to
emphasize the relationships.
4.4.3-26
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADBINTERNAL
OPE RATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 27
Update IV-2
INPUT-OUTPUT DESCRIPTIONS
When submitting documentation with new files (files not previously
registered with the Software Librarian) two different AEROS File
Description and Record Layout Forms are required:
1. AEROS File Description and Record Layout for Volume III of
the AEROS Manuals (see 4.4.3-28 and 29).
2. AEROS File Description and Record Layout for the subprogram
and program level documentation (see 4.4.3-29a and 29b).
When submitting documentation with registered files only to the
AEROS File Description and Record Layout for the subprogram or program
documentation is required.
The appropriate forms will be filled out for all permanent and
temporary files associated with the subprogram or program. This includes
the following:
Control cards
Data cards
Input and output files
All output (printer) listings will be included in this section
using a standard output layout form showing the position and size of
all items included on the printed output. This includes error listings
as well as reports, audit trail outputs, and special forms and will
show all associated page breaks and summary lines.
4.4.3-27
-------
"' A ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION CHA
4
DATE
12/20/78
Update IV-2
PTER SUBJECT
4 3
PAGE
28
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME III.
AEROS SUMMARY AND
RETRIEVAL MANUAL
SECTION
CHAPTER
SUBJECT
QUALIFIER
FILE NAME
SECTION CHAPTER SUBJECT
DATE PAGE
FILE DESCRIPTION AND USE
.FILE TYPE
QSOF
O PRINT FILE
D PUNCH FILE
0
O ASCII COBOL
O SEQUENTIAL
O DIRECT
O INDEXED -SEQUENTIAL
D FORTRAN
Q FORMATTED
O UNFORMATTED
n
a OTHER
FILE CREATION AND MAINTEN
FILE CREATED OR UPDATED B
FILESI7E:
UPDATE FREQUENCY:
ANTICIPATED GROWTH:
FILE BACKUP
TYPE: D NONE M
Q SYSTEM
O SPECIAL
•
CATALOGUED FILE DESCRIPTION
O NO PROCNAME,
BLOCKING
O BIOCKFD: . r-i nii.i..^i. »«
O UNBLOCKED ° RECORDS BLOCK
RECORD SIZE
O FIXED LENGTH: rMABACTFRfr
D VARIABLE LENGTH:
THROUGH CHARACTERS |
KEY (IF APPLICABLE)
CONTEUT,
ANCE
»: »c
ASAC
n
FOIIIM Q CABnf LOCATED AT,
D TAPE FILE UAMF-
O DISK EREOIIFUEV-
NUMBER OF GENERATIONS KEPT:
RECORDING MODE
Q INTERNAL O F Q AN
O COMPACT D U D AN
O CFH Q V Q AN
O
FILE AVAILABILITY
O RESTRICTED
a PERMANENT
D TEMPORARY
n -
STORAGE MEDIUM
O DISK
Q TAPE O LABELED
0 CARDS ° """««<>
n
OGRAM NAME)
Figure 4.4.3.C
AEROS File Description and Record Layout for
AEROS Manual Volume III
4.4.3-28
-------
5 ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 29
Update IV-2
ENVIRONMENTAL
PROTECTION ACENCV
NATIONAL AIR
DATA BRANCH
VOLUME III.
' AEROS SUMMARY AND
RETRIEVAL MANUAL .
SECTION
CHAPTER
SUBJECT
QUALIFIER
FILE NAME
FILE NAME/DESCRIPTION
APPLICATION OAT«
RECORD POSITION
FIRST
LAST
LENGTH
DATA ITEM
PICTURE
/
SECTION CHAPTER SUBJECT
DATE PAGE .
RECORD NAME/DESCRIPTION ,
DATA ITEM NAME
rust nr
DESCRIPTION
Figure 4.4.3.d
4.4 .3-29
-------
'* ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL ^
SECTION Systems Development
Section
CHAPTER standards
SUBJECT Documentation
SECTION CHAPTER , SUBJECT
443
DATE PAGE
12/20/78 29a
Update IV-2
AEROS SOFTWARE
DOCUMENTATION
COMPONENT NAME:
SECTION: .
SECTION,
DATE
PAGE
QUALIFIER
FILE DESCRIPTION AND USE
FILE NAME
PILE TYPE
QSOf
O PRINT FILE
O PUNCH f 1LE
O .
O ASCII COBOL
C SEQUENTIAL
Q OlRgCT
Q INDEXED- SEQUENTIAL
Q FORTHAN
Q FORMATTED
O UNFORMATTED
a
a OTHER
CATALOGUED FILE DESCRIPTION
O YES: F|LE NAME
Q NO *""•"" "'"'
BLOCKING
a BLOCKED; —
Q UNBLOCKED
Q CHARACTERS PER
O RECORDS BLOCK
RECORD SIZE
a FIXED LENGTH:
a VARIABLE LENGTH:
^CHARACTERS
THROUGH.
RECORDING MODE
Q INTERNAL Q F Q A>>
O COMPACT O U O if;
a CPU a v a A.\
a
FILE AVAILABILITY
Q RESTRICTED
Q PERMANENT
D TEMPORARY
a ^——
KEY [IF APPLICABLE)
.CHARACTERS LONG
CONTENT:.
.CHARACTERS |STORAG£M6D,gM
O DISK
Q TAPE Q LABELS;
_ Q UNLABELED
C CARDS
o '
FILE CREATION AND MAINTENANCE
FILE CREATED OR UPDATED 3Y:
FILE SIZE;
.(PROGRAM NAME)
UPDATE f HEQUENCY—i
ANTICIPATED GROWTH:.
_|TlM£ INTERVAL!
Q RECORD
• Q TRACKS
FILE BACKUP
TYPE: D NONE
Q SYSTEM
O SPECIAL
G CARDS LOCATED AT:
Q TAPE FILE NAME:
O DISK
cp«micm-v.
NUMBER OF GENERATIONS KEPT.
Figure 4.4.3.e - AEROS File Description and Record Layout
for the subprogram and program level documentation
4.4.3-29a
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78
Update IV-2
29b
AEROS SOFTWARE
DOCUMENTATION
COMPONENT NAME:
SECTION:
SECTION_
DATE
PAGE
FILS NAMg/OgSCaiPTIOM • RECORO HAMS/DESCRIPTION
APPLICATION
RECORD POSITION
' FIRST
LAST
LENGTH
•
DATE
PA
- DATA ITEM
PICTURE
DATA ITEM NAMg
_
CB no
DESCRIPTION
Figure 4.,4..3.f
4.4.3-29b
-------
ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 30
Update IV-2
TEST DESCRIPTIONS
The Test Description section is required for a subprogram, program
and procedure level documentation. This section should contain the
General Test Conditions table generated as part of the Design Phase
(see Software Design Standards 4.4.1) and all the Test Run Conditions
Forms approved and subsequently submitted with actual test runs dur-
ing the Programming (see Software Programming Phase 4.4.2) or Mainten-
ance (see Systems Maintenance 4.4.4).
As a program is modified and tested, all previous test conditions
should be applied and a new condition table added to the Test Descrip-
tions section to show any new test conditions generated as a result of
the modification.
4.4.3-30
-------
' <* ENVIRONMENTAL
PROTECTION AGENCY
NATIONAL AIR
DATA BRANCH
VOLUME IV.
NADB INTERNAL
OPERATIONS MANUAL
SECTION Systems Development
Section
CHAPTER Standards
SUBJECT Documentation
SECTION
4
CHAPTER
4
SUBJECT
3
DATE PAGE
12/20/78 31
Update IV-2
MAINTENANCE LOG
The Maintenance Log section which is required for all levels of
documentation will consist of the Changes Documentation Form (see
4.4.4-7) and all associated material except the specific rewrites of
the other sections of the documentation which are updated in their
appropriate places.
The Maintenance Log section for System level documentation will
only contain the Approach Study. Since there will be no line by line
changes at the System level, the Changes Documentation Form would
not be applicable.
4.4.3-31
-------
i -T- »•-•
CLOGP3
CLOGP3 User Guide
HedChem Software Release 3.32
••*;
'•-.. ABSTRACT ,
The CLOGP3 User Guide will help the user
understand why the CLOGP-3 program calcu-
lates log P(o/w) the way it does. Although the
procedure cannot be derived from first princi-
ples. We have tried to make the rules consistent
with solvation theory, if for no other reason
than they are more easily remembered. The
method simply adds together values for struc-
tural parts of a solute molecule and correction
factors dependent upon the particular way the
parts are put together. Example calculations
(in EXAMPLES section) illustrate every impor-
tant feature of the method and should be care-
fully studied. The symbol w appears in the text
when one or more examples are provided.
Funding for the development of CLOGP-3
was provided by the U.S. Environmental Protec-
tion Agency through Cooperative Agreement
No. 809295, and we wish to acknowledge the
encouragement and support of the project
officer. Dr. Oilman Veith of ERL-Duluth.
------- |