Project: CSS – ISEC Title: Coding Standards DOCUMENT NAME ABSTRACT
Page 1 of 22 Date : 22/03/2002 : CSS - NM COBOL Coding Standards. : This document provides the standards for COBOL coding for CSS NETWORK MANAGEMENT.
PREPARED BY REVIEWED BY
: Upendra Curpad : Sachin Punalekar Abhay Deshpande Sameer Saxena Umesh Shukla : Sachin Punalekar : Issue 1.0
APPROVED BY VERSION NO
VERSION HISTORY VERSION DATE Draft 0.1 26/02/02 Issue 1.0 22/03/02
PREPARED BY Upendra Curpad Upendra Curpad
CHANGES & REASONS FOR CHANGE First version Issued
REFERENCE DOCUMENT NAME Application Development Guidelines Dos and Don’ts for IDMS DML Programming
VERSION Issue 1.1 Issue 1
LOCATION \Projdocs\Standard\ Adgver1.1.doc \Projdocs\Standard\dmlprog.doc
Issue 1.0 By : UC Company Confidential Mahindra-British Telecom Limited
Project: CSS – ISEC Title: Coding Standards
Page 2 of 22 Date : 22/03/2002
THIS SECTION PROVIDES A SERIES OF GUIDELINES TO PROGRAMMING STAFF. IT IS ESSENTIAL THAT THESE GUIDELINES ARE FOLLOWED. The use of programming standards within the project ensures that the software produced is :Maintainable Robust Easily enhanceable Understandable Efficient Consistent across the project. A standard structure for any program within the system ensures that any programmer familiar with the conventions may rapidly understand any of the programs in the system, irrespective of who wrote them.
COBOL II PROGRAMMING LANGUAGE
All application programs will be written in COBOL II. This conforms to ANSI 85 COBOL, although CSS imposes the use of the CMPR2 compile option (compatibility with Release 2 of the compiler) which restricts full ANSI 85. In addition, it is a CSS convention that upper case is used for all COBOL statements. Lower case is reserved for comments. There are several features in COBOL II which are important to the CSS project. These include :Generation of fully re-entrant code. This means that only one copy of the procedure code of a program is held in main memory for programs running under CICS. Full 31-bit addressing. Structured language constructs Simplified CICS interfaces
Issue 1.0 By : UC Company Confidential Mahindra-British Telecom Limited
0 By : UC Company Confidential Mahindra-British Telecom Limited
. 47) Version Number (8. QA000M1 (IDMS progs only) Schema ref e. SSDCAA00 (IDMS progs only) DB records accesses e.47.doc
Issue 1.Project: CSS – ISEC Title: Coding Standards
Page 3 of 22 Date : 22/03/2002
The following types of embedded documentation are required in programs:Program header Section header Source level comments
2. The template consists of information relating to the program that would be of benefit to someone who may have to maintain or enhance it in the future.g. REC-1 NONE NONE A List of Message Codes issued by the program. The template is shown below:
INFORMATION AREA PROGRAM NAME PROGRAM TITLE PROGRAM RELEASE NUMBER PROGRAM VERSION NUMBER AUTHOR DATE WRITTEN SYNOPSIS MAPS USED SCHEMA SUBSCHEMA DB RECORDS PROGRAM CALLS PROGRAM LINKS MESSAGE CODES NOTES : : : : : : : : : : : : : : : QAOOODC skeleton program Release Number (e.0) Name Dd/mm/yyyy A brief description of the function of the program Maps used e.g. SCCS00 (IDMS progs only) Subschema ref e.g.1 PROGRAM HEADER The heading data consists of a standard template to be filled in by the application programmer.g. Additional Notes
. They should come before the corresponding code except for those denoting the end of a loop or end of data record declarations. CALLED BY : Section(s) which call this section.2 SECTION HEADER
Each main section should include a header.
3. The heading data will consist of a standard template to be filled in by the application programmer. it will cause a page break on the compilation listing. Do not code ‘EJECT’ and ‘TITLE’ unless you want two page breaks. Comments which pertain to a single statement of small code segment.0 By : UC Company Confidential Mahindra-British Telecom Limited
59861088. Call the abend handler. RETURN CODES : Return Codes for this section. briefly explaining the main functions of the section.3 SOURCE LEVEL DOCUMENTATION Source level documentation occurs within a section at two levels:Block comments which should precede complex code segments and describe their function. 2.Project: CSS – ISEC Title: Coding Standards
Page 4 of 22 Date : 22/03/2002
AMENDMENT HISTORY VER/DU AUTH DESCRIPTION
The heading data is a comment block. Determine which phase to execute. 2. Comments should be considered as an integral part of the program and as important as any other program statement. Return to Dialogue Manager.g.1
PROCEDURE DIVISION FORMAT Issue 1. A section header is shown below: A000-MAIN-CONTROL SECTION
NAME SYNOPSIS : : Section Name Overall section logic:. Address data areas using the pointers passed from Dialogue Manager.
Note: If a section is preceded by a ‘TITLE’ statement. these should be normal COBOL comment statements.e.
2. No other paragraph names are permitted within the Procedure Division. 7. Sections performed only by A000 (and other A sections) come next (e. Minor sections performed from more than one major section are considered service sections. These should have their own alpha character .
5. should only be performed from A000 and should perform the other main functions of the program. Commas and semi-colons are forbidden. This means that the only full stops needed will be at the end of each section and paragraph. The three-digit number should be 000 for the major section. 5. These service routines will be appended to the applications code.
7. Standard indentation will be three spaces for each level of condition Repetition is implemented with the PERFORM verb.
6. Only SECTIONS may be PERFORMed (apart from in-line PERFORMs).0 By : UC Company Confidential Mahindra-British Telecom Limited
. The EXIT paragraph is the exit-point and contains only the EXIT verb.one letter further down the alphabet.g. 4. Sections B.
2. DEPENDING ON 1. The sections are named according to hierarchical conventions. The minor ones should be grouped according to their relationships.. 3. Sections B000. 6. 3. Sections further down the hierarchy (and usually performed by many sections) are classified as service sections. A100SEND-MAP). Sections with alpha prefix of ‘Z’ are reserved for use by the Central Software teams for standard utility procedures which may be copied into any program as required. C etc.
Page 5 of 22 Date : 22/03/2002
A SECTION is composed of a Section Header and an EXIT-paragraph.Project: CSS – ISEC Title: Coding Standards 1. come next.
4.. Section A000 is the main section of the program and should contain its principal logic. All sections and paragraphs begin with a standard format prefix consisting of one alpha and a three-digit number. The order of sections in the source listing follows their order in the hierarchy of execution (i.
3. a parent is followed by its descendants according to their invocation order).e. A branch may be made only from within a SECTION to the EXIT-paragraph of that section (only local GO TOs are allowed).2
PROCEDURE DIVISION STATEMENTS
The program may consist of statements containing any valid COBOL II verb except: • ALTER • GO TO . C000 etc. A branch is implemented with the GO TO statement. The section header is the entry point and contains all the executable code for the section.doc
Issue 1. Only one statement may be coded per line. and to end labels. Each major section begins with a new alpha. Selection is implemented with the IF or EVALUATE verbs. Only mandatory full stops should be used.
For example. the variables rooted in section B300-GET-BILL-DETAILS SECTION might be arranged thus: 01 B300-GET-BILL-DETAILS-WORK. consider removing groups of lower-level logic into separate sections and perform them from the top of the original IF structure. The IF. The name of the work record is the name of the section to which it belongs.
Nesting of IF statements deeper than three levels is strongly discouraged. A data item is placed in a work record belonging to the section that is the root of all sections that use this data item. If the logic demands more than three. the ELSE clause should be supplied (if null the CONTINUE verb must be used). Data items within the work record are prefixed with the section number and an abbreviation of the section Name. ELSE and END-IF must be aligned.WORK. Where an EVALUATE is used the WHEN OTHER clause must always be coded. DISPLAY.
DATA DIVISION STANDARDS
Each item in a program should only have one purpose and its name should suggest that purpose. for example: EVALUATE TRUE WHEN PHASE-D PERFORM D000-PHASE-D WHEN PHASE-F PERFORM F000-PHASE-F WHEN OTHER CONTINUE END-EVALUATE
1. WORKING-STORAGE SECTION data items are grouped together in records depending on where they are used in the program.0 By : UC Company Confidential Mahindra-British Telecom Limited
. 05 B300-GBD-DATA-BASE-KEY 05 B300-GBD-CUSTOMER-NUMBER
3. for example: IF DM-PROG-FLAG = ‘K’ PERFORM G000-PHASE-K IF G000-UPDATE-FLAG = ‘1’ PERFORM H000-SETUP-PHASE-M ELSE CONTINUE END-IF ELSE CONTINUE END-IF
9. suffixed by . and their dependent statements indented by at least three spaces.
10. and terminated with END-IF. 2.
Page 6 of 22 Date : 22/03/2002
For all IF statements coded.Project: CSS – ISEC Title: Coding Standards 8.
PIC S9(8) PIC 9(8)
COMP. 4. To control program complexity a data item should not be referenced in more sections than necessary.doc
5. This type of usage is also known as Zoned Decimal. PIC S9(8) COMP..15 etc.0 By : UC Company Confidential Mahindra-British Telecom Limited
.1... PIC S9(7) COMP-3. Further redefinitions follow the sequence. 9.. arithmetic can be done on it. it is best not to mix operations on different data types. Numeric items must always be signed if required for arithmetic purposes. 59861088.1
NOTES ON DATA TYPING DISPLAY
One byte holds one character or one digit. Level 77 items will not be used..Project: CSS – ISEC Title: Coding Standards
Page 7 of 22 Date : 22/03/2002
5.05.2 DISPLAY (NUMERIC)
When a DISPLAY field has a numeric picture clause.
DATA TYPING STANDARDS
The following data types may be used:DISPLAY DISPLAY (NUMERIC) COMP-3 COMP POINTER INDEX Choice between these data-types may be determined by efficiency considerations.1 5.
5. The name of an item which is the redefinition of another item is the name of the first item suffixed with -R1.. 8. 6. 11. 05 B300-GBD-ITEM-NO 05 B300-GBD-ITEM-NO-R1 REDEFINES B300-GBD-ITEM-NUMBER 05 B300-GBD-ITEM-NO-R2 REDEFINES B300-GBD-ITEM-NUMBER PIC X(4). This is the default data type in COBOL.1.
10. Level 66 items will not be used.10. Use level 88 variables where possible to improve program readability.doc Issue 1. Keep VALUE clauses to a single line. 7. PICTURE clauses must be aligned. A PIC X(4) field would hold the EBCDIC string ‘QB4S’ in hexadecimal as ‘D8 C2 F4 E2’. Generally.
Level numbers will follow the sequence 01.
This is known as binary. This conversion is inefficient. 5. which is the most efficient usage for arithmetic. the following practice is recommended. It is not a simple case of the high-order bit being set. Before arithmetic can be done on a DISPLAY NUMERIC field.6 Boolean Data Types PIC S9(8) COMP. The number 1783 in a PIC S9(5) COMP-3 field would be held in EBCDIC in three bytes hexadecimal as ‘01 78 3F’ or ‘01 78 3C’. except that fields occupy multiples of 2 or 4 bytes. F and C mean positive. and holds numeric data in the most efficient way. Each represents four bits. Syntax rules in COBOL II forbid the manipulation of these variables in the manner of normal COBOL data types. A MOVE may not be used for assignment. A value of -1783 would be held as ‘FF FF F9 07’.Project: CSS – ISEC Title: Coding Standards
Page 8 of 22 Date : 22/03/2002
A PIC S9(5) field would hold the number 1783 in EBCDIC hexadecimal as either ‘F0 F1 F7 F8 F3’ or ‘F0 F1 F7 F8 C3’. Each byte. A PIC S9(5) COMP field occupies 4 bytes. The sign of the field is determined by the value of the left-most bit of the left-most byte (the high-order bit).1. 05 B310-APG-TABLE-PTR-R1 REDEFINES B310-APG-TABLE-PTR 5. so space may be wasted. This should be simulated by means of level 88 variables. as follows:59861088. because. nor may arithmetic be performed.1. The right-hand quartet of the right-most byte holds the sign.3 COMP-3. compared to the one digit per byte of DISPLAY. and then converted back to DISPLAY. whilst D means negative. The IBM architecture. POINTERS are full word binary variables. In DISPLAY NUMERIC the left-hand quartet of the right-most byte determines the sign of the number. because the number is held in two’s complement form. can work directly in packed decimal.1. it is first converted to COMP-3 or to COMP format. each byte has two digits ‘packed’ into it. apart form one byte. F and C mean positive. whilst D means negative. A value 1783 would be held as ‘00 00 06 F7’. (Flip the bits and add 1).
This is known as packed decimal.
COBOL II does not supply a boolean data type. is represented by two hexadecimal characters. The IBM architecture can work directly in binary.doc Issue 1. 5. To circumvent these difficulties in cases where pointer manipulation is necessary. known as quartets. 0 means positive whilst 1 means that the field is negative.5 Pointer Data Types
COBOL II introduced the USAGE IS POINTER clause in the Data Division. 05 B310-APG-TABLE-PTR POINTER. so its usage is relatively efficient for arithmetic.0 By : UC Company Confidential Mahindra-British Telecom Limited
.1. of 8 bits. the calculations done. 5.
Constants should be assigned meaningful names. and suitable action Wherever possible.
• The convention to be adopted for return codes issued by programs should be ZERO for success or > ZERO for error.
01 B300-GBD-RECORD-STATUS 88 BILL-DETAIL-REC-FOUND 88 BILL-DETAIL-REC-NOT-FOUND
For Boolean variables both TRUE and FALSE level 88 condition names should be coded. Note that INITIALIZE does not initialize FILLERs. To initialize the contents of FILLERs. • All return codes should be checked following any type of request. VALUE 1.1
Exception handling refers to error handling and unexpected events at run-time. VALUE ZERO.2 CICS CONSIDERATIONS Exception handling under CICS has been enhanced to enable properly structured programs to be written easily.doc
. As a general principle: • taken. A program’s working storage is initially set to binary zeros by the COBOL options used in CSS. CICS will abend the task with a code which directly indicates the failing condition.
6. or replace the FILLER by names.7 Literals and Constants
Literals and constants should be declared in the WORKING-STORAGE Section. There are general principles which must be noted: 1. VALUE clauses will supersede this. either MOVE data to a group at a higher level. Truth values should be coded following positive logic conventions:TRUE = 1 FALSE = 0 5. Where possible. A Linked submodule’s working storage will always be reset to the same initialized values.0 By : UC Company Confidential Mahindra-British Telecom Limited
59861088. New programs should use the second method exclusively. Issue 1. 6. possibly to the whole record. not embedded in the text. be careful when the data being initialzsed is redefined. input parameters to procedures should be checked for validity. or redefines something else.1. If you do not do so. 5. CALLed submodules retain values set from a previous invocation in the same task. Also. However.8 Initialization
Be aware of the capabilities (and spelling) of the INITIALIZE verb to simplify the setting-up of data areas.1. there are programs written before the enhancements arrived which need to be maintained and so both approaches are covered here.Project: CSS – ISEC Title: Coding Standards
Page 9 of 22 Date : 22/03/2002 PIC 9 VALUE ZERO. CICS will only allow a program to continue after an exceptional condition has occurred if the program has told it in advance that it will handle either a particular condition or all conditions. splitting a literal across multiple lines should be avoided.
the following methods were adopted: For each condition to be handled within the program. For example: Q100-READQ-SECTION. place the command in a separate section. over and above the EXIT paragraph required by the programming standard.
6.0 By : UC Company Confidential Mahindra-British Telecom Limited
Page 10 of 22 Date : 22/03/2002
A subprogram entered by a CICS LINK or a COBOL CALL will not inherit the conditions set up by the caller. The ‘HANDLE’ clause and its destination labels are placed within this section.Project: CSS – ISEC Title: Coding Standards 2. VALUE ZERO. and to preserve the advantages of structured programming. be coded. VALUE 1. To minimise the impact of this unavoidable conflict with standards. EXEC CICS HANDLE CONDITION ITEMERR(ITEMERR-LAB) QIDERR (QIDERR-LAB) END-EXEC SET NO-QIDERR TO TRUE SET NO-ITEMERR TO TRUE EXEC CICS READQ TS QUEUE (WC-MCS-QNAME) INTO (WD-MCS-QRECORD) ITEM (WE-MCS-REC-NUMBER) END EXEC 59861088. These statements effectively translate into GO TOs. 88 QIDERR 88 NO-QIDERR
VALUE 1. VALUE ZERO. declare a Boolean variable: 05 WA-MCS-MAPFAIL-INDICATOR PIC 9. producing the following programming problems : An EXEC CICS HANDLE statement requires a target label to be supplied. 88 MAPFAIL 88 NO-MAPFAIL 05 WB-MCS-QIDERR-INDICATOR PIC 9.
For each class of CICS command to be issued.2. This implies that additional paragraph names. It is also possible to use the NOHANDLE option on an individual command to override all relevant HANDLE commands temporarily.1
The Original Method
Under the original method.doc Issue 1. the main commands provided were: EXEC CICS IGNORE CONDITION condition name EXEC CICS HANDLE CONDITION condition name (program label) EXEC CICS HANDLE CONDITION ERROR (program label) The latter two either provide a label where the condition is handled or remove a previous label for the condition if the program label is null. The GO TO may result in transfer of control out of the section in which the exception occurred.
Q100-READQ-EXIT. The result of the command MUST then be tested on return and CICS provides readable values to test against. following normal structured techniques. The application coding then proceeded. SET ITEMERR TO TRUE . ITEMERR-LAB. EXIT.Project: CSS – ISEC Title: Coding Standards GO TO Q100-READQ-EXIT .2.0 By : UC Company Confidential Mahindra-British Telecom Limited
.doc Issue 1.
Page 11 of 22 Date : 22/03/2002
This class of section may contain paragraph names other than the EXIT paragraph. as necessitated by the CICS pre-processing. SET QIDERR TO TRUE GO TO Q100-READQ-EXIT . For example: EXEC CICS READQ TS QUEUE(WC-MCS-QNAME) INTO (WD-MCS-QRECORD) ITEM (WE-MCS-REC-NUMBER) RESP (WS-RESP) RESP2 (WS-RESP2) END EXEC EVALUATE WS-RESP WHEN DFHRESP(NORMAL) CONTINUE WHEN DFHRESP(QIDERR) MOVE ‘TSQ NOT FOUND’ TO DM-MSG-TEXT PERFORM Y100-ERROR-RETURN WHEN DFHRESP(ITEMERR) 59861088.2 The Preferred Method
The preferred method is to provide CICS with response fields whenever a condition needs to be handled by the application program. For example: PERFORM Q100-READQ IF QIDERR MOVE ‘QUEUE NOT FOUND’ TO DM-MSG-TEXT PERFORM Y100-ERROR-RETURN ELSE IF ITEMERR MOVE ‘RECORD NOT FOUND ON QUEUE’ TO DM-MSG-TEXT ELSE CONTINUE END-IF END-IF 6. QIDERR-LAB.
• If you do not code the RESP operand. These routines are copied in by the CMW Pre-Processor as part of the compilation process.Project: CSS – ISEC Title: Coding Standards
Page 12 of 22 Date : 22/03/2002
MOVE ‘REC NOT ON TSQ’ TO DM-MSG-TEXT PERFORM Y100-ERROR-RETURN WHEN OTHER STRING ‘TSQ ERROR’ . etc. assuming there is no HANDLE CONDITION in force. Following each DML request. the application will check the return code.3
IDMS exceptions are handled in the following way: 1. 6.). If you code a RESP operand on a command.for example PGMIDERR on a LINK. DB-END-OF-SET before performing the standard status check. Application-specific actions must be coded to handle all anticipated return codes which will commonly occur (e.doc
Issue 1. see “IDMS Error Handling”. It is not compulsory to code it.g.g. • It is quite acceptable to allow CICS to abend a transaction if a condition is genuinely an error .0 By : UC Company Confidential Mahindra-British Telecom Limited
. CICS assumes you will test it. record-not-found. Standard routines are provided to check the return status from each DML request. end-of-set.4 ABEND CONSIDERATIONS
Program abends under CICS are handled by inclusion of a standard section in each program. It is up to the programmer to check for specific conditions e. 3.WS-RESP INTO DM-MSG-TEXT PERFORM Y100-ERROR-RETURN END-EVALUATE It is important to note that : • • The response fields must be binary fullwords ( PIC S9(8) COMP). section 6. • The RESP2 field contains additional information about the problem which may be of use. 2. CICS will abend the transaction if an exceptional condition occurs.
PIC S9(x) DISPLAY
Whenever possible in arithmetic. will be the response time.doc
.2 COBOL FIELD DESCRIPTIONS
All counters and fields used in arithmetic should be signed whenever possible. as this is handled more efficiently.1
COBOL PROGRAMMING CONSIDERATIONS
There are a number of aspects to the run-time efficiency of a COBOL program. eg large money amounts. or to a similar database description.
7. Should be used only for numeric items which are to be output to a report or job journal. It is the most inefficient description for a subscript.e. and there are a number of ways to define data and arrange procedures which can affect run times. those used more than 1000 times per day) because the critical factor in the success of the system. If they are unsigned. use all fields of the same type.Project: CSS – ISEC Title: Coding Standards
Page 13 of 22 Date : 22/03/2002
7. This is the most efficient numeric description if arithmetic is being done on large numbers. same size and same number of decimal places. 7. Choose an appropriate type of field as follows: INDEX PIC S9(n) COMP PIC S9(x)V9(y) COMP-3 This should be used in preference to subscripting. That leaves programming. It is essential that program execution time is saved in the most heavily used CSS transactions (i.3
COBOL PERFORMS Issue 1. Always use an odd number of digits whenever possible. then one machine instruction is wasted in blanking out the sign following a MOVE or arithmetic instruction.0 By : UC Company Confidential Mahindra-British Telecom Limited
59861088. once it has stabilised. Should be used for counters and subscripts. Typical areas are: System software configuration Other software used (eg DBMS) Hardware configuration (eg disk drives) Compiler options (eg sign convention and optimisation) Link edit options Programming Changes to the first 5 areas above are not possible for authors of most CSS programs.
0 By : UC Company Confidential Mahindra-British Telecom Limited
. A CALLed subroutine will retain values for its working storage from a previous invocation on the second and subsequent calls. LINKed programs are provided with fresh working storage on each invocation and therefore the VALUE clause can be relied on. some means of identification must be provided to guard against unexpected use of the area by other transactions. Note that it is acceptable to design a set of linked transactions to hold common data in the user area .
59861088. always test for the most frequently occurring conditions first. ie.5 COBOL INITIALIZE
The USER-AREA must be initialised before use. WORKING-STORAGE is initialised to LOW-VALUES by the Cobol options implemented for CSS.4 for detailed management of the User Area. 7. never paragraphs. however. See also 8. Packed decimal items must be initialised to zero before arithmetic is performed.4. Under IBM COBOL the figure 0 behaves differently from the figurative constant ZERO. CONTINUE acts as a null operation. Ensure that these items are initialised by procedure division statements rather than VALUE clauses.Project: CSS – ISEC Title: Coding Standards
Page 14 of 22 Date : 22/03/2002
PERFORM only in-line code. Although this provides protection against random storage values being found in uninitialised items. or sections.4 PROCEDURE DIVISION COPYBOOKS These are NOT RECOMMENDED for Applications as readability is very poor. and the complexity of the compilation systems means that they are difficult to set up and very prone to error.
7. as illustrated below: ACTION MOVE ZERO TO display numeric item MOVE ZERO TO alphanumeric item MOVE ZERO TO group MOVE 0 TO display numeric item MOVE 0 TO alphanumeric item MOVE 0 TO group CONTENTS OF FIELD AFTER MOVE All 0 All 0 All 0 All 0 0 followed by all spaces 0 followed by all spaces
ZERO and 0 behave in ways corresponding to the above when used in IF or EVALUATE statements. LINKBC) which do include Procedure Division statements. so the statement logically following it is executed. It is totally ignored at run time.6
COBOL CONDITION STATEMENTS
When using IF or EVALUATE. to ensure a previous transaction’s data is not misinterpreted. and boolean flags should be initialised to their false state by VALUE clauses. Be aware that FILLER fields are not affected by an INITIALIZE command. that there are some generically-provided copybooks (e.
7. it is not a complete answer. Note. Always use ZERO rather than figure 0.doc
59861088. always end the literal string with a hash # character attribute byte. An easy way to test for a non-empty field content is to say ‘IF xxxxxx > SPACES’. should be completed before the next map is set up. If copying a section. As all of the output maps for a particular transaction use the same MAPOUT-AREA. please remove it.
7. MAPIN and MAPOUT are separate areas. Always close any open files before issuing a STOP RUN.Project: CSS – ISEC Title: Coding Standards
Page 15 of 22 Date : 22/03/2002
NEXT SENTENCE causes program execution to jump to the first statement after the next full stop. never move anything to the input area. If you have taken advantage of the option to miss out unnecessary full stops. or the next record may be corrupted. or perhaps have a NEXT SENTENCE in the middle of a complex in-line PERFORM.g. Note : USE OF NEXT SENTENCE MUST BE AVOIDED 7. It does NOT pass control to the most appropriate END-IF unless it is terminated by full stop. A literal string with long spaces in the middle should be split into several literal strings with few spaces. This should also be done in an abandoning subroutine if the contents of an output file are required for diagnosing the failure.doc
Issue 1. Otherwise the current buffer contents will be lost.0 By : UC Company Confidential Mahindra-British Telecom Limited
. degrading overall system performance. as all of the output maps for a particular transaction use the same MAPOUT-AREA. any attempt to move data to two maps at once may cause the transaction to abend with a data stream error. For a variable blocked file opened as INPUT. When defining literals on a map. It is important to recognise that under CMW. be sure to change the GOTO and the EXIT name. Therefore moving data to MAPOUT does not alter MAPIN. 7. cross-field validation.9
COBOL FILE HANDLING
Always define and check file status for every I/O for all types of files.8 ACCESSING MAP-AREA
THE MAPIN-AREA MUST NOT BE MODIFIED AS IT CAN CAUSE STORAGE VIOLATION IN CSS. Otherwise unnecessary spaces will be laboriously transmitted to the screen.7 USING GO TO
Use GO TO only to jump to the annn-EXIT paragraph of the section. All vetting of input from the current map which is done by the program itself. so a test that the field is empty must allow for both contents. Any optional field received from a map will contain either all LOW-VALUES or all SPACES.
DATA DIVISION..g. This IBM extension of COBOL enables the actual blocksize to be determined at run time. the suggested sample JCL for a 133-byte FBA print file is: //SFILE // // 59861088.RLSE). The suggested COBOL description for a 132-column print file is:FILE-CONTROL.
The BLOCK CONTAINS 0 RECORDS clause should always be coded for all files. explicit or default. File definition clauses. UNIT=DISK.1
Output Of Printer Files :
The maximum standard output width for printout is 132 columns. The omission of this clause will result in an UNBLOCKED file even if DCB=(RECFM=FBA.. then the output will be UNBLOCKED.(10. 05 S001-PRINT-LINE PIC X(132). and this will cause a waste of disk space. within the COBOL or ASSEMBLER program (overriding sources 2 and 3). To create a file for later printing.Project: CSS – ISEC Title: Coding Standards
Page 16 of 22 Date : 22/03/2002
7.CATLG). SPACE=(TRK. and a very large (e.doc DD DSN=userid. SELECT SFILE ASSIGN TO SFILE ORGANIZATION SEQUENTIAL FILE-STATUS W001-FILE-STATUS.9.0 By : UC Company Confidential Mahindra-British Telecom Limited
. This size will fit on either the remote matrix printers. to be used as a printer control character. then a laser printer with a standard 12 pitch font (12 characters per inch) will fail to print the remainder of the file if it encounters a non-space character past column 132. If this clause is not coded. 2.1). unnecessary physical I/O. CPU time and elapsed time. 01 S001-REC.BLKSIZE=. 4-fold) increase in disk usage.Explicit DCB clauses in the JCL DD statement (overriding source 3). If the print is wider than 132 columns.VOL=SER=vol-id. 3. enabling the program to function more flexibly. FILE SECTION.Dataset characteristics information contained within the existing dataset label. This is because dataset characteristics are determined at job running time strictly in the following sequence: 1. Thus the 132-byte file defined in COBOL to hold 132-character print-lines actually emerges from the job output spool as a 133-byte FBA or FBM file. Issue 1.DISP=(NEW.name. FD SFILE BLOCK CONTAINS 0 RECORDS LABEL RECORDS STANDARD DATA RECORD S001-REC.) is included in the JCL DD statement. or the main system laser printer. IBM software automatically inserts 1 byte before the print record.
4. the usual DCB=LRECL=133 is not necessary. 5. 9. Avoid hard-coding CSS transaction IDs within programs.10 COBOL FOR EASY MAINTENANCE This is a question of whether the code can be understood and altered quickly by someone other than the author. 7. Use CSS supplied map attributes. 8. However.doc Issue 1. This section also includes some of the things which can be done to help to prevent maintenance amendments causing unforeseen problems. Use meaningful data names. why the code does what it does.0 By : UC Company Confidential Mahindra-British Telecom Limited
3. to output directly to class R (CONTROL-D): //SFILE DD SYSOUT=R Note that in either case. (Record length is derived from the program. 1. Do not hard-code specific attribute bytes as literals. repeating in English what the COBOL is doing and anything else which may be obvious to you as the author. In addition to section annotation.Project: CSS – ISEC Title: Coding Standards //
Page 17 of 22 Date : 22/03/2002 DCB=(RECFM=FBA. or debug it at short notice. but not so obvious to the stranger who will have to maintain your code.)
7. try not to let the annotation interfere with the readability of the code. 6. The following scope terminators delimit both imperative and conditional statements:END-ADD END-CALL END-COMPUTE END-DELETE END-DIVIDE END-MULTIPLY END-READ END-RETURN END-REWRITE END-START END-STRING END-SUBTRACT END-UNSTRING 59861088. It ensures that someone else knows what is happening. This is sometimes seen as a waste as its purpose is to state the obvious. Use meaningful section names.BLKSIZE=4256)
or. Avoid NOT wherever possible.
. 2. what values a certain field can have at that point. Use 88 level condition names wherever possible. Use copybooks for any data that is referenced by more than one source module. put annotation in your code to say what is happening.
If a main module uses a CALL when a LINK is expected. The simplest approach to holding continuity data is to provide an area via the calling parameters copybook. If the program name is held in a working storage item. There is a similar performance advantage over CICS LINK for frequently invoked submodules. The following example is not valid: ADD A TO B ON SIZE ERROR DISPLAY X ADD Y TO Z END-ADD The following type of coding is recommended: ADD A TO B ON SIZE ERROR DISPLAY X ADD Y TO Z END-ADD END-ADD
8. It is entirely beneficial to break up a large program into smaller submodules. and the overheads caused by modularisation are relatively insignificant for the majority of business transactions. It supports inter-language calls and inter-system calls.Project: CSS – ISEC Title: Coding Standards END-WRITE e.and can result in excessive storage use. which generates coding complications . The following points are provided for consideration when deciding which method is appropriate. A full test of the calling 59861088. ADD 1 TO ABC END-ADD
Page 18 of 22 Date : 22/03/2002
When using the ‘ON SIZE ERROR’ statement the ‘END-ADD’ scope terminator must be coded for each corresponding ‘ADD’ statement. the submodule owner must be notified to ensure migration is carried out properly. Not only is maintenance and testing easier. defined in the working storage of the calling program. working storage elements will be smaller. Designers of a submodule should state what calling method is expected and provide an example of the invocation statements in the comments.1
Submodules are either static or dynamic in their invocation.g.doc Issue 1.values which are not initialised on entry may result in incorrect processing due to the hangover from previous invocations . It is the most efficient in CPU and storage terms for single invocations. It provides new program working storage on each call. The CICS LINK command is dynamic. static. program working storage is maintained over an entire task. but program loads will be quicker. COBOL CALL statements can be static or dynamic. On both types.0 By : UC Company Confidential Mahindra-British Telecom Limited
. and the same working storage considerations. Only limited inter-language facilities are possible. Dynamic COBOL calls are easier to manage than statically linked modules as no recompilation of main programs is required when they are migrated. if in a literal. the call is dynamic.
4 1. USAGE POINTER. Linked submodules can contain CICS commands and DML statements.Project: CSS – ISEC Title: Coding Standards
Page 19 of 22 Date : 22/03/2002
program must also be made to ascertain that the difference in working storage management does not result in errors. OPTIMUM USE OF SUBMODULES Each submodule should fulfil a single function. Submodule source should contain header comment lines documenting: • 59861088. 8.2 CICS LINKED SUBMODULES
These are initiated by the command:EXEC CICS LINK PROGRAM (‘module-name’) COMMAREA (‘data-name’) END-EXEC Each submodule should be designed to perform one specific function so that whenever it is invoked as much of the code as possible is used. 2.g. v-pointer is a variable (defined as USAGE POINTER in the COMMAREA) which will contain the address of the v-name on return from UT023UAS. UT023UAS is initiated in the host program by using a CALL statement: CALL ‘UT023UAS’ USING v-name. In any case.
The utility UT023UAS is used to provide the address of a parameter in WORKING-STORAGE.0 By : UC Company Confidential Mahindra-British Telecom Limited
. USAGE POINTER. You should pass multiple parameter areas using a LINK as follows: Set up the addresses of the areas to be passed rather than the areas themselves in the COMMAREA: 01 BR598-COMMAREA. 8.3 COBOL BATCH SUBMODULES For batch programs the CALL statement is very efficient. CALL ‘UT023UAS’ USING INST. It should be used whenever the work that you are doing can sensibly be packaged as a separately compiled module. A submodule which performs multiple services may incur high performance overheads which cannot be borne in on-line transactions. as CICS may decide to copy the area if the addressing capabilities of the two programs differ. The COBOL SET ADDRESS verb only works for the addresses in the LINKAGE SECTION. Issue 1. BR598-INST-REC-PTR
Where: v-name is the name of the WORKING-STORAGE parameter. CICS imposes a limit of 24K on the area to be passed between programs. 05 BR598-REQ-BLK-PTR 05 BR598-INST-REC-PTR 05 BR598-CUST-REC-PTR
USAGE POINTER. v-pointer
e. 8. It is slightly more expensive than a PERFORM but not appreciably so. it is always cheaper to pass addresses of parameters rather than the areas themselves.doc Records required by the submodule.
IDMS SPECIFIC POINTS SUBMODULES . 4..Sort-field-name must be defined in WORKING-STORAGE with the same length as the corresponding field in the database record. Large programs should be split up into submodules for readability and maintainability.If a submodule performs DML on behalf of the calling program. Submodules of large (usually batch) programs which behave as complete programs in their own right. 4. such as:System-wide submodules e. to access database queues or return customer name and address.5 1.. it will NOT be padded with spaces. 8. if your record is not a member then SET currency could be anything ! Use IF setname MEMBER’ first. but rather retain whatever values happening to be left in those bytes at the time..0 By : UC Company Confidential Mahindra-British Telecom Limited
. 3. WITHIN .doc Issue 1.g. 8. PROGRAM NAME . to ensure that your record is in the set. KEEP and KEEP EXCLUSIVE . since a REORGANISE will move these records to a different key value. especially the name of a submodule. This is a feature of COBOL II rather than IDMS. USING sort-field-name . and BIND all required record types in the calling program.
Programmers should assess the performance implications while deciding whether to use the submodule in question. Any program that receives control back from a submodule should move its own program name to the subschema control block. 5.
6. The WORKINGSTORAGE areas used for the database records must be held by the calling program and passed to the submodule as parameters. to facilitate debugging after an IDMS abend.
9. Note that the same problem exists in keyed access to VSAM KSDS datasets. READY all required database areas.This works on SET currency.
Page 20 of 22 Date : 22/03/2002
Areas accessed by the submodule Any submodules linked to. In the case of an optional set.Do not store DBKEY values in the database.
10. DBKEY ..Project: CSS – ISEC Title: Coding Standards • • 3. Contact the database team if you need assistance on this subject. Self-contained submodules which tend to be called frequently during a single run unit will waste resources if they BIND and READY at every call.
2. In order to lock records for a given area you must be in UPDATE mode. 59861088. No submodule should EVER require a MAP definition.
5.. within the submodule. leading to possible random errors. Common submodules that issue database requests can only be called by programs that have included in their subschema all of the AREAs required by the submodule. NEXT OF SET .Are ignored when your program is in RETRIEVAL mode on the area in which the record you are locking resides. There may be exceptions for submodules with database processing which is self-contained. If defined shorter. OBTAIN/FIND ..Always put it in the subschema control block.
READY once more” and simply condoning the IDMS-STATUS 0928 (area currently ready). must be PERFORM Z100-HANDLE-ABEND in order to suppress standard COBOL II abend routines which would: • • Duplicate much of the abend processing performed by Dialogue Manager Waste time and space by producing an unwanted dump. An unnecessary database call in an on-line program involves thousands of transparent assembler instructions transferring between CICS and IDMS. either used endlessly or handling vast volumes of data. but even a modest degree of inefficiency in an on-line program or submodule. BINDs and READYs . will impact system throughput. short delay in mounting tapes is likely to exceed the current IDMS wait interval of 3 minutes elapsed. when READY RETRIEVAL is sufficient. and lead to IDMS timeout without warning. it should be set immediately before the EXIT.6
Page 21 of 22 Date : 22/03/2002
SYSTEM THROUGHPUT AND EFFICIENCY
System throughput and efficiency is a pragmatic and quantitative issue. if any.if the program sets a RETURN-CODE. TAPE FILES . LUXURIES .use the necessary mode sparingly. 1. FINISH at the first possible moment. must be opened before issuing READYs. even when no physical I/O actually takes place during the DML call.EXEC CICS ASKTIME and TRACE should be removed before migration.
• Deprive Dialogue Manager abend handler of some of the data necessary to pinpoint the source of the problem. The overkill strategy of “when in doubt. 1. The rule is: READY at the last possible moment. IDMS SPECIFIC POINTS
3. Even a normal. Z100-HANDLE-ABEND . 2. READY RETRIEVAL MODE .doc
Issue 1. and program abend.
2.Project: CSS – ISEC Title: Coding Standards 8.7
The following list sumarises some of the key points regarding throughput and efficiency.
59861088. BIND and READY selectively only if and when it is required by the program logic path. do not READY UPDATE.
3. GOBACK or STOP RUN without any other intervening code. possibly by setting WORKING-STORAGE switches. the programmer should know whether an area is ready.0 By : UC Company Confidential Mahindra-British Telecom Limited
. RETURN-CODE .issue these only if strictly necessary.
4. and in the same phase as where I/O is performed. At any point in the program.
8.the first instruction in every on-line program (not submodules or copybooks).Tape file(s). This is because the IDMS FINISH resets the COBOL RETURN-CODE to zero. A high degree of waste and inefficiency in a rarely-used program is immaterial. Dateformatting submodule UT002DCS should not be used where a handful of COBOL MOVES will suffice. is inefficient. In popular transactions using a large variety of records.
OBTAIN NEXT record-name WITHIN CALC is not valid in IBM IDMS. It is far better to save the SUBSCHEMA-CTRL DBKEY field in work-fields defined as PIC S9(8) COMP.
7. ROLLBACK should only be used after a fatal error. not wastefully resolved by issuing another overkill FIND/OBTAIN “just to be sure of CURRENCY”.Project: CSS – ISEC Title: Coding Standards 4. The correct syntax is: ‘OBTAIN NEXT record-name WITHIN set-name’ or ‘OBTAIN DUPLICATE record-name’
5. releases locks and terminates the IDMS run unit.
Page 22 of 22 Date : 22/03/2002
FINISH and ROLLBACK . must FINISH or ROLLBACK. corresponding to the current record/set/area after each DML call. ROLLBACK nullifies all database changes since the last COMMIT..programmer’s uncertainty about CURRENCY should be efficiently clarified by consultation.doc
CURRENCY . ACCEPT db-key-v FROM (record-name/set-name/area-name) CURRENCY: This command does not change the currency. all this involving heavy IDMS overheads. but imposes heavy DML overheads.0 By : UC Company Confidential Mahindra-British Telecom Limited
. possibly I/O overheads. placing a strain on resources and an unacceptable burden on the system. In IBM IDMS this syntax produces no compilation errors. not to handle mild errors which are the province of the user program.all on-line and off-line programs which BIND RUN-UNIT and terminate without abending. because CALC is a system SET.
59861088. Failure to do so forces CICS and IDMS (often after a wasteful waiting period) to terminate the run unit by default. but causes database dumps.