DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

SUBJECT: GENERAL INFORMATION

THE USE OF SOME OF THE HIGHER LEVEL LANGUAGES, SUCH AS COBOL, HAS DONE MUCH TO MAKE PROGRAMS MORE EASILY MAINTAINED. IT STILL, HOWEVER, IS IMPOSSIBLE FOR ONE TO UNDERSTAND THE PURPOSE OF A PROGRAM OR SECTION OF CODING WITHOUT STUDYING EVERY MINUTE DETAIL OF THE PROGRAM. FOR THIS REASON MAINTENANCE OFTEN INVOLVES GUESSES BY THE PROGRAMMER TO MAKE THE NECESSARY CORRECTIONS.

THE PURPOSE OF INTERNAL PROGRAM DOCUMENTATION IS TO PROVIDE VITAL INFORMATION TO A READER WITHOUT HAVING TO STUDY EVERY DETAIL FOR BASIC COMPREHENSION. IT ALSO PROVIDES A HISTORICAL RECORD OF MAINTENANCE, REQUIREMENTS, AND STRUCTURE.

WHILE THESE STANDARDS ARE WRITTEN IN TERMS OF THE COBOL LANGUAGE, THEY APPLY LIKEWISE TO THE COUNTERPARTS OF OTHER LANGUAGES. FOR EXAMPLE, A SECTION NOTE IS A NARRATIVE EXPLANATION ABOUT A COBOL SECTION OF CODING. IN AN ASSEMBLY LANGUAGE PROGRAM A SUBROUTINE WOULD REQUIRE COMMENTS SIMILAR TO THE SECTION NOTE, THE MAJOR DIFFERENCE BEING IN THE FORMAT OF THE STATEMENT.

THE FOLLOWING CHAPTER DISCUSSES THOSE ITEMS REQUIRED BY THIS INSTALLATION FOR INTERNAL DOCUMENTATION OF A PROGRAM.

CHAPTER: PROGRAMMING NUMBER: 5.2.02.01

DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

SUBJECT: THE PROGRAM ABSTRACT

THE PROGRAM ABSTRACT IS THE FIRST ENTRY OF THE REMARKS SECTION IN THE IDENTIFICATION DIVISION OF A COBOL PROGRAM. ITS PURPOSE IS TO PROVIDE SUFFICENT INFORMATION TO DESCRIBE THE PROGRAM'S PURPOSE, REQUIREMENTS, AND MAINTENANCE CONSIDERATIONS AND HISTORY, AS A SELF-CONTAINED UNIT, WITHOUT RELIANCE ON ANY EXTERNAL DOCUMENTATION.

THE FORMAT OF THE IDENTIFICATION DIVISION IN A COBOL PROGRAM AND THE PROGRAM ABSTRACT ARE EXPLAINED ON THE FOLLOWING PAGES.

CHAPTER: PROGRAMMING NUMBER: 5.2.02.02

DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

IDENTIFICATION DIVISION
PROGRAM-ID. 'XXXXXXXX'.
AUTHOR. XXXXXXXXXXXX.
DATE-WRITTEN. XX/XX/XX
REMARKS.

1. PURPOSE:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

2. PROGRAM OPTIONS:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

3. LIBRARY MODULES:
    XXXXXXXX
    XXXXXXXX
    XXXXXXXX

4. MAINTENACE CONSIDERATIONS:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

5. MAINTENANCE PERFORMED:

DATE	PERSONS NAME	NATURE OF WORK
1. XX/XX/XX	XXXXXXXXXXXXXXX	XXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXX
2. XX/XX/XX	XXXXXXXXXXXXXXX	XXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXX

CHAPTER: PROGRAMMING NUMBER: 5.2.02.03

DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

THE VERTICAL ASTERISKS ARE IN COLUNMS 12 AND 68.

PURPOSE: A NARRATIVE DESCRIPTION OF THE PURPOSE AND SCOPE OF THE PROGRAM. MAY BE THE SAME AS THE 'PURPOSE AND SCOPE' AS ON THE PROGRAM SPECIFICATIONS. BE DEFINITIVE AND DESCRIPTIVE. AS MANY LINES MAY BE INCLUDED AS NECESSARY.

PROGRAM OPTIONS: DESCRIBE ANY EXTERNALLY CONTROLLABLE OPTIONS; E.G., OPTIONS EXERCISED THROUGH CONTROL CARDS. SPECIFY HOW THE OPTIONS ARE CONTROLLED.

