CICS Online Transaction Decoder

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/architecture/references/discovery/cics-online.md
Description	Not specified

Source Content

CICS Online Transaction Decoder

A field guide for reading CICS — the mainframe’s interactive layer. If mainframe COBOL is the batch world, CICS is the “green screen while a user waits” world. Read this alongside references/mainframe-cobol.md (the COBOL language is the same; the I/O model is not).

Contents

• What CICS is and why it feels weird
• Pseudo-conversational: the state machine you must understand
• The anatomy of a transaction
• BMS: the 3270 screen definitions
• The EXEC CICS commands that matter
• COMMAREA, channels, and where session state lives
• Temporary storage and transient data queues
• The EIB: the transaction’s dashboard
• Turning CICS into user-journey diagrams
• File-extension cheat sheet

What CICS is

CICS (Customer Information Control System) is the mainframe’s online transaction monitor — the thing that lets thousands of users at 3270 terminals run short interactive programs against shared VSAM/DB2 data, fast. Where batch COBOL is launched by JCL and reads datasets, a CICS program is launched by a transaction ID a user types (or a screen invokes) and does its I/O through EXEC CICS commands. Same COBOL language, completely different runtime contract: no OPEN/CLOSE, no JCL, no long-running session.

The one idea that unlocks CICS is that a CICS program does not stay running while the user thinks. It runs for milliseconds, paints a screen, and ends. That is the pseudo-conversational model.

Pseudo-conversational

Imagine two developers reading the same claims-inquiry program. Jack assumes it works like a desktop app: the program loops, showing a screen and waiting for input. He cannot find the loop and concludes the code is incomplete. Jill knows CICS: the program runs once, sends the screen, and returns control to CICS with a RETURN TRANSID — the terminal now sits idle with no program running. When the user presses Enter, CICS starts a brand-new task, re-invokes the program, and the program figures out “where was I” from saved state. Jill reads it correctly in minutes.

This is pseudo-conversational processing, and it is the defining trait of CICS:

stateDiagram-v2
  [*] --> FirstRun: user types TRANSID
  FirstRun --> ScreenShown: SEND MAP,<br/>RETURN TRANSID + COMMAREA
  ScreenShown --> [*]: program ENDS<br/>(nothing running)
  ScreenShown --> NextTask: user presses Enter/PF key
  NextTask --> Process: new task, RECEIVE MAP,<br/>read COMMAREA to resume
  Process --> ScreenShown: SEND next MAP,<br/>RETURN TRANSID + COMMAREA
  Process --> [*]: RETURN (no TRANSID) — done

What to notice: between screens, no program is running — the entire “session” is reconstructed each keystroke from the COMMAREA. There is no in-memory session object to find; the state you are looking for travels in the COMMAREA (see below). This is why CICS logic reads as a dispatcher on “which step am I on,” not as a linear script.

Anatomy of a transaction

The moving parts, and how they connect:

• Transaction ID (TRANSID) — a (usually) 4-character code (CLM1, PAY2) the user types or a screen triggers. CICS looks it up and starts the associated program.
• Program — the COBOL/PL/I/Assembler unit that runs. One transaction → one initial program (which may LINK/XCTL to others).
• Map / mapset — the screen layout, defined in BMS (below).
• Resource definitions — the tables (historically PCT/PPT; now the CSD via RDO/CEDA) that bind TRANSID → program → map. If you can get a CSD export, it is the routing table for the whole online app.

BMS

BMS (Basic Mapping Support) defines 3270 screens the way DDS/DSPF defines them on IBM i. A mapset contains maps; a map contains fields with row/column positions, lengths, and attributes (protected, bright, numeric, colored). Source is BMS macro assembler (DFHMSD, DFHMDI, DFHMDF), extension usually .bms.

The program interacts with a map two ways:

• SEND MAP — paint the screen (merge program data into the map’s variable fields).
• RECEIVE MAP — read what the user typed back into the program’s copy of the map fields.

Each map is roughly one screen/panel; the field names in the map’s DSECT are the on-screen fields. To reverse-engineer the UI, inventory the mapsets — they enumerate the screens, and their field attributes tell you what is input vs display vs error.

EXEC CICS commands

CICS I/O and control happen through EXEC CICS … END-EXEC. The commands that carry meaning:

