Coding Standards I01

Project: CSS – ISEC of 22Title: Coding Standards Date : 22/03/2002

DOCUMENT NAME : CSS - NM COBOL Coding Standards.

ABSTRACT : This document provides the standards for COBOL coding for CSS NETWORK MANAGEMENT.

PREPARED BY : Upendra Curpad

REVIEWED BY : Sachin Punalekar Abhay Deshpande Sameer Saxena Umesh Shukla

APPROVED BY : Sachin Punalekar

VERSION NO : Issue 1.0

VERSION HISTORYVERSION DATE PREPARED BY CHANGES & REASONS FOR CHANGEDraft 0.1 26/02/02 Upendra Curpad First version Issue 1.0 22/03/02 Upendra Curpad Issued

REFERENCEDOCUMENT NAME VERSION LOCATIONApplication Development Guidelines

Issue 1.1 \Projdocs\Standard\ Adgver1.1.doc

Dos and Don’ts for IDMS DML Programming

Issue 1 \Projdocs\Standard\dmlprog.doc

document.doc Issue 1.0 By : UCCompany Confidential

Mahindra-British Telecom Limited


1 INTRODUCTION

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.

1.1 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




2 IN-LINE DOCUMENTATIONThe following types of embedded documentation are required in programs:-

Program header

Section header

Source level comments

2.1 PROGRAM HEADERThe heading data consists of a standard template to be filled in by the application programmer.

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.

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

:

:

:

:

:

:

:

:

:

:

:

:

:

:

QAOOODC

skeleton program

Release Number (e.g. 47)

Version Number (8.47.0)

Name

Dd/mm/yyyy

A brief description of the function of the program

Maps used e.g. QA000M1

(IDMS progs only) Schema ref e.g. SCCS00

(IDMS progs only) Subschema ref e.g. SSDCAA00

(IDMS progs only) DB records accesses e.g. REC-1

NONE

NONE

A List of Message Codes issued by the program.




NOTES : Additional Notes

AMENDMENT HISTORY

DATE/MOD VER/DU AUTH DESCRIPTION

The heading data is a comment block.

The heading data will consist of a standard template to be filled in by the application programmer.

2.2 SECTION HEADER

Each main section should include a header, briefly explaining the main functions of the section.

A section header is shown below:

A000-MAIN-CONTROL SECTION

NAME : Section Name

SYNOPSIS : Overall section logic:- e.g.

Call the abend handler.

Address data areas using the pointers passed from Dialogue

Manager.

Determine which phase to execute.

Return to Dialogue Manager.

RETURN CODES : Return Codes for this section.

CALLED BY : Section(s) which call this section.

Note: If a section is preceded by a ‘TITLE’ statement, it will cause a page break on the compilation listing. Do not code ‘EJECT’ and ‘TITLE’ unless you want two page breaks.

2.3 SOURCE LEVEL DOCUMENTATIONSource level documentation occurs within a section at two levels:-

Block comments which should precede complex code segments and describe their function.

Comments which pertain to a single statement of small code segment; these should be normal COBOL

comment statements.

Comments should be considered as an integral part of the program and as important as any other program statement. They should come before the corresponding code except for those denoting the end of a loop or end of data record declarations.

3 PROGRAMMING STANDARDS




3.1 PROCEDURE DIVISION FORMAT

1. A SECTION is composed of a Section Header and an EXIT-paragraph. The section header is the entry point and contains all the executable code for the section. The EXIT paragraph is the exit-point and contains only the EXIT verb. No other paragraph names are permitted within the Procedure Division.

2. Only SECTIONS may be PERFORMed (apart from in-line PERFORMs).

3. The sections are named according to hierarchical conventions. All sections and paragraphs begin with a standard format prefix consisting of one alpha and a three-digit number. Each major section begins with a new alpha. Minor sections performed from more than one major section are considered service sections. These should have their own alpha character - one letter further down the alphabet.

4. The three-digit number should be 000 for the major section. The minor ones should be grouped according to their relationships. Section A000 is the main section of the program and should contain its principal logic. Sections performed only by A000 (and other A sections) come next (e.g. A100-SEND-MAP).

5. Sections B, C etc. come next. Sections B000, C000 etc. should only be performed from A000 and should perform the other main functions of the program. Sections further down the hierarchy (and usually performed by many sections) are classified as service sections.

