Part 5 — CICS Support¶

5.1 CICS Overview¶

The Heirloom PL/I platform provides comprehensive CICS transaction processing support through 98 runtime classes and 78 compiler-level EXEC CICS statement handlers. PL/I programs containing EXEC CICS commands are transpiled to Java code that invokes the Heirloom CICS emulation layer.

Quick Start: See Getting Started: 0.4 CICS Example for a basic CICS program example

Enterprise Examples: See Real-World Examples: 12.1 CICS Application for production application architecture

5.1.1 CICS Architecture¶

┌──────────────────────────────────────────────────┐
│              CICS Emulation Layer                  │
│                                                    │
│  ┌─────────────┐  ┌──────────┐  ┌──────────────┐ │
│  │ Terminal I/O │  │ File I/O │  │ Queue Mgmt   │ │
│  │ SEND/RECEIVE│  │ VSAM     │  │ TS/TD Queues │ │
│  │ SEND MAP    │  │ READ     │  │ WRITEQ/READQ │ │
│  │ RECEIVE MAP │  │ WRITE    │  │ DELETEQ      │ │
│  └─────────────┘  │ REWRITE  │  └──────────────┘ │
│                    │ DELETE   │                    │
│  ┌─────────────┐  │ BROWSE   │  ┌──────────────┐ │
│  │ Program     │  └──────────┘  │ Container    │ │
│  │ Control     │                │ Services     │ │
│  │ LINK/XCTL   │  ┌──────────┐  │ GET/PUT      │ │
│  │ RETURN      │  │ System   │  │ MOVE/BROWSE  │ │
│  │ START/CANCEL│  │ Services │  └──────────────┘ │
│  └─────────────┘  │ ENQ/DEQ  │                    │
│                    │ ASKTIME  │  ┌──────────────┐ │
│  ┌─────────────┐  │ ASSIGN   │  │ Memory Mgmt  │ │
│  │ Inquiry/Set │  │ LOAD     │  │ GETMAIN      │ │
│  │ INQ FILE    │  │ DUMP     │  │ FREEMAIN     │ │
│  │ INQ PROGRAM │  └──────────┘  └──────────────┘ │
│  │ INQ TASK    │                                  │
│  │ SET ...     │                                  │
│  └─────────────┘                                  │
└──────────────────────────────────────────────────┘

5.1.2 Compiling CICS Programs¶

• Enable with --cics compiler option
• EXEC CICS statements transpiled to CICSBuilder calls
• Instance strategy (--strategy instance) recommended for CICS programs
• Automatic DFHEIBLK injection

5.1.3 EXEC CICS Code Generation Pattern¶

/* PL/I Source */
EXEC CICS READ FILE('CUSTFILE')
    INTO(WS_RECORD)
    RIDFLD(WS_KEY)
    RESP(WS_RESP);

cics = CICSBuilder.getInstance()
    .readFile("CUSTFILE", _transenv)
    .into(ws_record)
    .ridfld(ws_key)
    .resp(ws_resp)
    .execute(this);

See also: Runtime Reference: 4.4.1 QR TCB Lock Management for thread safety implementation in CICS transactions

5.2 CICS Data Areas¶

5.2.1 Execute Interface Block (DFHEIBLK)¶

The EIB is automatically available in CICS programs and provides transaction context information.

5.2.2 DFHAID — Attention Identifier Keys¶

Standard AID key constants (ENTER, PF1–PF24, PA1–PA3, CLEAR, etc.).

5.2.3 DFHRESP and DFHVALUE Built-in Functions¶

Compile-time constants for CICS response codes.

5.3 CICS Response Codes¶

5.4 CICS Terminal Operations¶

5.4.1 SEND MAP¶

Send a BMS (Basic Mapping Support) map to the terminal.

Supported options: MAP, MAPSET, FROM, DATAONLY, MAPONLY, ERASE, ERASEAUP, CURSOR, FREEKB, ALARM, RESP

5.4.2 RECEIVE MAP¶

Receive terminal input into a BMS map.

Supported options: MAP, MAPSET, INTO, SET, RESP

5.4.3 SEND (Text/Control)¶

Send text data, control characters, or page content to the terminal.

Supported options: FROM, LENGTH, ERASE, CURSOR, FREEKB, WAIT

5.4.4 RECEIVE¶

Receive raw terminal input.

Supported options: INTO, SET, LENGTH, MAXLENGTH, RESP

5.4.5 SEND CONTROL¶

Send control information without data.

5.5 CICS File Operations¶

5.5.1 READ¶

Read a record from a VSAM or BDAM file.

Supported options: FILE, INTO, SET, RIDFLD, KEYLENGTH, GENERIC, UPDATE, GTEQ, EQUAL, RESP

5.5.2 READNEXT / READPREV¶

Sequential browse forward or backward.

Supported options: FILE, INTO, SET, RIDFLD, KEYLENGTH, RESP

5.5.3 WRITE¶

