- 2.5.4 Document Standards
- 126.96.36.199 Introduction to System Documentation
- 188.8.131.52.1 System Documentation Purpose
- 184.108.40.206.2 System Documentation Scope
- 220.127.116.11.3 System Documentation Background
- 18.104.22.168.4 System Documentation Responsibilities
- 22.214.171.124 General Preparation Standards
- 126.96.36.199.1 System-ID
- 188.8.131.52.2 Standard Page Information
- 184.108.40.206.3 Page Size
- 220.127.116.11.4 Page Numbering
- 18.104.22.168.5 Naming Conventions
- 22.214.171.124.6 General Rule
- 126.96.36.199.7 Original Run Packaging Considerations
- 188.8.131.52.8 Preparation For Publication
- 184.108.40.206.9 Transmittal Number and Transmittal Dates
- 220.127.116.11 Data Dictionary Purpose
- 18.104.22.168 Project Library Purpose
- 22.214.171.124 System Description Documentation
- 126.96.36.199.1 System Description Standard
- 188.8.131.52.2 System Description Purpose
- 184.108.40.206.3 Contents and Organization
- 220.127.116.11.4 Preparing a System Description
- 18.104.22.168 System Schematic Diagram Documentation
- 22.214.171.124.1 System Schematic Standard
- 126.96.36.199.2 System Schematic Purpose
- 188.8.131.52.3 System Schematic Background
- 184.108.40.206.4 Contents and Organization
- 220.127.116.11.5 Preparing a Schematic Diagram
- 18.104.22.168.5.1 Run Numbers
- 22.214.171.124.5.2 File Numbers
- 126.96.36.199.5.3 Charting Rules
- 188.8.131.52.5.4 Terminal and Connector
- 184.108.40.206.5.5 Run/Operation Box
- 220.127.116.11.6 Multiple Processes on Schematic Diagrams
- 18.104.22.168 Run Description Documentation
- 22.214.171.124.1 Run Description Standard
- 126.96.36.199.2 Run Description Purpose
- 188.8.131.52.3 Run Description Contents and Organization
- 184.108.40.206.4 Preparing Run Descriptions
- 220.127.116.11 Data Specification Documentation
- 18.104.22.168.1 Data Specification Standard
- 22.214.171.124.2 Data Specification Purpose
- 126.96.36.199.3 Data Specification Contents and Organization
- 188.8.131.52.4 Preparing Data Specifications
- 184.108.40.206 Computer Operations Handbooks (COH)
- 220.127.116.11.1 COH Standard
- 18.104.22.168.2 COH Purpose
- 22.214.171.124.3 COH Organization
- 126.96.36.199.4 COH Forms
- 188.8.131.52.5 COH Language Considerations
- 184.108.40.206.6 COH Paging
- 220.127.116.11.7 Operator Messages
- 18.104.22.168.8 IBM COH Guide
- Exhibit 2.5.4-1 Project Library Contents Development Phase
- Exhibit 2.5.4-2 Sample System Description Outline
- Exhibit 2.5.4-3 Schematic DiagramTitle Block
- Exhibit 2.5.4-4 File Media Symbols
- Exhibit 2.5.4-5 Processing and Control Symbols
- Exhibit 2.5.4-6 Sample Schematic Diagram
- Exhibit 2.5.4-7 Sample Data Specifications
- Exhibit 2.5.4-8 File and Record Index (Instructions)
- Exhibit 2.5.4-9 Record Layout
- Exhibit 2.5.4-10 IBM Core Record Layout
- Exhibit 2.5.4-11 Instructions for Completing the IBM Core Record Layout
- Exhibit 2.5.4-12 IBM Layout Reference
- Exhibit 2.5.4-13 Form 3864
- Exhibit 2.5.4-14 Instructions for Completing Form 3864I/O Units
- Exhibit 2.5.4-15 Form 3864A
- Exhibit 2.5.4-16 Instructions for Completing Form 3864ASet Up
- Exhibit 2.5.4-17 Form 3864D
- Exhibit 2.5.4-18 Instructions for Completing Form 3864DMessage List
- Exhibit 2.5.4-19 Instructions for Completing the IBM COH Guide
- Exhibit 2.5.4-20 IBM COH Guide
Part 2. Information Technology
Chapter 5. Systems Development
Section 4. Document Standards
The introduction provides the purpose, scope, background, and responsibilities of system documentation.
The purpose of this manual is to provide standards and guidelines on the preparation of deliverables that constitute documents.
The SDLC requires the completion of mandatory documentation for each phase and stage of software project development.
The standards and guidelines detailed in this manual apply to all software development projects within the IRS.
The software development process results in a significant amount of documentation. In developing a system, each piece of documentation is an essential building block upon which the next phase is created. Upon completion of a project, certain deliverables, such as module specifications, schematic diagrams, and Computer Operations Handbooks, are kept as formal documentation.
The ADP standards are intended to promote consistency among system documentation.
Applications Development personnel must adhere to the standards as outlined in this guideline.
If compliance to the established standards for system documentation is impossible: because of system specific characteristics, imposition of unreasonable costs, or for other valid reasons is considered not to be in the best interest of the Service, then an application for a Standards Waiver must be submitted to the National Office Software Quality Group.
These general preparation standards provide for the various components of the system documentation.
Assign a System-ID to each system. In the cases where the structured methodology is used, computer specialists determine the scope of a system by the context diagram in the system’s Functional Specification Package (FSP).
The System-ID must appear in the page header, and serves to link the individual development documents.
Every page of applications documentation within an organization/project must contain standard header data. The following type of information will be included on each page for identification purposes:
Project number (optional)
Related Analysis Specification Document number, e.g., FSP number, when available
Responsible organization. Region, Service Center, Division; branch/section; person’s name (optional)
Run/file/record reference number
For Schematic Diagrams, this information will appear in the title block of Form M–4327 or comparable form.
Page size considerations must lead to neat packaging of the document without sacrificing legibility. Reduce oversize pages to 81/2" by 11" for final publication.
Each page will be assigned Arabic numerals sequentially to the end of the document. When adding new pages between those already issued, a decimal system will be used (e.g., to insert a page between 7 and 8, assign it page number 7.1).
If electronic media is used, or a specific type of documentation could be more advantageously numbered, choose the best method of numbering and insertion specific to the system.
The names of programs, modules, files, groups (including records), and items, must be in accordance Data Naming Standards.
All identifiers (names and numbers) must be consistent throughout the different types of documentation (Record Layouts, Computer Operations Handbooks, Run Descriptions, etc.).
Documentation for periodic or optional runs is included with all other materials developed under the scope of a given FSP or requirements analysis document.
Schematics for a system must indicate where and when an optional run is executed.
Optional runs need not have an entirely separate set of documentation.
Avoid duplication of record layouts, specifications, etc.
If required according to site/system procedures, the following procedures must be followed when preparing the Public Service Requisition (Form 1767):
Item 22. Is security handling required? Check "YES" box.
Item 22a. Available to the public under FOl Act? Check "NO" box. The person signing under Item 23 should also initial this item.
Section B. Additional Instructions—As a further explanation of Item 22, insert the words "Security Level 3" . This will indicate that the lowest level of security will be in effect during the publishing process.
Further procedures for the publication of transmittal documentation may be established by individual organizations, e.g., through CyberDOCS. Refer to system and organization specific instructions for this information.
The transmittal numbers and dates entered on the documentation pages must be the same transmittal number and date used to transmit to production the corresponding program, control language or operating procedures described on that page of the documentation.
If a change is issued affecting the procedures described, or information on a particular page, the change page is issued with the new transmittal number and date.
The Data Dictionary (DD) is a central repository of information about the organization's data, used to maintain control over the definition and use of the data resources. In the Design stage, it is used to:
Determine which, if any, data elements are already used by other systems and/or databases;
Document all elements for a given system; and
Inventory all elements used by a system.
Data entered in the system glossary during the Analysis stage must be updated in subsequent stages such as when the physical attributes are determined or the file design is formulated. Design documentation is updated in more detail in the Data Dictionary to reflect these additions/changes.
The Project Library is created and maintained for audit, development and maintenance purposes through out all phases of software generation. Its contents are not restricted to Development phase documentation. Documentation is added to the library as it is generated at various points in the Software Development Life Cycle. It consists of specific Initiation, Development, and Operation phase deliverables.
Material produced during the Development phase should be retained as part of the project documentation in the Project Library. Notes, memos, changes or quality review reports, along with any updates, should be filed in the Project Library. This will ensure that Analysis, Design, and Programming documentation created during the Development phase will interface with the documentation created during the subsequent Initiation and Implementation phases. See Exhibit 2.5.4–1 for a display of what materials go into the Project Library during the Development phase. The project/team leader or other appropriate individual can retain a physical copy of the project library, store it on DOCS Open or maintain it in some other repository, electronic or otherwise.
This documentation addresses the various components of a system description.
A System Description is required for each Automated Data Processing (ADP) system.
The System Description serves as an introduction to the system, and provides any system-specific information which may be important for the reader to know. It is created in the Design stage of software development, when the physical design is fixed; and is updated as necessary.
The System Description will contain a general description that defines the scope of the system, identifies external interlaces, and provides the reader with any background information relevant to the system as a whole. The general description will always be the first item addressed.
The System Description may also include, but is not limited to, the following topics:
General operating environment considerations such as equipment, system/subsystem controls, differences based on site, etc.;
Failure contingencies such as back-up or fall-back capabilities;
Brief descriptions of optional run streams;
Number and type of runs/programs;
Data base characteristics such as storage allocation, device types, logical data relationships, access methods, etc., and
On-line transaction processing capabilities and requirements.
This documentation provides the generic information, contents, and organization for the system schematic.
A System Schematic Diagram is required for each ADP system. It is created during the Design stage of software development and must be developed in accordance with the standards outlined in this chapter.
Schematic Diagrams give a general overview of the work flow in a computer system and visually illustrate the relationships between the numerous computer runs in a system, as well as their input and output files.
Schematic Diagrams provide:
Management and testing personnel with the general overview of the computer runs involved in a system;
Project and programming supervisors with a tool for establishing workload requirements;
A reference for the control and disposition of all established input and output files; and
The operations scheduler with a graphic representation for job set-up and operational procedures.
Analyze all requirements analysis material, that is, the Programming Requirements Package (PRP), Functional Specification Package (FSP), or comparable system/site specific documents. (Analysis must take place prior to the development of schematics.) These are deliverables of the Analysis stage, the first stage of the development phase. These documents are passed on to the system designers and communicate to them the functional requirements of the system under development.
The affected development areas must work together when involved in related projects to prepare Schematic Diagrams in accordance with the procedures and standards prescribed in this guideline.
Ensure that approved amendments are incorporated as the development effort progresses in this and subsequent phases.
Review the System Schematic Diagrams periodically to ensure that they conform to the objectives and requirements expressed in the requirements analysis material.
Identify on each Schematic Diagram:
Terminal and intermediate files; and
Off-line machine operations related to the computer runs.
Organize the system into logically related groups of processes (runs and off-line operations) such as daily processing, weekend processing, etc. Each of these groups will become a separate diagram subset.
To the extent possible, depict the runs and operations within each diagram in a sequence that will reflect the actual order of processing.
The final schematics covering the entire system will usually consist of several diagrams (or "sheets" ), each containing a logical group of runs and operations. Use the appropriate connector symbols to provide a link between these diagrams.
Organize the Schematic Diagrams in ascending order of runs based on sequential interdependence.
This documentation provides instructions for preparing a schematic diagram.
Once a software developer requests a run number, the Software Quality Group (SQG) analyst should have the software developer complete the Run Number Registration Form, Form 11363. The SQG analyst should request a description of the computer run. This information should include the name of the system, project, and if the requested computer run is related to any other run number previously issued, etc. This information will assist in issuing the run number.
A run number must be developed from the System-ID. For example, given a three character System-ID, the format " SSS-RR(R)" , must be used. SSS = System-ID and RR(R) = run or operation number. Allocate the "RR(R)" numbers to provide for subsequent insertion of other runs when necessary (e.g., 01, 03, 05). Good judgment may dictate the need for more or less spacing between numbers. However, the computer system, tier, or platform may indicate alternative run number sequences in a format different from the guidelines stated in this paragraph.
If the run request is related to a run number previously issued, the SQG analyst should review the information received as well as the SQG run number data base to determine the new run number.
If the run request is not related to a previous run issued, the SQG analyst should review the information received as well as other pertinent information regarding the run request system or project. The SQG analyst should issue the run number associated to the appropriate system or project. For example, if the project is IRP, the SQG analyst should review the run number data base and issue the new run number with the next available number (e.g., IRP02).
The SQG analyst should record the new run number on the Run Number Registration Form.
The SQG analyst should provide the software developer the assigned run number via an electronic message.
The SQG analyst should enter the information from the completed Run Number Registration Form onto the SQG run number data base. The SQG analyst should place the completed form into the appropriate run number binder, and submit a copy of the new run number form to the PCDOCS administrators. This information may be submitted as often as necessary.
Assign a number to each file which appears on the Schematic Diagram. This number must be developed from the number of the run or operation which creates the file. For example, in a system where the System-ID is composed of three characters, the format "SSSRR(R)FF " shown below can be used. (For additional clarity, hyphens may be used to separate this number—"SSS-RR(R)-FF" , but this an optional feature.) Data set names are allowable if they provide more descriptive information.
SSS = System-ID
RR(R) = run number
FF = a two-digit number (00–99) identifying the file.
When feasible, the following numbers will be used for FF:
01–19 Tape Files
20–29 Disk Files
40–49 Print Files
An optional "VVV" can be added to the file number (SSSRR(R)FFVVV or SSS-RR(R)-FF-VVV) to indicate variable information such as segment number, region number, service center code, etc. There are several instances when the addition of this variable serves a very useful purpose:
To determine the point of origin when the same logical file is sent to several places;
To differentiate when a process is run at various sites; or
To distinguish when files are sent from multiple sites to one location for consolidation and processing (e.g., District Office files merged at the Regional Office or Service Center files with MCC).
Schematic diagrams must be prepared on Form M–4327 or a comparable form. A sample Form M–4327 with symbols and instructions is provided in Exhibit 2.5.4–3. The information contained in the ‘Title Block’ of this exhibit must be carried on any comparable form or automated form chosen for this purpose.
Depict as clearly as possible the flow of data through the computer runs and related off-line operations in an efficient sequence.
Identify every input and output file (intermediate and terminal) for each run with an appropriate media symbol (see Exhibit 2.5.4–4).
Maintain consistency in the size and symbols used. The relative size of a media symbol does not alter its significance. Thus, a larger symbol may be used to accommodate a longer title.
Label each input and output file symbol. For example, "INDIVIDUAL-MASTER-FILE" or abbreviated— "IMF" . The symbol represents the file medium. Therefore, do not express the medium (e.g., tape) in the title, unless the general I/O symbol is used.
Place the appropriate file number adjacent to each input and output symbol shown on the Schematic Diagram.
A sample Schematic Diagram is shown in Exhibit 2.5.4–6.
When an output file serves as input to two or more runs, identify that file with only one file number. Connect the output symbol to multiple runs with the appropriate terminal or connector symbols (see Exhibit 2.5.4–5).
Use the terminal symbol to identify the source of an input file or the destination of an output file outside the system. This external source may be another run, functional unit, etc. A sample label for this symbol would be—Posting Transaction: 450–45, where ‘450’ is the SYS-ID and ‘45’ is the Run number. Do not use the words "to" and "from" within this symbol.
Use the connector symbol as needed to continue logical flow between functional units within the system. Number this connector in the form ‘S.N.’ where ‘S’ = sheet number and ‘N’ = connector number. Begin a new sequence of connector numbers on each additional sheet.
Identify the run number. A format is shown in Exhibit 2.5.4–6. The run number is shown in the top space of the Run/Operation Box.
Identify the equipment used in this run. This includes both off-line and online computers, or printers used in this operation. It is identified in the left center portion of the Run/Operation Box (see Exhibits 2.5.4–5 and 2.5.4–6).
Identify the processing frequency of the run or operation. The frequency is shown in the right center position of the Run/Operation Box (see Exhibits 2.5.4–5 and 2.5.4–6).
Express frequency as follows:
D = daily Q = quarterly O = one time only W = weekly S/A = semi-annually P = periodic M = monthly A = annually V = variable
Periodic (P) processing applies to those runs which have a specific run interval not represented by D, W, M, Q, S/A, A or O (e.g., bi-monthly).
Variable (V) processing is used when no frequency is specified (e.g., upon demand).
List the run name in the lower portion of the Run/Operation Box. The name should relate to what the run accomplishes (e.g., Sort by Account Number, Sort and Edit, Translate, Merge, Convert PC to MT, Validate, Update).
In some cases, it will be necessary to show multiple copies of the same run being executed at the same time on Schematic Diagrams. See Figure 2.5.4–1 for one way to show multiple processes.
If the number of runs is so large that this method (Figure 2.5.4–1) clutters the page or is unworkable, an alternate method would be to use a footnote to explain that multiple copies of the run are to be executed. Regardless of the method used, this should be documented in the Run Descriptions, Schematic Diagrams and Computer Operations Handbooks.
This documentation provides the generic information, contents, and organization for the run description.
A Run Description is required for each individual computer run in a system.
Each run is described so that it can be understood with only a general background in computer technology.
Each Run Description will contain the:
List of files accessed; and
Internal and external controls.
The Run Descriptions will be organized in run number sequence.
This documentation provides instructions for preparing the run description.
Prepare a brief, accurate, clear narrative describing the function of each computer run program.
Identify the purpose of the run; that is, what it is intended to accomplish. List any pertinent facts about the run, such as externally called programs. If one run is used for daily, weekly, and yearly processing, etc., and different actions occur during each iteration, spell out the different actions. Do not include statements as to " how" the routines in the program process the data.
Provide a cross-reference list between individual runs and the corresponding processes (e.g., bubbles on the DFDs). When many levels of decomposition are encompassed by one run, only the highest level process which is uniquely identified needs to be referenced.
Prepare a list of the files which may be accessed by this run. Include both the file number and the file name. The list is divided into three parts: input files, output files, and I/O (input/output) files. Additional information may be included, such as "inquiry only " . This list is to include all files necessary to execute the run, such as print files, and runstream files.
Describe briefly each output file produced by the run. Input files need only be described when they enter the system for the first time. Avoid redundancy by references to files that have already been described.
Each description must contain:
Types of records contained in the file;
Manner in which records are batched, blocked, or grouped. Include a diagram when it is helpful; and
A statement about the sequence of records must be made, even when the file is in random order.
Describe the necessary controls, including any balancing instructions for utilizing the controls:
Internal Controls—any balancing schemes which have been developed to verify the validity of processing within a run.
External Controls—the information necessary for operations personnel to perform inter-run balancing, including which output file contains the control data, what control data are output, and to what element each item of control data should balance with.
This specification provides the generic information, contents, and organization for data specifications.
Data Specifications are required for each data structure.
Data Specifications are used to illustrate and define the data structures processed by the computer runs in the system.
Data structures are arranged hierarchically as follows:
Files — the physical, external interlaces between runs, each consisting of a set of related records;
Records — a logical I/O (input/output) unit; e.g., the data referred to by a READ or WRITE instruction;
Groups — a set of related items, defined together for convenience in manipulating as a unit (such as a date defined to be a group consisting of year, month, and day); and
Item — an element or field; data which is not further decomposed.
The Data Specifications document will contain, in this order:
File descriptions/record layouts; and
Appendices, when necessary.
Computer Specialists will sequence the file descriptions and record layouts by record reference number in ascending order. File descriptions will appear in this sequence under record reference number SSS/RR(R)/FF/000, where SSS/RR(R)/FF = file number.
Data Specification headers will contain the system name, responsible organization, operational date, revision date and the file or record reference numbers (see Exhibit 2.5.4–7).
This documentation provides the instructions for preparing the data specifications.
Assign a reference number to each record contained in a file shown on the Schematic Diagram. This number is developed from the file number. An example of the format is "SSS-RR(R)-FF-NNN" where:
SSS = System-ID;
RR(R) = run number;
FF = file number; and
NNN = record reference suffix.
The record reference number serves as a cross-reference document. Therefore, only one record reference number will be assigned to a given record format (see Exhibit 2.5.4–8).
The record reference suffix "NNN " is not the same as the optional variable indicator " VVV" , which is added to a particular file number. The record reference suffix is used to form the record reference number which identifies individual record formats. The record reference number is only used in Data Specifications to distinguish records from one another. The "VVV" suffix, referred to above, will not be necessary in this case.
Describe the file briefly. Include any information about the file which is relevant, such as:
Manner in which records are batched, blocked or grouped;
Access method; or
Sequence of records in the file (including random).
Any other information describing the file may be included.
Each record layout will be prepared in a format similar to that shown in Exhibit 2.5.4–9. A record layout describes the structure of a record, showing its component groups and elements (items). The format may be developed manually, or tools such as a word processor or an automated Data Dictionary may be used.
Record layouts will be prepared for all records contained in files identified in the Schematic Diagrams. (If screen displays and printer layouts are developed in Analysis, do not repeat their definition in the record layouts.)
All layouts must contain the following fields, regardless of the developmental method used:
Record name — as heading for the layout;
Element numbers for the elements;
Name — elements may be indented under a group name;
Starting position — relative to the first position of the record;
Type (group, numeric item, alpha); and
Remarks, including editing rules, valid ranges, etc., and separate or imbedded signs.
If the Automated Data Dictionary is used as a tool to aid in the definition of record structures, refer to the Data Dictionary section of this manual.
An IBM core record layout and IBM layout reference shall conform to the formats depicted in Exhibits 2.5.4–10 and 2.5.4–12 respectively, and must be developed using computer aided tools, e.g., electronic media, automated data dictionaries, spreadsheet programs, or other technologies.
An IBM core record layout comprises a layout and, if required, a layout reference. The layout describes the structure, groups, and fields that constitute a record. Instructions for completing the IBM core record layout can be found in Exhibit 2.5.4–11.
The requirements mentioned for the System Description, System Schematic, Run Description, Data Specifications, and Computer Operations Handbooks are needed to define the physical data. This data must be documented in the Servicewide Data Dictionary.
However, what the data actually is needs to be defined somewhere. A suggested means for detailed definition is a local data dictionary that is either manual or automated. Although the local data dictionary is used to further describe the data, the requirement to update the Servicewide Data Dictionary still exists.
Consistency is important; do not introduce redundancy by repeating in the local data dictionary information that is already contained in the Servicewide Data Dictionary.
This documentation provides details on the various components of the COH.
A Computer Operations Handbook (COH) is required, which contains a complete set of operating instructions for each computer run in the system.
It provides detailed instructions to a computer operator for the proper execution of a run.
The Computer Operations Handbook is a required deliverable for the Programming stage of development. However, Computer Operator Messages should be considered first in the Design stage of development. Updating of the COH should be throughout the program development life cycle. Among the items described in the operating instructions are set-up instructions, messages between the program and the operator, the input/output devices used and each file’s name and number.
Arrange instructions in System—ID/run number sequence.
Document the computer operating instructions in accordance with the following standards and the instructions specified in Exhibits 2.5.4–13 through 2.5.4–18.
Assemble the operating instructions for each run as a complete set.
Place operating steps in the proper sequence and cross-reference steps when applicable.
When a run contains options, document with separate operating instructions for each option.
Only one set of operating instructions are to be provided for programs which only differ by their file contents.
Operating instructions forms are published as a full page in the Computer Operations Handbook.
Examples of forms, which are to be used in compiling the Computer Operations Handbook, are shown in Exhibits 2.5.4–13, 2.5.4–15 and 2.5.4–17. These examples include the following forms:
3864 I/O UNITS 3864–A SET-UP INSTRUCTIONS 3864–D MESSAGE LIST
Comparable documents which convey similar information may be used if those listed do not satisfy requirements or are unavailable. Refer to the corresponding system-specific manuals for instructions when preparing those forms unique to particular systems. Instructions for completing the listed forms are in Exhibits 2.5.4–14, 2.5.4–16, and 2.5.4–18 at the end of this document.
Include only those forms that are necessary in the Computer Operations Handbook.
Use language that is clear and concise.
Be consistent in the use of abbreviations, formats, names and terminology, both within the Computer Operations Handbook and between the COH and other related documentation.
Avoid excessive abbreviations to insure readability.
Write the instructions to be implemented by the operator in simple imperative sentences.
Assign page numbers in unbroken sequence from 1 through "n" for each run, regardless of the number of run options involved.
Enter the page number on each page.
When run options are not involved, place the required pages in the following sequence:
When options are involved, document each option on separate pages. Place all the pages for each option together and place one option behind the other.
When inserting a new page between existing pages, use a decimal page number, e.g., 5.1.
Keep operator queries or messages to a minimum.
Console messages should require operator intervention or affect the continued operation of the runstream.
Information messages should appear on the printed listing only.
Console messages should have clear, concise explanations that the operator can follow easily.
If a computer run does not go to EOJ, include a console message to the operator that the contact point designated by the "User-Service Agreement" should be notified.
An IBM Computer Operations Handbook (COH) Guide shall conform to the format depicted in Exhibit 2.5.4–20. This guide is applicable to the IBM Tier 1 mainframe (except for the Automated Collection System), and applies to all computer specialists developing IBM or IBM-compatible programs.
The IBM COH Guide consolidates the COH, run descriptions, and file specifications into one unified and standard document. Instructions for completing the IBM COH Guide are found in Exhibit 2.5.4–19.
|SYSTEM ID:||OPERATIONAL DATE:|
|RESPONSIBLE ORG:||REVISION DATE:|
|A. General Description|
|B. Operating Environment|
|1.||Number and Type|
|2.||Optional Run Streams|
|3.||Data Base Characteristics|
|The title block will appear on every page of the Schematic Diagram. The following instructions are keyed to the illustration below:|
|A||Title||The words "Schematic Diagram" must appear on each page, followed by a descriptive title, such as "SC Daily Processing" .|
|B||Issued by||The organizational symbols of the originating office will appear here.|
|C||Date||Enter the operational date of the system.|
|D||Revisions||No. — The number of the revision, beginning with one ("1" ).|
|By — Enter the transmittal number assigned to the revision.|
|Date — Date of the transmittal.|
|SYSTEM NAME:||OPERATIONAL DATE:|
|SYSTEM I.D.:||REVISION DATE:|
|NUMBER OF RECORD TYPES:|
List the file numbers of all the files related to a given system. These files will be listed in ascending sequence based on file number.
Within the above list, list the records contained in each file, in ascending sequence by record reference number. The record reference number serves as a cross-reference to the record layouts in this document; therefore, only one record reference number will be assigned to a given record format. For example:
|File Number||Record Reference Number|
(repeat until all records for file 7600101 are listed)
Enter the record name for each record reference number listed.
Enter the file name for each file number listed.
Enter the block size established for each file.
Enter the maximum record length for each record.
Enter the file format as follows:
For tape files, enter the tape density (e.g., compressed files of 18 and 36 tracks).
If the file is a disk file, enter the word "DISK" . For tape files, enter the tape characteristic; e.g., "9" for 9 track tapes.
Enter the number of days a file must be retained.
|Element Number||Name||Start Pos||Length||Type||Remarks|
|3||EMPLOYEE-NAME||14||30||Char||Last name first|
|8||TELEPHONE-NUMBER||106||10||Num||Include area code|
|The IBM core record layout specifies the following fields:|
|a)||Element Name — The name of the elements that constitute a record layout. Elements may be indented under a group name ( begin group element names with a hyphen).|
|b)||Dec — The displacement in decimal. If this field does not apply, then it may be left blank.|
|c)||Hex — The displacement in hexadecimal. If this field does not apply, then it may be left blank. (The hexadecimal displacement does not show decimal points.)|
|d)||Length — The length of the field (designate 1/2 byte fields as 0.5).|
|e)||Type — This item indicates the data format of the element (e.g., packed decimal, zoned decimal, funny packed, character) and the number of decimal positions and sign.|
|f)||Ref — This item indicates the reference number (number sequentially beginning with 1) or whether a reference entry exists for the field (indicate with a " Y" ). Use a reference for lengthy remarks, otherwise leave this item blank. The references should be on a separate page at the end of the layout.|
|g)||Remarks — This item identifies additional information regarding the element such as editing rules and valid ranges. It may also be used for short remarks (one to a few lines).|
|h)||* — This item identifies elements that have been updated. Possible values are "I" (Insert — new field, record expands), " R" (Replace — field replaced or renamed), "M" (Move — field repositioned within record), and "C" (Change — field size changes, record expands/contracts).|
|The file name, record name (title) and date constitute the heading and must be displayed on each page.|
|Each record must end with the element "Total Record Length. " On variable records indicate a minimum and maximum length (if available).|
|If additional space is required for remarks regarding fields specified in the layout, then use an IBM Layout Reference.|
|The I/O Units page must contain all data files necessary to execute the run being documented (e.g. catalogued, temporary special print processor files, etc.). For each file the device file type, number and name used by the program being documented must be specified. Any specific conditions concerning the file translation or special device options must also be indicated. Program run options that include or exclude certain files must be mentioned under the conditions portion of the I/O Units page.|
|1.||SYSTEM-ID/RUN NUMBER||(1) Identify the program by System-ID and run number in the format SSS-RR(R). |
(2) When there are options involved in a single run and each option is documented on a separate page, identify the option by SSS-RR(R).n (where n = option number).
|4.||FILE NUMBER||(1) Enter the file number in the acceptable standard format. File numbers must be consistent with the ANSI File Header Label and any End-of-File Label for tape. ( |
(2) Input files are to be listed first in ascending file number sequence. These will be followed by output files also listed in ascending file number sequence. (
Files that serve as both input and output should be integrated in the list of input files according to the specified sequence and not repeated in the list of output files).
(3) Make no entry here if a tape is used as a work tape; such as a checkpoint file. This type of information is contained in CONDITIONS.
|5.||FILE NAME||Enter the name of the file identified by the file number in space 4. This identifier must be consistent with the Schematic Diagrams.|
|6.||I/O||Identify: I = Input Unit I/O = Input and Output (in the same run). |
O = Output Unit
List all Input Units first, Input/Output Units second and Output Units last.
|7.||CONDITIONS||Note any special restrictions on the file or unit. When the space provided is not adequate, cross reference the appropriate step in the Set-Up Instructions. All run options affecting file assignments must be listed under CONDITIONS, and cross referenced in the Set-Up Instructions.|
|8.||EFFECTIVE DATE/CYCLE||Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE may be substituted for the EFFECTIVE DATE/CYCLE.)|
|9.||PAGE NUMBER||Enter the page number of the pages for this run.|
|10.||COMPUTER AND SIZE||Identify the computer by name and number.|
|11.||RUN TITLE||Enter a brief title for run identification that is consistent with the Run Description and Schematic Diagrams.|
|12.||SYSTEM-ID/RUN NUMBER||Identify the System-ID and run number as entered in space 1.|
|1.||SYSTEM-ID/RUN NUMBER||(1) Identify the System-ID and run number in the format SSS-RR(R). |
(2) When there are options involved in a single run and each option is documented on a separate page, identify the option by SSSRR(R).n (where n = option number).
|2.||STEP NO.||Number each step in unbroken sequence beginning with 1.|
|3.||INSTRUCTIONS||Provide the necessary instruction, using imperative sentences, needed by the operator to set up the run as follows: |
(1) Include set-up steps for the job control language/executive control language (JCL/ECL — program, data, and control), the printer, disk unit, etc.
(2) When JCL/ECL statements, data cards or other special data cards are necessary in the job set up, provide a list of the statements or cards.
(3) Include complete, precise instructions and illustrations regarding the set-up of Checkpoint/Restart packets. It is recommended that this be a separate and unique set-up page.
(4) Rerun and restart procedures must be addressed for each run. If there are no special restart procedures this should be stated. A separate page containing rerun instructions must be included for each run. Precise information concerning file manipulation (delete, reload, or recatalog), and other pertinent instructions for the operator must be included on this page. If an alternate runstream is necessary to rerun a job, this must be listed and documented in the same fashion as all other runstreams. If no special instructions are required for a particular run, this should be stated with a reference to the appropriate first-time run instructions. Programs that access a data base must have rerun and restart instructions. Include information such as whether a data base area must be reloaded to eliminate updated records prior to rerun.
(5) When a controlling device is required for any I/O unit; e.g., printer carriage control tape, be sure to identify it by name and, when available, identification number. Include all application specifications.
(6) When there are options involved in one run, separate them into sets of loading steps accordingly. Begin each set on a new page. State the option number followed by option name on one line; e.g., OPTION 2. Monthly Tables. When necessary, include a two or three sentence synopsis of option. List the steps of the option sequentially beginning with 1.
|4.||EFFECTIVE DATE/CYCLE||Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE may be substituted for the EFFECTIVE DATE/CYCLE.)|
|5.||PAGE NUMBER||Enter the page number of the pages for this run.|
|6.||COMPUTER AND SIZE||Identify the computer by name and number.|
|7.||RUN TITLE||Enter a brief title for run identification that is consistent with the Run Description and Schematic Diagrams.|
|8.||SYSTEM-ID/RUN NUMBER||Identify the System-ID and run number as entered in space 1.|
|1.||SYSTEM-ID/RUN NUMBER||Identify the System-ID and run number in the format SSS-RR(R).|
|2.||NUMBER||Number each message in an unbroken sequence beginning with 1. List all messages whether computer processing continues or not.|
|3.||MESSAGE||(1) All program generated messages must be listed on the Message List Operating Instructions. All messages must be documented, and those that are not self-explanatory must have clear, concise instructions. If the message is informational only, this should be stated under the EXPLANATION column. It is recommended that messages be separated Into two categories: CONSOLE MESSAGES and INFORMATION MESSAGES (those appearing on the printed listing only). Discretion must be used in deciding which messages go where. Only those messages which require operator intervention or affect the continued operation of a runstream should appear on the console. All other messages should be routed to the run control print log (if available). If a computer run does not go to EOJ, include a CONSOLE MESSAGE to the operator that the contact point designated by the " USER SERVICE AGREEMENT" should be notified. |
(2) Enter any fixed message by writing it in capital letters; e.g., "EOJ" . In a variable message, indicate the variable part with lower case letters; e.g., mm-dd-yyyy for a date or nnnn for a displayed number.
|4.||EXPLANATION AND OPERATOR ACTION||If the message requires any operator action, explain in detail what the operator is to do. If there is no required action, state "No operator action" . Give any explanation or clarification of the message which will aid the operator.|
|5.||EFFECTIVE DATE/CYCLE||Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE my be substituted for the EFFECTIVE DATE/CYCLE.)|
|6.||PAGE NUMBER||Enter the page number of the page for this run.|
|7.||COMPUTER AND SIZE||Identify the computer by name and number.|
|8.||RUN TITLE||Enter a title for the run identification that is consistent with the Run Description and Schematic Diagrams.|
|9.||SYSTEM-ID/RUN NUMBER||Identify the System-ID and run number as entered in space 1.|
|1.||Purpose — The IBM Computer Operations Handbook (COH) Guide is required before processing and provides detailed instructions to a computer operator for the proper execution and validation of a run or program. It also provides the conventions and standards applicable to all IRS developers, and is a required deliverable for the programming stage of development. This guide is applicable to the IBM Tier 1 mainframe (except the Automated Collection System), and applies to all developers engaged in the development of IBM or IBM-compatible programs.|
|2.||Scope — The information presented in this manual covers the IBM COH Guide, and is composed of information from the previously used IBM Computer Operations Handbooks (such as the I/O Units), run description, schematics, and file specifications as described in this guideline. The instructions in this exhibit offer guidance in completing Exhibit 2.5.4–20, IBM COH Guide.|
|Purpose — The standard information contains the basic facts about the run in question. This data must appear at the top of every physical page (a standard 8 1/2 by 11 inch sheet of paper) or its electronic equivalent.|
|1.||Run/Command Code: The actual command code or run in PPP-RR format where PPP equals the project and RR equals the run. The Integrated Collection System (ICS) format may vary from six to eight alphanumeric characters.|
|2.||Title: A one line description of the run or command code.|
|3.||Page Number: The physical page number as if the document was printed on a 8 1/2 by 11 inch sheet of paper.|
|4.||Section-ID: The first two digits of your user ID.|
|Section I — Run Description and Nature of Changes|
|Purpose: The Run Description and Nature of Changes section gives the immediate information concerning the run or command code. It tells how often it is run, how many resources it is going to require, and what was changed in this transmittal.|
|1.||Run Description: A short paragraph describing what this run or command code accomplishes.|
|2.||Frequency: The number of times this project is executed in a given year. Valid responses are: daily, weekly, monthly, biweekly, bimonthly, annually, biannually, onetime, etc.|
|3.||System Resource Requirements: The number and type of input drives, output drives, Disk Requirements, or DB2/CICS/Teradata needed. Valid media types are: Bosch, STK, Optical, DASD, CART8, CART36, Tape9, Memorex ATL, etc. Indicate if the job updates or has exclusive access to a database (or is read only).|
|4.||Sort/Merge Fields: A list containing the order of the output. Ignore this field if the program is not a sort or merge and the files are already in order.|
|5.||Changes Included : Explanations for the changes should be specific, relevant, and easy to understand. When changes do occur, transmit a completely new IBM COH Guide to replace all prior transmittals.|
|Section II — Schematic|
|Purpose: The project schematic is important for processing validation; it informs the Processing Validation staff what files must be input and where the output is to go. The project schematic diagram must include output file destinations for audit purposes. The schematics can be on multiple pages as long as they include on each page the project title, the cycle designation, and page numbers (1 of x, 2 of x, etc.).|
|1.||Schematic Location: Provides the schematic location in PCDOCS. This would be a single run or the first run in a series of runs.|
|2.||MCC Cycle Designation: The cycle designation received from MCC schedulers. Valid responses are: BEW-, BEM-B, IPW-P, IEX-A, etc. For MCC purposes, put the cycle designation in the reference field on the schematic document profile.|
|Section III — I/O Page|
|Purpose: The I/O page will contain the information from the JCL. It must be in step order, first input then output. Also indicate if the job is multi-step.|
|1.||Job Step: This indicates a job step's association with the system resource requirements and I/O elements (ICS).|
|2.||DDNAME: The DDNAME from the JCL that is associated with this file.|
|3.||File Name & DSN: The complete data set name and a short description of the file.|
|4.||Unit: From the Unit parameter of the JCL.|
|5.||Label: From the Label parameter of the JCL. Not applicable for disk datasets.|
|6.||Ret: The retention in days required to keep this file. This is not applicable for input files.|
|7.||CRL: The Core Record Layout Reference Number; in order to access the CRL, go into PCDOCS and enter the run.|
|8.||TO: The major run or final destination to receive this file, if appropriate. This is not applicable for input files.|
|9.||BLKSIZE: Block size concerns how the records are transmitted and stored on an I/O device. Include block size, if appropriate.|
|10.||PRINT OPTION: Furnish the appropriate information, including the logical record length (LRECL) if necessary.|
|Section IV — Setup Cards/Sysin Cards|
|Purpose: This section will describe any sysin cards that are required by your job, and any necessary instructions needed by the operator to set up the run. Also incorporate other documentation related to the execution of the program, including the ENDEVOR memo, for any special instructions or input.|
|1.||Special Cards: The layout of any special cards, in the order that is required by the program, which also includes a short explanation. The CP23 or CP2000 cards should be included if needed. State if the program utilizes the CP23 or CP2000 macros if that is true. The DD name should be included if it is other than SYSIN.|
|2.||Rerun/Restart Requirements: Any rerun or restart requirements. Indicate any disk file that needs to be set back, e.g., to a previous time period or with a generation data group.|
|3.||Special Considerations: Any additional information that would help Scheduling, Production Control, or Operations run your job correctly the first time or how to restart it smoothly. Include any date considerations, e.g., on setup cards. Explain the PARM values on the EXEC card, if appropriate.|
|Section V — Halts/Messages/User Abends|
|Purpose: This section is needed to assist Operations and the Resident Programmer Analysts (RPAs)/ Computer Systems Analysts (CSAs) understand, answer, and restart a job after it has abnormally ended.|
|1.||Job Step: This indicates which job step created the message (ICS).|
|2.||Number: This must be the halt or abend codes so that the operators can research the abend code. When it is a message for information only, not requiring a reply, it can be just a sequential number of messages relative to the order of appearance.|
|3.||Message Text: The actual text in the message.|
|4.||Explanation: A short explanation as to why the message was sent.|
|5.||Action/No Action: Any expected action by Scheduling, Production Control, Operations, or RPA/CSA personnel. "No Action" is also a valid response.|
|6.||Restart Instructions: This must include any special instructions for Production Control, Operations or RPA/CSA personnel.|
|Section VI — Balancing|
|Purpose: This section is used to help Processing Validation and the RPAs/CSAs if there is a LARS out of Balance (LOOB) condition. Even though not enumerated below, it should be noted that ‘run-to-run’ balancing (i.e., LARS counters from previous runs need an audit trail) is required as well as "internal run" balancing.|
|1.||LARS Balancing Equations: The LARS formula as it will appear.|
|2.||Explanations: A paragraph explaining what the balancing instruction is trying to accomplish and how to manually balance if a LOOB is received.|
|3.||Counters: All single record counts, record count arrays, single money amounts, money amount arrays and explanations should be listed. LARS CNTL001 messages are needed in the balancing instructions along with the file number associated with each LARS counter. Also, a TOTAL line is required when more than one (1) pass is involved.|
|4.||Manual Balancing: If the program does not contain any LARS Balancing instructions it will be necessary to explain how the Processing Validation personnel will be able to verify the record counts or money amounts received.|
|5.||External Counters: If the records received are from an outside agency, one should include the number of records on the input and which counter it is equal to in the program, if appropriate.|
|6.||Auto Control Records (from external to center): If control records are included with the data records they should be described here, if appropriate.|
|Standard Information — To be included on each printable page.|
|1. Run/Command Code||2. Title||3. Page Number|
|PPP-RR (except ICS)|
|Section I — Run Description and Nature of Changes|
|System Resource Requirements||Input Drives:|
|Section II — Schematic|
|1. Schematic Location:|
|2. MCC Cycle Designation:|
|Section III — I/O Page|
|DDNAME||FILE NAME & DSN||UNIT LABEL||RET||CRL||TO|
|JOB STEP (ICS)||BLKSIZE:||PRINT OPTION:|
|Standard Information — To be included on each printable page.|
|1. Run/Command Code||2. Title||3. Page Number|
|PPP-RR (except ICS)|
|Section IV — Setup Cards/Sysin Cards|
|Special Cards (explanation & sequence):|
|DD Statement (Sysin or other):|
|Cards formatted (in required order):|
|CP23/CP2000 card or|
|CP23/CP2000 macro utilized or other options|
|Section V — Halts/Messages/User Abends|
|Job Step||Number||Message Text||Explanation||Action/||Restart Instructions|
|Section VI — Balancing|
|LARS Balancing Equations:|
|Auto Control Records (from external to center):|