Configure CICS to access 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

zosConnect-2.0 Applies to zosConnect-2.0.

The z/OS Connect communication stub is a module that establishes HTTP connections with the z/OS Connect server, transfers data between z/OS applications and z/OS Connect, and handles status and return codes that are issued by 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 z/OS Connect and the z/OS subsystem are on the same LPAR, the fast local socket is automatically available. If 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 A launch icon to indicate a link opens a new tab or window. HiperSockets concepts and connectivity in the z/OS documentation.
  • Shared Memory Communication (SMC), which requires z/OS 2.2 or later on z13® in the same CPC. For more information, see A launch icon to indicate a link opens a new tab or window. Shared Memory Communications in the z/OS documentation.

To set up the 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 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 z/OS Connect Server.
A PROGRAM resource with the name BAQCSTUB
This resource defines attributes for the z/OS Connect communication stub program BAQCSTUB. By default, BAQCSTUB is defined as threadsafe.

Sample resources are supplied with 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 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 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 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 A launch icon to indicate a link opens a new tab or window. Connection pooling for HTTP client performance in the CICS Transaction Server for z/OS 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. 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 z/OS Connect Server.

    The z/OS Connect communication stub uses CICS web API to communicate with the z/OS Connect server. You can specify DTIMOUT on the TRANSACTION definition to control the timeout of sending a request to z/OS Connect and specify RTIMOUT on the PROFILE definition to control the timeout of waiting a response from z/OS Connect. For more information, see A launch icon to indicate a link opens a new tab or window. WEB CONVERSE in the CICS Transaction Server for z/OS documentation.

    Note: Set the same timezone settings for z/OS Connect and the z/OS Application invoking the RESTful API by 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: A launch icon to indicate a link opens a new tab or window. z/OS Command Format in the z/OS documentation.