CICS Integration

CICS integration is how CICS applications connect to other programs and to external systems. Within the same CICS region, programs integrate by calling each other with LINK or XCTL and passing data in COMMAREA or channels and containers. Outside the region, CICS integrates with message queues (IBM MQ), web services (SOAP and REST), TCP/IP sockets, and tools like z/OS Connect that expose CICS as REST APIs. This page explains these mechanisms so you can choose and implement the right kind of integration for your application.

Explain Like I'm Five: What Is Integration?

Imagine your program is one person in a big office. Integration is how that person talks to others: sometimes they call a colleague in the same room (LINK or XCTL), sometimes they put a note in a shared mailbox for someone else to pick up later (MQ), and sometimes they use the phone or the internet to talk to someone in another building (web services or sockets). CICS integration is all the ways your CICS program can "talk" to other programs and systems—same room or far away—so they can work together.

Why Integration Matters

Few applications do everything alone. They need to call shared logic (e.g. validation, pricing), hand off to another program (e.g. from a menu to a specific function), or talk to external systems (e.g. other mainframe regions, distributed servers, cloud APIs). CICS provides several integration options. Picking the right one depends on whether the other side is in the same CICS region, on the same mainframe, or off-platform; whether you need a request-reply or fire-and-forget pattern; and whether you must follow a standard (e.g. REST, SOAP) or a custom protocol. Understanding LINK, XCTL, MQ, web services, and sockets lets you design and implement these connections correctly.

Types of Integration at a Glance

The following table summarizes the main integration types CICS supports and when each is typically used.

Program-to-Program: LINK and XCTL

Within one CICS region, the most basic integration is one program calling another. CICS provides two main commands: LINK and XCTL. Both pass control to another program and can pass data in a COMMAREA or (in newer styles) via channels and containers. The crucial difference is whether control is expected to return to the caller.

LINK: Call and Return

LINK passes control to the program named in the PROGRAM option. That program runs at a lower logical level. When the called program executes EXEC CICS RETURN, control returns to the instruction immediately after the LINK in the calling program. The caller remains in memory and on the call stack. You must pass the length of the COMMAREA when using COMMAREA; the called program receives it in the LINKAGE SECTION as DFHCOMMAREA. LINK is used when you have a main flow and call subroutines or shared logic (e.g. date validation, lookup) and then continue in the same transaction.

1
2
3
4
5
6
7
8
9
10
* Call a subroutine and return
EXEC CICS LINK
    PROGRAM('VALIDATE')
    COMMAREA(WS-COMMAREA)
    LENGTH(WS-COMMAREA-LEN)
    RESP(WS-RESP)
END-EXEC.
IF WS-RESP = DFHRESP(NORMAL)
    * Continue with validated data
END-IF.

XCTL: Transfer Control (No Return)

XCTL (transfer control) passes control to another program but does not expect return. The calling program is terminated and removed from the call stack. The program you XCTL to runs at the same logical level as the program that issued XCTL. When that program does RETURN, control goes back to CICS (or to a program that had LINKed to the one that did XCTL), not to the original caller. XCTL is used when the current program is finished and the next program should take over—for example, a menu program that, based on user choice, transfers to a specific application program. It saves memory because you do not keep the menu in the chain.

1
2
3
4
5
6
7
8
* Menu: user chose option 2; run program PROG2
EXEC CICS XCTL
    PROGRAM('PROG2')
    COMMAREA(WS-COMMAREA)
    LENGTH(WS-COMMAREA-LEN)
    RESP(WS-RESP)
END-EXEC.
* If we get here, XCTL failed (e.g. program not found)

LINK vs XCTL: Side-by-Side

COMMAREA and LENGTH

When you pass data between programs with LINK or XCTL using COMMAREA, the calling program places the data in an area (often in working storage) and passes its address and length. The LENGTH parameter is the length in bytes of that data (valid range is 0–32767). In the called program, the data is received in the LINKAGE SECTION in a area named DFHCOMMAREA, which must be the first linkage section item. Only the data (a copy) is passed; the called program does not get the address of the caller's area. You must ensure the length you pass matches the data you intend to pass: too short and you truncate; too long and you may expose or send unintended data. For longer or structured data, channels and containers are an alternative and support multiple named containers.

IBM MQ Integration

CICS integrates with IBM MQ so that applications can put messages on queues and get messages from queues. This allows asynchronous integration: one system puts a message and another (possibly later, possibly in another region or platform) gets it. The CICS-MQ adapter uses the CICS Resource Manager Interface (RMI). A task-related user exit (DFHMQTRU) enables MQI-style calls from CICS application programs. You open a queue, put or get messages, and close the queue. In addition, MQ trigger monitors can start CICS transactions when messages arrive on specified queues: the monitor reads the trigger message and starts the configured CICS transaction, which then processes the message. This pattern is common for decoupling producers and consumers and for integrating CICS with batch or other regions.

