CICS Web Services & JSON APIs — Modern CICS Development Guide

In this tutorial, you'll learn about CICS Web Services & JSON APIs. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

CICS Web Services transforms a traditional mainframe Transaction manager into a modern API server — CICS applications that once communicated through green-screen terminals can now expose RESTful JSON APIs consumed by mobile apps, web frontends, and cloud services.

What You'll Learn

CICS Web Services architecture, JSON API development using containers and channels, WS-Security, RESTful endpoint creation from COBOL programs, and integration with API management platforms.

Why It Matters

Banks and insurers cannot afford to rewrite their core CICS applications. CICS Web Services lets them wrap those COBOL programs with JSON APIs, enabling mobile banking, open banking APIs (PSD2), and cloud integration without replacing the trusted mainframe logic underneath.

Doda Browser uses CICS-inspired request-response patterns for tab communication. Durga Antivirus Pro applies CICS-style container processing for scan job Orchestration.

Real-World Use

A bank's account lookup program has run in CICS for 25 years. By adding a Web Services layer, the same COBOL program now serves balance inquiries to the mobile app (JSON), the call center (CICS screen), and the open banking API (REST) — all simultaneously.

Learning Path

flowchart LR
  A["COBOL Programming"] --> B["CICS Transactions"]
  B --> C["CICS Web Services
You are here"]
  C --> D["IBM MQ on z/OS"]
  D --> E["Mainframe DevOps"]
  style C fill:#f90,color:#fff

What Are CICS Web Services?

CICS Web Services allow CICS programs to communicate using HTTP, SOAP, and JSON. There are two approaches:

• SOAP Web Services: XML-based, WS-Security, WSDL contracts
• JSON Web Services: RESTful, lightweight, modern application focus

Architecture Overview

flowchart LR
  subgraph "External"
    A[Mobile App]
    B[Web Frontend]
    C[Cloud Service]
  end
  subgraph "CICS Region"
    D[TCP/IP Listener]
    E[URIMAP]
    F[Pipeline]
    G[Container]
    H[COBOL Program]
  end
  A -->|HTTPS/JSON| D
  B -->|HTTPS/JSON| D
  C -->|SOAP/XML| D
  D --> E --> F --> G --> H
  style D fill:#f90,color:#fff

Key Resources

Defining a RESTful Endpoint

Set up the TCP/IP listener:

DEFINE TCPIPSERVICE(JSONAPI) PORT(8080) PROTOCOL(HTTP) +
       BACKLOG(100) MAXDATALEN(65536) TRANSACTION(CWXN)

Define the URI mapping:

DEFINE URIMAP(ACCOUNTAPI) SCHEME(HTTPS) HOST(*) +
       PATH('/api/account/*') USAGE(PIPELINE) +
       PIPELINE(JSONPIPE) PROGRAM(ACCTLOOK)

COBOL with JSON Containers

The COBOL program receives and returns data through containers:

DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 WS-ACCT-ID        PIC X(20).
       01 WS-BALANCE        PIC S9(15)V99 COMP-3.
       01 WS-STATUS         PIC X(10).

       PROCEDURE DIVISION USING CHANNEL.
           EXEC CICS GET CONTAINER('INPUT')
                CHANNEL(CHANNEL)
                INTO(WS-ACCT-ID)
           END-EXEC

           EXEC CICS LINK PROGRAM('ACCTDB')
                INPUT(WS-ACCT-ID)
                OUTPUT(WS-BALANCE)
           END-EXEC

           MOVE 'SUCCESS' TO WS-STATUS
           EXEC CICS PUT CONTAINER('OUTPUT')
                CHANNEL(CHANNEL)
                FROM(WS-BALANCE)
                FLENGTH(LENGTH OF WS-BALANCE)
           END-EXEC

           EXEC CICS PUT CONTAINER('STATUS')
                CHANNEL(CHANNEL)
                FROM(WS-STATUS)
           END-EXEC

           EXEC CICS RETURN END-EXEC.

The pipeline converts JSON requests to containers and containers back to JSON responses — the COBOL program never handles JSON directly.

Security with WS-Security

CICS Web Services supports multiple security models:

• BasicAuth: HTTP Basic Authentication
• Certificate: Client certificate authentication
• JWT: JSON Web Token validation
• WS-Security: SOAP-level security with SAML tokens

DEFINE TCPIPSERVICE(API) PORT(8443) PROTOCOL(HTTPS) +
       SSL(YES) CERTIFICATE(APICERT) AUTHENTICATE(BASIC)

Common Errors

1. PIPELINE configuration mismatch

Pipeline message handler versions must match the CICS release. Check the PIPELINE configuration.

2. Container naming conventions

Containers are case-sensitive. COBOL programs expecting 'INPUT' will not find 'input'.

3. Max data length exceeded

Set MAXDATALEN on the TCPIPSERVICE to accommodate your largest JSON payload.

4. Missing URIMAP for dynamic paths

Use wildcards in PATH definitions for RESTful URL patterns.

5. Pipeline validation errors

Validate JSON/SOAP messages against the pipeline schema before troubleshooting program logic.

Practice Questions

1. What is the role of a PIPELINE in CICS Web Services? It defines the message processing steps — converting JSON to containers and containers to JSON.

2. How does a COBOL program receive JSON data in CICS? JSON data is converted to CONTAINERs by the pipeline. The program reads containers via EXEC CICS GET CONTAINER.

3. What does URIMAP define? The mapping from a URL path to a CICS program and its associated pipeline.

4. What security options are available for CICS Web Services? BasicAuth, SSL/TLS certificates, JWT validation, and WS-Security with SAML tokens.

5. What is the difference between a CONTAINER and a CHANNEL? A CONTAINER holds a single data item. A CHANNEL is a group of containers passed as a unit to a program.

Challenge: Create a CICS Web Service that accepts a customer ID in JSON, calls a COBOL program to retrieve account details from DB2, and returns the result as JSON with proper error handling.

FAQ

What's Next

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. Updated 2026-06-24.