Configuring IMS to access IBM z/OS Connect to call APIs

This section provides details on how to enable IMS applications to call APIs by using the z/OS Connect.

zosConnect-3.0 Applies to zosConnect-3.0.

When calling a REST API from IMS using z/OS Connect Host API, the communication channel from IMS to z/OS Connect must be configured. The z/OS Connect Host API supports two alternative mechanisms to communicate with the z/OS Connect Server from IMS and you must chose the one that best suits your needs. The two options use the following IBM® z/OS and IBM IMS services:

  • z/OS client web enablement toolkit's HTTP/HTTPS protocol enabler (referred to as Web toolkit in the rest of the section)
  • IMS Transaction Manager (TM) Resource Adapter

z/OS client web enablement toolkit

The z/OS client web enablement toolkit provides a set of application programming interfaces (APIs) to enable traditional, z/OS programs to participate in API-enabled applications.

Typically, the Web toolkit mechanism is chosen to communicate with z/OS Connect. It provides a simple and direct route from an IMS application to z/OS Connect using HTTP or HTTPS. However, the Web toolkit does mandate the Language Environment is configured with POSIX(ON) in the first TCB Enclave to enable signal handling, which is employed by the Web toolkit. This configuration option might cause issues with some IMS application configurations.

Figure 1. Overview of the z/OS client web enablement toolkit architecture
Illustration displaying the overview of the z/OS client web enablement toolkit

The z/OS client web enablement toolkit provides support for HTTP/HTTPS connections over SSL. For more information on the z/OS HTTP/HTTPS protocol enabler, see A launch icon to indicate a link opens a new tab or window. z/OS HTTP/HTTPS callable services in the z/OS documentation.

For more information on web enablement toolkit, see A launch icon to indicate a link opens a new tab or window. z/OS client web enablement toolkit in the z/OS documentation.

IMS Transaction Manager (TM) Resource Adapter

To overcome the POSIX(ON) restriction, a second communication mechanism is supported by using IMS Connect and IMS TM Resource Adapter to call z/OS Connect. This mechanism has the advantage that POSIX(ON) is not a required configuration, but the communication path is more complicated. The z/OS Connect Host API uses the IMS ICAL SENDRECV verb to send and receive a request using IMS OTMA services that stores an outgoing message in an Open Transaction Manager Access (OTMA) protocol Transaction Pipe (TPipe). IMS Connect is instructed by the IMS TM Resource Adapter running in the z/OS Connect Server to monitor the TPipe for messages. After one is received, IMS Connect reads the TPipe and sends the message to the IMS TM Resource Adapter, which calls z/OS Connect Message Driven Bean (called ConnectMDB). ConnectMDB then calls z/OS Connect using a local host HTTP/HTTPS connection. The response is returned in a similar manner.

Figure 2. Overview of the IMS TM Resource Adapter architecture
Illustration displaying the overview of the IMS TM Resource Adapter

For more information about IMS TM Resource Adapter, see A launch icon to indicate a link opens a new tab or window. IMS Transaction Manager Resource Adapter in the IBM Information Management System (IMS) documentation.

Restriction: Depending on the type of programs used, some restrictions apply to accessing z/OS Connect for API calls. Consider the following restrictions before you configure your z/OS applications to use the Host API:
  • Use of the RTEREUS (COBOL only) option has multiple restrictions, and should not be used in this context. To learn more, see A launch icon to indicate a link opens a new tab or window. RTEREUS (COBOL only) in the z/OS documentation.

    Pre-loading the Message Processing Program (MPP) can make the COBOL program work with RTEREUS(ON) as a last resort. While unsupported, this technique might offer you a temporary work around to use RTEREUS(ON).

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 V2.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.