6. 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. These service routines will be appended to the applications code.

7. The order of sections in the source listing follows their order in the hierarchy of execution (i.e. a parent is followed by its descendants according to their invocation order).

3.2 PROCEDURE DIVISION STATEMENTS

The program may consist of statements containing any valid COBOL II verb except: ALTER GO TO ... DEPENDING ON

1. Commas and semi-colons are forbidden.

2. Only mandatory full stops should be used. This means that the only full stops needed will be at the

end of each section and paragraph, and to end labels.

3. Only one statement may be coded per line.

4. Standard indentation will be three spaces for each level of condition

5. Repetition is implemented with the PERFORM verb.

6. A branch is implemented with the GO TO statement. A branch may be made only from within a

SECTION to the EXIT-paragraph of that section (only local GO TOs are allowed).




7. Selection is implemented with the IF or EVALUATE verbs.

8. For all IF statements coded, the ELSE clause should be supplied (if null the CONTINUE verb must be

used), and terminated with END-IF. The IF, ELSE and END-IF must be aligned, and their dependent

statements indented by at least three spaces; for example:

IF DM-PROG-FLAG = ‘K’PERFORM G000-PHASE-KIF G000-UPDATE-FLAG = ‘1’

PERFORM H000-SETUP-PHASE-MELSE

CONTINUEEND-IF

ELSECONTINUE

END-IF

9. Nesting of IF statements deeper than three levels is strongly discouraged. If the logic demands more

than three, consider removing groups of lower-level logic into separate sections and perform them from the top of the original IF structure.

10. Where an EVALUATE is used the WHEN OTHER clause must always be coded; for example:

EVALUATE TRUEWHEN PHASE-DPERFORM D000-PHASE-D

WHEN PHASE-FPERFORM F000-PHASE-F

WHEN OTHERCONTINUE

END-EVALUATE

4 DATA DIVISION STANDARDS

1. Each item in a program should only have one purpose and its name should suggest that purpose.

2. WORKING-STORAGE SECTION data items are grouped together in records depending on where

they are used in the program. 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. To control program complexity a data item should not

be referenced in more sections than necessary.

3. The name of the work record is the name of the section to which it belongs, suffixed by - WORK.

4. Data items within the work record are prefixed with the section number and an abbreviation of the

section Name. For example, the variables rooted in section B300-GET-BILL-DETAILS SECTION

might be arranged thus:

01 B300-GET-BILL-DETAILS-WORK.




05 B300-GBD-DATA-BASE-KEY PIC S9(8) COMP. 05 B300-GBD-CUSTOMER-NUMBER PIC 9(8) DISPLAY.

5. Level numbers will follow the sequence 01...05...10...15 etc.

6. PICTURE clauses must be aligned.

7. Keep VALUE clauses to a single line.

8. Use level 88 variables where possible to improve program readability.

9. Level 77 items will not be used.

10. Level 66 items will not be used.

11. The name of an item which is the redefinition of another item is the name of the first item suffixed

with -R1. Further redefinitions follow the sequence.

05 B300-GBD-ITEM-NO PIC X(4).

05 B300-GBD-ITEM-NO-R1 REDEFINES B300-GBD-ITEM-NUMBER PIC S9(8) COMP.

05 B300-GBD-ITEM-NO-R2 REDEFINES B300-GBD-ITEM-NUMBER PIC S9(7) COMP-3.

5 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. Generally, it is best not to mix operations on different data types. Numeric items must always be signed if required for arithmetic purposes.

5.1 NOTES ON DATA TYPING

5.1.1 DISPLAY

One byte holds one character or one digit. This is the default data type in COBOL. A PIC X(4) field would hold the EBCDIC string ‘QB4S’ in hexadecimal as ‘D8 C2 F4 E2’.

5.1.2 DISPLAY (NUMERIC)




When a DISPLAY field has a numeric picture clause, arithmetic can be done on it. This type of usage is also known as Zoned Decimal.

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, of 8 bits, is represented by two hexadecimal characters. Each represents four bits, known as quartets. In DISPLAY NUMERIC the left-hand quartet of the right-most byte determines the sign of the number. F and C mean positive, whilst D means negative.

Before arithmetic can be done on a DISPLAY NUMERIC field, it is first converted to COMP-3 or to COMP format, the calculations done, and then converted back to DISPLAY. This conversion is inefficient.