Command	Does	Discovery note
SEND MAP / RECEIVE MAP	Paint / read a BMS screen	The UI boundary
READ / WRITE / REWRITE / DELETE	File control against VSAM (REWRITE=update)	The CRUD verbs; FILE() names the VSAM file
STARTBR / READNEXT / READPREV / ENDBR	Browse a file (cursor over a key range)	Sequential list screens
LINK	Call another program, return here	Like CALL; sub-routine, own COMMAREA
XCTL	Transfer to another program, no return	Hands off control; trace as a flow edge, not a call/return
RETURN TRANSID(x) COMMAREA(y)	End task, set next transaction + saved state	The pseudo-conversational hinge
READQ/WRITEQ TS	Temporary storage queue I/O	Scratchpad state (below)
READQ/WRITEQ TD	Transient data queue I/O	Often printing/logging/triggers
SYNCPOINT	Commit the unit of work	Transaction boundary
ABEND / HANDLE CONDITION / RESP(...)	Error handling	Where failure paths hide
GETMAIN / FREEMAIN	Allocate/free storage	Dynamic buffers
ASKTIME / FORMATTIME	Time-of-day	Date/time rules

Modern CICS prefers the RESP(rc) option (check a return code) over the older HANDLE CONDITION (set up a goto-on-error). Both mean “handle the not-found / duplicate / error case” — read them as the exception rules.

COMMAREA and state

Because the program ends between screens, session state must be saved somewhere and handed back. The classic mechanism is the COMMAREA (communication area): a block of storage the program fills, names on RETURN TRANSID(...) COMMAREA(...), and receives back (via the DHCOMMAREA in LINKAGE) on the next task. EIBCALEN tells the program how many bytes of COMMAREA arrived — a common “first time vs resuming” test is IF EIBCALEN = 0 (fresh start) vs non-zero (resuming).

The modern replacement is channels and containers (EXEC CICS PUT/GET CONTAINER … CHANNEL …) — named, typed, larger-than-32K state. Functionally the same role: it is where the “session” lives. When you hunt for what a screen remembers between keystrokes, read the COMMAREA/channel layout — it is the session model.

TSQ and TDQ

Two queue types that hold state and cross boundaries:

Temporary Storage Queue (TSQ)

A named scratchpad (WRITEQ TS QUEUE(...)) that survives across tasks/terminals until deleted. Used to stash a list between browse screens, or pass data between transactions. Treat a shared TSQ name as a hidden coupling point.

Transient Data Queue (TDQ)

A sequential queue with a destination. Intrapartition TDQs can trigger a program when they reach a threshold (an event hook); extrapartition TDQs map to real datasets (often print/report/log output). A TDQ that triggers a transaction is an easy-to-miss control-flow edge — put it on the dependency map.

The EIB

Every CICS program has an EXEC Interface Block (EIB) — a control structure CICS fills in, readable without declaring it. The fields you will see tested:

EIB field	Holds
EIBAID	Which key the user pressed (Enter, PF1–PF24, Clear)
EIBCALEN	Length of the COMMAREA received (0 = first entry)
EIBTRNID	The current transaction ID
EIBRESP / EIBRESP2	Return code from the last EXEC CICS command
EIBDATE / EIBTIME	Task start date/time

EVALUATE EIBAID is the standard “what did the user press” dispatcher — PF3 to exit, PF7/PF8 to page, Enter to submit. That dispatcher is the screen’s keyboard contract; capture it for the user-journey diagram.

Turning CICS into journeys

CICS maps almost perfectly onto two diagram types (see references/mermaid-legacy-patterns.md):

• A state diagram per transaction — each screen is a state; each EIBAID branch and RETURN TRANSID/XCTL is a transition. This is the truest picture of a green-screen user journey.
• A flowchart of the online app — TRANSIDs as entry points, XCTL/LINK edges between programs, FILE() names as the data touched.

Because the pseudo-conversational model already is a state machine, resist drawing CICS flows as linear steps — model the wait-for-user states explicitly, or the diagram will lie about how the program actually behaves.

File-extension cheat sheet

Extension(s)	It is a…
.cbl, .cob	COBOL program (look for EXEC CICS to confirm it is online, not batch)
.cpy	Copybook (COMMAREA layouts, map DSECTs, file records)
.bms	BMS map/mapset source (a screen)
.csd, .rdo	CICS resource definitions (TRANSID→program→map routing)
.jcl	JCL — for the CICS region startup or associated batch, not the online programs

The reliable tell: a COBOL program containing EXEC CICS is a CICS (online) program and will not run in batch; a COBOL program with OPEN/READ/CLOSE and no EXEC CICS is batch. Sort your COBOL into these two buckets early — they modernize very differently.