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

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

COBOL Considerations (More)

Procedure Division
Uses most COBOL statements Also uses CICS Commands like:
RETURN XCTL SEND MAP RECEIVE MAP READ DATASET

CICS-Prg

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

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 dont code it, CICS Will! The commarea (if any) placed here! EIBCALEN gives length of commarea 0 (ZERO) means there is NO commarea

CICS-Prg

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 DUPREC FILENOTFND INVREQ IOERR NOTAUTH NOTFND Dataset disabled Record already exists Dataset not in FCT Invalid request File I/O error User not authorized 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? Wheres 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 dont 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 PF1-PF24 ENTER CLEAR ANYKEY Program Attention Keys Program Function Keys The ENTER Key The CLEAR Key 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 Dont 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 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 212) You can update a few of them-EIBTRNID
CICS-Prg

49

EIB Useful Fields

EIBCALEN EIBAID EIBCPOSN EIBDATE EIBTIME EIBTRNID EIBTRMID EIBRSRCE EIBDS Length of COMMAREA Current AID Key pressed Position of CURSOR Task DATE (00YYDDD) Task Time (0HHMMSS) Transaction of Task Terminal ID of Task Recently used Resource Name Recently accessed Data Set
CICS-Prg 50

DEBUGGING EIB FIELDS

EIBFN EIBRESP EIBRESP2 EIBRCODE EIBRSRCE
MAP PRG CTL FILE CTL

Last CICS Command Completion Status More Completion Status Response Code (OLD) Recent Resource Name
Map Name Program Name Data Set Name
CICS-Prg 51

Access to Heavy Stuff

CWA CSA TWA TCTUA Common Work Area
Installation defined (Sometimes handy)

Common System Area Transaction Work Area 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