5.1.3 COMP-3.

This is known as packed decimal, because, apart form one byte, each byte has two digits ‘packed’ into it, compared to the one digit per byte of DISPLAY.

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’.

The right-hand quartet of the right-most byte holds the sign. F and C mean positive, whilst D means negative.

The IBM architecture, can work directly in packed decimal, so its usage is relatively efficient for arithmetic.

5.1.4 COMP

This is known as binary, and holds numeric data in the most efficient way, except that fields occupy multiples of 2 or 4 bytes, so space may be wasted.

A PIC S9(5) COMP field occupies 4 bytes. A value 1783 would be held as ‘00 00 06 F7’.The sign of the field is determined by the value of the left-most bit of the left-most byte (the high-order bit). 0 means positive whilst 1 means that the field is negative. A value of -1783 would be held as ‘FF FF F9 07’. It is not a simple case of the high-order bit being set, because the number is held in two’s complement form. (Flip the bits and add 1).

The IBM architecture can work directly in binary, which is the most efficient usage for arithmetic.

5.1.5 Pointer Data Types

COBOL II introduced the USAGE IS POINTER clause in the Data Division. POINTERS are full word binary variables. 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, nor may arithmetic be performed.

To circumvent these difficulties in cases where pointer manipulation is necessary, the following practice is recommended.

05 B310-APG-TABLE-PTR POINTER.05 B310-APG-TABLE-PTR-R1 REDEFINES B310-APG-TABLE-PTR PIC S9(8) COMP.

5.1.6 Boolean Data Types




COBOL II does not supply a boolean data type. This should be simulated by means of level 88 variables, as follows:-

01 B300-GBD-RECORD-STATUS PIC 9 VALUE ZERO. 88 BILL-DETAIL-REC-FOUND VALUE 1. 88 BILL-DETAIL-REC-NOT-FOUND VALUE ZERO.

For Boolean variables both TRUE and FALSE level 88 condition names should be coded. Truth values should be coded following positive logic conventions:-

TRUE = 1FALSE = 0

5.1.7 Literals and Constants

Literals and constants should be declared in the WORKING-STORAGE Section, not embedded in the text. Constants should be assigned meaningful names. Where possible, splitting a literal across multiple lines should be avoided.

5.1.8 Initialization

Be aware of the capabilities (and spelling) of the INITIALIZE verb to simplify the setting-up of data areas.Note that INITIALIZE does not initialize FILLERs. To initialize the contents of FILLERs, either MOVE data to a group at a higher level, possibly to the whole record, or replace the FILLER by names.

Also, be careful when the data being initialzsed is redefined, or redefines something else.

A program’s working storage is initially set to binary zeros by the COBOL options used in CSS. VALUE clauses will supersede this. A Linked submodule’s working storage will always be reset to the same initialized values. CALLed submodules retain values set from a previous invocation in the same task.

6 EXCEPTION HANDLING

6.1 GENERAL CONSIDERATIONS

Exception handling refers to error handling and unexpected events at run-time. As a general principle:

All return codes should be checked following any type of request, and suitable action taken.

Wherever possible, input parameters to procedures should be checked for validity.

The convention to be adopted for return codes issued by programs should be ZERO for success or

> ZERO for error.

6.2 CICS CONSIDERATIONSException handling under CICS has been enhanced to enable properly structured programs to be written easily. However, there are programs written before the enhancements arrived which need to be maintained and so both approaches are covered here. New programs should use the second method exclusively.

There are general principles which must be noted:

1. 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. If you do not do so,




CICS will abend the task with a code which directly indicates the failing condition.

2. A subprogram entered by a CICS LINK or a COBOL CALL will not inherit the conditions set up by the caller.

6.2.1 The Original Method

Under the original method, the main commands provided were:

EXEC CICS IGNORE CONDITION condition nameEXEC 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. It is also possible to use the NOHANDLE option on an individual command to override all relevant HANDLE commands temporarily.

These statements effectively translate into GO TOs, producing the following programming problems :

An EXEC CICS HANDLE statement requires a target label to be supplied. This implies that additional

paragraph names, over and above the EXIT paragraph required by the programming standard, be coded.

The GO TO may result in transfer of control out of the section in which the exception occurred.

To minimise the impact of this unavoidable conflict with standards, and to preserve the advantages of structured programming, the following methods were adopted:

