Can CICS serve REST APIs directly?

Yes. CICS TS 5.2 and later supports RESTful web services natively. A URIMAP resource maps HTTP method and path to a CICS transaction, a PIPELINE handles JSON transformation, and the COBOL program reads and writes request/response data using EXEC CICS GET CONTAINER and PUT CONTAINER. No proxy layer required — CICS serves HTTP directly from its TCPIPSERVICE listener.

What is a CICS PIPELINE resource?

A CICS PIPELINE resource defines the message processing chain for web service requests — the handlers applied to the request on input and the response on output. For SOAP web services, the pipeline contains the SOAP handler that parses the envelope. For JSON REST services, the pipeline contains a JSON-to-data transformation handler. The pipeline is referenced by the URIMAP that routes incoming HTTP requests.

What is a CICS URIMAP?

A URIMAP (URI Mapping) is a CICS resource definition that maps incoming HTTP requests to CICS resources. A provider URIMAP specifies a URI path pattern, an HTTP method (GET, POST, PUT, DELETE), and the CICS resource to invoke. CICS matches incoming HTTP requests against installed URIMAPs and routes them accordingly — exactly like URL routing in a web framework.

How does a CICS COBOL program process an HTTP JSON request?

When a JSON REST request arrives, the CICS pipeline transforms the JSON body and places it in a channel container. The COBOL program uses EXEC CICS GET CONTAINER to retrieve the request data, processes it (file reads, DB2 queries, business logic), then uses EXEC CICS PUT CONTAINER to write the JSON response. The pipeline serialises the container data back into a JSON HTTP response. The COBOL program never directly parses JSON — the pipeline handles serialisation and deserialisation.

What is CICS Liberty and when should you use it instead of native CICS web services?

CICS Liberty is an OSGi-based WebSphere Liberty profile running as a JVM server inside a CICS region. It allows Java/Spring Boot applications to run in CICS, call CICS programs and resources via the JCICS API, and expose REST endpoints using JAX-RS or Spring MVC. Use native CICS web services (URIMAP + PIPELINE) when wrapping existing COBOL programs with no Java involvement. Use CICS Liberty when building new API layers in Java that need to call existing CICS/COBOL logic.

CICS Web Services and REST APIs: The Complete Tutorial (2026)

For decades, CICS was synonymous with 3270 green-screen terminals. Modern CICS has changed that fundamentally. IBM CICS Transaction Server 6.x on z/OS is a fully capable web application server that can expose existing COBOL business logic as REST APIs, SOAP web services, and JSON microservices — without rewriting the original COBOL code.

This tutorial covers the complete CICS web services architecture: how HTTP requests reach CICS, how URIMAP and PIPELINE resources route and transform them, how COBOL programs interact with JSON data using channels and containers, and the patterns organisations use to modernise mainframe systems through CICS APIs.

This is Module 19 of the CICS Mastery Course.

Why CICS Web Services Matter

The value proposition for CICS web services is straightforward: most large enterprises have CICS COBOL applications containing decades of battle-tested, audited, regulatory-compliant business logic. Rewriting that logic in Java or Python to build a microservice is expensive, risky, and rarely necessary. Wrapping the CICS program with a REST API layer achieves the same result — modern clients get a standard JSON interface, the COBOL logic runs unchanged.

This pattern — called the façade over legacy or API-enabled mainframe — is the dominant modernisation approach in financial services and insurance. Instead of ripping out the mainframe, organisations expose it as a first-class API participant in a hybrid architecture.

CICS Web Support Architecture

When an HTTP request arrives at a CICS region, it flows through these layers:

text

Client (browser / mobile / microservice)
         │  HTTP/HTTPS
         ▼
TCPIPSERVICE  — TCP/IP listener, defines port + protocol
         │
         ▼
CICS Web Support  — URIMAP routing: matches URI path + HTTP method
         │
         ▼
PIPELINE  — message transformation: JSON parsing, SOAP handling
         │
         ▼
