COBOL Considerations

Identification Division.
 No differences
Environment Division
 MUST be EMPTY in CICS Program!
 No SELECT statements allowed!
Data Division
 No FILE SECTION – (No SELECTS)

CICS-Prg 1
COBOL Considerations (More)
Data Division
 WORKING-STORAGE SECTION.
 Switches, Flags, Variables, Records, etc.
 You get ‘fresh’ copy each time program loaded!
 LINKAGE SECTION (New Item!!)
 DFHCOMMAREA defined or CICS will!
 Used to receive data from CICS.
 CICS also inserts EIB Block definition

CICS-Prg 2
COBOL Considerations (More)
Procedure Division
 Uses most COBOL statements
 Also uses CICS Commands like:
 RETURN
 XCTL
 SEND MAP
 RECEIVE MAP
 READ DATASET

CICS-Prg 3
Where are WE?
Program must be able to determine!
Always starts at beginning of Program
Starts with initialized Working-Storage
Can use several methods:
 EIBCALEN (First time program loaded)
 COMMAREA (Tran-ID, EIBAID)
 Hidden Data on Screen

CICS-Prg 4
Where are We? (More)
Beginning of Program must determine!
Can use series of ‘IF’ statements
 Can be nested (or not if careful!)
 Usually each path ends with RETURN
Can use EVALUATE statement
 EVALUATE TRUE most common (New Dev)
 General WHEN OTHER for errors

CICS-Prg 5
Sample CICS COBOL Program
WORKING-STORAGE SECTION.
 Switches, Flags, and Misc Variables
 COMMUNICATION-AREA (Your copy!)
 RESPONSE-CODE PIC S9(08) COMP.
 RECORD Descriptions
 COPY Library for MAP
 Other COPY Members as needed

CICS-Prg 6
Sample CICS COBOL Program
LINKAGE SECTION.
 DFHCOMMAREA PIC X(nnn).
If you don’t code it, CICS Will!
The commarea (if any) placed here!
EIBCALEN gives length of commarea
0 (ZERO) means there is NO commarea

CICS-Prg 7
Sample CICS COBOL Program
PROCEDURE DIVISION (Where are we?)
IF first-time
SEND Initial-Map
ELSE
IF <ENTER>
Process Screen
ELSE
Process Function-Key
END-IF
END-IF
SEND MAP

CICS-Prg 8
Sample CICS COBOL Program
PROCEDURE DIVISION
EVALUATE TRUE
WHEN EIBCALEN = 0
First time in Program
WHEN EIBAID = DFHENTER
Process Screen
WHEN EIBAID = DFHPF3 or DFHPF12
Exit Program
WHEN OTHER
Invalid key
END-EVALUATE
CICS-Prg 9
Basic CICS Commands

General Structure:
EXEC CICS
CICS COMMAND
OPTION(value) …
(Parameters as needed)
END-EXEC

CICS-Prg 10
Basic CICS Commands
EXEC CICS
RETURN [ TRANSID(name) ]
[ COMMAREA(data-area) ]
[ LENGTH(data-value) ]
END-EXEC
Length – PIC S9(4) COMP or Literal

CICS-Prg 11
Basic CICS Commands
EXEC CICS
XCTL PROGRAM(name)
[ COMMAREA(data-area) ]
[ LENGTH(data-value) ]
END-EXEC

CICS-Prg 12
Basic CICS Commands
EXEC CICS
SEND MAP(name)
[ MAPSET(name) ]
[ FROM(data-area) ]
[ MAPONLY | DATAONLY ]
[ ERASE | ERASEUP ]
[ CURSOR [ (value) ] ]
END-EXEC

CICS-Prg 13
Basic CICS Commands
EXEC CICS
RECEIVE MAP(map-name)
[ MAPSET(mapset-name) ]
INTO(data-area)
END-EXEC