For each condition to be handled within the program, declare a Boolean variable:

05 WA-MCS-MAPFAIL-INDICATOR PIC 9. 88 MAPFAIL VALUE 1. 88 NO-MAPFAIL VALUE ZERO.05 WB-MCS-QIDERR-INDICATOR PIC 9. 88 QIDERR VALUE 1. 88 NO-QIDERR VALUE ZERO.

For each class of CICS command to be issued, place the command in a separate section. The ‘HANDLE’

clause and its destination labels are placed within this section. For example:

Q100-READQ-SECTION.EXEC CICS HANDLE CONDITION

ITEMERR(ITEMERR-LAB)QIDERR (QIDERR-LAB)

END-EXEC

SET NO-QIDERR TO TRUESET NO-ITEMERR TO TRUE

EXEC CICS READQ TSQUEUE (WC-MCS-QNAME)INTO (WD-MCS-QRECORD)ITEM (WE-MCS-REC-NUMBER)




END EXEC

GO TO Q100-READQ-EXIT.QIDERR-LAB.

SET QIDERR TO TRUEGO TO Q100-READQ-EXIT

.ITEMERR-LAB.

SET ITEMERR TO TRUE.

Q100-READQ-EXIT.EXIT.

This class of section may contain paragraph names other than the EXIT paragraph, as necessitated by the

CICS pre-processing.

The application coding then proceeded, following normal structured techniques. For example:

PERFORM Q100-READQIF QIDERR MOVE ‘QUEUE NOT FOUND’ TO DM-MSG-TEXT PERFORM Y100-ERROR-RETURNELSE IF ITEMERR MOVE ‘RECORD NOT FOUND ON QUEUE’ TO DM-MSG-TEXT ELSE CONTINUE END-IFEND-IF

6.2.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. The result of the command MUST then be tested on return and CICS provides readable values to test against.

For example:

EXEC CICS READQ TSQUEUE(WC-MCS-QNAME)

INTO (WD-MCS-QRECORD) ITEM (WE-MCS-REC-NUMBER) RESP (WS-RESP) RESP2 (WS-RESP2)

END EXEC

EVALUATE WS-RESPWHEN DFHRESP(NORMAL)

CONTINUE WHEN DFHRESP(QIDERR)

MOVE ‘TSQ NOT FOUND’ TO DM-MSG-TEXT




PERFORM Y100-ERROR-RETURNWHEN DFHRESP(ITEMERR)

MOVE ‘REC NOT ON TSQ’ TO DM-MSG-TEXT PERFORM Y100-ERROR-RETURNWHEN OTHER

STRING ‘TSQ ERROR’ ,WS-RESP INTO DM-MSG-TEXT PERFORM Y100-ERROR-RETURNEND-EVALUATE

It is important to note that :

The response fields must be binary fullwords ( PIC S9(8) COMP).

If you code a RESP operand on a command, CICS assumes you will test it.

If you do not code the RESP operand, CICS will abend the transaction if an exceptional condition

occurs, assuming there is no HANDLE CONDITION in force.

It is quite acceptable to allow CICS to abend a transaction if a condition is genuinely an error - for

example PGMIDERR on a LINK.

The RESP2 field contains additional information about the problem which may be of use. It is not

compulsory to code it.

6.3 IDMS CONSIDERATIONS

IDMS exceptions are handled in the following way:1. Following each DML request, the application will check the return code. Application-specific

actions must be coded to handle all anticipated return codes which will commonly occur (e.g. end-of-set, record-not-found, etc.).

2. Standard routines are provided to check the return status from each DML request, see “IDMS Error Handling”, section 6.5. These routines are copied in by the CMW Pre-Processor as part of the compilation process.

3. It is up to the programmer to check for specific conditions e.g. DB-END-OF-SET beforeperforming the standard status check.

6.4 ABEND CONSIDERATIONS

Program abends under CICS are handled by inclusion of a standard section in each program.

Z100-HANDLE-ABEND




7 COBOL PROGRAMMING CONSIDERATIONS

7.1 COBOL EFFICIENCY

There are a number of aspects to the run-time efficiency of a COBOL program.

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.

That leaves programming, and there are a number of ways to define data and arrange procedures which can affect run times. It is essential that program execution time is saved in the most heavily used CSS transactions (i.e. those used more than 1000 times per day) because the critical factor in the success of the system, once it has stabilised, will be the response time.

