CICS COBOL Programming: Your First EXEC CICS Program
CICS COBOL Programming: Complete Guide
Writing your first CICS COBOL program requires understanding two things: how CICS controls the execution environment (replacing batch COBOL's standard I/O), and how to use EXEC CICS commands to interact with terminals, files, and other CICS services. This guide takes you through every aspect of CICS COBOL programming from the initial structure to a complete working transaction.
CICS COBOL Program Structure
A CICS COBOL program has four divisions like any COBOL program, but with important differences in what each section contains.
IDENTIFICATION DIVISION.
PROGRAM-ID. EMPINQ.
ENVIRONMENT DIVISION.
*> No FILE-CONTROL section — CICS handles all file I/O
DATA DIVISION.
WORKING-STORAGE SECTION.
*> ---- CICS Communication Area ----
01 WS-COMMAREA.
05 CA-FUNCTION PIC X(1).
05 CA-EMPNO PIC X(6).
05 CA-RETURN-MSG PIC X(50).
*> ---- Map Data Area ----
COPY EMPINQM. *> BMS map copybook
*> ---- Host Variables for DB2 ----
EXEC SQL INCLUDE SQLCA END-EXEC.
01 WS-EMPNO PIC X(6).
01 WS-LASTNAME PIC X(15).
01 WS-SALARY PIC S9(7)V99 COMP-3.
*> ---- Work Fields ----
01 WS-LENGTH PIC S9(4) COMP VALUE +50.
01 WS-RESP PIC S9(8) COMP.
01 WS-EOF PIC X VALUE 'N'.
LINKAGE SECTION.
*> DFHCOMMAREA maps the COMMAREA passed by the caller
01 DFHCOMMAREA.
05 CA-FUNCTION PIC X(1).
05 CA-EMPNO PIC X(6).
05 CA-RETURN-MSG PIC X(50).
PROCEDURE DIVISION.
0000-MAIN.
EXEC CICS HANDLE CONDITION
ERROR(9900-CICS-ERROR)
NOTFND(1200-NOT-FOUND)
END-EXEC.
*> Check if first invocation or return from sub-screen
IF EIBCALEN = 0
PERFORM 1000-FIRST-TIME
ELSE
MOVE DFHCOMMAREA TO WS-COMMAREA
EVALUATE CA-FUNCTION
WHEN 'I' PERFORM 1100-INQUIRY
WHEN 'U' PERFORM 1200-UPDATE
WHEN OTHER PERFORM 1000-FIRST-TIME
END-EVALUATE
END-IF.
PERFORM 9000-RETURN.
...Key Differences from Batch COBOL
No Standard File I/O
In a batch COBOL program, you define files in FILE-CONTROL and read them with READ statements. In CICS, all file access goes through EXEC CICS commands:
*> BATCH — not used in CICS:
READ EMPFILE INTO WS-EMP-RECORD KEY IS WS-EMPNO.
*> CICS equivalent:
EXEC CICS READ FILE('EMPFILE')
INTO(WS-EMP-RECORD)
LENGTH(WS-LENGTH)
RIDFLD(WS-EMPNO)
RESP(WS-RESP)
END-EXEC.No STOP RUN — Use EXEC CICS RETURN
*> BATCH:
STOP RUN.
*> CICS — ends the task cleanly:
EXEC CICS RETURN END-EXEC.
*> CICS — ends task and re-invokes next time user presses ENTER:
EXEC CICS RETURN
TRANSID(EIBTRNID)
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC.Using STOP RUN in a CICS program abends the entire CICS region. Never use it.
No DISPLAY to Terminal
*> BATCH:
DISPLAY 'Enter employee number: '.
*> CICS — send a formatted map:
EXEC CICS SEND MAP('EMPINQM')
MAPSET('EMPMAP')
ERASE
END-EXEC.
*> CICS — send raw text:
EXEC CICS SEND TEXT
FROM(WS-MESSAGE)
LENGTH(WS-MSG-LEN)
ERASE
END-EXEC.The EIB — Execute Interface Block
Every CICS program has access to the Execute Interface Block (EIB) — a system-maintained area filled with task and context information. Key EIB fields:
| Field | Type | Content |
|---|---|---|
| EIBTRNID | PIC X(4) | Current transaction ID (e.g., 'EMPL') |
| EIBCALEN | PIC S9(4) COMP | Length of COMMAREA (0 if none) |
| EIBAID | PIC X(1) | Attention Identifier key pressed |
| EIBRCODE | PIC X(6) | CICS response code (6 bytes) |
| EIBRESP | PIC S9(8) COMP | Numeric response code |
| EIBRESP2 | PIC S9(8) COMP | Secondary response code |
| EIBDATE | PIC S9(7) COMP-3 | Current date (0CYYDDD) |
| EIBTIME | PIC S9(7) COMP-3 | Current time (HHMMSS) |
| EIBTERMID | PIC X(4) | Terminal ID of this task |
| EIBCPOSN | PIC S9(4) COMP | Cursor position on the screen |
*> Check what key the user pressed:
IF EIBAID = DFHPF3
EXEC CICS RETURN END-EXEC
END-IF.
*> Check if this is the first invocation:
IF EIBCALEN = 0
PERFORM 1000-INITIALIZE
END-IF.
*> Get current date for audit:
MOVE EIBDATE TO WS-TODAY.DFHAID is a CICS copybook providing named constants for attention identifiers:
COPY DFHAID.
*> Contains: DFHENTER, DFHPF1 through DFHPF24, DFHPA1, DFHCLEAR, etc.Common EXEC CICS Commands
Sending a Screen
*> Send a BMS map (most common)
EXEC CICS SEND MAP('EMPINQM')
MAPSET('EMPMAP')
FROM(EMPINQ-MAP-AREA)
ERASE *> Clear the screen first
CURSOR(cursor-position) *> Optional: position cursor
RESP(WS-RESP)
END-EXEC.
*> Send the map layout only (no data) — show blank screen
EXEC CICS SEND MAP('EMPINQM')
MAPSET('EMPMAP')
MAPONLY
ERASE
END-EXEC.
*> Send data only (keep existing screen layout)
EXEC CICS SEND MAP('EMPINQM')
MAPSET('EMPMAP')
FROM(EMPINQ-MAP-AREA)
DATAONLY
END-EXEC.Receiving Input
*> Receive map data from terminal
EXEC CICS RECEIVE MAP('EMPINQM')
MAPSET('EMPMAP')
INTO(EMPINQ-MAP-AREA)
RESP(WS-RESP)
END-EXEC.
*> Receive raw data (no BMS map)
EXEC CICS RECEIVE
INTO(WS-INPUT-AREA)
LENGTH(WS-INPUT-LEN)
RESP(WS-RESP)
END-EXEC.Reading a File
EXEC CICS READ FILE('EMPFILE')
INTO(WS-EMPLOYEE-RECORD)
LENGTH(WS-REC-LEN)
RIDFLD(WS-EMPNO) *> Key to read by
RESP(WS-RESP)
RESP2(WS-RESP2)
END-EXEC.
EVALUATE WS-RESP
WHEN DFHRESP(NORMAL)
PERFORM 1000-PROCESS-RECORD
WHEN DFHRESP(NOTFND)
MOVE 'Employee not found' TO MSG-AREA
WHEN OTHER
PERFORM 9900-CICS-ERROR
END-EVALUATE.Returning to CICS
*> End the task completely
EXEC CICS RETURN END-EXEC.
*> End task and set up for next user interaction (pseudo-conv)
EXEC CICS RETURN
TRANSID(EIBTRNID)
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC.Responding to Function Keys
Users navigate CICS screens with PF keys. Your program must check EIBAID after RECEIVE MAP to determine what the user pressed:
COPY DFHAID.
PROCEDURE DIVISION.
0000-MAIN.
EXEC CICS RECEIVE MAP('EMPINQM')
MAPSET('EMPMAP')
INTO(EMPINQ-MAP-AREA)
RESP(WS-RESP)
END-EXEC.
EVALUATE EIBAID
WHEN DFHENTER
PERFORM 1000-PROCESS-REQUEST
WHEN DFHPF1
PERFORM 2000-SHOW-HELP
WHEN DFHPF3
PERFORM 9000-EXIT
WHEN DFHPF5
PERFORM 3000-REFRESH-SCREEN
WHEN DFHCLEAR
PERFORM 9000-EXIT
WHEN OTHER
MOVE 'Invalid key' TO MSGO
PERFORM 5000-SEND-MAP
END-EVALUATE.WORKING-STORAGE vs LINKAGE SECTION
This is one of the most important concepts in CICS COBOL:
WORKING-STORAGE: Initialised with VALUE clauses every time the task starts — a fresh copy for each task invocation. Use it for work fields, counters, flags, and DB2 host variables.
LINKAGE SECTION: Addresses external storage — the COMMAREA passed in (DFHCOMMAREA), storage obtained via GETMAIN, or pointers set by CICS. Do NOT initialise LINKAGE SECTION items — they map storage that already exists.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNTER PIC 9(4) VALUE 0. *> Reset to 0 every task
01 WS-NAME PIC X(30) VALUE SPACES.
LINKAGE SECTION.
01 DFHCOMMAREA. *> DO NOT add VALUE clauses
05 CA-PAGE-NUM PIC 9(4).
05 CA-LAST-KEY PIC X(6).Compile, Link, and Define Workflow
Deploying a CICS COBOL program requires several steps:
Step 1 — COBOL Compile
//COMPILE EXEC PGM=IGYCRCTL,PARM='RENT,RMODE(ANY),APOST,CICS'
//SYSLIB DD DSN=CICSTS61.SDFHCOB,DISP=SHR *> CICS copybooks
//SYSIN DD DSN=MY.SOURCE(EMPINQ),DISP=SHR
//SYSLIN DD DSN=&&OBJ,DISP=(NEW,PASS)The CICS compiler option preprocesses all EXEC CICS statements into CALLs to CICS stub routines.
Step 2 — Link-Edit
//LKED EXEC PGM=IEWL,PARM='RENT,LIST,XREF'
//SYSLIB DD DSN=CICSTS61.SDFHLOAD,DISP=SHR *> CICS load modules
//SYSLIN DD DSN=&&OBJ,DISP=(OLD,DELETE)
//SYSLMOD DD DSN=MY.LOADLIB(EMPINQ),DISP=SHRStep 3 — Define in CICS CSD
CEDA DEFINE PROGRAM(EMPINQ)
GROUP(EMPBASE)
LANGUAGE(COBOL)Step 4 — Install or Refresh
CEDA INSTALL PROGRAM(EMPINQ) GROUP(EMPBASE)
*> or if already installed:
CEMT SET PROGRAM(EMPINQ) NEWCOPYNEWCOPY causes CICS to load the new executable on the next invocation without a region restart.
Complete Example: Employee Inquiry Transaction
IDENTIFICATION DIVISION.
PROGRAM-ID. EMPINQ.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-EMPNO PIC X(6).
01 WS-LASTNAME PIC X(15).
01 WS-SALARY PIC S9(7)V99 COMP-3.
01 WS-RESP PIC S9(8) COMP.
01 WS-REC-LEN PIC S9(4) COMP VALUE +200.
01 WS-COMMAREA.
05 CA-EMPNO PIC X(6).
01 EMPLOYEE-RECORD.
05 ER-EMPNO PIC X(6).
05 ER-LASTNAME PIC X(15).
05 ER-SALARY PIC S9(7)V99 COMP-3.
05 FILLER PIC X(171).
COPY DFHAID.
LINKAGE SECTION.
01 DFHCOMMAREA.
05 CA-EMPNO PIC X(6).
PROCEDURE DIVISION.
0000-MAIN.
IF EIBCALEN > 0
MOVE DFHCOMMAREA TO WS-COMMAREA
END-IF.
EVALUATE EIBAID
WHEN DFHPF3
EXEC CICS RETURN END-EXEC
WHEN OTHER
CONTINUE
END-EVALUATE.
IF EIBCALEN = 0 OR CA-EMPNO = SPACES
PERFORM 1000-SEND-BLANK-SCREEN
ELSE
MOVE CA-EMPNO TO WS-EMPNO
PERFORM 2000-READ-EMPLOYEE
PERFORM 3000-SEND-RESULTS
END-IF.
EXEC CICS RETURN
TRANSID(EIBTRNID)
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC.
1000-SEND-BLANK-SCREEN.
EXEC CICS SEND TEXT
FROM('Enter Employee Number and press ENTER')
LENGTH(38)
ERASE
END-EXEC.
2000-READ-EMPLOYEE.
EXEC CICS READ FILE('EMPFILE')
INTO(EMPLOYEE-RECORD)
LENGTH(WS-REC-LEN)
RIDFLD(WS-EMPNO)
RESP(WS-RESP)
END-EXEC.
IF WS-RESP = DFHRESP(NOTFND)
EXEC CICS SEND TEXT
FROM('Employee not found')
LENGTH(18) ERASE
END-EXEC
EXEC CICS RETURN TRANSID(EIBTRNID)
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC
END-IF.
3000-SEND-RESULTS.
EXEC CICS SEND TEXT
FROM(ER-LASTNAME)
LENGTH(15)
ERASE
END-EXEC.Next Steps
With your first CICS program written, the next skill to master is the Execute Interface Block and all the EIB fields available to your programs. Read CICS EIB: Using the Execute Interface Block. For the full learning path, visit the CICS Mastery course hub.