CICS-Prg 14
Basic CICS Commands
EXEC CICS
READ DATASET(filename)
INTO(data-area)
RIDFLD(data-area)
[ RRN | RBA ]
[ UPDATE ]
END-EXEC
CICS-Prg 15
Basic CICS Commands
EXEC CICS
ABEND [ ABCODE(name) ]
END-EXEC

(ABCODE used to identify storage dump -

Usually omitted!)

CICS-Prg 16
CICS Program Design
Event-driven design
Structure Chart - Consider All Functions
Identify Events and Context
 Any action that starts program
 List All (Valid) Possible User Actions
Design Appropriate Response
 Processing required for an event
 Managing user interaction

CICS-Prg 17
CICS Program Design
COMMAREA usually stores ‘context’
 Get Key
 Add Customer
 Change Customer
 Delete Customer
Response to same key can be different
depending on ‘context’ (ENTER key)

CICS-Prg 18
CICS Program Design
Event/Response Chart
 Helps with design or Program
 Serves as Documentation of Program
 Sometimes replaced with ‘Structure Chart’
Structure Chart ‘Evolves’ into Design
 Start with Major Functions
 Add Detail as Needed
 Assign Paragraph Numbering (If Used)

CICS-Prg 19
More CICS Commands
EXEC CICS
WRITE DATASET(filename)
FROM(data-area)
RIDFLD(data-area)
[ RRN | RBA ]
END-EXEC

CICS-Prg 20
More CICS Commands
EXEC CICS
REWRITE DATASET(filename)
FROM(data-area)
END-EXEC
NOTES:
Record MUST be READ with UPDATE!
data-area - NOT have to match Read
CICS-Prg 21
More CICS Commands
EXEC CICS
DELETE DATASET(filename)
[ RIDFLD(data-area) ]
[ RRN | RBA ]
END-EXEC
NOTE: If no RIDFLD last READ is Deleted

CICS-Prg 22
More CICS Commands
EXEC CICS
UNLOCK DATASET(filename)
END-EXEC
NOTE: If READ/UPDATE command is
used and you determine that record
does not need to be updated. Usually
not needed as record is unlocked when
the task is terminated.

CICS-Prg 23
Exception Conditions
Most Common Exceptions:
 DISABLED Dataset disabled
 DUPREC Record already exists
 FILENOTFND Dataset not in FCT
 INVREQ Invalid request
 IOERR File I/O error
 NOTAUTH User not authorized
 NOTFND Record not in file

CICS-Prg 24
Checking for Exceptions
ALL CICS Commands allow RESP Parm
01 RESP-CODE PIC S9(8) COMP.
IF RESP-CODE = DFHRESP(NORMAL)
MOVE ‘Y’ TO OK-COMMAND
ELSE
IF RESP-CODE = DFHRESP(NOTFND)
MOVE ‘N’ TO REC-NOT-FOUND
ELSE
PERFORM DISPLAY-MISC-ERROR
END-IF
END-IF

CICS-Prg 25
Preventing File Corruption
PREVENT
 Add ‘busy’ flag in record (Special Maint)
 All programs MUST follow procedure
 Extra I/O required (to Set/Reset flag)
DETECT
 Save copy and compare before updating
 OR – Add Maint-Timestamp and check it
 Notify User to get latest version of data

CICS-Prg 26
Avoiding Deadlock
Sometimes called ‘Deadly Embrace’
Happens when records from multiple
files must be updated as a unit
 Withdraw from Savings – Deposit to Check
 Crash after withdraw? Where’s money?
Must both be done or neither! (Atomic)

CICS-Prg 27
Program Control Commands
EXEC CICS
RETURN [ TRANSID(name) ]
[ COMMAREA(data-area) ]
[ LENGTH(data-value) ]
END-EXEC