7.2 COBOL FIELD DESCRIPTIONS

All counters and fields used in arithmetic should be signed whenever possible. If they are unsigned, then one machine instruction is wasted in blanking out the sign following a MOVE or arithmetic instruction.

Choose an appropriate type of field as follows:

INDEX This should be used in preference to subscripting.

PIC S9(n) COMP Should be used for counters and subscripts.

PIC S9(x)V9(y) COMP-3 This is the most efficient numeric description if arithmetic is being done on large numbers, eg large money amounts. Always use an odd number of digits whenever possible, as this is handled more efficiently.

PIC S9(x) DISPLAY Should be used only for numeric items which are to be output to a report or job journal, or to a similar database description. It is the most inefficient description for a subscript.

Whenever possible in arithmetic, use all fields of the same type, same size and same number of decimal places.

7.3 COBOL PERFORMS




PERFORM only in-line code, or sections, never paragraphs.

7.4 PROCEDURE DIVISION COPYBOOKSThese 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.

Note, however, that there are some generically-provided copybooks (e.g. LINKBC) which do include Procedure Division statements.

7.5 COBOL INITIALIZE

The USER-AREA must be initialised before use, to ensure a previous transaction’s data is not

misinterpreted. Note that it is acceptable to design a set of linked transactions to hold common data in the

user area - however, some means of identification must be provided to guard against unexpected use of the

area by other transactions. See also 8.4.4 for detailed management of the User Area.

WORKING-STORAGE is initialised to LOW-VALUES by the Cobol options implemented for CSS.

Although this provides protection against random storage values being found in uninitialised items, it is not

a complete answer. Packed decimal items must be initialised to zero before arithmetic is performed, and

boolean flags should be initialised to their false state by VALUE clauses.

A CALLed subroutine will retain values for its working storage from a previous invocation on the second

and subsequent calls. Ensure that these items are initialised by procedure division statements rather than

VALUE clauses. LINKed programs are provided with fresh working storage on each invocation and

therefore the VALUE clause can be relied on.

Be aware that FILLER fields are not affected by an INITIALIZE command.

Always use ZERO rather than figure 0. Under IBM COBOL the figure 0 behaves differently from the

figurative constant ZERO, as illustrated below:

ACTION CONTENTS OF FIELD AFTER MOVEMOVE ZERO TO display numeric item All 0MOVE ZERO TO alphanumeric item All 0MOVE ZERO TO group All 0MOVE 0 TO display numeric item All 0MOVE 0 TO alphanumeric item 0 followed by all spacesMOVE 0 TO group 0 followed by all spaces

ZERO and 0 behave in ways corresponding to the above when used in IF or EVALUATE statements.

7.6 COBOL CONDITION STATEMENTS

When using IF or EVALUATE, always test for the most frequently occurring conditions first.

CONTINUE acts as a null operation, ie. It is totally ignored at run time, so the statement logically

following it is executed.




NEXT SENTENCE causes program execution to jump to the first statement after the next full stop. It does

NOT pass control to the most appropriate END-IF unless it is terminated by full stop. If you have taken

advantage of the option to miss out unnecessary full stops, or perhaps have a NEXT SENTENCE in the

middle of a complex in-line PERFORM, please remove it.

Note : USE OF NEXT SENTENCE MUST BE AVOIDED

7.7 USING GO TO

Use GO TO only to jump to the annn-EXIT paragraph of the section.

If copying a section, be sure to change the GOTO and the EXIT name.

7.8 ACCESSING MAP-AREA

THE MAPIN-AREA MUST NOT BE MODIFIED AS IT CAN CAUSE STORAGE VIOLATION IN

CSS.

When defining literals on a map, always end the literal string with a hash # character attribute byte. A

literal string with long spaces in the middle should be split into several literal strings with few spaces.

Otherwise unnecessary spaces will be laboriously transmitted to the screen, degrading overall system

performance.

Any optional field received from a map will contain either all LOW-VALUES or all SPACES, so a test

that the field is empty must allow for both contents. An easy way to test for a non-empty field content is to

say ‘IF xxxxxx > SPACES’.

All vetting of input from the current map which is done by the program itself, e.g. cross-field validation,

should be completed before the next map is set up, as all of the output maps for a particular transaction use