Write a new record.

Supported options: FILE, FROM, RIDFLD, KEYLENGTH, RESP

5.5.4 REWRITE¶

Update an existing record (requires prior READ UPDATE).

Supported options: FILE, FROM, RESP

5.5.5 DELETE¶

Delete a record from a file.

Supported options: FILE, RIDFLD, KEYLENGTH, GENERIC, NUMREC, RESP

5.5.6 STARTBR / ENDBR / RESETBR¶

Start, end, or reset a browse operation.

Supported options: FILE, RIDFLD, KEYLENGTH, GTEQ, EQUAL, RESP

5.5.7 UNLOCK¶

Release a record lock without updating.

5.6 CICS Queue Operations¶

5.6.1 Temporary Storage (TS) Queues¶

5.6.2 Transient Data (TD) Queues¶

5.7 CICS Program Control¶

5.7.1 LINK¶

Transfer control to another program with return.

Supported options: PROGRAM, COMMAREA, LENGTH, CHANNEL, RESP

5.7.2 XCTL¶

Transfer control to another program without return.

Supported options: PROGRAM, COMMAREA, LENGTH, CHANNEL, RESP

5.7.3 RETURN¶

Return control to the invoking program or CICS.

Supported options: TRANSID, COMMAREA, LENGTH, CHANNEL, IMMEDIATE

5.7.4 START¶

Start a new transaction.

Supported options: TRANSID, FROM, LENGTH, TERMID, REQID, INTERVAL, TIME, RESP

5.7.5 CANCEL¶

Cancel a previously started interval control request.

5.7.6 LOAD¶

Load a program or table into memory.

5.8 CICS Container and Channel Operations¶

5.8.1 GET CONTAINER¶

Retrieve data from a container.

Supported options: CONTAINER, CHANNEL, INTO, SET, FLENGTH, RESP

5.8.2 PUT CONTAINER¶

Put data into a container.

Supported options: CONTAINER, CHANNEL, FROM, FLENGTH, RESP

5.8.3 MOVE CONTAINER¶

Move a container between channels.

5.8.4 BROWSE CONTAINER / GET NEXT CONTAINER¶

Browse containers within a channel.

5.9 CICS Memory Management¶

5.9.1 GETMAIN¶

Acquire main storage.

Supported options: SET, FLENGTH, LENGTH, INITIMG, RESP

5.9.2 FREEMAIN¶

Release previously acquired storage.

Supported options: DATA, DATAPOINTER, RESP

5.10 CICS System Services¶

5.10.1 ASKTIME / FORMATTIME¶

Retrieve and format the current date/time.

ASKTIME: Returns absolute time (ABSTIME)

FORMATTIME options: ABSTIME, DATESEP, TIMESEP, YYDDD, YYMMDD, YYYYMMDD, DDMMYY, MMDDYY, DATE, DATESTRING, DAYCOUNT, DAYOFWEEK, DAYOFMONTH, MONTHOFYEAR, TIME, YEAR

5.10.2 ASSIGN¶

Retrieve system information.

Supported fields: APPLID, USERID, SYSID, OPID, FACILITY, STARTCODE, CWALENG, TWALENG, NETNAME, and others.

5.10.3 ADDRESS¶

Retrieve addresses of CICS system areas (CWA, TWA, EIB, COMMAREA).

5.10.4 ENQ / DEQ¶

Enqueue (lock) and dequeue (unlock) resources for serialization.

5.10.5 SYNCPOINT¶

Establish a synchronization point (unit-of-work boundary).

5.10.6 ABEND¶

Abnormally terminate a transaction.

Supported options: ABCODE, CANCEL, NODUMP

5.11 CICS Inquiry and Set Operations¶

5.11.1 INQUIRE Commands¶

5.11.2 SET Commands¶

SET FILE, SET PROGRAM, SET TASK, SET TRANSACTION, SET TERMINAL — modify resource attributes at runtime.

5.12 CICS Condition Handling¶

5.12.1 HANDLE CONDITION¶

Establish condition handlers for specific CICS response codes.

5.12.2 IGNORE CONDITION¶

Suppress handling of specific conditions.

5.12.3 RESP / RESP2 Option¶

Inline response code checking (preferred modern approach).

5.13 CICS Web and Service Operations¶

5.13.1 INVOKE SERVICE¶

Invoke an external web service from a CICS transaction.

5.13.2 EXTRACT EXIT¶

Extract information from an exit environment.

5.13.3 ENABLE PROGRAM / DISABLE PROGRAM¶

Enable or disable a user exit program.

5.14 CICS Spool Operations¶

5.14.1 SPOOL OPEN / SPOOL WRITE / SPOOL CLOSE¶

JES spool interface for report output.

5.15 CICS External Call Interface (EXCI)¶

5.15.1 Overview¶

Support for CICS External Call Interface, allowing non-CICS programs to call CICS programs.

5.15.2 Enabling EXCI¶

Compile with --exci option.