Compiling EXEC CICS Programs (the `--cics` Option)

Table of Contents

1. Overview
2. What --cics does
3. How EXEC CICS becomes Java
4. Supported EXEC CICS commands
5. CICS and the compile strategy
6. What you do not configure at compile time
7. Summary
8. Related articles

Audience: developers and build engineers compiling PL/I programs that contain embedded EXEC CICS commands. Explains what the --cics (and --exci) compiler options do, how CICS commands are translated to Java, and how this pairs with the compile strategy. For runtime setup and deployment, see "How to Configure and Deploy a Migrated CICS Application."

Overview

Online PL/I programs drive screens, files, queues, and program flow through command-level CICS — EXEC CICS … ; blocks. The --cics compiler option tells the Heirloom PL/I compiler to recognize and translate those commands. Without it, EXEC CICS is not processed; with it, each command becomes a Java call into the runtime's CICS layer, which provides the same services on standard Java infrastructure.

This article covers the compile-time side: the option, the related --exci option, what the generated Java looks like, and why CICS programs are normally built with the instance strategy. The run-time side — region configuration, program/file registries, BMS, and deployment — is covered in How to Configure and Deploy a Migrated CICS Application.

Note: CICS and SQL processing are independent. A program that uses both is compiled with --cics --sql together.

What --cics does

--cics

When set, the compiler:

1. Parses each EXEC CICS … ; block against its CICS command grammar.
2. Maps options — RESP/RESP2, NOHANDLE, INTO/FROM, LENGTH, RIDFLD, map/program names, and so on — to builder calls.
3. Generates Java that invokes the runtime's CICS services and captures results back into your variables.

--exci — calling CICS from batch

--exci

--exci selects the External CICS Interface form of code generation. It is for batch programs that need to LINK into CICS programs from outside a CICS region, rather than running inside one. In EXCI mode the generated LINK uses the external-interface path (with an application id, no online transaction context) instead of the in-region path. Use --cics for programs that run as online transactions; use --exci for batch callers that reach into CICS.

How EXEC CICS becomes Java

Each command is translated into a call on a fluent CICS builder, with the command's options chained on and results read back afterward. A program-control LINK:

EXEC CICS LINK PROGRAM(PGM) COMMAREA(CA) LENGTH(LEN) RESP(RC) END-EXEC;

becomes (illustrative):

CICSLink cicsLink = CICSBuilder.getInstance().link(_transenv)
    .program(pgm)
    .commarea(ca)
    .length(len)
    .resp(rc);
cicsLink.execute(this);
rc = (Integer) cicsLink.resp();      // RESP read back after execution

Points to recognize when reading the output:

• A builder per command. CICSBuilder.getInstance().<command>(_transenv) with the command's options chained on, then .execute(this).
• _transenv carries task state. The transactional environment (terminal id, transaction id, unit-of-work) is passed into each command.
• RESP/RESP2 are read back after execute(...) and cast to your variable's type. If a RESP variable is referenced but not declared, the compiler auto-declares it as an integer so the program still compiles.
• NOHANDLE is honored to suppress condition handling for a command.

Response codes, conditions, and the EIB

• EXEC CICS HANDLE CONDITION / IGNORE CONDITION are translated so your condition-driven flow is preserved.
• Symbolic response checks via DFHRESP(...) (and DFHVALUE(...)) resolve to the corresponding numeric values, so IF RC = DFHRESP(NOTFND) works as written.
• EXEC CICS ADDRESS EIB(...) gives your program the Execution Interface Block; the EIBxxx fields (EIBCALEN, EIBTRMID, EIBAID, EIBRESP, …) are then read in the usual way.

Supported EXEC CICS commands

The compiler handles a broad command-level surface — over ninety distinct commands — across the usual functional groups:

See Supported CICS Features for the published feature list, and CICS INVOKE SERVICE Integration Guide for web-service calls.

CICS and the compile strategy

CICS programs are normally compiled with the instance strategy:

--cics --strategy instance

Each CICS transaction is a separate task, and instance strategy gives every invocation a fresh program instance (matching PL/I's AUTOMATIC storage and keeping per-task state isolated). The CICS command execute(this) calls pass that instance as their context, and ON-condition handlers are wired to it. The compiler does not force instance strategy, but it is the right pairing for online transaction programs. See Static vs Instance Strategy for the details.

What you do not configure at compile time

Region and inventory details are run-time configuration, not compiler options:

• the CICS application id (applid), program and transaction registries,
• file/DCB definitions and BMS mapsets,
• programs that start automatically (PLT).

These live in your deployment configuration (deploy.properties and friends) and are covered in How to Configure and Deploy a Migrated CICS Application. The compiler only produces CICS-aware Java; how the region is wired is decided at deployment.

Summary

• --cics makes the compiler parse and translate embedded EXEC CICS; without it, CICS commands are not processed.
• --exci generates the External CICS Interface form so batch programs can LINK into CICS from outside a region.
• Each command becomes a fluent builder call (CICSBuilder…execute(this)) with RESP/RESP2, NOHANDLE, and DFHRESP(...) preserved, and the EIB reachable via ADDRESS EIB.
• The compiler supports a broad command surface (BMS, program/file control, TS/TD queues, storage, task/interval control, conditions, containers, inquire/set).
• CICS programs are normally built with --strategy instance; region and inventory setup is run-time configuration, not a compiler option.

Related articles

• How the Heirloom PL/I Compiler Translates Your Code and Reading Your Generated Java.
• Compiling EXEC SQL Programs (the --sql Option).
• Static vs Instance Strategy.
• How to Configure and Deploy a Migrated CICS Application and How to Build a CICS Application with BMS Screens.
• Supported CICS Features and CICS INVOKE SERVICE Integration Guide.