Configure CICS to access IBM z/OS Connect to call APIs

To enable CICS® applications to call APIs through IBM z/OS Connect , enable the communication stub in the CICS region.

About this task

The IBM z/OS Connect communication stub is a module that establishes HTTP connections with the IBM z/OS Connect server, transfers data between z/OS applications and IBM z/OS Connect , and handles status and return codes that are issued by IBM z/OS Connect . Before your CICS applications can make RESTful API calls, you must configure the communication stub in your CICS region.

Tip: z/OS provides functions to optimize performance for HTTP connections. If IBM z/OS Connect and the z/OS subsystem are on the same LPAR, the fast local socket is automatically available. If IBM z/OS Connect and the z/OS subsystem are on different LPARs, you must enable the following functions:
  • HiperSocket, a zSeries hardware feature that provides high-performance internal communications between LPARs within the same central processor complex (CPC). For more information, see HiperSockets concepts and connectivity in the z/OS documentation.
  • Shared Memory Communication (SMC), which requires z/OS V2.2 or later on z13® in the same CPC. For more information, see Shared Memory Communications in the z/OS documentation.

To set up the IBM z/OS Connect communication stub in CICS, you must have the following resources in your CICS region:

A TDQUEUE resource with the name BAQQ
This resource defines the transient data queue that is used by the IBM z/OS Connect communication stub to log communication stub error messages. By default, messages are printed to DD BAQOUT in the CICS job log.
A URIMAP resource with the name BAQURIMP
This resource handles HTTP client requests from the communication stub to the IBM z/OS Connect server.
A PROGRAM resource with the name BAQCSTUB
This resource defines attributes for the IBM z/OS Connect communication stub program BAQCSTUB. By default, BAQCSTUB is defined as threadsafe.

Sample resources are supplied with IBM z/OS Connect and are provided in a CSD group with the name BAQAPIR.

It is recommended that you use the resources as supplied. Based on the topology you want to use and your CICS and IBM z/OS Connect environment, you might need to modify the attributes of the BAQURIMP resource definition.

Procedure

  1. Import the BAQAPIR CSD group into your CICS system by using the DFHCSDUP utility program.
    The supplied BAQAPIR CSD group is in the hlq.SBAQSAMP data set.
    1. Edit the job control statements that you can use to invoke DFHCSDUP. Include a DD statement that references the hlq.SBAQSAMP data set.
    2. Run the DFHCSDUP utility program.
  2. Modify the BAQURIMP URIMAP resource definition, based on the topology you want to use and system environment.
    1. Specify the host and port of IBM z/OS Connect .
      Note: The HOST attribute and the PORT attribute are mandatory attributes that you must specify based on your situation.
    2. To secure this connection with basic authentication or client authentication, see How to configure basic authentication from CICS or How to configure TLS from CICS.
    3. By default, connection pooling is enabled to keep the connection between CICS and the IBM z/OS Connect server open as a persistent connection. It is set up with the SOCKETCLOSE attribute value set to 30s, which means CICS closes the socket when the socket keeps idle for 30s.
      If needed, you can specify the SOCKETCLOSE value of 0 to disable connection pooling. For more information about connection pooling in CICS, see Connection pooling for HTTP client performance in the CICS documentation.
  3. Install the BAQQ, BAQURIMP, and BAQCSTUB resource definitions in your CICS system.
  4. Define and install a new CICS LIBRARY to include the hlq.SBAQLIB1 data set.

    You have two options to do this:

    • Add a DD statement that references the hlq.SBAQLIB1 data set in the CICS static load LIBRARY concatenation, DFHRPL.

      Note that when CICS is running, changes to DFHRPL are not possible without stopping and restarting CICS.

    • Use a dynamic LIBRARY concatenation to add the load library to CICS.
  5. Setting timeout for CICS to send a request to and receive the response from the IBM z/OS Connect server.

    The IBM z/OS Connect communication stub uses CICS web API to communicate with the IBM z/OS Connect server. You can specify DTIMOUT on the TRANSACTION definition to control the timeout of sending a request to IBM z/OS Connect and specify RTIMOUT on the PROFILE definition to control the timeout of waiting a response from IBM z/OS Connect . For more information, see WEB CONVERSE in the CICS documentation.

    Note: Set the same timezone settings for IBM z/OS Connect and the z/OS Application invoking the RESTful API using the API requester feature. Set timezone settings using the TZ environment variable in the STDENV JCL procedure. For more information on TZ settings, refer to: z/OS Command Format.