Using MQ from CICS requires the MQ adapter and queue manager to be set up and the CICS region to have the right definitions and security. Messages can be text or binary; your program must agree with the other side on format. MQ provides reliability (persistent messages, once-and-once-only delivery where configured) and is well suited for workload distribution and event-driven flows.

Web Services: SOAP and REST (JSON)

CICS supports web services so that CICS and non-CICS systems can integrate using standard protocols and data formats. Two main styles are SOAP (XML-based) and JSON (often used with REST). CICS can act as a web service provider (exposing CICS programs or transactions as services that others call) or as a requester (a CICS program calling an external web service).

Provider and Requester

As a provider, CICS makes a program or transaction available as a web service. External clients send HTTP (or MQ) requests; CICS maps the incoming message to the program's input (e.g. COMMAREA or containers), runs the program, and maps the response back to the web service response. As a requester, a CICS application invokes an external service: it builds the request, sends it (e.g. over HTTP), and processes the response. Provider and requester can use SOAP (with WSDL) or JSON (with a JSON schema). Transport is typically HTTP or MQ.

Top-Down and Bottom-Up

Provider and requester implementations can be created top-down or bottom-up. Top-down means you start from a WSDL (for SOAP) or a JSON schema / REST definition, and generate skeleton programs and bind files that map application data to messages. Bottom-up means you start from an existing CICS program and generate the WSDL or JSON description and bind files so that the program can be exposed as a web service. Security (e.g. WS-Security, SSL/TLS) and transaction boundaries (e.g. atomic updates across CICS and external systems) can be configured as needed.

z/OS Connect and REST APIs

z/OS Connect is an IBM product that exposes z/OS assets—including CICS programs and transactions—as REST APIs. You define the API (URL path, HTTP method, request and response body) and bind it to a CICS program or transaction. Incoming REST calls are transformed into the format the CICS program expects; the program runs; and the result is mapped back to the REST response. This gives mobile, web, and cloud applications a simple way to call CICS without using CICS-specific protocols. z/OS Connect can run in its own address space or inside the CICS region. It is often used together with CICS web support and modernization efforts.

TCP/IP Sockets

CICS provides a TCP/IP socket interface so that applications can communicate over TCP/IP as clients or servers. You create a socket (with address family, e.g. IPv4 or IPv6, and type, e.g. stream for TCP), connect to a remote host (client), or listen and accept (server). Then you send and receive data. Sockets are useful when you need a custom protocol or direct connection to a specific external system that is not using MQ or web services. CICS sockets support both IPv4 and IPv6. Programming is typically done in C, COBOL, or PL/I using the CICS SOCKET API. You are responsible for the application-level protocol and message format.

Step-by-Step: Calling Another Program with LINK

1. Define the data to pass in working storage (or a copybook) and ensure the called program has a matching definition in its LINKAGE SECTION as DFHCOMMAREA (first item).
2. Set the length of the COMMAREA in a halfword binary or equivalent (0–32767 bytes).
3. Move the data you want to pass into the COMMAREA area.
4. Issue EXEC CICS LINK PROGRAM(program-name) COMMAREA(data-area) LENGTH(length) RESP(response-code).
5. Check the response code. If NORMAL, the called program ran and returned; the COMMAREA may have been updated by the called program. If not NORMAL, handle the error (e.g. PGMIDERR, LENGERR).
6. Continue with the next instruction; the returned data in COMMAREA is now available for use.

Step-by-Step: Transferring Control with XCTL

1. Build the data to pass (e.g. user choice, keys) in the COMMAREA and set LENGTH.
2. Issue EXEC CICS XCTL PROGRAM(program-name) COMMAREA(data-area) LENGTH(length) RESP(response-code).
3. If XCTL is successful, your program is terminated and the named program runs. You do not get control back.
4. If XCTL fails (e.g. program not found), CICS does not transfer control; you get a non-normal response and can handle the error (e.g. message to user, retry, or RETURN).

Choosing the Right Integration

• Same region, same transaction flow, need to return: use LINK with COMMAREA or channels/containers.
• Same region, replace current program (e.g. menu to application): use XCTL.
• Asynchronous, reliable messaging, other regions or platforms: consider IBM MQ.
• Standard web or mobile clients, SOAP or REST: use CICS web services (provider/requester) or z/OS Connect for REST.
• Custom protocol, direct TCP connection: use CICS TCP/IP sockets.

Test Your Knowledge