EXAMPLE:
PARAMETER CARD
SW-A ON = CLEAR MTD TOTALS
SW-B ON = CLEAR YTD TOTALS
SW-C ON = ELIMINATE DETAIL PRINTING LIBRARY MODULES - LIST ALL CALLED OR LINKED LIBRARY MODULES, INCLUDING FD'S, SUBROUTINE, ETC. THIS DATA IS NECESSARY TO RE-LINK A PROGRAM FOLLOWING MAINTENANCE.
MAINTENANCE CONSIDERATIONS: INCLUDE IN THIS PARAGRAPH ANY CONSIDERATIONS ONE SHOULD BE AWARE OF WHEN PERFORMING MAINTENANCE, E.G., TABLE SIZE, INDEXING TECHNIQUE. IDENTIFY ALL 'TRICKY' AREAS COULD GET ONE IN TROUBLE.
MAINTENANCE PERFORMED: THIS IS A VITAL PARAGRAPH. IT MUST IDENTIFY WHO DID WHAT TO THE PROGRAM AND WHEN. IT IS A HISTORICAL ACCOUNTING OF ALL MAINTENANCE TO THE PROGRAM. THE 'NATURE OF WORK' MUST BE DEFINITIVE.

DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

SUBJECT: PARAGRAPH NOTES AND NAMES

SECTION NOTES -EACH COBOL SECTION (ALC SUBROUTINE) SHALL CONTAIN AS THE FIRST ENTRY A NOTE DESCRIBING THE PURPOSE AND FUNCTION OF THAT SECTION. THE NOTE SHOULD BE DESCRIPTIVE AND DEFINITIVE.

PARAGRAPH NOTES - EACH COBOL PARAGRAPH WHICH, BECAUSE OF SIZE OR COMPLEXITY, IS NOT EASILY UNDERSTOOD SHOULD BE FURTHER DEFINED WITH A PARAGRAPH NOTE.

PARAGRAPH NAMES - PARAGRAPH NAMES FOR ALL NEW PROGRAMS MUST INCLUDE A SEQUENCE NUMBER. THIS NUMBER MUST ORIGINALLY BE IN INCREMENTS OF NOT LESS THAN TEN (10) TO PERMIT FUTURE ADDITIONS TO THE PROGRAM, AND MUST REMAIN IN SEQUENCE FOR AS LONG AS THE PROGRAM IS ACTIVE.

CHAPTER: PROGRAMMING NUMBER: 5.2.04.01

DATE: 11/06/85

SECTION: INTERNAL PROGRAMMING DOCUMENTATION REVISED:

SUBJECT: ERROR HANDLING

ALL NEW COBOL PROGRAMS MUST INCLUDE ERROR HANDLING FACILITIES FOR ISAM FILES IN CASE AN INPUT/OUTPUT ERROR ARISES DURING PROCESSING. SPECIFIC- ALLY A FORMAT 2 USE STATEMENT SHOULD APPEAR IN THE DECLARATIVES SECTION. THE FOLLOWING IS GIVEN AS AN EXAMPLE.

PROCEDURE DIVISION.
DECLARATIVES.
ERROR-HANDLING SECTION
USE AFTER STANDARD ERROR PROCEDURE ON FILE-NAME-1, FILE-NAME-2... GIVING DATA-NAME-1.
PARRA-10.
DISPLAY DATA-NAME-1A.
DISPLAY DATA-NAME-LB.
DISPLAY NOMINAL-KEY.

DISPLAY 'STANDARD ERROR ON',
                FILE-NAME-1.
CALL 'ABEND'.

END DECLARATIVES.
* IN THE ABOVE EXAMPLE, FILE-NAME-1, FILE-NAME-2 ARE ISAM FILES USED IN THE PROGRAM. DATA-NAME-1A AND DATA-NAME-LB ARE PARTS OF THE 136-BYTE DATA-NAME-1 DEFINED IN WORKING STORAGE. NOMINAL-KEY SPECIFIES THE RELATIVE RECORD NUMBER FOR A SPECIFIC LOGICAL RECORD, RELATIVE TO THE BEGINNING OF THE FILE. IF AN ERROR ARISES, THIS PROCEDURE WILL HELP PINPOINT THE PROBLEM.

DATE: 11/06/85

SECTION: PROGRAMMING DOCUMENTATION REVISED:

SUBJECT: RETURN CODE

THE RETURN-CODE SPECIAL REGISTER IS A MEANS FOR A PROGRAMMER TO SELECTIVELY EXECUTE A PROGRAM IN A JOB STREAM, WHEN USED IN CONJUNCTION WITH THE 'COND' PARAMETER IN AN 'EXEC' STATEMENT.

IF, DURING THE EXECUTION OF A JOB STREAM, ONE OF THE JOB STEPS WERE TO BE SKIPPED IF A PRECEEDING JOB STEP ENCOUNTERED A CONTROL CARD ERROR, THE COBOL PROGRAM ENCOUNTERING THE CONTROL CARD ERROR WOULD EXECUTE THE FOLLOWING 'MOVE' STATEMENT:

ERROR-ROUTINE.
MOVE 111 TO RETURN-CODE.
*THE JOB STEP THAT IS TO BE SKIPPED BECAUSE OF THE CONTROL CARD ERROR WOULD THEN HAVE ITS 'EXEC' STATEMENT CODE AS FOLLOWS:

A COMPLETE EXPLANATION OF THE 'COND' OPERAND MAY BE FOUND IN THE JOB CONTROL LANGUAGE MANUAL.