CICS-Prg 28
Program Control Commands
EXEC CICS
LINK PROGRAM(name)
[ COMMAREA(data-area) ]
[ LENGTH(data-value) ]
END-EXEC
NOTE: Program name must be in PPT.
Works like COBOL PERFORM statement.
CICS-Prg 29
Program Control Commands
EXEC CICS
XCTL PROGRAM(name)
[ COMMAREA(data-area) ]
[ LENGTH(data-value) ]
END-EXEC
NOTE: Program name must be in PPT.

CICS-Prg 30
Terminal Handling
CURSOR Positioning (in SEND MAP)
 IC option in DFHMDF Macro (ATTRB Parm)
 If more than one – LAST position is used.
 DIRECT Cursor Positioning
 CURSOR(nnn) where nnn is position on screen
 Displacement from start of the screen
 ( Row – 1 ) * 80 + ( Column – 1 )
 0 is Row 1, Column 1
 1919 is Row 24, Column 80 (24 by 80 Screen)
 Changes in screen require changes to program
(Not used much - too complex!)

CICS-Prg 31
Terminal Handling (More)
CURSOR Positioning (in SEND MAP)
 Symbolic Cursor Positioning (Preferred!)
 CURSOR – with no position parameter!
 Specify the FIELD where the CURSOR goes
 Place –1 in the LENGTH Attribute of the field
where the cursor is to be placed
 ‘FIELD NAME’ with ‘L’ appended is LENGTH
 If more than one – FIRST position is used.
 BINARY HALFWORD - PIC S9(04) COMP.

CICS-Prg 32
Terminal Handling (More yet)
Determining the position of CURSOR
when the user types an AID key.
 EIBCPOSN – in EIB Block (binary halfword)
 READ only-Available before RECEIVE MAP
 Can be used to determine user selection
instead of requiring user to enter character

CICS-Prg 33
Attribute Modification
Symbolic Map includes Attribute byte
‘Field Name’ with ‘A’ appended
Cryptic ‘bit’ codes and names used
Copy library supplied by IBM (Horrible)
Most shops have their own copy book
We don’t have ‘extended attributes’!

CICS-Prg 34
Editing Input Data
All data entered should be validated
Required data must be present
Numeric data needs to be ‘normalized’
Alpha data should not be spaces
Meaningful error messages displayed
Very tedious coding required!
Do checking from ‘bottom to top’!
CICS-Prg 35
Misc CICS Commands
EXEC CICS
SEND TEXT FROM(data-area)
[ LENGTH(data-value) ]
[ ERASE ]
[ FREEKB]
END-EXEC
NOTE: No FREEKB user must hit RESET!
CICS-Prg 36
Misc CICS Commands
EXEC CICS
HANDLE AID
option(procedure name)
…
END-EXEC

CICS-Prg 37
Misc CICS Commands
HANDLE AID Options:
 PA1-PA3 Program Attention Keys
 PF1-PF24 Program Function Keys
 ENTER The ENTER Key
 CLEAR The CLEAR Key
 ANYKEY Any key not Specified
(Except the ENTER key)

CICS-Prg 38
Handle AID Example (Old)
EXEC CICS
HANDLE AID PF3(900-MENU)
CLEAR(850-CLEAR)
ENTER(700-ENTER)
ANYKEY(750-ERROR)
END-EXEC
NOTE: HANDLE AID sets up RECEIVE MAP!
Not executed when encountered! In OLD Progs.

CICS-Prg 39
Error Processing
There are over 70 CICS error Conditions
Mercifully only a few are handled
TWO Methods of handling exceptions:
 HANDLE CONDITION (Old Method)
 Similar in function to HANDLE AID
 RESPONSE Code checking
 Allows cleaner program structure

CICS-Prg 40
Strange Exception - MAPFAIL
MAPFAIL Condition
 Raised by RECEIVE MAP with no data
 User entered no data but pressed AID key
 User pressed CLEAR key or PA key
 Simplest to PREVENT it from occurring
 Check EIBAID to see what key was pressed
 Don’t issue RECEIVE MAP if PA or CLEAR hit
 Include ‘DUMMY’ field with MDT set ON