the same MAPOUT-AREA.

It is important to recognise that under CMW, MAPIN and MAPOUT are separate areas. Therefore moving

data to MAPOUT does not alter MAPIN. 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.

7.9 COBOL FILE HANDLING

Always define and check file status for every I/O for all types of files.

For a variable blocked file opened as INPUT, never move anything to the input area, or the next record

may be corrupted.

Always close any open files before issuing a STOP RUN. This should also be done in an abandoning

subroutine if the contents of an output file are required for diagnosing the failure. Otherwise the current

buffer contents will be lost.




7.9.1 Output Of Printer Files :

The maximum standard output width for printout is 132 columns. This size will fit on either the remote matrix printers, or the main system laser printer. If the print is wider than 132 columns, 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.

IBM software automatically inserts 1 byte before the print record, to be used as a printer control character. 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.

The suggested COBOL description for a 132-column print file is:-

FILE-CONTROL.SELECT SFILEASSIGN TO SFILEORGANIZATION SEQUENTIALFILE-STATUS W001-FILE-STATUS.

DATA DIVISION.FILE SECTION.

FD SFILEBLOCK CONTAINS 0 RECORDSLABEL RECORDS STANDARDDATA RECORD S001-REC.

01 S001-REC.05 S001-PRINT-LINE PIC X(132).

The BLOCK CONTAINS 0 RECORDS clause should always be coded for all files. This IBM extension of COBOL enables the actual blocksize to be determined at run time, enabling the program to function more flexibly.

If this clause is not coded, then the output will be UNBLOCKED, and this will cause a waste of disk space, unnecessary physical I/O, and a very large (e.g. 4-fold) increase in disk usage, CPU time and elapsed time. The omission of this clause will result in an UNBLOCKED file even if DCB=(RECFM=FBA,BLKSIZE=...) is included in the JCL DD statement. This is because dataset characteristics are determined at job running time strictly in the following sequence:

1. File definition clauses, explicit or default, within the COBOL or ASSEMBLER program (overriding sources 2 and 3).

2.Explicit DCB clauses in the JCL DD statement (overriding source 3).

3.Dataset characteristics information contained within the existing dataset label.

To create a file for later printing, the suggested sample JCL for a 133-byte FBA print file is:

//SFILE DD DSN=userid.name,DISP=(NEW,CATLG),

// SPACE=(TRK,(10,1),RLSE),

// UNIT=DISK,VOL=SER=vol-id,




// DCB=(RECFM=FBA,BLKSIZE=4256)

or, to output directly to class R (CONTROL-D):

//SFILE DD SYSOUT=R

Note that in either case, the usual DCB=LRECL=133 is not necessary. (Record length is derived from the program.)

7.10 COBOL FOR EASY MAINTENANCEThis is a question of whether the code can be understood and altered quickly by someone other than the author. This section also includes some of the things which can be done to help to prevent maintenance amendments causing unforeseen problems.

1. Avoid NOT wherever possible.

2. In addition to section annotation, put annotation in your code to say what is happening, what values a

certain field can have at that point, why the code does what it does; repeating in English what the

COBOL is doing and anything else which may be obvious to you as the author, but not so obvious to

the stranger who will have to maintain your code, or debug it at short notice. This is sometimes seen

as a waste as its purpose is to state the obvious. It ensures that someone else knows what is happening.

However, try not to let the annotation interfere with the readability of the code.

3. Use meaningful section names.

4. Use meaningful data names.

5. Use 88 level condition names wherever possible.

6. Use copybooks for any data that is referenced by more than one source module.

7. Avoid hard-coding CSS transaction IDs within programs.

8. Use CSS supplied map attributes. Do not hard-code specific attribute bytes as literals.

9. The following scope terminators delimit both imperative and conditional statements:-

END-ADDEND-CALLEND-COMPUTEEND-DELETEEND-DIVIDEEND-MULTIPLYEND-READEND-RETURNEND-REWRITEEND-STARTEND-STRINGEND-SUBTRACTEND-UNSTRING




END-WRITEe.g.

ADD 1 TO ABCEND-ADD

When using the ‘ON SIZE ERROR’ statement the ‘END-ADD’ scope terminator must be coded for each corresponding ‘ADD’ statement.

The following example is not valid:

ADD A TO BON SIZE ERROR

DISPLAY XADD Y TO Z

END-ADD

