COBOL Considerations

1
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)

2
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

3
COBOL Considerations (More)

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

4
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

5
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

6
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

7
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

8
Sample CICS COBOL Program

• PROCEDURE DIVISION (Where are we?)
• IF first-time
• SEND Initial-Map
• ELSE
• IF
• Process Screen
• ELSE
• Process Function-Key
• END-IF
• END-IF
• SEND MAP

9
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

10
Basic CICS Commands

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

11
Basic CICS Commands

• EXEC CICS
• RETURN TRANSID(name)
• COMMAREA(data-area)
• LENGTH(data-value)
• END-EXEC
• Length PIC S9(4) COMP or Literal

12
Basic CICS Commands

• EXEC CICS
• XCTL PROGRAM(name)
• COMMAREA(data-area)
  LENGTH(data-value)
• END-EXEC

13
Basic CICS Commands

• EXEC CICS
• SEND MAP(name)
• MAPSET(name)
• FROM(data-area)
• MAPONLY DATAONLY
• ERASE ERASEUP
• CURSOR (value)
• END-EXEC

14
Basic CICS Commands

• EXEC CICS
• RECEIVE MAP(map-name)
• MAPSET(mapset-name)
• INTO(data-area)
• END-EXEC

15
Basic CICS Commands

• EXEC CICS
• READ DATASET(filename)
• INTO(data-area)
• RIDFLD(data-area)
• RRN RBA
• UPDATE
• END-EXEC

16
Basic CICS Commands

• EXEC CICS
• ABEND ABCODE(name)
• END-EXEC
• (ABCODE used to identify storage dump -
• Usually omitted!)

17
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

18
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)

19
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)

20
More CICS Commands

• EXEC CICS
• WRITE DATASET(filename)
• FROM(data-area)
• RIDFLD(data-area)
• RRN RBA
• END-EXEC

21
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

22
More CICS Commands

• EXEC CICS
• DELETE DATASET(filename)
• RIDFLD(data-area)
• RRN RBA
• END-EXEC
• NOTE If no RIDFLD last READ is Deleted

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

24
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

25
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

26
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

27
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)

28
Program Control Commands

• EXEC CICS
• RETURN TRANSID(name)
• COMMAREA(data-area)
• LENGTH(data-value)
• END-EXEC

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

30
Program Control Commands

• EXEC CICS
• XCTL PROGRAM(name)
• COMMAREA(data-area)
• LENGTH(data-value)
• END-EXEC
• NOTE Program name must be in PPT.

31
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!)

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

33
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

34
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!

35
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!

36
Misc CICS Commands

• EXEC CICS
• SEND TEXT FROM(data-area)
• LENGTH(data-value)
• ERASE
• FREEKB
• END-EXEC
• NOTE No FREEKB user must hit RESET!

37
Misc CICS Commands

• EXEC CICS
• HANDLE AID
• option(procedure name)
• END-EXEC

38
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)

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

40
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

41
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

42
HANDLE CONDITION (Old!)

• EXEC CICS
• HANDLE CONDITION
• condition(procedure-name)
• condition(procedure-name)
• up to 16 per statement
• END-EXEC

43
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

44
HANDLE CONDITION Example

• EXEC CICS
• HANDLE CONDITION
• MAPFAIL(500-NO-DATA)
• DUPREC(600-DUPLICATE)
• NOTOPEN
• END-EXEC
• NOTE Condition by itself will nullify it!

45
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!

46
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

47
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

48
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

49
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

50
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

51
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

52
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

53
Infrequently Needed Stuff

• EXEC CICS
• ADDRESS CWA(pointer)
• CSA(pointer)
• TWA(pointer)
• TCTUA(pointer)
• END-EXEC

54
Infrequently Needed Stuff

• EXEC CICS
• ADDRESS CWA(ADDRESS OF CWA)
• END-EXEC
• NOTE Holdovers from MACRO-Level CICS
• Seldom needed any more!