COBOL CODING AND DOCUMENTATION STANDARDS The following standards will be used in CSCI 465; however, some will not be relevant until later in the course. Flowcharts will not be required, but your instructor or your teaching assistant may suggest that you construct one to help with any programming problems you may encounter. Whenever you seek the assistance of an instructor or any teaching assistant for this course, you should bring your assignment copy and any manuals for the course that you may need to reference. This course is designed for you to learn how to independently make use of manuals. Be sure to purchase all of the required manuals for this course because you will need them. As usual, unstructured coding will not be acceptable. 'GO TO' statements are not allowed unless your instructor explicitly grants permission. Avoid using 'NEXT SENTENCE' in any IF statements. PROGRAM LISTING Each COBOL DIVISION should begin on a new page; however, it is okay to put the ENVIRONMENT DIVISION on the same page with the IDENTIFICATION DIVISION. A reasonable use of 'SKIP' and 'EJECT' should improve the readability of the program listing. At most one statement or paragraph name is allowed per line. If any statement exceeds the length of one line, it should be continued on the following line after proper indentation. The continuation should be made in such a manner as to make the statement clearly understandable. At times a statement may not need to be continued on another line for lack of space, but doing so might make the statement more readable. No commas or semicolons are allowed. They may be mistaken for periods on the printed listing. The program must be designed and coded in a modular fashion so that it is easy to maintain and modify. IDENTIFICATION DIVISION The AUTHOR statement is required. A block of neatly formatted, easily readable documentation must be included and must provide the following information: 1. FUNCTION: State the function of the program in one or two sentences. Focus on WHAT the program does, not HOW it does it. 2. INPUT: List the names of any files used as input to the program. Include the DD name, file type, and logical record description associated with the file. 3. OUTPUT: List the names of any files or printed reports resulting from the program. Include the DD name, file type, and output description of each one separately. 4. ENTRY/EXIT CONDITIONS: List any parameters passed into and/or out of the program. State the name of the parameter as declared in the program and for what the parameter is used. Consider the following types of parameters: INPUT PARM: A value is received but is not altered. OUTPUT PARM: Has no initial value, but is expected to return a value. VARIABLE PARM: A value is received, possibly altered, and then returned. List any return codes set by the program and what each value indicates. State in what field the return codes are passed. 5. NOTES: Include any additional information that will be helpful (external routines or programs referenced, usage of linkage section, program limitations, complex formulas, etc.). ENVIRONMENT DIVISION The ENVIRONMENT DIVISION has no required documentation. It may be on the same page as the IDENTIFICATION DIVISION if both will fit. DATA DIVISION Organize common data items together under an 01-level group heading, e.g., 'ACCUMULATORS', 'FLAGS', 'PRINTER-CONTROLS', etc. Check with your teacher about 88-level conventions. Each data item associated with a record description must have a unique prefix which identifies to which record it belongs, e.g., 'CUST-NAME', 'CUST-ADDRESS', and 'CUST-PHONE' may be data items in 'CUSTOMER-RECORD'. Use descriptive, self-documenting names for all data items. Use additional comments to supplement unexplicit data names. For example, 'EOF-FLAG' is self-defining if there is one input file; however, ERROR-FLAG is not self- defining if there is more than one possible error in the program. When in doubt, provide a brief explanation. Number group items and their subordinates consistently, and use 2-digit values (e.g. 01, 05, 10). Arrange attributes in uniform columns. For example, PICTURE clauses might all start in column 45 and VALUE clauses in column 60. File descriptions must include the RECORDING MODE clause. PROCEDURE DIVISION All paragraph names should consist of a sequential number, a verb and its subject (e.g., '100-PRINT-HEADINGS', '200-READ-CUST-RECORD', '300-PROCESS- CATALOG-ORDER'). Each paragraph should be followed by an exit paragraph, which is named the same sequential number plus the word 'EXIT'. The only verb in this paragraph should be the verb 'EXIT'. For example, the exit paragraph for '100-PRINT-HEADINGS' should be '100-EXIT. EXIT.'. Note the exception here to the rule that there should only be one statement or paragraph name per line. Some paragraphs names need not include the sequential number. These are the short paragraphs that must be placed in a procedure of their own because of syntax problems associated with nested conditionally imperative statements. For example, the READ...AT END statement may be one of several imperative statements within an IF statement. It is not clear which statements are associated with the IF condition and which statements are associated with the AT END condition. The READ...AT END statement must be performed in a separate procedure to avoid including the AT END imperatives with the IF imperatives. This separate procedure should follow the paragraph that references it. Each numbered procedure must start on a new page in a printed listing, with the exception of short procedures (one to four lines of code) that may be printed two (maximum) per page. Each procedure must be preceded by a section of documentation including a statement of the FUNCTION of the procedure. The statement of FUNCTION should include any programming notes. The IF statement and its corresponding ELSE must begin in the same column. Statements subordinate to an IF or ELSE must be indented. On a CALL statement, the parameters must be lined up in the same column, one parameter per line. For example, CALL SUBRTN USING PARM-1 PARM-2 PARM-3. The examples on the following pages illustrate the points discussed above. COBOL IDENTIFICATION DIVISION Documentation Example: *********************************************************** * * * FUNCTION: THIS PROGRAM PRODUCES CUSTOMER CHECKING * * ACCOUNT STATEMENTS. * * * * INPUT: CUSTOMER-FILE -- * * A SEQUENTIAL FILE CONTAINING CUSTOMER * * ACCOUNT AND TRANSACTION INFORMATION. * * * * OUTPUT: STATEMENT-FILE -- * * CHECKING ACCOUNT STATEMENTS ARE PRODUCED * * CONTAINING ITEMIZED TRANSACTION DATA FOR * * EACH CUSTOMER. * * * * ENTRY CONDITIONS: * * MONTH-LS -- INDICATES THE MONTH FOR * * WHICH THE STATEMENTS ARE TO BE PRODUCED. * * * * EXIT CONDITIONS: NONE. * * * * NOTES: THE PARAMETER, MNTHPARM, IS PASSED INTO * * THE PROGRAM VIA THE 'EXEC' STATEMENT. * * * *********************************************************** COBOL DATA DIVISION Documentation Example: WORKING-STORAGE SECTION. ************************************************************** * * * FIELD: DESCRIPTION: * * * * LINE-SUB SUBSCRIPTS USED TO ACCESS A TWO- * * COLUMN-SUB DIMENSIONAL TABLE FOR BUILDING * * TRANSACTION DETAIL LINES * * * * WORK-TRANS-DATE USED IN A MOVE STATEMENT TO UNPACK * * TRANSACTION DATE * * * * TRANS-DATE-BREAK-DOWN * * USED TO ACCESS THE INDIVIDUAL * * FIELDS OF THE TRANSACTION DATE * * * ************************************************************** 01 EOF-FLAG PIC X VALUE 'N'. 01 SUBSCRIPTS. 05 LINE-SUB PIC S9(4) COMP SYNC. 05 COLUMN-SUB PIC S9(4) COMP SYNC. 01 ACCUMULATORS COMP-3. 05 TOTAL-WITHDRAWN PIC S9(9)V99. 05 TOTAL-DEPOSITED PIC S9(9)V99. 05 TOTAL-SERVICE-CHARGE PIC S9(5)V99. 05 TOTAL-INTEREST-EARNED PIC S9(5)V99. 05 NEW-ACCOUNT-BALANCE PIC S9(9)V99. 05 TOTAL-CUSTOMERS-PROCESSED PIC 9(7). 01 WORK-FIELDS. 05 CONVERTED-TRANS-DATE PIC 9(6). 05 TRANS-DATE-BREAK-DOWN. 10 TRANS-MONTH PIC 99. 10 TRANS-DAY PIC 99. 10 TRANS-YEAR PIC 99. COBOL PROCEDURE DIVISION Documentation Examples: 1. Main routine documentation: *********************************************************** * * * THIS ROUTINE CONTROLS THE FLOW OF LOGIC TO PROCESS * * THE CUSTOMER FILE AND PRINT THE CHECKING ACCOUNT * * STATEMENTS. * * * *********************************************************** 2. Several subroutine documentation examples: *********************************************************** * * * THIS ROUTINE FORMATS AND PRINTS A DETAIL LINE OF * * TRANSACTION DATA TO APPEAR WITHIN THE CHECKING * * ACCOUNT STATEMENT OF ONE CUSTOMER. A COUNT OF ONE IS * * ADDED TO A LINE COUNTER. * * * *********************************************************** *********************************************************** * * * THIS ROUTINE CONTROLS THE LOGIC OF ACCUMULATING AND * * PRINTING CUSTOMER CHECKING ACCOUNT STATEMENT * * INFORMATION. * * * *********************************************************** *********************************************************** * * * THIS ROUTINE PROCESSES A TRANSACTION AGAINST THE * * ACCOUNT BALANCE. * * * *********************************************************** Example Program with Documentation Starting on the next page is an example of a complete COBOL program with documentation. IDENTIFICATION DIVISION. ******************************************************** * * * PROGRAM NAME: GPA * * * * AUTHOR: ANN STUDWELL * * * * FUNCTION: THIS PROGRAM COUNTS THE UPPER- * * DIVISION STUDENTS WITH GPA >= 3.0 * * AND THE LOWER-DIVISION STUDENTS * * WITH GPA >= 3.0. * * * * INPUT: A DISK FILE CONTAINING ONE RECORD * * PER STUDENT. EACH RECORD CONTAINS * * THE STUDENT-ID, STUDENT-NAME, * * CREDIT-HOURS COMPLETED, AND HONOR- * * POINTS EARNED. * * * * OUTPUT: NO DETAIL LINES ARE PRODUCED. THE * * ONLY THING PRINTED IS A SUMMARY * * LINE WITH THREE TOTALS -- UPPER- * * DIVISION STUDENTS WITH GPA >= 3.0, * * LOWER-DIVISION STUDENTS WITH GPA >= * * 3.0, AND THE GRAND TOTAL OF ALL * * STUDENTS WITH GPA >= 3.0. * * * * NOTES: NONE * * * ******************************************************** PROGRAM-ID. GPA. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT STUDENT-FILE ASSIGN TO S-STUDENT. SELECT PRINT-FILE ASSIGN TO S-PRINTER. DATA DIVISION. FILE SECTION. ******************************************************* * STUDENT-FILE IS A DISK FILE USED AS INPUT. IT * * CONTAINS AN UNKNOWN NUMBER OF RECORDS. EACH RECORD * * CONTAINS THE STUDENT-ID, STUDENT-NAME, CREDIT HOURS * * COMPLETED, AND HONOR POINTS EARNED. * ******************************************************* FD STUDENT-FILE RECORDING MODE IS F. 01 STUDENT-RECORD. 05 STU-ID PIC X(11). 05 STU-NAME PIC X(20). 05 STU-CREDIT-HOURS PIC 9(3). 05 STU-HONOR-POINTS PIC 9(4). 05 FILLER PIC X(42). ******************************************************* * * * PRINT-FILE CONTAINS A GENERIC PRINT LINE THAT IS * * USED TO PRINT A HEADER LINE THAT LABELS THE TOTALS * * AND THE SUMMARY LINE THAT CONTAINS THE TOTALS. * * * ******************************************************* FD PRINT-FILE LABEL RECORDS ARE OMITTED RECORDING MODE IS F. 01 PRINT-LINE PIC X(132). WORKING-STORAGE SECTION. ******************************************************* * VARIABLES: * * * * EOF-FLAG CHANGED TO 'Y' WHEN END OF FILE * * OCCURS. * * * * UPPER-TOT USED TO COUNT THE UPPER-DIVISION * * STUDENTS WITH HIGH GPA. * * LOWER-TOT USED TO COUNT THE LOWER-DIVISION * * STUDENTS WITH HIGH GPA. * * GRAND-TOT USED TO CALCULATE THE TOTAL OF ALL * * STUDENTS WITH HIGH GPA. * * * * STUDENT-GPA CALCULATED BY THE PROGRAM (HONOR- * * POINTS / CREDIT-HOURS) * * * * HEADER-LINE USED TO PRINT LABELS ABOVE THE * * TOTALS. * * SUMMARY-LINE USED TO PRINT THE TOTALS. * * * ******************************************************* 01 EOF-FLAG PIC X VALUE 'N'. 01 TOTALS. 05 UPPER-TOT PIC 9(4) VALUE 0. 05 LOWER-TOT PIC 9(4) VALUE 0. 05 GRAND-TOT PIC 9(5) VALUE 0. 01 STUDENT-GPA PIC 9V9. 01 HEADER-LINE. 05 FILLER PIC X(34) VALUE SPACES. 05 FILLER PIC X(14) VALUE 'UPPER DIVISION'. 05 FILLER PIC X(10) VALUE SPACES. 05 FILLER PIC X(14) VALUE 'LOWER DIVISION'. 05 FILLER PIC X(12) VALUE SPACES. 05 FILLER PIC X(12) VALUE 'ALL STUDENTS'. 05 FILLER PIC X(36) VALUE SPACES. 01 SUMMARY-LINE. 05 FILLER PIC X(39) VALUE SPACES. 05 SUM-UPPER PIC 9(4). 05 FILLER PIC X(20) VALUE SPACES. 05 SUM-LOWER PIC 9(4). 05 FILLER PIC X(20) VALUE SPACES. 05 SUM-GRAND PIC 9(5). 05 FILLER PIC X(40) VALUE SPACES. PROCEDURE DIVISION. ******************************************************* * 000-MAIN. THIS ROUTINE CONTROLS THE FLOW OF THE * * PROGRAM. IT CALLS ROUTINES TO (1) READ THE FIRST * * RECORD, (2) INCREMENT THE UPPER-DIVISION AND LOWER- * * DIVISION TOTALS, AND (3) PRINT THE SUMMARY. * ******************************************************* 000-MAIN. OPEN INPUT STUDENT-FILE. OPEN OUTPUT PRINT-FILE. PERFORM 100-READ. PERFORM 200-PROCESS-STUDENT UNTIL EOF-FLAG = 'Y'. PERFORM 300-PRINT. CLOSE STUDENT-FILE PRINT-FILE. STOP RUN. ******************************************************* * 100-READ. THIS ROUTINE READS A RECORD FROM THE * * INPUT FILE. * ******************************************************* 100-READ. READ STUDENT-FILE AT END MOVE 'Y' TO EOF-FLAG END-READ. ***************************************************** * 200-PROCESS-STUDENT. THIS ROUTINE IS USED TO * * PROCESS EACH STUDENT RECORD. THE STUDENT'S * * GPA IS CALCULATED. IF IT IS >= TO 3.0, THE * * APPROPRIATE COUNT IN INCREMENTED. THEN, THE NEXT * * RECORD IS READ. * ***************************************************** 200-PROCESS-STUDENT. DIVIDE STU-HONOR-POINTS BY STU-CREDIT-HOURS GIVING STUDENT-GPA. IF STUDENT-GPA >= 3.0 IF STU-CREDIT-HOURS < 60 ADD 1 TO LOWER-TOT ELSE ADD 1 TO UPPER-TOT END-IF END-IF. PERFORM 100-READ. ******************************************************* * 300-PRINT. THIS ROUTINE CALCULATES THE GRAND * * TOTAL, THEN BUILDS AND PRINTS THE SUMMARY LINE. * ******************************************************* 300-PRINT. ADD UPPER-TOT LOWER-TOT GIVING GRAND-TOT. MOVE UPPER-TOT TO SUM-UPPER. MOVE LOWER-TOT TO SUM-LOWER. MOVE GRAND-TOT TO SUM-GRAND. WRITE PRINT-LINE FROM SUMMARY-LINE AFTER ADVANCING 2 LINES.