The following type of coding is recommended:

ADD A TO BON SIZE ERROR

DISPLAY XADD Y TO ZEND-ADD

END-ADD

8 SUBMODULES

8.1 ON-LINE SUBMODULES

Submodules are either static or dynamic in their invocation. The following points are provided for consideration when deciding which method is appropriate.

The CICS LINK command is dynamic. It supports inter-language calls and inter-system calls. It is the most efficient in CPU and storage terms for single invocations.

It provides new program working storage on each call. The simplest approach to holding continuity data is to provide an area via the calling parameters copybook, defined in the working storage of the calling program.

COBOL CALL statements can be static or dynamic. If the program name is held in a working storage item, the call is dynamic, if in a literal, static. On both types, program working storage is maintained over an entire task, which generates coding complications - values which are not initialised on entry may result in incorrect processing due to the hangover from previous invocations - and can result in excessive storage use. 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. There is a similar performance advantage over CICS LINK for frequently invoked submodules, and the same working storage considerations.

It is entirely beneficial to break up a large program into smaller submodules. Not only is maintenance and testing easier, but program loads will be quicker, working storage elements will be smaller, and the overheads caused by modularisation are relatively insignificant for the majority of business transactions.

Designers of a submodule should state what calling method is expected and provide an example of the invocation statements in the comments. If a main module uses a CALL when a LINK is expected, the submodule owner must be notified to ensure migration is carried out properly. A full test of the calling




program must also be made to ascertain that the difference in working storage management does not result in errors.

8.2 CICS LINKED SUBMODULES

These are initiated by the command:-

