IBM Support

Creating CICS REST Service provider in Business Developer

White Papers


Venkatasuresh Kothuri
Lead Software Engineer

IBM Business Developer offers various deployment architecture models for generated applications for its users based on their needs.
This paper details the functionality of functions enhanced to support IBM i environment, their limitations and functioning for various requirement scenarios.



The CICS implementation of RESTful web services is similar to that of SOAP web Services, but CICS requires the use of a JSON schema. Each URL sent from the client is called a request, while the data sent back to the user from the server is called a response.

image 12657

The scenarios described in this paper explain how the communication on request & response between the Server & Client for CICS rest services.

  • IBM Rational Business Developer (RBD). 
  • Knowledge of developing code using EGL. 
  • Knowledge of generating the COBOL programs from EGL.

Pipeline Configuration 

The pipeline configuration file is stored in the z/OS® UNIX System Services file system, and its name is specified in the CONFIGFILE attribute of a PIPELINE resource definition. When CICS processes a web service request, it uses a pipeline of one or more message handlers to handle the request.

Location Unix Shell Path: /u/rbdtest/services (this should match on the destdirectory in the builddescriptor)

Configuration file: basicRESTprovider.xml
image 12658
image 12661
CICS Region Setup
For CICS to provide a service to an external service requester, it must receive the service request and pass it through a pipeline to the target application program. The response from the application is returned to the service requester through the same pipeline.
  • A PIPELINE resource definition is required for every web service. It provides information about the message handler programs acting on a service request and the response.
       Example: RESTPROV is the Pipeline name for REST Service, which was created for development.
image 12662
  • A TCPIPSERVICE definition is required in a service provider that uses HTTP transport. It contains information about the port on which inbound requests are received.
       Example: 9090 is the port that was created & using for REST service in the development.
image 12663
        After scanning the pipeline, the URIMAP & WEBSERVICE are created.
image 12659
  • A WEBSERVICE resource definition is required only when the mapping between application data structure and messages has been generated using the CICS web services assistant. It defines aspects of the runtime environment for a CICS application program deployed in a web services setting.
image 12664
  • A URIMAP definition is also required if user use HTTP basic authentication because the URIMAP resource definition specifies that the service requester user ID information is passed in an HTTP authorization header to the service provider.
image 12656
EndPoint URL for client:
EGL Program
  • To define an EGL Interface part in a file that is made available to the requester of that service. The Interface part can be in the same EGL package or imported from a separate package.
image 12668
  • Here is the sample service to implement the above specified Interface.
image 12669
  • During the Deployment Descriptor generation, WSBIND file will get created by using CICS JSON assistant procedure DFHJS2LS. The generated WSBIND file is moved into the UNIX directory in the Mainframe, defined in the Build Descriptor. 
image 12670
Mainframe UNIX Shell path directory: /u/urbdtest/services/RESTprovider
image 12671
  • Declaring a variable to access a REST service (RUI As client in the example)
image 12672
Response Message to Client:
  • SetCICSRestResponse function sets the HTTP response headers from a CICS REST service. This function is available in an EGL-generated CICS REST service.
image 12673
Example: (POSTMAN)
image 12674
We have some restrictions on this design as below:
  • For all methods, the path & query parameters should be in order - path parameters should be first, and query parameters (?) should be next. At the same time, variables having in the function should be in the same order while handing on the path and query parameter.
  • The single record must be used when multiple methods are present in the same EGL service.
  • The BOOLEAN datatype doesn’t support in Path & Query parameter. It supports the REQUEST body.
  • EGL record of Array supports only in GET Method.
  • Currently, RBD supports the data types like Integer, Decimal, String, and Boolean for the REST Methods GET, POST, PUT, and DELETE.
  • For FLOAT fields, we should define the DECIMAL as a datatype in the EGL language.
  • The user should create a CPIH TWASIZE as 01024 with a different group id apart from DFHPIPE, which is CICS default. 

[{"Type":"MASTER","Line of Business":{"code":"LOB35","label":"Mainframe SW"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSMQ79","label":"Rational Business Developer"},"ARM Category":[{"code":"a8m0z0000000BB1AAM","label":"Rational Business Developer"}],"ARM Case Number":"","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"9.7.0"}]

Document Information

Modified date:
16 June 2022