CICS-Prg 41
HANDLE CONDITION (Old!)
EXEC CICS
HANDLE CONDITION
condition(procedure-name)
condition(procedure-name)
… up to 16 per statement
END-EXEC

CICS-Prg 42
HANDLE CONDITION
Common CONDITIONS
 DUPREC Record already exists
 MAPFAIL No data sent by user
 NOSPACE No space left in file
 NOTOPEN Data set not OPEN
 NOTFND Record not in file
 PGMIDERR Program not in PPT
 ERROR ALL conditions not coded

CICS-Prg 43
HANDLE CONDITION Example
EXEC CICS
HANDLE CONDITION
MAPFAIL(500-NO-DATA)
DUPREC(600-DUPLICATE)
NOTOPEN
END-EXEC
NOTE: Condition by itself will nullify it!
CICS-Prg 44
HANDLE CONDITION (Notes)
Not an executable command
Establishes paragraph to correct error
Can issue multiple times
Last one executed is in effect
Causes ‘GO TO’ to paragraph named
Done BEFORE CICS Command executed
OLD method of coding – AVOID!
CICS-Prg 45
RESPONSE CHECKING (NEW!)
ADD ‘RESP’ option to CICS Command
Define binary fullword PIC S9(8) COMP
Name that field in each RESP option
COPY of EIBRESP from EIB
EIBRESP2 (RESP2) also available
 Not many CICS Commands use it
 Seldom needed as RESP is usually enough

CICS-Prg 46
USE General ERROR Handling
Most good shops have a standard error
handling method
If not, use sample linkage on Page 255
Sample program is on Page 257
Called whenever a condition is not
handled in the program
Displays error to user and terminates

CICS-Prg 47
LINKAGE SECTION
Used to access data left by previous
execution of a program
Data should be moved to your W/S!
Each execution starts with initial W/S
Define COMMAREA in Working-Storage
DEFINE DFHCOMMAREA in Linkage
RETURN references Working-Storage

CICS-Prg 48
Executive Interface Block
EIB definition added by CICS Compiler
In Linkage Section after DFHCOMMAREA
Contains several useful fields
 EIBCALEN, EIBAID, EIBCPOSN, EIBDATE,
EIBTIME, EIBTRNID, EIBTRMID, EIBRSRCE
Most kept current by CICS (Page 258)
You can update a few of them-EIBTRNID

CICS-Prg 49
EIB Useful Fields
EIBCALEN Length of COMMAREA
EIBAID Current AID Key pressed
EIBCPOSN Position of CURSOR
EIBDATE Task DATE (00YYDDD)
EIBTIME Task Time (0HHMMSS)
EIBTRNID Transaction of Task
EIBTRMID Terminal ID of Task
EIBRSRCE Recently used Resource Name
EIBDS Recently accessed Data Set
CICS-Prg 50
DEBUGGING EIB FIELDS
EIBFN Last CICS Command
EIBRESP Completion Status
EIBRESP2 More Completion Status
EIBRCODE Response Code (OLD)
EIBRSRCE Recent Resource Name
 MAP Map Name
 PRG CTL Program Name
 FILE CTL Data Set Name

CICS-Prg 51
Access to Heavy Stuff
CWA Common Work Area
 Installation defined (Sometimes handy)
CSA Common System Area
TWA Transaction Work Area
TCTUA Terminal Control Table
User Area
Must establish Addressability if needed

CICS-Prg 52
Infrequently Needed Stuff
EXEC CICS
ADDRESS CWA(pointer)
[ CSA(pointer) ]
[ TWA(pointer) ]
[ TCTUA(pointer) ]
END-EXEC

CICS-Prg 53
Infrequently Needed Stuff
EXEC CICS
ADDRESS CWA(ADDRESS OF CWA)
END-EXEC

NOTE: Holdovers from MACRO-Level CICS

Seldom needed any more!

CICS-Prg 54