EXEC CICS LINKPROGRAM (‘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.

Linked submodules can contain CICS commands and DML statements.

CICS imposes a limit of 24K on the area to be passed between programs. In any case, it is always cheaper to pass addresses of parameters rather than the areas themselves, as CICS may decide to copy the area if the addressing capabilities of the two programs differ.

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. 05 BR598-REQ-BLK-PTR USAGE POINTER.

05 BR598-INST-REC-PTR USAGE POINTER.

05 BR598-CUST-REC-PTR USAGE POINTER.

The utility UT023UAS is used to provide the address of a parameter in WORKING-STORAGE. The

COBOL SET ADDRESS verb only works for the addresses in the LINKAGE SECTION.

UT023UAS is initiated in the host program by using a CALL statement:CALL ‘UT023UAS’ USING v-name, v-pointere.g. CALL ‘UT023UAS’ USING INST, BR598-INST-REC-PTRWhere: v-name is the name of the WORKING-STORAGE parameter, 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.

8.3 COBOL BATCH SUBMODULESFor batch programs the CALL statement is very efficient. It is slightly more expensive than a PERFORM but not appreciably so. It should be used whenever the work that you are doing can sensibly be packaged as a separately compiled module.

8.4 OPTIMUM USE OF SUBMODULES

1. Each submodule should fulfil a single function. A submodule which performs multiple services may

incur high performance overheads which cannot be borne in on-line transactions.

2. Submodule source should contain header comment lines documenting:

Records required by the submodule.




Areas accessed by the submodule

Any submodules linked to, within the submodule.

3. Programmers should assess the performance implications while deciding whether to use the submodule

in question.

4. Large programs should be split up into submodules for readability and maintainability.

5. No submodule should EVER require a MAP definition.

8.5 IDMS SPECIFIC POINTS

1. SUBMODULES - If a submodule performs DML on behalf of the calling program, READY all

required database areas, and BIND all required record types in the calling program. The WORKING-

STORAGE areas used for the database records must be held by the calling program and passed to the

submodule as parameters. There may be exceptions for submodules with database processing which is

self-contained, such as:-

2. System-wide submodules e.g. to access database queues or return customer name and address.

3. Submodules of large (usually batch) programs which behave as complete programs in their own right.

4. 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. Contact the database team if you need assistance on

this subject.

5. KEEP and KEEP EXCLUSIVE - Are ignored when your program is in RETRIEVAL mode on the area

in which the record you are locking resides. In order to lock records for a given area you must be in

UPDATE mode.

6. NEXT OF SET - This works on SET currency. In the case of an optional set, if your record is not a

member then SET currency could be anything ! Use IF setname MEMBER’ first, to ensure that your

record is in the set.

7. DBKEY - Do not store DBKEY values in the database, since a REORGANISE will move these

records to a different key value.

8. PROGRAM NAME - Always put it in the subschema control block, especially the name of a

submodule, to facilitate debugging after an IDMS abend. Any program that receives control back from

a submodule should move its own program name to the subschema control block.

9. OBTAIN/FIND .... WITHIN .... USING sort-field-name - Sort-field-name must be defined in

WORKING-STORAGE with the same length as the corresponding field in the database

record. If defined shorter, it will NOT be padded with spaces, but rather retain whatever values

happening to be left in those bytes at the time, leading to possible random errors. This is a feature of

COBOL II rather than IDMS. Note that the same problem exists in keyed access to VSAM KSDS

datasets.

10. 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.




8.6 SYSTEM THROUGHPUT AND EFFICIENCY

System throughput and efficiency is a pragmatic and quantitative issue. A high degree of waste and inefficiency in a rarely-used program is immaterial, but even a modest degree of inefficiency in an on-line program or submodule, either used endlessly or handling vast volumes of data, will impact system throughput. An unnecessary database call in an on-line program involves thousands of transparent assembler instructions transferring between CICS and IDMS, even when no physical I/O actually takes place during the DML call.

1. Z100-HANDLE-ABEND - the first instruction in every on-line program (not submodules or

copybooks), 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.

Deprive Dialogue Manager abend handler of some of the data necessary to pinpoint the source of

the problem.

2. LUXURIES - EXEC CICS ASKTIME and TRACE should be removed before migration. Date-

formatting submodule UT002DCS should not be used where a handful of COBOL MOVES will

suffice.

3. TAPE FILES - Tape file(s), if any, must be opened before issuing READYs. Even a normal, short

delay in mounting tapes is likely to exceed the current IDMS wait interval of 3 minutes elapsed, and

lead to IDMS timeout without warning, and program abend.

4. RETURN-CODE - if the program sets a RETURN-CODE, it should be set immediately before the

EXIT, GOBACK or STOP RUN without any other intervening code. This is because the IDMS

FINISH resets the COBOL RETURN-CODE to zero.

8.7 IDMS SPECIFIC POINTS

The following list sumarises some of the key points regarding throughput and efficiency.

1. BINDs and READYs - issue these only if strictly necessary, and in the same phase as where I/O is performed. In popular transactions using a large variety of records, BIND and READY selectively only if and when it is required by the program logic path. The rule is: READY at the last possible moment; FINISH at the first possible moment.

2. At any point in the program, the programmer should know whether an area is ready, possibly by setting WORKING-STORAGE switches. The overkill strategy of “when in doubt, READY once more” and simply condoning the IDMS-STATUS 0928 (area currently ready), is inefficient.

3. READY RETRIEVAL MODE - use the necessary mode sparingly, do not READY UPDATE, when READY RETRIEVAL is sufficient.




4. FINISH and ROLLBACK - all on-line and off-line programs which BIND RUN-UNIT and terminate

without abending, must FINISH or ROLLBACK. Failure to do so forces CICS and IDMS (often after

a wasteful waiting period) to terminate the run unit by default, placing a strain on resources and an

unacceptable burden on the system. ROLLBACK should only be used after a fatal error, not to handle

mild errors which are the province of the user program. ROLLBACK nullifies all database changes

since the last COMMIT, releases locks and terminates the IDMS run unit, all this involving heavy

IDMS overheads.

5. ACCEPT db-key-v FROM (record-name/set-name/area-name) CURRENCY: This command does not

change the currency, but imposes heavy DML overheads, possibly I/O overheads. It is far better to

save the SUBSCHEMA-CTRL DBKEY field in work-fields defined as PIC S9(8) COMP.,

corresponding to the current record/set/area after each DML call.

6. OBTAIN NEXT record-name WITHIN CALC is not valid in IBM IDMS. In IBM IDMS this syntax

produces no compilation errors, but causes database dumps, because CALC is a system SET.

The correct syntax is: ‘OBTAIN NEXT record-name WITHIN set-name’ or‘OBTAIN DUPLICATE record-name’

7. CURRENCY - programmer’s uncertainty about CURRENCY should be efficiently clarified by

consultation, not wastefully resolved by issuing another overkill FIND/OBTAIN “just to be sure of

CURRENCY”.



Coding Standards I01

Documents

Transcript of Coding Standards I01