EPB Hiii Bcmpi t ar
aid Programming
Standards
SEPA
JflNUflRY 1979
ENVIRONfTlENTflL PROTECTION flGENCY
management Information and Data Systems Division
!Pm-218
Washington, D.C. 2O46O
-------
EPA MINICOMPUTER SOFTWARE DOCUMENTATION
AND PROGRAMMING STANDARDS
-------
PREFACE
Documentation is required to properly operate and maintain computer software. The
EPA Automatic Data Processing (ADP) Manual , March 1975, established the initial
policies and guidelines for EPA in-house and contractor developed software documenta-
tion. While these provide overall guidance in software documentation development,
they apply primarily to software developed for general purpose computer systems.
With the standardization of minicomputer systems in 1976 for EPA regional offices
and laboratories, an increasing number of minicomputer installations will be capable
of sharing common use software products. In order to ensure the greatest opportunity
for sharing software, good documentation and programming standards and conventions
are required in addition to standardized computer configurations.
This n nual establishes documentation and programming standards specifically for the
DEC PDP-11/45 and 70 minicpmputer systems. However, the documentation standards,
and except for the programming language and hardware usage restrictions, the pro-
gramnhing standards and conventions, are applicable to other minicomputer systems.
The documentation and programming guidelines generally conform to established industry!
user practices. The intent has been to scale down and minimize the standards to the
extent possible to better address to the less complex, less structured environment of
the typical minicomputer installation. While they have been developed for a closed shop
environment, they are equally applicable to the open shop environment. These standards
will help to ensure that software developed by one author can be properly maintained
by another; an essential requisite for any installation whether opened or closed.
Comments or suggestions on this mnnual should be submitted to:
Thomas Tracy
Environmental Protection Agency
CSSD, Room 308
26 W. St. Clair Street
Cincinnati, Ohio 45268
Telephone (513) 684—7759
1.
-------
ABSTRACT
This m nt l defines the documentation requirements for application software developed
for EPA minicomputers. It also presents recommended programming conventions and
standards to ensure good programming and software transferability. While this manual
was specifically written for the DEC PDP 11-45/70 minicomputers, it is generally
applicable for application software developed for other minicomputers. These docu-
mentation requirements apply to both EPA and contractor developed application software.
Docinnentation guidelines and standards are presented for each phase of software
development, from systems design to operation and maintenance. Four documentation
ni nuals are identified and described in detail. All EPA minicomputer installations, and
programs for EPA Minicomputer Software Exchange submission, must conform to these
requirements. Sample forms and checklists are provided to assist in documentation
development and evaluation.
iI_
-------
TABLE OF CONTENTS
Page
Preface I
Abstract
1. INTRODUCTION 1-1
1.1 Purposes for Documentation and Programming Guidelines 1-1
and Standards
1.2 Types of Software Documentation 1-3
1.3 Classification of Software and Its Impact on Level of 1-4
Documentation
1.4 Documentation Development and Maintenance ResponsibIlities 1-8
2. OVERVIEW OF SOFTWARE DEVELOPMENT LIFE CYCLE 2-1
2.1 Software Project Development Life Cycle Phases 2—1
2.2 Documentation Related to Software Development Life Cycle 2—2
3. SYSTEM/SUBSYSTEM DOCUMENTATION 3-1
3.1 DefinitIon of System/Subsystem Documentation 3-1
3.2 Document Content 3—1
3.3 Software Classification Documentation Consideration 3—7
4. MAINTENANCE DOCUMENTATION 4-1
4.1 Definition of Maintenance Documentation 4-1
4.2 Documentation Content 4-1
4.3 Software Classffication Documentation Considerations 4-5
5. RUN DOCUMENTATION 5-1
5.1 Definition of Run Documentation 5—1
5.2 Documentation Content 5-1
5.3 Software Classification Documentation Considerations 5—7
ill
-------
Table of Contents (Continued)
Page
6. USERS DOCUMENTATION 6-1
6.1 Definition of Users Document 6-1
6.2 Documentation Content 6-i
6.3 Software Classification Documentation Considerations 6-6
7. SPECIAL DOCUMENTATION CONSIDERATIONS 7-i
7.1 - Environmental Information System Interface Requirements 7-i
7.2 Software Installation Documentation Requirements 7-1
7.3 EPA Minicomputer Software Exchange, FSEP and DECUS 7-2
Requirements
7.4 Operations Review Requirements 7-2
8. RECOMMENDED PROGRAMMING CONVENTIONS AND STANDARDS 8-i
8.1 Purpose of Conventions and Standards 8-1
8.2 Languages Supported 8-1
8.3 Software Identification 8-1
8.4 Nomenclature 8-2
8.5 Structure 8-4
8.6 Language Restrictions 8-4
8.7 Hardware Restrictions 8—7
8.8 Other General Considerations 8-8
APPENDICES
A. Recommended Flowcharting Conventions A-i
B. Documentation Sample Forms B-i
C. Software Submission Forms c-i
D. Programmer Checklist D-i
E. References E-i
iv
-------
1. INTRODUCTION
Documentation and programming guidelines have been established to ensure that soft-
ware Is properly developed and maintained. Software documentation must address the
information needs of the technicians as well as the less sophisticated users. Software
documentation requirements are a function of software complexity. Software authors,
or developing organizations, are primarily responsible for software documentation
development and maintenance.
1.1 Purposes for Documentation and Programming Guidelines and Standards
Adequate documentation of computer software is necessary for a complete and accurate
understanding of computer processing activities and the impact of such processing on
user groups.
While the need for documentation is generally accepted, adherence to it in practice
varies considerably, ranging from where everything is in a programmers’ memory to
organizations which will not permit new processing to begin before complete documenta-
tion has been prepared and checked.
The preparation of even minimum documentation requires an appreciable amount of
time and effort on the part of system analysts and programmers and, in the face of
tight implementation schedules and scarce resources, it is often compromised or ignored.
However, such time and resource “savings” have often been greatly exceeded by the
costs of subsequent software modification. In these situations, software modification
often means a lengthy reconstruction of the software logic followed by software revision,
or even a complete replanning and rewriting of the software. This problem is drastically
compounded when the software developer is no longer available.
The purposes of documentation guidelines and standards are:
• To ensure that all planned software is adequately documented .
Computer software can be introduced and may fail to meet the objectives of
the user, or it may be inefficient or uneconomical. Documentation helps ensure
1 —1
-------
that the users’ requirements and processing problems have been clearly
stated so that they can be reviewed before programming and operation are
allowed to begin.
• To ensure that all software is adequately documented .
Coding may be started by one programmer but, for various reasons, may
have to be completed by another. Similarly, revis Eons to software may
have to be made by a programmer who did not write it. Management will
often request to review the logic, design, and controls incorporated into
the software. Documentation ensures that sufficient details are available
for a complete technical understanding of the software.
• To ensure that Instructions to operators and users are adequately documented .
In a closed shop environment, computer operators are often responsible
for the running of many batch processing programs or systems each
requiring their own unique operating requirements. Others, such as users,
must interface with these software products, providing Input data or using
output results. Documentation is required to enable operators to properly
set up, execute, or. react to abnormal run terminations, and provide guid-
ance to users so that they can correctly perform their duties.
While documentation guidelines help to ensure that software products are understood and
maintainable, programming guidelines are designed to serve a different purpose,
namely:
• To enhance readability of coding .
Nomenclatare, structure and layout have a significant impact on software
readability and, therefore, the ease by which it can be maintained or
tested.
• To ensure efficient utilization of computer hardware resources .
Software design can have a drastic impact on the efficient utilization of
system resources. Language commands, memory and peripheral device
1—2
-------
usage, and processing mode are some factors that must be controlled to
ensure that system performance is not needlessly degraded.
• To improve portability of common use software .
If software is to be shared, users must adapt basic standards and con-
ventions to ensure that the software will be properly executed on their
configuration without degrading system performance. Software main-
tenance is also easier for shared software when users follow common
programming standards and conventions.
While the implementation of standards for documentation and programming may impose
some burden on minicomputer analyst and programming personnel In the short term,
the benefits to management, users, computer operations, and ultimately, to analysts
and programmers, wili more than justify their adoption.
1.2 Types of Software Documentation
Software documentation is written for specific audience types. It is important when
developing documentation to keep this in mind for it defines the scope, level of detail,
and technical content of the document. The audience may be an individual or group of
individuals who will use the document to perform a specific function. In general, the
audience types will include the following:
• Management . Technical or nontechnical personnel who will review software
plans, requirements, and general approach to assess cost—benefit, deter-
mine schedules, and evaluate final software product.
• Programmers/Analysts . Technical personnel who will maintain the software.
• Users . Nontechnical personnel who will provide the input data and/or use
software output to perform their duties.
• Operators . Nontechnical personnel who will schedule and run software.
In a closed shop environment or for noninteractive, complex software products, all of
these audience types are normally represented and can be composed of many different
individuals. For open shop environments or interactive software products, all audience
types may be represented in one or two individuals.
1—3
-------
Documentation types parallel audience types and is produced during the development
and testing of the software. The need for any one of these documents is determined by
th complexity of the software as discussed in 1.3 below.
• System/Subsystem Documentation
This is the first document developed after the feasibility study (if required)
has been completed and approved. It provides a general description of the
proposed software product to allow management, programmers and
analysts to understand the design and approach, review progress, and
evaluate results.
• Maintenance Documentation
This Is developed prior to, during, and following coding and testing. It
contains detailed logic and design information to allow a programmer to
maintain the software.
• Run Documentation
This documentation is developed during and following coding and testing.
It provides operating information on the software to allow a computer
operator to properly run the software.
• Users Documentation -
This is written during coding and testing. It provides sufficient information
on the software in non-ADP terminology to allow the user to determine its
applicability, and when and how to use it.
Additional documentation is required for shared software. This documentation describes
how to install the software in the user’s environment. This can be a separate document
or part of the maintenance documentation. It is written for systems people.
1.3 Classification of Software and Its Impact on Level of Documentation
The extent and level of detail of documentation required for each software product is
a function of the size, complexity, and risk of the software effort. In general, as the
size, complexity and risk of the software effort increases, so does the need for formality,
1—4
-------
extent, and level of detail of the documentation. The users’, run, and maintenance
documentation, whether separate or combined within one manual, should be formal since
they support the use of the software, particularly If the software will be shared or if
extensive changes are expected during the life of the software.
Deriving a true index of the complexity of a software effort is very difficult because
most of the factors cannot be accurately measured until the project has been completed.
However, a first approximation of software complexity is the hierarchy of software:
system, program, or subroutine.
• System
Software systems represent the most complex software products. A system
Is generally defined as a set of logically related computer programs
designed to accomplish specific objectives or functions.
• Pro am
This represents the next level of software complexity. It is generally
defined as a set of coded instructions arranged in proper.sequence to
direct the computer to perform a desired operation or series of operations.
• Subroutine
This Is the least complex software product. It is generally defined as a
set of instructions that direct the computer to carry out a well-defined
mathematical or logical operation. The subroutine is coded so that
control may be transferred to it from a program and returned to the calling
program at the completion of the subroutine.
Based on software hierarchy, the following guidelines are established for documentation
requirements. These guidelines are designed to protect against both over and under
software documentation. Additional factors such as sharing potential, life expectancy,
and usage frequency should also be considered in the determination of documentation
levels. Table 1, following this page, presents levels of documentation required as a
function of software hierarchy.
1—5
-------
Table 1-1. Levels of Documentation Checklist
Software Hierarchy Documentation Requirements
System J J System/Subsystem Document
Maintenance Document
Run Document
Users Document
— ; i ;c;e;
— — — Maintenance, Run, Users Document
Subroutine System/Subsystem, Maintenance, Run, Users
Document
1—6
-------
• System Software
System/subsystem, maintenance, run, and user documentation Is
generally required for system software. System software Is normally
used by a number of people and is likely to be shared with other EPA
operating units. System software documentation should include all pre-
scribed elements of each document. Because of its potentially wide
audience, each should be a separate document.
• Program Software
Program software, and less complex system software requires system!
subsystem documentation similar to system software, but maintenance,
user and run documentation being less complex, can be combined and
presented in a separate document.
• Subroutine Software
Minimum effort is required to document software in this category. All
documentation types are summarized and presented in one document.
Other factors to consider in determining software documentation requirements include:
• Originality Required
As the originality of the approach or technique increases, so should the
formality and level of documentation. This is particularly important for
maintenance documentation.
• Degree of Generality
If the software has broad applicability, the documentation should be more
formal and detailed. This is particularly true for users’, maintenance,
and run documentation.
• Number of Persons Assigned to Its Development
As more persons are involved in the software development effort, more
formality and detail is required in documentation. This is particularly
important for system/subsystem and maintenance documentation.
1—7
-------
• Developmental Cost
As software development costs increase, so does the need for documenta-
tion. While all documentation types will generally have to be more formal and
detailed, it is particularly true for system/subsystem documentation.
Each document type outline presented in the following chapters-of this guide can
be used to develop documents that range from a few to several hundred pages. The
size depends on the complexity of the project, the opinion of the project manager
as to the level of detail required, and other factors. While size guidelines can vary
considerably, a rough estimate of the general size of documentation for software products
is presented below:
• System Software
For all documents, between 50 and 150 pages total.
• Program Software
For both documents, a total of between 25 and 50 pages.
• Subroutine Software
Between 5 and 10 pages.
1.4 Documentation Development and Maintenance Responsibilities
Documentation development and maintenance is the responsibility of the minicomputer
installation. The Branch Chief/AD? Coordinator is responsible for ensuring that
the guidelines and standards contained in this document are understood and followed
by his/her staff. In addition to standards enforcement, the Branch Chief/AD P
Coordinator is also responsible for establishing and maintaining documentation
development schedule, and review and approving software documentation.
The software developer/analysts is responsible for software documentation develop—
ment and maintenance. The documentation must be developed and maintained in
accordance with the guidelines contained in this document. Software documentation
requirements should be discussed with the Branch Chief/ADP Coordinator prior to
their development to ensure that they will meet the guidelines.
1—8
-------
he EPA Minicomputer Software Exchange will provide technical assistance, as required,
o assist sites in documentation preparation. All software documentation submitted
to the Exchange must conform to the requirements contained in this document. The
Exchange will review documentation for compliance and, when required, inform the
submittingorganization what is required to bring the documentation into compliance.
1—9
-------
2. OVERVIEW OF SOFTWARE DEVELOPMENT LIFE CYCLE
Software documentation is prepared concurrently with software design, coding and
testing. It Is not something that is done after the software becomes operational.
Software documentation is a continuing part of the developmental effort and should be
completed about the time the software becomes operational.
2.1 Software Project Development Life Cycle Phases
The software development can be divided into four phases. These phases are generally
applicable to all software development efforts regardless of software complexity.
However, for simple software efforts, such as subroutines, the phases tend to merge
with little, It any, concern given to their boundaries or formal rn n2gement review and
evaluation.
S Initiation Phase
During this phase, a project request for the software product is prepared.
This request can take the form of an informal verbal request for simple
software (subroutine) to formal justification documents for large, complex
systems. Software request requirements and procedures are defined in
Automatic Data Processing (ADP) Manual , March 1975. The project request
specifies the objectives, general capabilities, and problems to be overcome
by the software being requested. Depending upon the estimated life cycle
cost of the requested software, a feasibility study is conducted to analyze
the situation to develop cost-benefit estimates and alternatives.
• Development Phase -
The Development Phase is the major phase and can be considered to be
comprised of three stages: Definition, Design and Coding. In the Definition
Stage, the overall software requirements are identified and described.
During the Desi Stage, detailed specifications, procedures, input/output
formats, and other information required for coding and implementation
are developed. In the final stage, Coding, the computer code is written,
compiled and debugged.
2—1
-------
• Evaluation Phase
During this phase, the software is evaluated using test and real data. The
software results are reviewed with the requesting group to ensure that the
software meets their requirements. An important aspect of the Evaluation
Phase Is to demonstrate that the software produces valid results.
• Operation Phase
In this phase, the tested and validated software is turned over to the
requesting group. The software is now considered in the production and
maintenance state. Routine maintenance is performed during this phase to
correct bugs and revise software to meet changing requirements.
Documentation is important for the successful and efficient planning, conduct, and
evaluation of each phase. It should be reviewed and approved at the completion of the
phase (stage) in which it was developed.
2.2 Documentation Related to Software Development Life Cycle
Different documentation types are prepared throughout the software development
life cycle. This Is an evolutionary process as the software approaches the Operation
Phase. Information is presented and updated as more becomes available. It is Em-
portent to keep in mind that the information included in each document differs in
context, terminology, and level of detail since the information is intended to be read
by different audiences and/or at different points in the software life cycle. Additions
to draft documents should be made as frequently as possible to avoid introducing errors
or requiring massive updating at the completion of the project. Documentation type
and content track software development phases thus facilitating the evolutionary
creation of the various documents at the appropriate point in time.
The documentation that is developed and evolves from each phase Is presented below.
Table 2-1, following this page, presents this information graphically.
2—2
-------
Table 2-1. Documentation Development As A Function of Software Life Cycle
3
Phase
Type of
Document
Initiation
Development
Evaluation
Operation
Project
Request
Stage
Project
Analysis
Stage
Definition
Stage
Design
Stage
Coding
Stage
Test
Stage
ValidatLon
Stage
Production
Stage
Maintenance
Stage
System!
Subsystem
Maintenance
Run
Users
N
s —
-------
• Initiation Phase
Software request documentation and feasibility study documents are
produced during this phase. These documents are covered in the Automatic
Data Processing (ADP) Manual , March 1975 and Guide to Conducting ADP
Feasibility Studies , April 1977, respectively.
• Development Phase
Documentation prot]uction Is keyed to the three stages in this phase. The
System/Subsystem document is drafted during the Definition. Stage and
finalized at the completion of the Design Stage. The Maintenance document
Is drafted during the Design and Coding Stage. The Run and Users Documents
are drafted during the Coding Stage.
• Evaluation Phase
The Maintenance, Run, and Users documents are finalized at the end of
the Evaluation Phase.
• Operation Phase
Any necessary revisions (updates) are made in a timely manner to the
Maintenance, Run and Users’ documents during the Maintenance Stage of
of the Operation Phase. The Maintenance Stage is somewhat indeterminent
since it depends upon the occurrance of a bug or change request.
The content of each document and the flexibility within each to accommodate software
hierarchy is presented in the following four chapters.
2-4
-------
3. SYSTEM/SUBSYSTEM DOCUMENTATION
System/Subsystem Documentation presents the software in sufficient detail to permit
its effective review by management, facilitate its efficient development, and provide
a basis for evaluating the finished product. It is required for system and program
level software.
3.1 Definition of System/Subsystem Documentation
System/Subsystem Documentation provides all interested groups with a clear and
accurate understanding of the software Including the objectives, methods, problem
solutions, data files, flow of information through the system, processing stages and
computer programs, compilation and linkage procedures, output from the software,
and test and validation plan and specifications. This document provides the basis for
the mutual understa.nding between users and designers, and specifies for the pro-
grammer and analyst the requirements, operating environment, design characteristics,
and program specifications for the software. It is required for system and program level
software.
3.2 Document Content
It is difficult to specify a System/Subsystem document outline that will accommodate
a]l system software situations. Since each system is designed to address a specific
problem, meet unique objectives, handle different types of data in a particular
fashion, produce unique types of output, and function under different operating modes
and conditions, no one outline can serve this purpose. However, general categories
of information can be specified that should be included in a minicomputer System/
Subsystem document. The specific information, level of detail, and similar content
considerations within each category must be adopted for each particular system. A
topic System/Subsystem document outline is presented in Figure 3—1, following this
page. A general discussion of the information to be included within each topic area is
presented below.
3—1
-------
Figure 3-1. System/Subsystem Document Topic Outline
• Title Page
• Table of Contents
• Introduction
— General System Description
— System Objectives
• System Description
- System Flowchart
- System Narrative
• User Information
— Inputs Required for Submission
- Outputs and Distribution
— Controls Required
- Timing: Cut-off Dates, Processirg Cycles
- - Files Used and Change Procedures
• Program Specifications
- Run Charts
— Input/Output Descriptions
- Report Formats
— File Layouts, Organization, and Access Methods
- Processing
— Applicable Constants, Processing Rules
• Environment
— Equipment
— Support Software
- Interface
- Security
• System Test
- Test Plan
- Test Data
3—2
-------
3.2.1 General System Description
The general system description should include an overview of the system structure
and data flow. It should summarize the information that has been developed in the
system flowchart and system narrative. A brief description of the system design
history and expected growth provisions (if any) should be presented and include:
• An explanation of how the need for a system developed
• The conditions that induced the user to submit a request for a feasibility
study (If required)
• A summary of the results of the feasibility study
• Present system features that allow for ease of expansion so that increased
user activity can be absorbed.
3.2.2 System Objectives
Statements of the major perform ince requirements or goals of the software system
should be included. These statements should be concise and include examples. Any
anticipated operational changes that will affect the system and its use should be identified
and the provisions within the system for including them be explained. In addition to
the stated objectives, the following should also be provided: a list of the major accomp-
lishments of the system, and illustrations of how user requirements are satisfied; and
a description of the accomplishments in quantitative terms, where possible.
3.2.3 System Description
The system description includes the system flowchart and the system narrative. The
flowchart is an overall system flowchart and should show all manual and computer
processes, input and output files, run-to-run relationships, and similar system
relationships. A system flowchart shows the flow of information from one major
operation (manual or computer) to another. The system flowchart symbols that should
be used are presented in Appendix A.
3—3
-------
A system narrative should be developed that contains descriptive information to support
the system flowchart and expand on the general description. A detailed description of
user operations, a synopsis of each computer program, a detailed description of
system controls, and a listing of system functional requirements should be provided.
For user operations, the following should be Included:
• A description of the input to each operation
• A description of each operation in detail, especially complex functions,
exception conditions, and unique processing requirements
• A description of the use, distribution, and format of each output.
For each computer program, the following should be included:
• A description of the inputs
• A description of the primary processing functions
• A description of the outputs.
For system controls, the following should be included:
• A description of user operation controls
• A description of the controls used in computer processing
• A description of the relationships between user operation and computer
processing controls.
Finally, state the functions required of the software in quantitative and qualitative
terms, and how these functions will satisfy the system objectives.
3.2.4 User Information
The next section of the manual should present information pertinent to the user. This
material will be required for their review of the system, and later for development of
the users manual. The user information should include descriptions and samples of the
following items, if appropriate:
3—4
-------
• Source Data
- Preparation
— Transmission
— Fields and codes used
- Documents, if any
• Control of Input Data
- Logs
- Control sheets
— Control totals
- Balancing procedures
- Error handling
• Reports
- Content and format
- Usage
- Distribution
• Files
- Content and format
- Usage
- Update procedures.
3.2.5 Program Specifications
Program specifications section should contain all information required to write the
programs. These specifications should be prepared for each program so that
individual programs may be assigned as complete entities to programmers. Each
program specification should contain the following information:
• Program Identification
• Program Abstract
• Input File Description
- Input media
- File organization
3—5
-------
— Access method
- File sequence
— Key(s) used
- Data conversion requirements
— Record layout
• Input Record(s) Description
Key(s)
— Transaction codes
-Data
• Processing Required
- Listof functions
— Narrative description of each function
— Decision tables, if desirable
- Table of constants and codes
- Block diagram
• Output File Description
— Record layout
- Printed reports
• Snmm ry of Controls
- Data edits
- Error codes
- Error Interpretation
3.2.6 Operating Environment
This section should include a description of system hardware and software require-
ments. For hardware, Identify the equipment required for the operation of the software.
Identify any new equipment required and relate it to specific functions and requirements
to be supported. Include information such as:
• Processor and size of internal storage
• Storage, online and offline, media, form, and devices
3-6
-------
• Input/output devices, online and offline
• Data transmission devices
Identify the support software and describe any test software. If the operation of the
software depends on changes to support software, identify the nature and pl nn d date
of these changes. Also describe the interfaces with other software.
3.2.7 System Test
A system test plan should include types of tests and test data. The responsibilities
of each affected organization in determining test details, performing the tests, and
approving the results should be spedlfted. This is especially important for software
that interfaces with other agencywide systems.
Appendix B presents forms that should be helpful in preparing System/Subsystem docu-
mentation.
3.3 Software Classification Documentation Consideration
The System/Subsystem outline presented in Figure 3-1 should help structure and
facilitate the development of the System/Subsystem document. FIgure 3-2, following
this page, presents a checklist that should aid in assessing the completeness of System/
Subsystem documentation.
The type of software will also have an impact on the System/Subsystem Documentation.
More detail Is required for a complex system than for program software.
• System Software
In general, system software documentation should conform to the
guidelines presented above. Factors to consider in sizing the document
thclude
- Operating mode, whether interactive, batch or combination
— Size of data base
— Number of options, features, or special conditions
- Number and capability of users
3—7
-------
Figure 3-2. System/Subsystem Documentation Checklist
• Title Page
• Index
• Problem definition and general description
• General systems description and specifications
• Compilation and linkage specifications
• General systems flowchart showing the flow of information through
the system and the interrelationship between the processing steps
and computer runs
• Resource requirements
• Special treatment for exceptions
• LISt of programs required by the system
• Program specifications
• Overlay procedures where applicable
• Description of source documents arid of the method of conversion
and control of source data to machine readable form
• Constants, codes and tables
• Input format and descriptions
• Output formats and descriptions
• Processing controls and data validation considerations
• File control procedures and specifications
• Test data specifications
• Test plan and acceptance procedures
3—8
-------
• Program Software
For program software, the System/Subsystem Documentation can be more
concise. In general, less information is required in all topic areas except
program specifications.
Since the preparation of System/Subsystem Documentation can be costly and time
consuming, it should only be prepared in sufficient detail to:
• Allow users to determine if system meets their requirements, and how
• Provide Instructions to programmers to permit them to code the system
• Provide information from which the users manual can be developed.
3—9
-------
4. MAINTENANCE DOCUMENTATION
Maintenance Documentation provides the necessary information that allows programmers
to correct software bugs or make revisions. It is required for system, program, and
subroutine software.
4.1 Definition of Maintenance Documentation
Maintenance Documentation provides programmers with sufficient software information
to allow them to correct errors in the software, or to make requested modification to
it. This documentation should be designed so that a competent programmer or systems
analyst, with no prior experience with the software, can read the documentation and
understand it well enough to be able to modify or repair it. Maintenance Documentation
is required for system, program, and subroutine level software.
4.2 Documentation Content
Maintenance Documentation should contain a general description of the software, a
functional overview of the software, input/output descriptions, program logic, and
software compilation, loading, and run procedures. This information is supported
by a well-commented listing, sample output and other relevant examples. Most of
the general and introductory information can be obtained for the System/Subsystem
document. Figure 4—1, following this page, presents a topic outlizE of the Maintenance
document. A general discussion of the information to be included in each topic area
is presented below.
4.2.1 Introduction
This section should summarize the purpose and function of the software, the required
equipment configuration, software environment, software conventions, and pertinent
references. The purpose and function of the software should be described in non-ADP
terms. This information can be obtained from the System/Subsystem document. A
brief summary of the equipment configuration and its general characteristics should
be presented. The interaction of the software with any controlling support software,
or other software should be described.
4-1
-------
Figure 4-1. Maintenance Documentation Topic Outline
• Title Page
• Table of Contents
• Revision Page
• Introduction
- Software Application
- Operating Environment
- Software Environment
- Conventions
— References
• Software Description
- General Description
- Detailed Description
• Software Compiling, Loading and Maintenance Procedures
- Procedures
- Verification
— Error Conditions
— Listings
4—2
-------
If the software utilizes a general software support capability as an integral part of Its
overall design, this paragraph should state what these systems are and whether or not
a basic understanding of them is a prerequisite for effectively utilizing the software
being described.
This section should also explain all rules, schemes, and conventions that have been
used within the software. Information of this nature would include the following items:
• Design of mnemonic identifiers and their application to the tagging or
labeling of programs, subroutines, records, data fields, storage areas, etc.
• Procedures and standards for flowcharts, listings, serialization of cards,
abbreviations used in statements and remarks, and symbols appearing in
charts and listings.
Finally, a brief sumrn2ry of the references applicable to the history and development
of the software should be Included.
4.2.2 Software Description
The purpose of this section is to show the structure, operation, and composition of the
software as a program or set of interrelated programs or subroutines.
• General Description
This paragraph should provide a comprehensive description of the system,
programs, or subroutines in terms of their overall functions. This
description can be accompanied by a flowchart showing the interrelationships
of the major components of the software.
• Detailed Descriptions
The purpose of this paragraph is to supply details and characteristics of
each program and subroutine that would be of value to a maintenance
programmer in understanding the program and its relationship to other
programs. This paragraph should initially contain a list of all programs
and subroutines to be discussed, followed by a narrative description of each
program and its respective subroutines under separate paragraphs. Informa-
tion to be included in the narrative description should include:
4—3
-------
— Program title or tag (including a designation of the version number
of the program).
— Description of program functions.
— Storage - Specify the amount of storage required to use the program
and the broad parameters of the storage locations needed.
— Data file records used by the program during operation.
- Branching conditions provided in the program.
— Entry requirements concerning the Initiation of the program.
— Input data type and location(s) used by the program when Its operation
begins.
— Exit requirements concerning termination of the operation of the
program.
— Communications or lin1 ge to the next logical program (operational,
control).
— Output data type and location(s) produced by the program for use by
related processing segments of the system.
— Response to errors detected during the input—processing-output
operations of the program.
— Restrictions that have been designed into the system with respect to
the operation of this program, or any limitations on the use of the
program.
— Permanency - Note whether the program is a normal link in the cycle
of programs to be run or will be used only under certain circumstances.
— Associated programs — Identify the programs which can access this
program.
- Major operations — The major operations of each program should also
be described. The description can be referenced to flowchart(s) which
may be included in an appendix. This flowchart should show the general
logical flow of operations, such as read an input, access a data record,
major decision, and print an output which would be represented by
segments or subprograms within the program. Reference may be made
to included flowcharts that present each major operation in more detail.
4.2.3 Software Compiling, Loading and Maintenance Procedures
This section of the manual should provide information on the specific procedures
required to maintain the software.
4-4
-------
• Procedure
The procedures, presented in a step-by-step manner, should detail the
method of preparing the inputs, such as the keypunching, structuring, and
sequenct ig of inputs. The operations or steps to be followed in setting up,
running, and terminating the maintenance task on the computer system
should also be given.
• Verification
This paragraph should include those requirements and procedures necessary
to check the performance of a program section following its modification.
These procedures should be consistent with the test plan provided in the
System/Subsystem document.
• Error Conditions
A description of error conditions, not previously documented, should be
included. This description should include an explanation of the source of
the error and recommended methods to correct it.
• Listings
Source and compiled listings, cross reference listings and similar listings,
appropriately annotated should be included as an appendix. The liberal
use of comment cards, as well as by following the other programmings
conventions and standards recommended in Chapter 8 of this manual, should
fulfill listing annotation requirements.
Appendix B contains forms that should be helpful in preparing Maintenance Documentation.
4.3 Software Classification Documentation Considerations
The general outline presented in Figure 4- ]. is appropriate for system and program
software. As with System/Subsystem Documentation, the size of the maintenance
manual must adjust to the complexity of the software. Figure 4-2, following this page,
presents a Maintenance Documentation Checklist to assess the completeness of Main-
tenance documentation.
4—5
-------
Figure 4-2. Maintenance Documentation Checklist
• Title Page
• Revision Page
• Software Overview Description
• Overall Process Flowchart
• Program Narrative description
• Program Specifications
• Logic Diagram and/or Decision Tables
• Constants, Codes and Tables
• Input and Output Formats
• File Formats and Descriptions
• Source Program Listing
• System Tables and Reference Listings
• Maintenance Instructions
4—6
-------
Subroutine level software Maintenance Documentation need not be as complex or
detailed as shown in Figure 4—1. Figure 4—3, following, presents a suggested outline
for subroutine level Maintenance Documentation.
4-7
-------
Figure 4-3. Subroutine Software Level Maintenance Documentation
• Title
• Revision Page
• Sunmi ry Description
- Objective
- Method
- Function
• Call Statement Description
— Call Statement Description
— Argument Description
- Options
— Error Messages
• External References
• Other Entry Points
.. Calling Sequence
• Subroutine Description
-Logic
- Variables
- Options
— Error Messages
• Environment
- Region Size
- Timing Estimate
• Listing
4-8
-------
5. RUN DOCUMENTATION
Run Documentation is necessary for software that requires computer operator
assistance for execution. It contains the necessary information to properly setup and
respond to both normal and abnormal terminations. It is generally required for
recurring system and program level production software operating In a batch mode.
5.1 Definition of Run Documentation
Computer operator assistance may often be required to run certain software. This
software could require operator assistance because it runs in the batch mode, requires
the mounting of tapes or disks, or requires other special setup or Initiation assistance.
This software is at the system or program level performing a recurring production
function. For such software, it must be possible for any operator to carry out the
processing operations for that software even though they may have no previous experience
witI it. Such instructions are contained in the Run Documentation.
The situation is somewhat different in an open computer shop where the user or
programmer also functions as an operator. However, even in these situations it is
desirable to have Run Documentation for the above types of software because the user or
programmer might not be available and a third party may have to run it, or the
computer center may expand to a size where It is no longer efficient to function as an
open shop environment.
5.2 Documentation Content
Run Documentation should include an overview of the software, a discussion of control
procedures, and procedures to follow for both normal and abnormal termination.
Figure 5-1, following this page, presents a suggested outline for Run Documentation.
The major areas are discussed in more detail below.
5.2.1 General Description
This section should contain a brief summary of the software application and operation,
and include a program/subroutine inventory.
5—1
-------
Figure 5-1. Run Documentation Topic Outline
• Title Page
• Table of Contents
• Revision Page
• General Description
- Software Application
- Software Operation
- Program/Subroutine Inventory
• Software Control
• - Control Requirements
- Phasing Requirements
— Data Retention Requirements
• Operating Procedures
- Equipment Configuration
- Input Materials
- Output Expected
- Procedures
• Nonroutine Operations
5—2
-------
• Software Application
A brief snmvn ry of the software describing its purpose and uses. This
can be sunimarized from Maintenance or System/Subsystem Documentation.
• Software Op ratton
This paragraph should describe the operation of the software using a
chart showing the data flow and data processing operations, including how
the various operations are interrelated regarding input data and output
information. If sets of runs are grouped by time cycles, then each set
of Integrated operations required on a daily, weekly, etc. basis should be
presented. The diagram blocks should be labeled to indicate appropriate
npme or number and the purpose. The input and output symbols denoting
cards, tapes, etc. associated with their particular operation and with
other operations as inputs or outputs should also be identified.
• Program/Subroutine Inventory
This paragraph should provide an inventory In tabular form of the various
software modules. .Each should be identified by title, number, and
mnemonic reference, as applicable.
5.2.2 Software Control
This section should present information on how the operations and environment
associated with the software are controlled so that scheduling of operations, assignment
of equipment, and the management of input data, output data, and other output informa-
tion may proceed in an orderly and productive manner. For online systems, some of
the description of software operational control will be related to the capability of the
supervisory program which functions as a real-time controller of the operations and
environment.
• Control Requirements
This paragraph should present clear and concise instructions for control
personnel who are responsible for the overall administration, security,
and control of the operation of the computer software. The following items
are representative of control considerations which may be applicable:
5—3
-------
— Processing cycles (continuously, daily, weekly, etc.)
- Receipt time and identity of input (data, parameters, program
modifications, etc.)
- Coordination and control (including security) of input, library, and
output material
- Instructions for the preparation of the data and required control cards
- Disposition of output
- Disposition of input after processing.
Phasing Requirements
This paragraph should provide a schedule of acceptable phasing of the
software into a logical series of operations. A software run may be
phased to permit manual or semi-automatic checking of intermediate
results, to provide the user with intermediate results for other purposes,
or to permit a logical break if higher priority jobs are submitted. An
example of the minimum division for most systems would be edit, file
update, and report preparation.
• Data Retention Requirements
Basic information generally required is:
- Project number
- Run number generated
- Tape name
— Retention schedule to include:
- - Retention duration
—— Release date (if applicable)
-- Replacement instructions
5.2.3 Operating Procedures
This section should present the procedures and materials required to perform each of
the Individual operations. The presentation of procedural actions and responses
required by operator for input, machine operation, and output should be made in a
logical manner and should foUow the sequence normally required in performing the run.
In addition, procedures covering the occurrence of abnormal or unexpected operations
should be covered.
5-4
-------
• Equipment Configuration
List all equipment required to execute the software.
• Input Materials
List and describe all materials needed to initiate the run such as:
- Control/administrative forms authorizing the run
- Input data forms or decks — e.g., name, general content, sequence
— Instruction forms specifying what is to be done to the input
- Sources of input materials - e. g., control supervisor, operator of a
prior run.
— Disposition of input materials - e. g., return to control supervisor,
pass to operator of a succeeding run.
• Output Expected
The following are representative of the detailed information needed
concerning expected outputs:
- Specify the output(s) expected
- Note any checks or verifications that may be required
— Specify the disposition of the output - e.g., forward to control
supervisor, forward to operator of a succeeding run.
• Procedures
Setup procedures should itemize the logical sequence of operator actions
In selecting and initializing the specified peripherals and the central
processor console so that the programs associated with the run may be
loaded and readied for operation. On-line runs may have a control program
assisting in setup procedures and communicating instructions to the
operator via the control console. Use of preprinted forms or multiple ply
paper for the printer should be noted.
Operation procedures should itemize the logical sequence of operator
actions in loading the input data for entry into the processor and initiating
the run at the console. Attention shall be given to noting the correct
5—5
-------
sequence or order of the reading of data - e.g., control cards for date,
Job nnmber, file ID, etc. followed by data sets and end—of—input cards.
An Illustration of the card deck sequence for each run along with a card
image listing should be included. Similar information should be provided
for any console keyboard messages. Included in this section should be
applicable information on data processor operator communications that
can occur during the run. Specifically, information should be presented on:
— Error messages
- Program normal halts
- Program abnormal halts.
Termination procedures should inform the operator of the sequence of
actions that must be followed in returning the processor and the peripherals
to their standby condition from which setup procedures for the next
operation may proceed, If these procedures are other than standard.
5.3.4 Nonroutine Operations
The purpose of this section is to provide, as applicable, control information and
operator procedures to cover emergency or nonroutine computer operations. Repre-
sentative of the situations that may be covered in the paragraphs of this section are the
following:
• Recovery from a failure condition
• Switchover to a redundant system or to a standby system
• Procedures for turnover to maintenance programmers for system
testing, modification, or debugging
• Normal and priority restart procedures.
Appendix B provides forms that should be helpful in developing Run Documentation.
5—6
-------
5.3 Software Classification Documentation Considerations
The general outline presented in Figure 5-1 is appropriate for any software requiring
computer operator assistance. It, however, should be tailored to properly describe
the specific type of assistance required. Figure 5-2, following this page, presents a
Run Documentation checklist to assess the completeness of Run Documentation.
5—7
-------
FIgure 5-2. Run Documentation Checklist
• Program number and name
• Brief description of the purpose of the program
• Schematic of the operation showing inputs and sequence, card, tape
and disk files, output, and the allocation of Input and output devices
• Input, output formats
• Special operating Instructions relating to computer set-up and take down
• List of messages and programmed halts, if any, and what corrective
action Is required in order to proceed
• Recovery and restart procedures to be followed if equipment mal-
function is found
• End-of-job instructions which advise the operator of the labeling and
disposition of input and output files and reports, run to run balancing
procedures, and other general requirements for end-of-job clean—up
• Esth nted normal run time and permitted maximum run time
5—8
-------
6. USERS DOCUMENTATION
Users Documentation sufficiently describes the functions performed by the software
in non—ADP terminology such that the user organization can determine its applicability
and when and how to use it. It should serve as a reference document for preparation of
input data and parameters and for interpretation of results. It is required for system
and program level software. For subroutine level software, user information is
generally incorporated in the Maintenance Documentation.
6.1 Definition of Users Documentation
Users Documentation explains the purpose and operation of software in nontechnical
terms. Most users are not particularly interested in the coding level mechanics of
software, and will not read bulky documentation. The users manual should be designed
so that a user at each level interfacing with the software, who has no prior exposure
to the software, can read the users manual and be able to use It with no other assistance.
6.2 Documentation Content
Users Documentation should be concise, informative an i nontechnical. The description
of the problem addressed by the software should be brief, and the method, algorithm,
and data structure used by the software should be presented in only enough detail to
enable the user to understand what the software does and why it does it. Flowcharts
and software listings can generally be omitted unless they are essential to the user’s
understanding of the software. Selected test results are generally informative and
should be included. Operating instructions should be clear, concise, and complete.
As with the other software documents, the scope of the documentation must be geared
to the specific application, and is determined by the nature and complexity of it.
Figure 6—1, following this page, presents a suggested topic outline for Users Docu-
mentation. The key topic areas are discussed in detail below.
6.2.1 General Information
This section should briefly summarize the application and general functions of the
software, the computer configuration upon which the software operates, and applicable
references, such as:
6—1
-------
FIgure 6—1. Users Documentation Topic Outline
• Title Page
• Table of Contents
• Revision Page
• General Information
— Sumimiry
- Environment
— References
• Software Snmm iry
— Software Application
- Software Operation
- Equipment Configuration
- Performance
- Data Base
— General Description of Inputs, Processing, and Outputs
• Procedures and Requirements
- Initiation
— Input
- Output
- Error and Recovery
6—2
-------
• Project request document
• Related project documents
• Scientific references.
6.2.2 Software Summary
This section should provide a general overview of the application, software operation
and organization, performance, and input, process and output procedures.
• Software Application
This paragraph describes when and how the software is used and the unique
support provided to the user organization. The description should include:
- Purpose of the software
- Capabilities and operating improvements provided
- Functions performed.
• Software Operation
This paragraph shows the operating relationships of the functions performed
to the organization that provides input to and receives output from the
software. Describes the security and privacy considerations. Include
general charts and a description of the inputs and outputs shown on the
charts.
• Equipment Configuration
Describes the equipment used by the software including type of computer
and input/output devices.
• Performance
This paragraph should present a brief description of the overall performance
capabilities of the software including how it meets the information require-
ments of the user and how it supports associated activities. Perforrrt nce
measures and information of interest may include:
- Input - types, volumes, rate of inputs
6—3
-------
- Output - types, volume, accuracy, rate of outputs
- Response time - Include qualifications, where necessary, that affect
response time in processing operational reports, such as listing a
tape, compiling an object program, etc.
— Limitations — for example, maximum size per unit of input, format
constraints, restrictions on what data files may be queried and by what
location, language constraints
— Error rate - capabilities for detecting various legal and logical
errors and the means provided for error correction
— Processing time - show typical processing times
- Flexibility - note provisions allowing extens ion of the usage of the
system
— Reliability - note system provisions that support, for example,
alternate processing or a switch-over capability.
• Data Base
The data files that are referenced, supported, or kept current by the
system should be described. These files should be identified in operational
or functional terms rather than by program designations. The brief de-
scription should include the type of data in the file and the usage made of it.
• General Description of Inputs, Processing, and Outputs
This paragraph should present a general narrative description of the
inputs, the flow of data through the processing cycle, and the resultant
outputs.
In describing the inputs, consideration should be given to the following:
— Purpose of input - explain why the input is made and note conditions
or events requfrthg its submission
— Content of input - describe what the input contains in the way of
operational, control, or. reference data
— Associated inputs — describe any other Inputs required in addition
to the direct input
- Origin of inputs - identify the source or preparer of the input
- Data files - identify in general or functional terms the data files
associated with the input.
6—4
-------
Processing should describe the relationship of the input to the output
with a general description of the flow of data through the processing cycle.
In describing the outputs, consideration should be given to the following:
— Output - list the outputs produced showing their relationship to the
inputs
— Purpose of output - explain the reason for the output and note con-
ditions or events that require its generation
- Content of output - describe in general terms the information provided
by the output
— Associated outputs - reference other outputs that complement the
information in this output
— Distribution of outputs - note the recipients in the organizations who
receive this output.
6.2.3 Procedures and Requirements
This section should provide Information about initiation procedures, and preparation
of data and parameter inputs for the software. The scope, quality, and logical arrange-
ment of the information should enable the user to prepare required inputs and should
explain in detail the characteristics and meaning of the outputs. It should also describe
error and recovery procedures and requirements.
• Initiation
Describe step-by-step procedures required to initiate processing. Pro-
cedures should include both batch and time—share operations, if appropriate.
Include detailed instructions necessary for initiation, preparation, and
processing of a query application to the data base. Describe the query
capabilities, forms, commands used, and control instructions required.
Provide instructions for terminal operators. Describe terminal setup
or connect procedures, data or parameter input procedures, and control
instructions. Reference related materials describing query capabilities,
languages, installation conventions and procedures, program aids, etc.
6—5
-------
• Input
Define the requirements for preparing input data and parameters, describe
the layout forms used for preparation, and include samples of completed
forms. When defining input preparation requirements consideration should
be given to: conditions, frequency, origin, medium, restrictions, quality
control, and disposition of inputs. Explain each entry on the data preparation
form, referencing it to the sample, and provide detailed instruction for its
completion.
• Output
Describe the requirements for each output, include output formats and
samples. Typical considerations when describing output requirements include:
use, frequency, variations, destination, medium, quality control, and dis-
position of outputs. Explain each item on output with reference to sample
output.
• Error and Recovery
List error codes or conditions generated by the software and corrective
action to be taken by the user. Indicate procedures to be followed by the user
to ensure that any restart and recovery capability can be used.
Appendix B includes forms that should facilitate the development of Users Documenta-
tion.
6.3 Software Classification Documentation Considerations
Users Documentation must be designed based on a consideration of software application
complexity, user responsibilities for data input and/or software operations, and their
ADP skills and experience. As the software application becomes more complex, or
user responsibilities and/or duties become greater, Users Documentation takes on more
significance. Users Documentation should be submitted to the intended users for testing
prior to finalization. This will quickly reveal any gaps or ambiguities in the material.
Figure 6—2, following this page, presents a checklist for assessing completeness of
Users Documentation.
6—6
-------
Figure 6-2. Users Documentation Checklist
• Title Page
• Revision Page
• Software Overview and Summary Description
• Operating Instructions: Batch and Terminal
• Input Data Preparation and Edit Procedures, Including Screen Formats
• Error Conditions and Interpretation
• Codes and Corn m inds
• Options, Special Procedures and Considerations
• Glossary of Terms
6—7
-------
In general, all system and program level software require Users Documentation.
Program level software user information, if an interactive application used primarily
- by programmer/analysts, can be included in Maintenance Documentation. Subroutine
user Information is generally included in Maintenance Documentation.
6—8
-------
7. SPECIAL DOCUMENTATION CONSIDERATIONS
Additional documentation requirements exist if the software produce provides data
to an EPA National System or is to be included in the EPA Minicomputer Software
Exchange. This chapter also provides information on submitting software to other
exchanges, and stresses the Importance of periodic software documentation review by
site management.
7.1 Environmental Information System Interface Requirements
Minicomputer software interfacing with EPA National Systems must conform to their
Interface requirements. These National Systems are identified and described in the
Environmental Information Systems Directory , January 1976. The documentation for
such minicomputer software should be reviewed with the designated person responsible
for the National System to enst.we that it accurately describes its input/output, and
conforms to such systems.
7.2 Software Installation Documentation Requirements
Minicomputer software that has been approved for submission to the EPA Minicomputer
Software Exch uige must also include documentation describing the procedures required
to install the software on another computer.
This documentation should include the following information:
• Description of the software distribution tape or card deck, including
header or label information, format and layout, and similar information
• Description of procedures to follow in setting up and preparing software
for installation, including any options or special features
• Description of compilation and linkage specifications and instructions,
overlay structure, coirntt5lnd and linkage file, and similar software loading
information
• Description of the procedures, with output examples, for testing and
valithting the software installation.
7—1
-------
This Information can be presented as a separate document or included as a section
of the Maintenance Documentation.
7.3_i EPA Minicomputer Software Exchange, FSEP and DECUS Requirements
EPA, GSA, and DEC support software exchanges. The EPA Exchange, called the
EPA Minicomputer Exchange, is described in User& Guide to EPA Minicomputer
Software Exchange , January, 1979. Software candidates must be fully documented
as defined by this document and have agencywide applicability. Software candidate
submission forms for the EPA, GSA (PSEP) and DEC (DECUS) including instructions for
their completion are presented in Appendix C.
7.4 Operations Review Requirements
EPA minicomputer management thould periodically review operations to ensure that
they meet good operating practices. This review should include a sampling of software
documentation to ensure that the documentation guidelines are being properly imple-
mented. The various document outlines and checklists included in this document should
facilitate this review and evaluation. -
7—2
-------
8. RECOMMENDED PROGRAMMING CONVENTIONS AND STANDARDS
This chapter presents minicomputer programming conventions and standards for the
PDP-11/45 and 70 systems.
8.1 Purpose of Conventions and Standards
programming conventions and standards have been set up to be adhered to whenever
feasible in order to:
• Encourage good acceptable programming by all EPA and contractor
personnel
• Improve program readability (clarity) and cut down on maintenance time
• Enable all software to be transferable among sites
• Ensure efficient utilization of the PDP 11/45’s and 70’s at all EPA sites.
Appendix B presents programmer checklists to facilitate the application of these con-
ventions and standards.
8.2 Languages Supported
The standard languages to be used on the EPA Dec PDP 11 minicomputers are the
following:
• FORTRAN IV PLUS V.2.51
• BASIC +2V.I.X
• Macro—il
• INFORM-li
8.3 Software Identification
All software must have the following standard identification as part of the documenta-
tion for each program:
• A unique and identifying program name, e.g., Grants Data Entry System
(GDES)
8—1
-------
• The programmer’s name, e.g., Joe Smith, Jr. Application’s
Programmer
• The source language, e.g., FORTRAN W PLUS V.2.51
• The originating installation, e.g., Region X; Gulf Breeze
• The computer and operating system, e.g , PDP—11/70, lAS V.2.0
• The date the software became operational (turned over to production)
• The date of the most recent revision
• A brief statement of function telling the purpose of the program.
8.4 Nomenclature
The following nomenclature conventions should be used:
• Use self—defining variables and constants wherever possible. The name of
a variable should be a precise indicator of the meaning of the variable
(the same as in its flowchart and descriptions). It is recommended that
all variables be declared explicitly by data type in the program.
• All switches and conditions should be clearly defined. The programmer
should exercise his own discretion as to how extensive the comments must
be in order to convey an understanding of program decision points and to give
other instructions on program logic.
• Error conditions and messages should be short and concise, informative
and self exp1 m tory.
• Each line of code must be numbered. An ideal numbering increment is
ten, for ease of line insertion. This practice facilitates error reporting -—
for Fortran and Macro 11 use Columns 73-80; for INFORM-li and BASIC
use Columns 1-5. See Figure 8-1, following, for examples in INFORM-il
and FORTRAN IV PLUS.
8—2
-------
Figure 8-1. Sequencing (Line Numbering) for Inform-il and Fortran IV Plus
SI’3 = 1.0
IF ‘NC 1 ,2 2
• er —
4 . jW — —
2 NRC = IRB NC”
1 )4 = THETA • 0.017453
TA lK CIEPEFItIED
INFORM
r r iv-- ! P!€ I-PC’S
ECHO OFFU4LCW
0 11’) TEMP ::8PUN. A’ P TEMP ::80FF’ET ’ 2’ C
0015 LO Att.TAFE.LO
fl 1? TYPE — EN T EP Plirl NAME -
002’) I NPUT :n F UN -
00i2 IF 8 ;PUN = 0’ S n TO tflOfl •
0% 125 T’r ’PE — E ’4TEFLTIMEDFFIET
r030 - IN tfT ::#QCF ET . - - -
( %i )3ó Lii EF SrnrcLr TU PECIF.t’AT —
flfl3 NLILH
0040 DISPLAY PUN.NAME,TAPE.NO,USEP.RUN.NAME,tJSEP.FILE.NO,8flOFF ET,CP .;
0050 EXTRACT. NOYEPR. AMPLE.NO.CP a
( 10 55 FPACTION. TYPE. INDUSTPIAL.CAT STAGE. TREATMENT’CP .;
M .GC.C.OLUMN.cfL ‘1AL.LAB FINDING PIJN.NAME = tSPUN -
0€’E6 TERMINAL 4 - -
etoG GO TO 0015 — - —-
1008 :.- . QUIT .- ___________
-- _ _ _ _ _ _ _ _ _
- S -
FORTRAN IV PLUS
PDI> TV t31.3 .313]AXI C.FTN
C...SUEPOUTINE AXflC V068R — 07 ’31J’&9 PRODUCT NIJMPEP 99212 R::C00’)l
c...COPYPIGHT 1968 CALIFORNIA COMPUTER PPODUCTI AcC0002
C........04 CHAP PLOT EBCDIC INCHES A::C0003
UBPOUTINE AXIW tX.1,IBCD.NC.n:E.THETAtYMIN.DY A:CC0004
DIMENSION
-------
• Comments should be used throughout the code for clarity of program logic
and description. Comment lines can also be used for visual clarity and logical
separation of code.
8.5 Structure
The following program structure conventions are recommended:
• It is recommended that the software be organized according to standard
language practices. All housekeeping instructions should be together in
one place.
• Identification and spacing should be used to effectively display the logical
structure of a program. Indentation should be used to show nesting levels
and looping. Figure 8-2, following this page, is an example of nesting in
Inform—il.
• Use spacing to separate logical blocks, and code and text comments.
Standard spacing conventions must be followed for a given language.
• Modular programming techniques should be adhered to in all software
development. Modularization is the technique of dividing a program into
logical units (modules) of not more than about fifty lines. Bugs are located
must faster in small modules as opposed to a lengthy source code of 1000
lines. Clarity and ease of coding are also products of these techniques.
• The use of the FLECS FORTRAN Preprocessor is highly recommended
where feasible. FLECS allows structured programming. The FLECS
listing is indented and separated according to prografli logic and flow.
Figure 8-3, following, is an example of a FLECS FORTRAN Preprocessor
listing.
8.6 Language Restrictions
The following language restrictions are commended:
• All standard INFORM-il features are acceptable. Certain INFORM
practices need to be avoided when possible: e.g., numerous process
re—entries; large sorts; inefficient data base structures.
8—4
-------
Figure 8-2. Program Nesting Example Inform-il
_ _ — - --
.O ECHD’tJFF;I4LJSH
j ) ’PPUCgSS -
& ITNITIFiL
SCREEN FIELDS
t a,. .flrNULL
ACCEPT
3+1 -----:
:NEXT INITIAL
REJECT - “
-‘ t ;3t ]NExT INITiAL
t’ -EISPLA-Y •HC..ES.’
f::- ; -‘--EXIT SCREEN,
- I -
-- - ‘:<- -
- - - - - - - - -w
— - ,c — •- . — - - -
8—5
-------
Figure 8-3. FLECS FORTRAN Preprocessor Listing
a _ — _ — _ — _ aS — — _ _ _ _ — _ _ — _ _ — — — — _ — _ Se
00001 DIMENSION DATA(500,10),YMNS(3) ,YP4XS(3)
00002 DIMENSION Y(4)
00003 DATA Y/4*0./
00004 OPEN (UNIT2,NAMF’MAR1.DAT,TYP ’OLD’)
00005 INITIALIZE—PLOT-ROUTINES
00006 ZERO—COUNTER-HOLD—END
00007 FILL—DATA—ARRAY
00008 MASSAGE-DATA—ARRAY
00009 PLOT-YELLOW-BUOY
00010 PLOT—GREEN—BUOY
00011 PLOT—GRAY—BUOY
00012 CALL PLOT(O.,0.,999)
00013 CALL EXIT
— a S S — e — — — — — as — — — — — a — — — a a 5 a — — — — —
00014 TO CORRECT—DATA-BY—DIVISION
00015 • DO (J2,10)
00016 • • WHEN CJ.EQ.2.OR.J.EQ.5.OR.J.EO.8)
00017 • • • DATA(I,J)—DATA(I,J)/10.
00018 • • •..FIN
00019 • • ELSE
00020 • • . DATA(I,J)—DATA(t,J)/100.
00021 • •
00022 • ...FIN
00023 .,.FIN
— — a — a a — — — — — — — — — — — as — — — — — — — a — — — — — e — — — — — — —
00024 TO CONVERT—TIME DATA(INO,l)FLOAT(60*IHR+IMIM)
— S — — — — — — — — Seas — S 000 C — — — — — — — S — C — — — — — —
00025 TO CORRECT—DATA—FOR—DOUBLE—TIMES
00026 • IF (DATA(I+1,1) .EQ.DATA(I,1))
00027 . • COMBINE—DATA
00028 . . REARRANGE—ARRAY
00029 • • IENDIEND—1
00030 • •..FIN
0003i •..FIN
• — a — — — a — a — — — e S — — — — — a — — — e a — — — — — — — — — — — — —
00032 TO C0MBtNE DATA
00033 • DO (J2,10)
00034 • . DATA(I,J) (DATA(I,J)+DATA(I+1,J))/2.
00035 • •..FIN
00036 •..FIN
—5 SSS — — — — — a — a — C — e S — — — — as — — — a — — a as
8—6
-------
• All standard DEC FORTRAN IV PLUS features are acceptable. Try tø
avoid the BACKSPACE Command.
• All standard DEC BASIC + 2 features are acceptable.
• All standard DEC MACRO -il features are acceptable. The programming
standards and conventions found in IAS/RSX 11 MACRO-il Reference
Manual , Chapter 2, must be adhered to.
8.7 Hardware Restrictions
The following hardware restrictions are recommended:
• The maximum program size Is 32K.words. It has been found that extremely
large programs have had unexplained problems especially when they are
using the SORT package. Large programs which have requirements for
overlaying must have their overlay structures included in the documentation.
• Input/output device usage Is restricted to the standard configuration devices.
• Processing modes available are real time, timesharing and batch. All
real time programs require approval by the System Manager.
Program and system software with the following characteristics must be run in batch mode:
• 2 minutes of CPU time
• 1000 print lines of output
• Large INFORM sorts -
• Large models and statistical programs.
If any question arises about whether a system/program can be run in timesharing
mode consult with the appropriate System Manager.
• Console messages should be kept to a minimum. Under normal situations
only standard system messages should be sent to the operator’s console.
8—7
-------
8.8 Other General Considerations
Additional programming standards and convention considerations include:
•. All software should be written as general as possible in order to facilitate
transportability among sites. Make programs flexible in order to
accommodate changes: e.g., use parameter to define array sizes; use
- symbolic unit designators in input/output statements: do not specify UIC’s
In “OPEN” statements wherever feasible. All constants should be
parameterized; make use of the “INCLUDE” Statement in FORTRAN.
• Complex expressions should be broken up into smaller, less complicated
statements. Comments used to explain the complexity of the expressions
will help clarify the problem.
• “Clever” coding should be avoided. Obscure code is harder to debug, thus
cancelling any savings which may accrue from greater efficiency.
• All program output should be able to stand by itself. Proper identification
should be on au output pages.
8—8
-------
APPENDIX A
RECOMMENDED FLOWCHARTING CONVENTIONS
A-i
-------
APPENDIX A
RECOMMENDED FLOWCHARTING CONVENTIONS
Flowcharts are required for system software projects, and recommended for program
and subroutine effects. All flowcharts should be drawn on a standard diagramming and
charting worksheet. The st indard symbols for flowcharting are presented in Exhibit A-i
at the end of this appendix.
General Rules for Flowcharting
- Listed below are some general groundrules to follow when developing flowcharts.
• Layout
Draw the flowchart from top to bottom and from left to right.
• Template
Use the flowchartthg template that produces the ‘TIPS Flowchart Symbols”
which conforms to FIPS 24.
• Flowchart Descriptive Text
Descriptive information contained on the flowchart should read from left
to right and top to bottom.
• Symbol Descriptive Information
Descriptive information used to clarify, identify or define a symbol should
be placed above and to the right of the symboL
• Common Connector Identifiers
Letters should be used within connector symbols to identify logic continuations.
• Multiple Exits from Symbols
These should be shown by general flowlines from the symbol to other
symbols or by a single flowline which branches into the appropriate number
of flowlines.
A-2
-------
. Multiple Symbol Exit Identification
Decision
Statement
Paths
Each exit from the symbol should be identified to indicate the logic that
It represents. Each logic path may be represented by the appropriated
number of Identified flowlines or a branching table. A sample branching
table is presented below.
CODE
Branching
Table
CODE EQUAL TO
GOTO
1
CONNECTOR A
2
CONNECTOR B
3
CONNECTOR C
4
CONNECTORD
A—3
-------
EXHIBIT A-i
SYMBOL USE
1. INPUT/OUTPUT
2. PROCESS
3. FLOWLINE
/
/
STANDARD FLOWCHARTING SYMBOLS
A. BASIC SYMBOLS . A basic symbol is established for each
function and can be always used to represent that function.
Specialized symbols are established which may be used in
place of a basic symbol to give additional information.
____________ This symbol represents the input!
________ output (I/o) function, i.e., the
making available of information
for processing (input) or
recording processed information
(output).
________ This symbol represents the processing
function i.e., the process of
executing a defined operation or -
group of operations resulting in a
change in value, form, or location
of information or in the determination
___________ of which of several flow directions
are to’be taken.
_________ This symbol represents the flow].ine
function, i.e., the indication of
____________ the sequence of available infor-
mation arid executable operations.
___________ This symbol represents the annotation
________ _________ function, i.e., the addition of
descriptive comments or explanatory
notes as clarification,
_______ This symbol represents an operation
using a key driven device — such as
punching, verifying, typing.
B. SPECIALIZED I/O SYMBOLS . Specialized I/O symbols may represent
the I/O function and, in addition, denote the medium on which
the information is recorded or the manner of handling the
iñformatiôn or both. If no specialized symbol exits, the basic
I/O symbol may be used,
4. ANNOTATION .
5. KEYING
I—. — —
A-4
-------
SYMBOL
USE
1. PUNCHED CARD
r I
2. MAGNETIC TAPES .
For an I/O function in which the
medium is punched cards, including
mark sense cards, partial cards, stub
cards, etc.
______________ For an I/O function in which the
medium is magnetic tape.
___________ For an I/O function in which the
medium is punched tape.
4. DOCUMENT . For an I/O function in which the
medium is a document.
I I
____________ For an. I/O function in which the
information is entered manually
at the time of processing, by means
of online keyboards, switch settings,
push buttons, card readers ,etc.
_______ For an I/O function in which the
information is displayed for human
use at the time of processing, by
means of online indicators, video
devices, console printers, plotters,
etc.
__________________ For an I/O function in which inf or-
mation is transmitted automatically
from one location to another.
_____________ For an I/O function in which infor-
mation for processing (input) or the
recording of processed information
(output) is stored online on magz etic
drum. — -
A-5
5. MANUAL INPUT .
6. DISPLAY .
7. COMMUNICATION LINK .
8. MAGNETIC DRUM .
3. PUNCHED TAPE .
-------
SYMBOL
9. MAGNETIC DISK . —
10. TRANSMITTAL TAPE
11. ONLINE STORAGE .
12. OFFLINE STORAGE
USE
_____________ For an I/O function in which infor-
______ matiori for processing (input) or the
_______ recording of processed information
(output) is stored online on magnetlô
disc.
_______________ Proof or Adding Machine tape, or
other batch control information.
______________ For an I/O function utilizing
auxiliary mass storage of inf or—
mation that can be accessed online,
e.g. n agnetIc drums, magnetic discs,
magnetic tape, automatic magnetic
card systems, or automatic chip or
strip systems.
________________ For any off line storage of inf or—
mation, regardless of the medium on
which the information is recorded.
____ Represents an I/O function in which
the medium is magnetic core.
C. SPECIALIZED PROCESS SYMBOLS . Specialized process symbols
may represent the processing function, and in addition,
identify the specific type of operation to be performed on
the information. If no specialized symbol exists, the
basic process symbol may be used.
SYMBOL USE
1. DECISION . Represents a decision or switching
type operation that determines which
of a number of alternate paths it is
to be followed.
13. CORE .
A-6
-------
SYMBOLS
USE
2. PREDEFINED PROCESS -
—
3. AUXILIARY OPERATION .
4. MANUAL OPERATION .
5. CONNECTOR .
0
6. TERMINAL .
cii
7. PREPARATION .
9. MERGE .
Represents a named process consistin
of one or more operations or prograi
steps that are specified elsewhere.
e.g., subroutine or logical unit.
Represents an off line operation
performed on equipment not under
direct control of the central pro-
cessing unit.
Represents any of fline process
geared to the speed of a human
being.
Represents a junction in a line
of flow.
Represents a terminal point in a
system or communication network
at which data can enter or leave.
e.g., start, stop, halt, delay or
interrupt.
Represents modification of an in-
struction or group of instructions
which change the program itself,
for example, set a switch, modify or
index register, and initialize a
routine.
Represents merging with extracting,
that is, the formation of two or
more other sets.
Represents the combining of two
or more sets of items into one
set.
8. COLLATE .
A-7
-------
SYMBOLS
10. EXTRACT .
12. PARALLEL NODE .
USE
Represents the removal of one or
more specific sets of items from
a single set of items.
Represents the arranging of a set
of items into a particular -sequence
Represents the- beginning or end -
of two or more simultaneous
operations. - -
3.1. SORT .
A-8
-------
APPENDIX B
DOCUMENTATION SAMPLE FORMS
B-i
-------
SOFIWABE CHA E RECORD
CHG. DATE DATE
RECEIVED MADE DESCRIPTI APPROVED “
(1) (2) (3) (4) (5)
PAR1 S OF FORM
1. Sequential number assigned to the
thange.
2 • Date the thange request was received.
3. Date the d anged program(s) became
operational.
4. Brief description of c±iange.
5. Signature of manager, usually systems,
who approved the diange.
B—a
-------
INPUT-OUTPUT DESCRIPTION
A sample Input-Output Description form is presented on the following page.
The 13 Items, listed below, provide an explanation of the specific parts of the
exhibit.
1. Record name
2. Function-—such as transaction input, master file.
4. Software-software name and/or number.
5. Run--run name and/or number.
6. Analyst--name of analyst who prepared description.
7. Date--date description was originally prepared.
8. Revised——date current revised description was prepared.
9. Field Name—-such as “account number.”
10. Size—a number indicating quantity of characters, bits, etc. in the field.
11. Data Type-—if known, the analyst identifies the data type as bits, integer, etc.
12. Key—if the field is a sequencing or identifying key of the record, a digit
Is recorded such as: 1 = Primary key; and 2 = Secondary key.
13. Remarks——indicates characteristics of the field, such as “computational,”
“check digit included,” “validation required,” etc.
B-3
-------
- — Record Name
Software - - -
Function ( 2)
( 5 )
Revised
nwur-CUIPUT DESCRIPTI(XJ
______ Media ( 3 )
na1yst ( 6 )
(8) ____
uata
—
Size
Type
Key
Remarks
(10)
(11)
(12)
(13)
I
(1)
Date (7)
B-4
-------
REPORT DEFINITION SKEET
1. Report name: Identifying name and/or number
2. Softwaie: identification of software that produces report
3. Run: Identification of run that produces report
4. Analyst: name of the preparing analyst
5. Date: original preparation date
6. Revised: date of current revision
7. Line number: number of the print line, e.g., from 1-66.
8. Field definition: Identification of the printed field
9. Field size: maximum number of characters In the field
10. Print location: limit positions on the print line such as 80-95
11. Remarks: any additional requirements.
12. *Headjng: this section of the sheet defines the heading fields
13. *Data elements: this section of the sheet defines the body of the report
14. *Subtotals and totals: this section of the sheet defines all totals and subtotals
*Note that these three terms are not pre-printed on the sheet but are written by the
rnR1yst.
B-5
-------
REPORL ’ DEFINITICN SHE
Report name ( 1) Software (2) ( 3 )
klalyst ( 4 ) Date ( 5 ) Revised ( 6 )
LINE
- NUMBER
FIELD
DEFINITIQ
FIELD
SIZE
PRINT
LOCATIC J
RF14ARKS
BEADING (12)
(7) (8) (9) (10) (11)
D PA EE 1 EL4ENTS (13)
SUB-TOI ’ALS - & TO1’ALS (14)
___________ ____________ ___________ - j
B—6
-------
RECORD FORMAT
1. Check disk or tape box to indicate record media.
2. Check 7- or 9-track box to indicate recording device.
3. Check one box to indicate tap density.
4. Indicate type of file organization used to store records. File organization
may be: sequential, Index sequential, direct, or positioned.
5. Specify the type of file label:
• NL--No Label
• SL—Standard Label
• NSL--Non-Standard Label
6. SpecIfy the size (In bytes) of the record. If record is variable, specify
the minimum and maximum size.
7. Specify the number of records allocated to a physical block.
8. Indicate the type of record format:
• F-—Fixed Record
• V--Variable Record.
B-7
-------
FILE NUMBER&T TLE (Description) I
EFFEC rIVE 1 DATE REVISIQ DATE -
PAGE
SOFTWARE I.D.
rAPE
(2) Track (3) — 800 BPI
9 Track — 1600 BPI
LABEL (5)
— NL
NO. OF RECORDS/BLOCK i
RECORD NAME
)ISK
FILE ORGANIZAPIQ
(4)
LENGTh OF RE(X)RD I
TARIABLE OF FIXED
(8)
FILE NAME
Provide in this space complete description of input and output
records. Record description is divided into three parts:
o File Description.
o Record Format.
o Description of Record Data Elements.
1 2 3 4 5 6 7 I 9
r’r 2 r 3 r r 5 56 5 i r 9 r°r
-------
DATA ELEMENTS
1. Item-—sequential number assigned to a field.
2. Unique name of the data element (field).
3. Description of the data element with a possible range of specific values for
that element.
Example: EYES 1—Black
2-—Blue
3—Green
4. Size of data element expressed by bytes.
• Express Ion refers to the actual number of characters, rather
fh n the storage space It occupies.
• Indicate if element Is alphanumeric (AN) or numberic (N).
NOTE : If the record is used by more than one system and/or program, the
other systems and/or programs mt t be identified beneath the page headIng.
B-9
-------
EFFECI’IVE DATE REVISI 1 DATE PAGE
INPU r/OCTPtJr DES RIPTIQ 1
Data Elements SOF.LWABE I.D.
REO BD LAY JT
RECORD
- FIELD SIZE -
______ ___________________ ______________________ ( Length/Type )
(1) (2) (3) (4)
R 1fl -.
-------
APPEND]X C
SOFTWARE SUBMISSION FORMS
c -i
-------
APPENDIX C
SOFTWARE SUBMISSION FORMS
EPA Minicomputer Software Exchange (MSX), Federal Software Exchange Program
(PSEP), and Digital Equipment Computer Users Society (DECUS) Software Submission
Forms.
C-2
-------
EPA MINICOMPUTER SOFTWARE EXCHANGE
SOFTWARE SUBMISSiON FORM
01 TYPEOFSUBMISSION:
o NEW SOFTWARE Q SOFTWARE UPDATE 0 SOFTWARE DELETION
02 SOFTWARE NAME AND VERSION
03 OPERATiONAL DATE 04 MOST RECENT REVISION DATE
05 DESCRIPTIVE TITLE
06 SOFTWARE TYPE:
o SYSTEM 0 PROGRAM 0 SUBROUTINE
07 SOFTWARE CATEGORY: o STATISTICAL
o DATA ENTR’t 0 TEXT/DOCUMENTATION 0 DATA MANAGEMENT
o GRAPHIC 0 MODEL /REPORT GENERATOR
o UTILITY 0 SYSTEM ENHANCEMENT 2 TEM
08 KEYWORD DESCRIPTORS
00 SOFTWARE AUTHOR
itO TECHNICAL CONTACT (NAME, LOCATION, TELEPHONE)
SOFTWAREO ESCR IPTION (PURPOSE, PROCEDURE(S). FUNCTiON(S), OR ALGORITHM(S),
PROGRAM LOGIC, DATA INPUT AND OUTPUT, REFERENCES.) -.
112 PROGRAM LANGUAGE I 13 NUMBEROFSOURCESTATEMENTS
I 14 MINIMUM SYSTEM REQUIREMENTS:
- — COMPUTER MODEL AND SPECIAL FEATURES
— MAIN MEMORY SIZE
15 PROCESSING MODE:
o REALTIME 0 TIMESHARE 0 BATCH 0 COMBINATION
DOCUMENTATION AVAILABILITY 0 MAINTENANCE DOCUMENTATION
0 RUN DOCUMENTATION
3 SYSTEM/SUBSYSTEM DOCUMENTATION 0 USERS DOCUMENTATION
— OPERATING SYSTEM
— SYSTEM OR CATALOG ROUTINES
— PERIPHERAL DEVICES
- C-2
-------
SOFThARE SUBMISSION FORM
(CONTINUED)
17 OPERATION HISTORY:
— LENGTH IN OPERATION
— CERTIFICATION OF VALIDITY
-
— FREQUENCYOF USE
‘18 RESOURCE DEVELOPMENT INFORMATiON:
— MONTHS TO DEVELOP J — DOLLAR ESTIMATE
— PERSON MONTHS OF EFFORT 1
18. BRANCH CHIEFIADP COORDINATOR APPROVAL
20 SOFTWARE DISCRIPTION CONTINUATION
C—4
-------
Instructions for Software Submission Form
01 Type of Submission . Indicate whether the software is a new submission,
an updated version of previously submitted software, or to delete previously
submitted softw e because It Is noiónger supported (applies only to category
2 and 3 software.)
02 Software l’kme and Version . Enter software title, acronym, and version number,
if appropriate.
03 Operational Date . Enter date software obtained production status; use month,
day, and year format. -
04 Most Recent Revision Date . Enter date of most recent software revision,
of any); use month, day, year format. -
05 Descriptive Title . Provide a title that describes the purpose or function of
the software.
06 Software Type . Indicate whether the software submission is a system, program,
or subroutine. See Chapter 2 for definitions.
07 Software Category . Indicate primary category where the software belongs.
See Chapter 2 for category definitions.
08 Keyword Descriptions . List significant words or phrases which reflect the
functions, applications and features of the software, separate entries with
semicolons.
09 Software Author . Indicate name of progrpmmer.
10 Technical Contact . Enter person(s) or office(s) to contact for technical
information on software, include location and telephone number.
11 Software Description . Provide concise information on the problems addressed
and methods of solutions; procedures, functions, or algorithms employed;
summary of program logic; description of data input and output; any pertinent
mathematical or system references.
12 Program Language . Indicate source language: FORTRAN IV Plus, MACRO U,
INFORM U, or BASIC +2.
13 Number of Source Sl2tement! . Include total number of statements, including
macro, function, and subroutine statements.
C-5
-------
14 MInimum System Requirements . Indicate minimum hardware/software con-
figuration required to compile and execute the software. -
15 Processing Mode . Indicate what mode the software has been designed to
execute under. -
16 Documentation Avallabi j y . Indicate what software documentation is available.
See EPA Documentation and Programming Guidelines for Minicomputer Software
p nualfoi definiti.o s and_mini1 uni reqt rements. -
17 Operation History . Provide frequency and use data on the software; Branch
Chief/ADP Coordinator or user must state that it produces design results. -
18 Resource Development information . Provide reasonable estimates of time,
number of person months, and cost required to design, devilop, test and
validate the software.
19 Branch Chief/ADP Coordinator Approval . Must obtain signature of Branch
Chief/ADP Coordinator.
20 Software Description (Continuation). Continuation of description from Block 11.
C-6
-------
EPA MINICOMPUTER SOFTWARE EXCHANGE
DECUS PROGRAM SUBMISSION FORM
01 PROGRAM TITLE
02 PROGRAM AUThOR (NAME, ADDRESS)
03 PROGRAM DESCRIPTION (PURPOSE. OPERATiON. REFERENCES)
04 MINIMUM HARDWARE REQUIREMENTS
05 STORAGE REQUIREMENTS 06 OPERATING SYSTEM
07 OThER PROGRAMS NEEDED
08 RESTRICTIONS
09 MISCELLANEOUS
10 SOURCE LANGUAGE
C—7
-------
Instructions for DECUS Program Submission Form
01 Program Title . Enter software title.
02 Program Author . Enter author’s name and complete address.
03 Program Description . Provide concise information on the problem addressed
and methods of solutions; procedures, functions or algorithms employed
amninary of program logic; description of data input and output; any pertinent
mathematical or system references.
04 - Minimum Hardware Requirements . State main frame, I/O device and special
hardware devices.
05 Storage Requirements . State minimum main storage required to run the
program.
06 Operating System . State operating system under which software is operated.
07 Other Programs Needed . List any ancillary programs needed.
08 Restrictions . Note any special requirements or restrictions not stated above.
09 Miscellaneous . Note any other Information you feel should be included for
correct performance of the software.
10 Source Language . Identify the progrn-mn ing language in which the software
is written.
C-8
-------
FEDERAL INFORMATION PROCESSING STANDARD SOFTWARE SUMMARY
ói himmaryJ.Ur
Yt. I MO. I 0 iY
02. Summ i> pr.pa:cJ by .n.)
NCW Replacement Deletion
Ptcvsovs Internal Soitware ID
IL I I I L OS. eftwate titic
04. Sultware dilL
i IMo• 1 ) Y
1111E:
06. Short i d e
software
08. Sot iware typc
Automated Data
0 System .
0 Computer Program
0 Subroutine/MOdUle
09. P:eeessing
mode
lnteraciiv.
r:i Batch
c:i Combination
10.
General Application Specific
Computer Systems )Ja gemen t/
[ J Suppoii,’Ut ity Business
LScientific/Eng ineering Process Coutrolt -
) Bibliographic/Textual Other
11. Submkdng organization and addtess
contact(s) phone
13. Narrative
14. Keyword.i
Number of
15. Computer msntaf’r and modeL
19. Computer memory requIrements
16. Computer operating yscem
17. Programming language(s)
source program
statements
22. Terminals
20. Tape drives
units
23. Other operational requirements
24. Software availabiiity
A ilabI e Limited In-house only
0 0 0
25. Documentation availability
Available Inadequate In-bouse only
0 0 0
STAIIOARD F3cu in
JULY :97k
U.S DCPT. C0MMERC 4’5S
,ws. eve. :e
C-9
-------
INSTRUCTIONS
C I. 5 ,mory Dote, Enter d ii . summary prepared. Use Year, Month, Day format: YYMMDO.
G2. 5umn ery P,.pored By. Ester name and phone number (isciuding area code) of indiyijuil who prep ted this summary.
03. Sui,.me’v Action. Mark the apprupriare bos for n. summary, replacement sumstlary 0: d.Ieflon of summary. If this software sum—
g ,a.-y is a replacement, enter under “Previous Internal Software ID” the internal soltwa :e ulentihcaeion as reported in item 07 of
the original summary. and enter the new inte,nal softaare ijentilicatio., in item 0? of thu ‘orm complete all other items as for a
new summary. Ii a software summary is to be d.Ieted, enter under “Previous Internal Software ID” the internal software idcnti—
fication as reported is item 07 of the original summary; complete only items 01. 02.03 and ii on this form.
04. Sefnoor. Dote. Enter date software was completed or last upLiced. Use Year, Month, Day format: YYMMDD.
05. Soft’s’. T;tl.. Make title as descriptive as possible.
06. Sh.rt Title. (Optional) Enter commonly used abbreviation or acronym which identifies the software.
. Internal Software ID. Enter a unique identUicarion uumber or code,
CS. Sofia. ,. Typ.. Mark the appropriate boa for an Auioms..sd Dote System (set of computer programs. Compute. Program, or Subrou.
tLn./Medule. whichever best describes the sottware.
09. Proc. slng mode. Mark the appropriate box for an Interactive Botch, or Combination mode, whichever best describe, the soft-
ware.
10. Applicotion Area.
G.n.rol: Mark the appropriate boa which best describes the Eenerat area of application fron, among:
Computer Syst.ma S ppert/UtiHty Process Control
Monogem.nP/Bushi.ss Bibllogrophic/Tes puol
SclentiIc/Eng ine.ring Other
Speedlm Specify the subarea oi application; e.g.: “COBOL optimizer” if the general area is “Computer Systems Supportf
Utility”; “Payroll” if the general area is “Management/Business”; etc. Elaborate here if the general area is “Other.”
11. Submitting Orgsnisaflon and Address. Identify the organisacioe esponsible for the software as completely as possible, to the
Branch or Division level. but including Agency, Department (Bureau/Administration), Service, Corporation, Commission, or Coun-
cil. Fill in complete mailing address, including mail eade, street address, city, stale, and ZIP code.
13, Technical Contact(s) and Phone. Enter person(s) or office(s) to be tontscted for technical information on subject matter anJ,’or
operational aspects of software. Include telephone area code. Proyide o:ganization name and mailing address, if different from
thatiaitem ll.
13. NarratIve. Describe concisely the problem addressed and methods of solution. Include significant factors such as special opera—
ii g system modifications, security concerns, relationships to other software, input and output media, virtual memory requirements,
sod snque hardware features. Cite references, ii appropriate. -
14. Keywords. List sgnWicairi words or phrases which reflect the functions, applications and features of the software. Separate
carries with semicolons.
IS. Computer Manufacturer and Model. Identify mainframe computer(s) on which software is operational.
16. Computer Op.roting System. Enter name, number, and release under which software ‘is operating. Identity enhancements in the
Narrative (item 13).
17. Programming Language(s). !dentif ‘the language(s) in which the software’is written, incl’4iag version; e.g.. ANSI COBOL,
FORTRAN V. $IMSCRIPT 11.5, SLEUTH II.
18. Number of Source Program Statements. Include statements in this software, separate macros, called subreutises, etc.
19. Computer Memory Requirements. Enter minimum internal memory necessary to execute software, exclusive of memory ,e.uited for
the operating system. Specify words, bytes, characters, etc., and number of bits per unit. Identify virtual memory requirements in
the Narrative (item 13).
20. Tap. Drives. Identify number needed to operate software. Specify, if critical, maniJacmuree, model, tracks, recording density, cit.
21. Disk/Drum Units. Identify number and size (in same units as “Meniory”4iem 19) needed to operate software. Specify, if critical,
manufacturer, model, etc.
22. Terminols. Identify number of terminals required. Specify, if critical, type, speed, character set, screen/line size, etc.
23. Other Op.rotonal Requrements. Identify peripheral devices. support software, or related equipment not indicated above,
e.g.. optical churaccer devices, facsimile, cornputer urpuc m,crorslm, graphic plotters.
24. Soft —or. Avnlob lity. Mack the appropriate boa which best describes the s frwa,e availability front among: Available to the Pub.
lie, Limted Availability (c. .: for o c :ncnent use only), snd F., ln.hous. Us. Only. If the software is “Available”, include..
mail or phune contact point, as well ta the price and form in which the software is available, it possible.
25. Docur ,entotion A a.IobIlt,. Mark the appropriate box which best describes the documentation availability from among: Available
to the Public, Inedequere fu’ Distribution. ant For ln.house Us. Only. If documenca:wn is “Available”, include a mail or phutic
contact point, ac well as the price md form in shich the documentation is available, it possible. II documentation ic presently
“lnadelu.ue”. show the espectc’d availability djtc.
26. F., Subm;tting Organ zoton Use. This ate,, is pruviJed to: the use of the organization submitting this summary. It nmay contain
3?) infcmnmacion Jee iued u ,eEuI fur internal opvtniiun.
.C —10 8. S. CWEP3 t T p1t .Tt C OFFtcC 1 5e4 0
-------
APPENDIX D
PROGRAMMER. CHECKLISTS
D-1
-------
A PROGRAMMEP’3 CRECKLIST
Program
Programmer
Date Started ____________ Date Completed
o 1. Problem specifications prepared and checked with originator
o a. Statement of problem
o b. Input/output specifications
o e. Restrictions and constraints
o 2. Algorithms and data structures selected and checked
Cl a. Search for existing algorithms—check of suitability
o b. Search for existing programs
O e. Development of specialized algorithms
C d. Verification and error analysis of algorithms
o e. Selection of data structures
O f. Consultation
o 3. Selection of language(s)
o 4. Program logic and structure
o a. Modularization
o b. Flowcharts—organization
o c. Plowcharts—neatness and readability
C d. Module structure
0e. Debugging design
o 5. Coding
o a. Module labeling
o b. Statement labeling
Cl c. Variable names
o d. Source code formatting
o e. Organization of control and informational statements
o f. Comments and visual impact
C g. Flexibility
ci h. Code written legibly, confusing characters distinguished
O i. Use of standard language; nonstandard statements isolated
o j. Input and output data formats
C k. Code checked
o 6. Checkout
o a. Review of problem statement
o b. Review of algorithms/data structures
Cl c. Review of program logic and structure
O d. Recheck of code
o e. Check of keypunching or other transcription
o f. Desk check of program
0 g. Compilation/assembly/loading (diagnostic)
O h. Test data prepared
o i. Debugging
C j. Program verification
O 7. Revision of algorithms, flowcharts, code, etc.
C 8. Documentation
a. Problem statement
C b. Algorithm and data structure descriptions
C c. Program logic and structure description
C d. Program listing (commented and sequenced)
Cl e. Testing procedure write-up (including test data listing)
C f. Operating instructions
D-2
-------
PROGRAM MAiNTENANCE
CHECKLIST
Program
Programmer
Date Started _________ Date Completed
o 1. Documentation of error
D a. Symptoms
o b. Conditions under which it occurs
o 2. Determination of necessary corrections
o a. Check that proposed repair will work
Q b. Cheek effect of proposed repair on rest of program
C 3. Checkout of correction
C a. Desk check
o b. Cpmpilation/assembly/Ioading (diagnostic)
o c. Test data prepared
o d. Debugging
o 4. Documentation
C a. Errata to problem specifications
o b. Errata to algorithm descriptions
e. Errata to program logic and structure descriptions
C d. Errata to program
o e. Errata to operating instructions (if any)
C 5. Distribution of correction
D-3
-------
APPENDIX K
UflRENC
let
-------
REFERENCES
1. Automatic Data Processing (ADP) Manual, March 1975.
2. - Users’ Guide to EPA Minicomputer Software Exch inge, January, 1979.
3. IAS/R.SX 11 MACRO-il Reference Manual, Digital Equipment Company.
4. EnvIronmental Information Systems Directory, January 1976.
5. - Guidelines for Preparing and Reviewing Feasibility Studies, April 1977.
E-2
------- |