Invoke CICS Transactions Through HTTP

Last Updated: February 2025 Applies To: ETP 25.5.1 and later

Overview

The Elastic Transaction Platform (ETP) provides HTTP-based access to CICS transactions and programs running within the platform. This allows both interactive web applications and programmatic service integrations to invoke CICS functionality over standard HTTP/HTTPS protocols.

ETP supports two distinct invocation modes:

1. Session-Based Mode - Interactive conversational transactions with BMS map rendering
2. EXCI Mode - Stateless program invocation for programmatic integration (External CICS Interface)

Session-Based Mode (Interactive Transactions)

Session-based mode converts traditional CICS "green screen" 3270 terminal applications into web-based applications. BMS maps are rendered as HTML forms, maintaining conversational state through HTTP sessions.

Use Cases

• Interactive web applications (browser-based)
• Converting legacy 3270 applications to web
• Multi-screen conversational flows
• User-driven terminal emulation

URL Format

GET  http://server-address:8080/sysid/servlet              - Initial transaction
GET  http://server-address:8080/sysid/servlet?transid=XXXX - Start specific transaction
POST http://server-address:8080/sysid/servlet              - Submit form data

Request Parameters

Response Formats

HTML Response (Default)

Request:

curl -c cookies.txt http://localhost:8080/SYS1/servlet?transid=CUST

Response: Content-Type: text/html or application/xhtml+xml

The BMS map is rendered as a complete HTML page with:

• Form fields corresponding to BMS map fields
• CSS styling and JavaScript for terminal behavior
• PF key buttons
• Session cookie for state management

Example HTML:

<form method="POST" action="/SYS1/servlet">
    <input type="text" name="CUSTID" maxlength="6" />
    <input type="text" name="CUSTNAME" maxlength="30" />
    <button name="AID" value="PF3">F3-Exit</button>
</form>

Interaction Flow

1. Initial Request (GET)
   → Creates HTTP session
   → Starts transaction
   → Returns BMS map as HTML/JSON

2. User Input (POST)
   → Sends form data with session cookie
   → Processes transaction
   → Returns next screen

3. Continue conversation...
   → Multiple POST requests maintain session
   → Pseudo-conversational flow

curl Examples

# Initial request (saves session cookie)
curl -c cookies.txt http://localhost:8080/SYS1/servlet?transid=CUST

# Submit form data (uses saved cookie)
curl -b cookies.txt -X POST http://localhost:8080/SYS1/servlet \
  -d "CUSTID=123456&CUSTNAME=&AID=ENTER"

# Press PF3 key
curl -b cookies.txt -X POST http://localhost:8080/SYS1/servlet \
  -d "CUSTID=123456&CUSTNAME=John+Doe&AID=PF3"

Important: Session cookies (JSESSIONID) must be maintained between requests using -c (save) and -b (send) options.

EXCI Mode (External CICS Interface)

EXCI mode provides stateless program invocation for programmatic integration. Programs are invoked directly without BMS map rendering, with input/output through the communication area (COMMAREA).

Use Cases

• Programmatic API access
• Backend service integration
• Stateless program calls
• Batch processing and automation
• Service-to-service communication

URL Format

GET/POST http://server-address:8080/sysid/servlet?exci=yes&progId=XXXX&commarea=YYYY

Request Parameters

Response Formats

Binary Response (Default)

Request:

curl 'http://localhost:8080/SYS1/servlet?exci=yes&progId=CUSTPROG&commarea=12345'

Response: Content-Type: application/octet-stream

Binary format:

┌─────────────────────┬──────────────────┬──────────────────┐
│  20-byte header     │  Error message   │  COMMAREA bytes  │
│  (error info)       │  (if error)      │  (output data)   │
└─────────────────────┴──────────────────┴──────────────────┘

20-byte Header Structure:

Bytes  0-3:  resp   (int, big-endian) - Response code (0 = success)
Bytes  4-7:  resp2  (int, big-endian) - Response code 2
Bytes  8-11: abcode (4 chars)         - Abend code (e.g., "APCT")
Bytes 12-15: msglen (int, big-endian) - Error message length
Bytes 16-19: reserved (zeros)

Success Response:

• Header bytes all zeros
• COMMAREA data starts at byte 20

Error Response:

• Header contains error codes
• Error message follows header (msglen bytes)
• COMMAREA follows error message

curl Examples

Binary Mode

# Basic call
curl 'http://localhost:8080/SYS1/servlet?exci=yes&progId=TESTPROG&commarea=input123'

# Save to file and parse
curl -s 'http://localhost:8080/SYS1/servlet?exci=yes&progId=TESTPROG&commarea=input123' \
  -o response.bin

# View hex dump
xxd response.bin | head -n 10

# Extract commarea only (skip 20-byte header)
tail -c +21 response.bin

# Check for success (first 4 bytes should be zeros)
od -An -j0 -N4 -tu4 response.bin

Session Management

By default, EXCI calls are stateless and do not maintain session state. To maintain state across multiple calls:

# First call - create session
curl 'http://localhost:8080/SYS1/servlet?exci=yes&progId=PROG1&commarea=data1&keepsession=true' \
  -c cookies.txt

# Subsequent calls - reuse session
curl 'http://localhost:8080/SYS1/servlet?exci=yes&progId=PROG2&commarea=data2&keepsession=true' \
  -b cookies.txt -c cookies.txt

# Final call - close session
curl 'http://localhost:8080/SYS1/servlet?exci=yes&progId=PROG3&commarea=data3' \
  -b cookies.txt

Comparison: Session-Based vs EXCI Mode

Programmatic Access

Java Example (Binary Mode)

import java.io.*;
import java.net.*;
import java.nio.ByteBuffer;

URL url = new URL("http://localhost:8080/SYS1/servlet?exci=yes&progId=TESTPROG&commarea=input");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");

InputStream is = conn.getInputStream();
byte[] response = is.readAllBytes();

// Parse 20-byte header
ByteBuffer buffer = ByteBuffer.wrap(response);
int resp = buffer.getInt();      // Bytes 0-3
int resp2 = buffer.getInt();     // Bytes 4-7
byte[] abcode = new byte[4];     // Bytes 8-11
buffer.get(abcode);
int msglen = buffer.getInt();    // Bytes 12-15

if (resp == 0 && resp2 == 0 && msglen == 0) {
    // Success - extract commarea
    byte[] commarea = Arrays.copyOfRange(response, 20, response.length);
    System.out.println("Result: " + new String(commarea));
} else {
    // Error
    String errorMsg = new String(response, 20, msglen);
    byte[] commarea = Arrays.copyOfRange(response, 20 + msglen, response.length);
    System.err.println("Error " + resp + "/" + resp2 + ": " + errorMsg);
}

Python Example

import requests
import base64
import struct

# Binary mode
response = requests.get(
    'http://localhost:8080/SYS1/servlet',
    params={'exci': 'yes', 'progId': 'TESTPROG', 'commarea': 'input123'}
)

data = response.content

# Parse header
resp, resp2, abcode, msglen = struct.unpack('>II4sI', data[0:16])

if resp == 0 and msglen == 0:
    commarea = data[20:]
    print(f"Success: {commarea.decode()}")
else:
    error_msg = data[20:20+msglen].decode()
    commarea = data[20+msglen:]
    print(f"Error {resp}/{resp2}: {error_msg}")

Error Codes and Troubleshooting

Common Response Codes

Troubleshooting

Problem: Binary output shows in terminal

# Solution: Save to file or pipe to xxd
curl -s 'http://...' | xxd

Problem: URL parsing error (zsh: parse error near '&')

# Solution: Quote the URL
curl 'http://localhost:8080/servlet?exci=yes&progId=PROG'

Problem: Session not maintained

# Solution: Use -c and -b for cookies
curl -c cookies.txt ...  # Save cookies
curl -b cookies.txt ...  # Send cookies

Problem: COMMAREA data corrupted

# Solution: Use proper encoding
# URL mode: URL-encode special characters
# JSON mode: Base64-encode data

Platform Information

ETP runs under:

• Java Containers: Apache Tomcat, VMware tcServer
• JEE Application Servers: Apache Geronimo, Payara, IBM WebSphere, Oracle WebLogic, Red Hat JBoss

Transport Security:

• HTTP (default)
• HTTPS (TLS 1.0+ / SSL 3.0+)

Session Management:

• HTTP session cookies
• Configurable timeout
• Multi-tab support via btsg parameter