COBOL Program  — business logic, EXEC CICS GET/PUT CONTAINER
         │
         ▼
Response flows back through PIPELINE → HTTP response to client

The Four Key Web Service Resources

Resource	Purpose
TCPIPSERVICE	TCP/IP port and protocol (HTTP/HTTPS) that CICS listens on
URIMAP	Maps URI path + HTTP method to a pipeline or program
PIPELINE	Message processing chain (JSON/SOAP transformation handlers)
WEBSERVICE	(SOAP only) Links WSDL definition to service binding

Defining CICS Web Service Resources

Step 1: TCPIPSERVICE — the HTTP Listener

text

CEDA DEFINE TCPIPSERVICE(HTTPPORT)
     GROUP(WEBSVCS)
     PORTNUMBER(3001)
     PROTOCOL(HTTP)
     SOCKETCLOSE(60)
     MAXDATALEN(32768)
     BACKLOG(10)

In production, use PROTOCOL(HTTPS) with a TLS certificate bound to the port. The MAXDATALEN value sets the maximum request/response body size in bytes — increase this for large payloads.

Step 2: URIMAP — URI Routing

A provider URIMAP maps an incoming request to a pipeline:

text

CEDA DEFINE URIMAP(EMPGET)
     GROUP(WEBSVCS)
     USAGE(PIPELINE)
     HOST(*)
     PATH(/api/employee/*)
     SCHEME(HTTP)
     METHOD(GET)
     PIPELINE(JSONPIPE)
     TRANSACTION(EMPQ)
     USERID(APIUSER)
     STATUS(ENABLED)

Key fields:

PATH — URI path pattern, wildcards supported
METHOD — GET, POST, PUT, DELETE, or * for any method
PIPELINE — which pipeline to use for message transformation
TRANSACTION — CICS transaction to run (links to the COBOL program)
USERID — security user ID to run the transaction under

Define separate URIMAPs for each HTTP method + path combination. A POST to /api/employee and a GET to /api/employee/* are two separate URIMAPs.

Step 3: PIPELINE — Message Transformation

text

CEDA DEFINE PIPELINE(JSONPIPE)
     GROUP(WEBSVCS)
     CONFIGFILE(/cics/pipelines/jsonhandler.xml)
     SHELF(/cics/pipelines/shelf)
     WSDIR(/cics/pipelines/wsdl)

The pipeline references a configuration XML file that specifies which message handlers to apply. For a JSON REST pipeline:

xml

<?xml version="1.0"?>
<provider_pipeline
    xmlns="http://www.ibm.com/software/htp/cics/pipeline"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <service>
    <terminal_handler>
      <cics_json_channel_handler>
        <request_container>DFHWS-DATA</request_container>
        <response_container>DFHWS-DATA</response_container>
      </cics_json_channel_handler>
    </terminal_handler>
  </service>
</provider_pipeline>

The cics_json_channel_handler reads the HTTP JSON body and places it in the DFHWS-DATA container. After the COBOL program runs, it reads the response from DFHWS-DATA and sends it as the HTTP response body.

Channels and Containers

Modern CICS web services use channels and containers rather than COMMAREA to pass data between the pipeline and the application program.

A channel is a named set of containers (like a key-value store scoped to a task)
A container holds a single data item — a request body, a status code, a header

This design removes the 32 KB COMMAREA size limit. Containers can hold megabytes of data, and a single channel can carry dozens of containers.

Predefined Web Service Containers

Container Name	Content
`DFHWS-DATA`	Request/response body (JSON, XML, or SOAP body)
`DFHWS-BODY`	Full HTTP body
`DFHHTTP-REQUEST`	HTTP request details (method, path, headers)
`DFHRESPONSE`	HTTP response status code
`DFHWS-URI`	The full URI of the incoming request

Accessing Containers in COBOL

cobol

*── Get the current channel name ─────────────────────────────────
EXEC CICS ASSIGN CHANNEL(WS-CHANNEL) RESP(WS-RESP) END-EXEC

*── Read the JSON request body from DFHWS-DATA ───────────────────
EXEC CICS GET CONTAINER('DFHWS-DATA')
              CHANNEL(WS-CHANNEL)
              INTO(WS-REQUEST-JSON)
              FLENGTH(WS-REQUEST-LEN)
              RESP(WS-RESP)
END-EXEC

*── After processing, write the JSON response ────────────────────
EXEC CICS PUT CONTAINER('DFHWS-DATA')
              CHANNEL(WS-CHANNEL)
              FROM(WS-RESPONSE-JSON)
              FLENGTH(WS-RESP-LEN)
              DATATYPE(CHAR)
END-EXEC

*── Set HTTP response status code ────────────────────────────────
EXEC CICS WEB SEND
              STATUSCODE(200)
              STATUSTEXT('OK')
              STATUSLEN(2)
END-EXEC

Complete Example: Employee Lookup REST API

This example builds a GET /api/employee/{empno} endpoint backed by a VSAM file.

COBOL Program: EMPAPI

cobol

IDENTIFICATION DIVISION.
PROGRAM-ID. EMPAPI.

DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-CHANNEL         PIC X(16).
01  WS-RESP            PIC S9(8) COMP VALUE ZERO.
01  WS-HTTP-STATUS     PIC S9(4) COMP VALUE ZERO.

*── Request/response JSON buffers
01  WS-REQUEST-JSON    PIC X(1024).
01  WS-REQUEST-LEN     PIC S9(8) COMP VALUE +1024.
01  WS-RESPONSE-JSON   PIC X(512).
01  WS-RESP-LEN        PIC S9(8) COMP VALUE ZERO.

*── URI for path parsing
01  WS-URI             PIC X(256).
01  WS-URI-LEN         PIC S9(8) COMP VALUE +256.

*── Employee record (VSAM key = 6-char empno)
01  WS-EMP-KEY         PIC X(6).
01  WS-EMP-REC.
    05  WS-EMP-NO      PIC X(6).
    05  WS-EMP-NAME    PIC X(30).
    05  WS-EMP-DEPT    PIC X(10).
    05  WS-EMP-SAL     PIC S9(7)V99 COMP-3.
01  WS-EMP-LEN         PIC S9(4) COMP VALUE +52.

LINKAGE SECTION.
01  DFHCOMMAREA        PIC X.

PROCEDURE DIVISION.
MAIN-LOGIC.
    *── Identify our channel ──────────────────────────────────────
    EXEC CICS ASSIGN CHANNEL(WS-CHANNEL)
                     RESP(WS-RESP)
    END-EXEC

    IF WS-RESP NOT = DFHRESP(NORMAL)
        PERFORM SEND-500-ERROR
        EXEC CICS RETURN END-EXEC
    END-IF

    *── Get the URI so we can extract the employee number ─────────
    EXEC CICS GET CONTAINER('DFHWS-URI')
                  CHANNEL(WS-CHANNEL)
                  INTO(WS-URI)
                  FLENGTH(WS-URI-LEN)
                  RESP(WS-RESP)
    END-EXEC

    *── Extract last 6 chars of path as employee key ──────────────
    *── URI format: /api/employee/000100
    MOVE WS-URI(17:6) TO WS-EMP-KEY

    *── Read employee from VSAM ───────────────────────────────────
    EXEC CICS READ FILE('EMPFILE')
                   RIDFLD(WS-EMP-KEY)
                   INTO(WS-EMP-REC)
                   LENGTH(WS-EMP-LEN)
                   RESP(WS-RESP)
    END-EXEC

    EVALUATE WS-RESP
        WHEN DFHRESP(NORMAL)
            PERFORM BUILD-SUCCESS-JSON
            MOVE 200 TO WS-HTTP-STATUS
        WHEN DFHRESP(NOTFND)
            MOVE '{"error":"Employee not found","code":"EMP404"}'
                 TO WS-RESPONSE-JSON
            MOVE 47 TO WS-RESP-LEN
            MOVE 404 TO WS-HTTP-STATUS
        WHEN OTHER
            PERFORM SEND-500-ERROR
            EXEC CICS RETURN END-EXEC
    END-EVALUATE

    *── Write JSON response to output container ───────────────────
    EXEC CICS PUT CONTAINER('DFHWS-DATA')
                  CHANNEL(WS-CHANNEL)
                  FROM(WS-RESPONSE-JSON)
                  FLENGTH(WS-RESP-LEN)
                  DATATYPE(CHAR)
    END-EXEC

    EXEC CICS RETURN END-EXEC.

BUILD-SUCCESS-JSON.
    STRING '{"empNo":"'    WS-EMP-NO
           '","name":"'    FUNCTION TRIM(WS-EMP-NAME)
           '","dept":"'    FUNCTION TRIM(WS-EMP-DEPT)
           '","salary":'   WS-EMP-SAL
           '}'
           DELIMITED SIZE
           INTO WS-RESPONSE-JSON
    MOVE FUNCTION LENGTH(FUNCTION TRIM(WS-RESPONSE-JSON))
         TO WS-RESP-LEN.

SEND-500-ERROR.
    MOVE '{"error":"Internal server error"}'
         TO WS-RESPONSE-JSON
    MOVE 34 TO WS-RESP-LEN
    EXEC CICS PUT CONTAINER('DFHWS-DATA')
                  CHANNEL(WS-CHANNEL)
                  FROM(WS-RESPONSE-JSON)
                  FLENGTH(WS-RESP-LEN)
                  DATATYPE(CHAR)
    END-EXEC.

CSD Resource Definitions for this Example

text

CEDA DEFINE PROGRAM(EMPAPI)
     GROUP(WEBSVCS)
     LANGUAGE(COBOL)
     DATALOCATION(ANY)

CEDA DEFINE TRANSACTION(EMPQ)
     GROUP(WEBSVCS)
     PROGRAM(EMPAPI)
     TASKDATALOC(ANY)

CEDA DEFINE URIMAP(EMPGET)
     GROUP(WEBSVCS)
     USAGE(PIPELINE)
     HOST(*)
     PATH(/api/employee/*)
     SCHEME(HTTP)
     METHOD(GET)
     PIPELINE(JSONPIPE)
     TRANSACTION(EMPQ)
     STATUS(ENABLED)

CEDA INSTALL GROUP(WEBSVCS)

JSON Processing Approaches in CICS COBOL

When CICS pipelines with JSON binding are not available (older CICS versions or complex JSON structures), COBOL programs must handle JSON directly.

Approach 1: CICS JSON Binding (Recommended for CICS TS 5.5+)

The JSON binding feature automatically maps JSON fields to COBOL data items based on a JSON schema. IBM's DFHLS2JS tool generates the mapping from a COBOL copybook. The COBOL program accesses data as native COBOL variables — no string parsing.

cobol

*── With JSON binding, COBOL data items are populated automatically
*── from the JSON request before the program starts
MOVE WS-EMP-NUMBER TO WS-LOOKUP-KEY   *> Field populated from JSON

Approach 2: COBOL JSON PARSE (CICS TS 6.1+ with COBOL for z/OS 6.4+)

COBOL for z/OS 6.4 introduced native JSON PARSE and GENERATE verbs:

cobol

DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-JSON-DATA  PIC X(1024).
01  WS-EMP-RECORD.
    05  WS-EMP-NO   PIC X(6).
    05  WS-EMP-NAME PIC X(30).

PROCEDURE DIVISION.
    *── Parse JSON into COBOL data items ──────────────────────────
    JSON PARSE WS-JSON-DATA INTO WS-EMP-RECORD
         ON EXCEPTION
             PERFORM HANDLE-JSON-ERROR
         NOT ON EXCEPTION
             PERFORM PROCESS-REQUEST
    END-JSON

    *── Generate JSON from COBOL data items ───────────────────────
    JSON GENERATE WS-JSON-DATA FROM WS-EMP-RECORD
         ON EXCEPTION
             PERFORM HANDLE-JSON-ERROR
    END-JSON

Approach 3: Manual STRING/UNSTRING Parsing

For simple JSON structures on older CICS versions, COBOL's STRING and UNSTRING verbs parse and build JSON directly. Practical but error-prone — reserve for simple key-value JSON with no nesting.

CICS as a Web Service Requester

CICS can also act as a web service requester — calling external REST or SOAP APIs from within a CICS COBOL program. This enables CICS to consume microservices, cloud APIs, or third-party web services.

cobol

CALL-EXTERNAL-REST-API.
    *── Open HTTP connection ──────────────────────────────────────
    EXEC CICS WEB OPEN
              SESSTOKEN(WS-SESSION-TOKEN)
              HOST('api.example.com')
              HOSTLENGTH(15)
              HTTPSPORT(443)
              SCHEME(HTTPS)
              RESP(WS-RESP)
    END-EXEC

    IF WS-RESP NOT = DFHRESP(NORMAL)
        PERFORM HANDLE-CONNECT-ERROR
        GO TO API-CALL-DONE
    END-IF

    *── Send GET request ──────────────────────────────────────────
    EXEC CICS WEB SEND
              SESSTOKEN(WS-SESSION-TOKEN)
              PATH('/v1/validate')
              PATHLENGTH(12)
              METHOD(GET)
              MEDIATYPE('application/json')
              MEDIATYPELENGTH(16)
              RESP(WS-RESP)
    END-EXEC

    *── Receive response ──────────────────────────────────────────
    EXEC CICS WEB RECEIVE
              SESSTOKEN(WS-SESSION-TOKEN)
              INTO(WS-RESPONSE-JSON)
              LENGTH(WS-RESPONSE-LEN)
              STATUSCODE(WS-HTTP-STATUS)
              RESP(WS-RESP)
    END-EXEC

    *── Close the connection ──────────────────────────────────────
    EXEC CICS WEB CLOSE
              SESSTOKEN(WS-SESSION-TOKEN)
    END-EXEC.

API-CALL-DONE.
    EXIT.

Key WEB commands for requester mode:

Command	Purpose
`WEB OPEN`	Opens a session to an external host (HTTP or HTTPS)
`WEB SEND`	Sends an HTTP request (method, path, body)
`WEB RECEIVE`	Receives the HTTP response body and status code
`WEB CLOSE`	Closes the session and frees resources

Always call WEB CLOSE — open sessions consume CICS socket resources and can exhaust connection limits.

SOAP Web Services with WSDL

For SOAP-based integration, CICS uses a WEBSERVICE resource that links a WSDL definition to a CICS program. IBM's DFHWS2LS utility generates COBOL copybooks from the WSDL and creates the binding between SOAP envelope fields and COBOL data items — no manual XML parsing required.

The SOAP workflow:

Developer provides WSDL describing the service interface
DFHWS2LS generates COBOL copybooks and JSON/XML binding data
CICS WEBSERVICE, PIPELINE, and URIMAP resources are installed
CICS handles SOAP envelope parsing automatically
COBOL program uses EXEC CICS GET/PUT CONTAINER — same as REST

text

CEDA DEFINE WEBSERVICE(EMPSVC)
     GROUP(WEBSVCS)
     PIPELINE(SOAPPIPE)
     WSBIND(/cics/wsbind/employee.wsbind)
     WSDLFILE(/cics/wsdl/employee.wsdl)
     VALIDATION(NO)

Security for CICS Web Services

Exposing CICS to HTTP traffic requires appropriate security controls:

TLS/HTTPS. Use PROTOCOL(HTTPS) on the TCPIPSERVICE and bind a certificate using AT-TLS (Application Transparent TLS) or CICS-managed certificates. Never expose production CICS web services on unencrypted HTTP.

RACF authentication. The URIMAP's USERID field sets the security context. For authenticated APIs, configure HTTP Basic Auth or AT-TLS client certificates mapped to RACF user IDs. CICS checks RACF authorisation on the TRANSACTION resource before invoking the program.

Input validation. Always validate JSON input before passing values to VSAM reads, DB2 queries, or CICS file control commands. Unchecked input can produce unexpected key lookups or COMMAREA overflows.

RACF profiles for web services. Define RACF SERVAUTH profiles to control which clients can access specific CICS services:

text

RDEFINE SERVAUTH CBIND.CICSPROD.EMPQ UACC(NONE)
PERMIT CBIND.CICSPROD.EMPQ CLASS(SERVAUTH) ID(APIUSER) ACCESS(READ)

CICS Liberty: The Java API Layer Option

For new API development — rather than wrapping existing COBOL — CICS Liberty provides an alternative path:

CICS Liberty is an OSGi-based WebSphere Liberty profile running as a JVM server inside a CICS region. It allows Java/Spring Boot applications to run in CICS, call CICS programs and resources via the JCICS API, and expose REST or SOAP endpoints using JAX-RS or Spring MVC.

When to use native CICS web services vs CICS Liberty:

Scenario	Recommended Approach
Expose existing COBOL program as REST API	Native CICS web services (URIMAP + PIPELINE)
Build new Java microservice calling CICS	CICS Liberty + JCICS
SOAP web service from WSDL	Native CICS web services (WEBSERVICE + DFHWS2LS)
OpenAPI/Swagger documented REST API	CICS Liberty (Liberty has OpenAPI support)
Low-latency transaction with no Java overhead	Native CICS web services

Common Issues and Diagnostics

Symptom	Likely Cause	Resolution
HTTP 404 on valid URI	URIMAP not installed or wrong path pattern	`CEMT INQUIRE URIMAP` — check STATUS and PATH
HTTP 500 from CICS	Program ABEND inside the pipeline	Check CICS SYSLOG for ABEND code; run CICS trace
DFHWS-DATA container empty	Pipeline config not matching handler	Verify `configfile` XML and handler class name
WEB OPEN IOERR	DNS resolution failure or network ACL	Verify hostname, port, and CICS outbound TCP/IP rules
JSON parse error in COBOL	Malformed JSON from client	Log `DFHWS-DATA` container contents for diagnosis
MAXDATALEN exceeded	Request body too large	Increase MAXDATALEN on TCPIPSERVICE definition

CICS trace (CETR transaction) with SPECIAL option captures HTTP request and response data for detailed diagnosis of pipeline issues.

What You Learned

This module covered:

CICS web support architecture — how HTTP requests flow from TCPIPSERVICE through URIMAP and PIPELINE to the COBOL program
Resource definitions — TCPIPSERVICE, URIMAP, PIPELINE, and WEBSERVICE for both REST and SOAP
Channels and containers — how COBOL programs access JSON request and response data via EXEC CICS GET/PUT CONTAINER
Complete REST API example — employee lookup GET endpoint with VSAM file access, error handling, and JSON response building
JSON processing approaches — JSON binding, COBOL JSON PARSE verb, and manual STRING handling
CICS as requester — WEB OPEN/SEND/RECEIVE/CLOSE for calling external APIs from COBOL
Security — TLS, RACF authorisation, and input validation for production deployments
CICS Liberty — when to use the Java API layer instead of native CICS web services

Ready to Master CICS?

This lesson is Module 19 of the CICS Mastery Course — the complete guide to IBM CICS programming from transaction fundamentals to DB2 integration and REST API modernisation. 22 modules, beginner to senior, free.

→ View the full CICS Mastery Course

CICS Mastery Course

22 modules. Beginner to senior. Free.

Start the Course →