Invoking CICS Transactions via REST API

Overview

The Heirloom Elastic Transaction Platform (ETP) provides a comprehensive RESTful API for invoking CICS transactions over HTTP/HTTPS. The HTMLServlet acts as the primary endpoint for all transaction invocations, supporting multiple request formats, response types, and invocation modes.

Servlet Endpoint

The HTMLServlet is deployed at the following URL pattern:

Where:

• <server> - Application server hostname or IP address
• <port> - HTTP/HTTPS port (typically 8080 for HTTP, 8443 for HTTPS)
• <sysid> - System identifier / application context path

HTTP Methods

GET - Retrieve Initial Transaction or Invoke DPL

The GET method is used for two primary purposes:

1. Initial Transaction Request - Start a new session and display the initial transaction (usually "INIT")
2. DPL Invocation - Invoke a transaction with a communication area without maintaining session state

Starts a new session with the default initial transaction (INIT).

Starts a new session with the specified transaction.

Invokes transaction with communication area (DPL style).

POST - Submit Transaction Data or Execute Programs

The POST method is used for submitting form data, invoking EXCI programs, or sending JSON requests.

Continues an existing pseudo-conversational transaction with form data.

Invokes a COBOL program via EXCI mode (External CICS Interface).

Transaction Invocation Modes

1. Standard BMS Transaction Mode (Default)

Traditional CICS transaction invocation with BMS map rendering as HTML forms.

Initial Request (GET):

GET http://localhost:8080/MYSYS/servlet?transid=MENU
Accept: text/html

Response:

HTML page with rendered BMS map, input fields, and PF/PA buttons. Includes a unique browser tab ID (btsg).

Subsequent Request (POST):

POST http://localhost:8080/MYSYS/servlet?btsg=12345
Content-Type: application/x-www-form-urlencoded

DFH_ENTER=Enter&CUSTNO=123456&CUSTNAME=John+Doe

Response:

Next BMS map in the pseudo-conversational flow.

2. EXCI Mode (External CICS Interface)

Invokes COBOL programs directly without BMS maps, suitable for batch processing or API integration.

HTTP Form Request (POST):

POST http://localhost:8080/MYSYS/servlet?exci=yes&progId=CUSTPROG
Content-Type: application/x-www-form-urlencoded

commarea=CustomerData123

Binary Response:

Content-Type: application/octet-stream

[20 bytes error info][commarea contents]

EXCI with Session Persistence:

POST http://localhost:8080/MYSYS/servlet?exci=yes&progId=PROG1&keepsession=true
Content-Type: application/x-www-form-urlencoded

commarea=InitialData

The keepsession=true parameter maintains the HTTP session across multiple EXCI calls, preserving program context and state.

3. JSON Mode

Modern REST API for JSON clients, automatically enabled when Content-Type is application/json.

JSON Request (POST):

POST http://localhost:8080/MYSYS/servlet
Content-Type: application/json
Accept: application/json

{
    "transid": "CUST",
    "commarea": "SGVsbG8gV29ybGQ="
}

JSON Success Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "commarea": "UmVzcG9uc2UgRGF0YQ=="
}

JSON Error Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "error": {
        "resp": "16",
        "resp2": "0",
        "abcode": "ASRA",
        "msg": "Program check exception occurred"
    }
}

JSON with Program Invocation:

POST http://localhost:8080/MYSYS/servlet
Content-Type: application/json

{
    "progId": "CUSTPROG",
    "commarea": "Q3VzdG9tZXJJZDEyMw=="
}

4. DPL (Distributed Program Link) Mode

Invoke transactions via GET with transid and commarea parameters, similar to CICS DPL.

GET http://localhost:8080/MYSYS/servlet?transid=CALC&commarea=1234567890
Accept: text/html

Request Parameters

Complete Examples

Example 1: Standard BMS Transaction Flow

# Initial request - display menu
curl -X GET "http://localhost:8080/BANK/servlet?transid=MENU" \
     -H "Accept: text/html"

# Response includes btsg parameter, e.g., btsg=54321

# User selects option and submits form
curl -X POST "http://localhost:8080/BANK/servlet?btsg=54321" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "DFH_ENTER=Enter&OPTION=1&ACCOUNT=12345"

Example 2: EXCI Program Invocation

# Invoke customer lookup program
curl -X POST "http://localhost:8080/BANK/servlet?exci=yes&progId=CUSTLKUP" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "commarea=CUST0001" \
     --output response.bin

# Check return code (first 20 bytes)
hexdump -C response.bin | head -2

# If successful (all zeros), extract commarea
dd if=response.bin bs=1 skip=20 of=commarea.dat

Example 3: JSON Transaction Invocation

# Invoke transaction with JSON
curl -X POST "http://localhost:8080/BANK/servlet" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "transid": "ACCT",
           "commarea": "QUNDTE0wMDAx"
         }'

# Response (success):
# {"commarea": "QWNjb3VudCBEYXRh"}

# Response (error):
# {"error": {"resp": "13", "resp2": "0", "abcode": "NOTF", "msg": "Transaction not found"}}

Example 4: Java HTTP Client (JSON Mode)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class ETPClient {
    public static void main(String[] args) throws Exception {
        // Prepare communication area
        String commarea = "CUSTOMER123";
        String commareaBase64 = Base64.getEncoder()
            .encodeToString(commarea.getBytes());

        // Build JSON request
        String json = String.format(
            "{\"transid\":\"CUST\",\"commarea\":\"%s\"}",
            commareaBase64
        );

        // Create HTTP client
        HttpClient client = HttpClient.newHttpClient();

        // Build request
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("http://localhost:8080/BANK/servlet"))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        // Send request
        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        // Process response
        System.out.println("Status: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
}

Example 5: Python Requests (EXCI Mode)

import requests
import struct

# EXCI program invocation
url = "http://localhost:8080/BANK/servlet"
params = {
    "exci": "yes",
    "progId": "CUSTPROG"
}
data = {
    "commarea": "CUSTOMER123"
}

response = requests.post(url, params=params, data=data)

# Parse binary response
if response.status_code == 200:
    # First 20 bytes are error information
    error_info = response.content[:20]

    # Unpack error codes (big-endian integers)
    resp = struct.unpack('>I', error_info[0:4])[0]
    resp2 = struct.unpack('>I', error_info[4:8])[0]
    abcode = error_info[8:12].decode('ascii')
    msglen = struct.unpack('>I', error_info[12:16])[0]

    if resp == 0 and resp2 == 0 and msglen == 0:
        # Success - extract commarea
        commarea = response.content[20:]
        print(f"Success: {commarea.decode('utf-8')}")
    else:
        # Error occurred
        error_msg = response.content[20:20+msglen].decode('utf-8')
        commarea = response.content[20+msglen:]
        print(f"Error: resp={resp}, resp2={resp2}, abcode={abcode}")
        print(f"Message: {error_msg}")
else:
    print(f"HTTP Error: {response.status_code}")

Best Practices

Session Management

• Use btsg parameter to isolate browser tabs
• Handle session timeout gracefully in client code
• For EXCI mode, use keepsession=true only when necessary
• Clean up sessions explicitly when done

Error Handling

• Always check HTTP status codes before parsing response
• In EXCI binary mode, validate error header before processing commarea
• In JSON mode, check for error object in response
• Log transaction exceptions with resp/resp2/abcode for troubleshooting

Security

• Always use HTTPS in production environments
• Implement proper authentication (Basic Auth, OAuth2, etc.)
• Validate and sanitize commarea data
• Enable Content Security Policy (CSP) headers

© 2010-2025 Heirloom Computing, Inc. All rights reserved.