How to Configure and Deploy a Migrated CICS Application

Table of Contents

1. Overview
2. How a CICS request enters the application
3. The deploy.properties file
4. BMS screens
5. Common CICS services available
6. Build & deploy flow
7. Summary
8. Related articles

Audience: developers and operations engineers packaging and deploying a CICS PL/I application migrated to Java with Heirloom.

Overview

A migrated CICS application runs as a Java web application (a WAR) on an application server. The transpiled PL/I programs keep their EXEC CICS commands, their BMS screens, and their transaction/program structure. What you provide at deploy time is configuration: which programs and transactions exist, where files and the database live, the application id, and the default user.

This article walks through that configuration and the deploy flow. It does not require changing your PL/I source.

Note: All program names, transaction ids, application ids, file names, map names, and connection strings below are examples — replace them with your own. The configuration keys are the part to learn.

How a CICS request enters the application

The WAR is hosted by a servlet on the application server. A request (from a 3270 emulator/terminal front end or an HTTP client) carries a transaction id; the server routes it to the program registered for that transaction, the runtime sets up the transaction environment (terminal, commarea, EIB), and your program runs — exactly as a CICS region would dispatch it. Program-to-program EXEC CICS LINK / XCTL calls are dispatched the same way within the running transaction.

The deploy.properties file

Application configuration lives in deploy.properties (packaged under WEB-INF/classes/). The main groups of keys:

Application identity

Program registry

Every program the application can run is registered with a program.<name> entry. This is the equivalent of CICS program definitions — it tells the runtime which classes are installed and runnable (as LINK/XCTL/transaction targets):

program.proga = com.example.app.Proga
program.progb = com.example.app.Progb

Transaction declarations

Each transaction id is declared and mapped to the program that runs when that transaction starts — the equivalent of a CICS transaction (PCT) definition. An optional .uctran sub-key controls whether terminal input is translated to upper case for that transaction:

transaction.trn1        = proga      # transaction id TRN1 starts program PROGA
transaction.trn1.uctran = true       # upper-case-translate terminal input

transaction.trn2        = progb
transaction.trn2.uctran = false

This is what lets an incoming request's transaction id be routed to the right program (see How a CICS request enters the application above). Declare one transaction.<id> entry per transaction your application exposes.

Startup programs (PLT)

Programs that must run automatically at startup go in the program-list table. This is how a trigger monitor or initialization program is launched:

plt.pi.1 = ckti

Files / datasets (VSAM-style)

Each file the application uses is mapped to a backing store with its DCB-style attributes (record format, length, key length/offset, organization):

file.CUSTFILE       = <backing-store-or-jndi>
CUSTFILE-dsorg      = VSAM
CUSTFILE-recfm      = F
CUSTFILE-lrecl      = 200
CUSTFILE-keylen     = 10
CUSTFILE-keyoff     = 0

Database / SQL

(For embedded EXEC SQL connection details, see How to Configure DB2 / SQL Connectivity.)

BMS / screens

There is no per-map declaration — you do not register each map or mapset in deploy.properties. The runtime loads BMS map definitions by convention from WEB-INF/classes/; just make sure your BMS files are packaged there. Two optional, global BMS settings may be present:

BMS screens

BMS map definitions (DFHMSD / DFHMDI / DFHMDF source, LANG=PLI) are carried into the application and used by EXEC CICS SEND MAP / RECEIVE MAP just as on the host:

/* Send a screen, then receive the operator's input */
EXEC CICS SEND MAP('MYMAP') MAPSET('MYSET') ERASE
          RESP(WS_RESP) RESP2(WS_RESP2);

EXEC CICS RECEIVE MAP('MYMAP') MAPSET('MYSET')
          RESP(WS_RESP) RESP2(WS_RESP2);

The maps render to the terminal front end; field attributes (protected, bright, etc.) and positions from the BMS source are preserved.

Package the BMS map files under WEB-INF/classes/ — that is where the runtime looks for them. No per-map entry in deploy.properties is required; the files being present on the classpath is enough.

Tip: Every CICS command supports RESP / RESP2. Always test them rather than assuming success — they carry the same condition/reason codes you relied on under CICS.

Common CICS services available

Migrated programs can use the familiar CICS surface, including:

• Screens (BMS): SEND MAP, RECEIVE MAP, SEND TEXT
• Program control: LINK, XCTL, RETURN, START, LOAD
• Files (VSAM): READ, WRITE, REWRITE, DELETE, STARTBR, READNEXT, READPREV
• Queues: WRITEQ / READQ (TS and TD)
• Storage: GETMAIN, FREEMAIN
• Unit of work: SYNCPOINT, SYNCPOINT ROLLBACK
• System/inquiry: ASSIGN, ADDRESS, INQUIRE, SET, ASKTIME, FORMATTIME
• Serialization: ENQ, DEQ
• Exits / global areas: EXTRACT EXIT (Global Work Area)
• Web services: INVOKE SERVICE (see the SOAP integration guide)

Build & deploy flow

The high-level loop most teams follow:

1. Transpile the PL/I to Java (Heirloom compiler) — produces the program classes.
2. Build the WAR with your build tool (e.g. ./gradlew clean war), bundling deploy.properties and the BMS maps under WEB-INF/classes/, plus the runtime jars.
3. Provision dependencies: the database (DB2), any MQ queue manager, and the file backing stores the configuration references.
4. Deploy the WAR to the application server (often via a container image).
5. Smoke test: start a transaction and navigate a few screens; confirm no errors. Watch the server log on first start for the program-list-table programs coming up.

Summary

• A migrated CICS app is a WAR; requests carry a transaction id and are dispatched to the registered program.
• deploy.properties is the control file: applid, dfltuser, the program.* registry, transaction.<id> declarations (+ .uctran), plt.pi.* startup programs, file.* + DCB attributes, and DB settings.
• BMS maps need no declaration — package them under WEB-INF/classes/. The full EXEC CICS surface (screens, program control, files, queues, storage, syncpoint) is preserved.
• Build → provision DB/MQ/files → deploy WAR → smoke-test a few screens.

Related articles

• How to Configure DB2 / SQL Connectivity — database setup for EXEC SQL.
• How to Use IBM MQ Messaging — for MQ-driven transactions.
• How Transactions Are Managed (ETP + PL/I Runtime) — the transaction lifecycle behind LINK/SYNCPOINT.