Expose CICS Programs as WebServices in Liberty to clients

Introduction

In IBM CICS, the integrated WebSphere Liberty profile provides a modern, lightweight runtime for Java applications.
If your goal is to expose CICS business logic through SOAP without modifying existing programs, a clean approach is to wrap only those programs that can be called via EXEC CICS LINK from Java.

With this method, the Liberty application:

1. Receives a SOAP request.
2. Calls the CICS program directly via LINK using the Java API.
3. Returns the result to the SOAP client.

Our testing confirms: This configuration works in both CICS 5.6 and CICS 6.2 without any changes.

---

Why the LINK Approach?

• Direct program invocation – No additional CICS pipeline or WEBSERVICE resources.
• Low latency – Runs in the same CICS region as the target program.
• Encapsulation – Liberty handles SOAP marshalling/unmarshalling and passes a commarea to the target program.

---

Required Liberty Features

To enable SOAP and Java programmatic access in Liberty for CICS 5.6 and 6.2:

<featureManager>
    <feature>javaee-7.0</feature>
    <feature>jaxws-2.2</feature>
    <feature>jaxb-2.2</feature>
    <feature>servlet-4.0</feature>
</featureManager>

---

Implementation Pattern

1. Receive SOAP Request in Liberty

The SOAP endpoint is implemented as a JAX-WS service:

@WebService
public class AccountFacade {

    public AccountDetails getAccount(String accountId) {
        return callCicsProgram("ACCTPROG", accountId);
    }
}

---

2. Call the CICS Program via LINK

Calling the COBOL / PLI program using the CICS Java API equivalent to EXEC CICS LINK.

import com.ibm.cics.server.Program;
import java.util.logging.Logger;

private static final Logger logger = Logger.getLogger(AccountFacade.class.getName());

private AccountDetails callCicsProgram(String pgmname, String requestData) {
    try {
        // Prepare commarea
        CommAreaHolder commarea = new CommAreaHolder(requestData.getBytes());

        Program programToCall = new Program();
        programToCall.setName(pgmname);

        logger.finer(String.format("Entering EXEC CICS LINK (%s)", pgmname));
        long elapsed = System.currentTimeMillis();

        // Perform the LINK
        programToCall.link(commarea.getByteBuffer());

        elapsed = System.currentTimeMillis() - elapsed;
        logger.fine(String.format("Returning from EXEC CICS LINK (%s) in %d ms", pgmname, elapsed));

        // Parse commarea response
        return parseAccountDetails(commarea.getBytes());

    } catch (Exception e) {
        throw new RuntimeException("Error calling CICS program " + pgmname, e);
    }
}

---

3. Package and Deploy

1. Build a WAR file containing:
   • The SOAP endpoint class.
   • The CICS LINK wrapper code
2. Deploy via Liberty’s dropins/ directory or define in server.xml:

<webApplication location="cics-facade.war" contextRoot="/cics" />

---

Example server.xml

<server description="CICS Liberty SOAP LINK Client">    <featureManager>
        <feature>javaee-7.0</feature>
        <feature>jaxws-2.2</feature>
        <feature>jaxb-2.2</feature>
        <feature>servlet-4.0</feature>
    </featureManager>

    <httpEndpoint id="defaultHttpEndpoint"
        httpPort="9080"
        httpsPort="9443" />

    <webApplication location="cics-facade.war" contextRoot="/cics" />
</server>

---

Best Practices

• Restrict to LINK-capable programs – Avoid dependencies on channels, containers, or custom transactions.
• Validate commarea size – Ensure the Java-side buffer matches the program’s expected commarea length.
• Error handling – Catch and log all exceptions from the LINK call for diagnostics.
• Performance monitoring – Track elapsed time for each LINK invocation.

---

Forward Compatibility

• The Liberty features and EXEC CICS LINK Java API usage described here run unchanged in CICS 5.6 and CICS 6.2.
• No feature version bumps are required — javaee-7.0, jaxws-2.2, jaxb-2.2, and servlet-4.0 work as expected.

---

Diagram

---

Conclusion

By combining Liberty’s SOAP capabilities with the CICS Java API for EXEC CICS LINK, you can wrap eligible CICS programs in modern SOAP services — all without touching pipelines, WSDL generation in CICS, or complex configuration.
It’s a clean, future-proof way to expose mainframe logic while keeping the integration layer entirely in Liberty.

Enhancements and modifications

When SOAP is no longer the format your clients communicate, the very same approach is feasible to expose your CICS application programs via REST. Instead of jaxws you then want to turn towards jax-rs.

In case your CICS is at 6.2 already, we recommend moving forward from javaee-7, jaxws-2.2 and jaxb-2.2 to jakartaee-10 and xmlWS-4.0. That reduces the number of features. You are then using the most current implementations available for SOAP web services.

What is next

How about integrating your existing CICS applications with modern systems via SOAP and/or REST calls? Imagine you would be able to enrich your core business system by including services from modern service implentations seamlessly. Call that service the very same way you call other programs in CICS using EXEC CICS LINK. Consider replacing Assembler, COBOL or PL/1 code in CICS with services existing in your distributed world.

How about those modern services could also be directly called from batch via EXCI in Liberty in CICS? Imagine your COBOL batch program directly calls an external service by simply invoking a Java program via CICS EXCI running in Liberty.