Introduction

One of our customers has a Web application running on Tomcat with the backend logic implemented in CICS programs on mainframe. The application part in Tomcat is responsible for the workflow control. It uses a IBM CICS Transaction Gateway® (CTG) Java interface for calling the CICS programs in Cobol.  In the new versions of IBM CTG it is possible to call CICS programs via REST-API. In this post I’ll show you how to create and use such REST-API.

Use-Case

In the past the CICS programs were called via IBM CTG using „old-fashioned“ Java Record framework developed for IBM Visual Age. The customer updated its IBM CTG to the version 9.2 which is not compatible to this Java Record framework. The CTG version 9.2 can create a REST-API for a given CICS program interface.  A possible solution is to migrate the IBM CTG CICS interfaces to REST.

Approach

The full description of the REST services in IBM CTG can be found in JSON web services – IBM Documentation. The following picture from this documentation explains this approach:

Concept

The CICS programms are called using COMMAREA payload. In CTG a REST service is created which converts the JSON data to COMMAREA and invokes the CICS program. CTG converts then the returned COMMAREA from CICS to JSON which is passed to the REST client. The REST service implementation is contained in the CICS program. CTG exposes the CICS program via REST-API. In this approach only HTTP POST method is possible.

REST-API Creation

For the REST service creation 2 COMMAREAS of the CICS program are required:

• Input-COMMAREA
• Output-COMMAREA

The JSON WS assistant (ctgassist) generates the JSON schemas and WSBind file which describe the REST-API for the given CICS program. The JSON WS assistant uses a configuration file as input like:

CHAR-VARYING=NO
CCSID=1208
LANG=COBOL
MAPPING-MODE=LS2JS
JSON-SCHEMA-REQUEST=/path/request.json
JSON-SCHEMA-RESPONSE=/path/response.json
LS-REQUEST=/path/request.copybook
LS-RESPONSE=/path/response.copybook
WSBIND=/path/PROGXXX.wsbind
PGMNAME=PROGXXX
PGMINT=COMMAREA
TARGET-CICS-PLATFORM=zOS

The conifuration file format description can be found in https://www.ibm.com/support/knowledgecenter/SSZHFX_9.2.0/progguide/topics/ls2js.html. The following field values contain the COMMAREA definitions:

• LS-REQUEST – Input COMMAREA definition in Cobol
• LS-RESPONSE – Output COMMAREA definition in Cobol

The generated files are:

• JSON-SCHEMA-REQUEST – JSON schema for REST requests
• JSON-SCHEMA-RESPONSE – JSON schema for REST responses
• WSBIND – WSBind file

The WSBind file is used for the REST service configuration in CTG.

REST Service Configuration

The REST service configuration in CTG is described in https://www.ibm.com/support/knowledgecenter/SSZHFX_9.2.0/configuring/topics/json_ovw.html.

A new REST service is defined in the CTG configuration file (default name is ctg.ini).

The REST service definition is contained in the section WEBSERVICE of the CTG configuration file:

SECTION WEBSERVICE=PROGXXX
uri=/servxxx --> URI of the REST service
bindfile=/path/PROGXXX.wsbind --> WSBind file
server=CICSSERVXXX --> CICS server name
....
timeout=60
ENDSECTION

In addition to the WEBSERVICE section you need a HTTP or HTTPS handler definition in the CTG configuration file to enable calling the REST service via HTTP/HTTPS protocol. Here is an example of the HTTP handler definition which is placed in the GATEWAY section of the CTG configuration file:

SUBSECTION HTTP
port=9009 --> HTTP handler port number
bind=serv.host.xxx.de --> host name of the HTTP handler
ENDSUBSECTION

Afterwards the CTG must be restarted to activate the REST service.

Result

If you made all the steps above properly, the outcome will be a REST service available under the endpoint:
http://serv.host.xxx.de:9009/servxxx

You can test it using any REST test client like Postman® or SoapUI®. Here is an example of such REST service:

Assume you have an input/output COMMAREA like:

01   CUSTOMER            PIC X(11000).
02 CUSTOMER-NAME .....

The generated JSON schema will require a JSON input object like:

{"SERVXXXOperation": {
"customer": "......"}}

You have to send a HTTP POST request with such input to the REST endpoint above. The output JSON object will be like:

{"SERVXXXOperationResponse":
{"customer":"....."}}

If your REST service doesn’t work, please look at the CTG log files to find the issue.