Configuring other z/OS applications to access z/OS Connect Server for API calls

Before your z/OS applications that are not running on CICS® or IMS can make RESTful API calls through IBM z/OS Connect, you must configure the communication stub.

About this task

zosConnect-2.0 Applies to zosConnect-2.0.

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 API requester communication stub:

z/OS Connect requires the z/OS Language Environment (LE) option POSIX(ON) for signal handling. There can be only one LE enclave, the first enclave, with POSIX(ON) per TCB. To avoid invalid configurations, specify POSIX(ON) at the application level by using CEEUOPT. If there are any nested enclaves, the main program in the nested enclave must use CEEUOPT to set POSIX(OFF).
If the first or main program for a child enclave is COBOL, CEEUOPT cannot be used to set POSIX(OFF). Child enclaves for these programs can inherit z/OS LE options only from their parent enclave, consequentially resulting in invalid configurations due to inheriting POSIX(ON) from the parent. Therefore, if you need to use nested enclaves for your program, the main program of the child enclave cannot be COBOL. To learn more about this restriction, see Child enclave has a COBOL main program in the z/OS documentation.

The z/OS Connect communication stub is a load module to configure in your z/OS system to handle the HTTP connection and communication with the z/OS Connect Server.

The load module for the communication stub must be added to the STEPLIB concatenation. In addition, the z/OS Connect Server name and port number must be specified for the communication stub. Use the CEEOPTS DD statement for the Language Environment® (LE).

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 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 Shared Memory Communications in the z/OS documentation.

Procedure

Include the load module BAQCSTUB from the hlq.SBAQLIB data set into the STEPLIB concatenation.
Use STEPLIB rather than LINKLST for library concatenation to avoid runtime issues after applying maintenance to the communication stub.
In your z/OS application, specify the URI and port number for the z/OS Connect Server in the CEEOPTS DD statement.

Note: z/OS Connect also supports the use of CEEENV to set LE environment variables dynamically. For more information, see CEEENV—Process environmental variables in the z/OS documentation.
To configure secure connections, you can use basic authentication or client certificate to authenticate your z/OS applications. For more information, see How to configure basic authentication from an IMS or z/OS application or API requester client certificate authentication to IBM z/OS Connect.
```
CEEOPTS   DD *
 POSIX(ON),
 ENVAR("BAQURI=MYSERVER.MY.COM", "BAQPORT=10053")
```
Note:
- Ensure that POSIX is set to ON to allow the Language Environment to access the UNIX System Services environment for the required HTTP-enabling services. A POSIX(ON) environment also requires the user ID associated with the address space that uses these HTTP-enabling services to have an OMVS segment that is defined and associated with it.
- Persistent connections are automatically enabled between the z/OS Connect Server and the communication stub in the non-CICS z/OS applications, which requires z/OS Connect 3.0.10 or later.
The following connection options are supported by the communication stub.

BAQPASSWORD

Specifies the password, in clear text, for the specified BAQUSERNAME to be authenticated with the z/OS Connect Server. The user name and password are used for basic authentication, when the SSL clientAuthentication attribute is set to false but the service requireSecure and requireAuth attributes are set to true.

The value cannot exceed 255 characters.

BAQPORT

Specifies the port number for the z/OS Connect Server.

BAQTIMEOUT

An optional 4-byte integer to set a timeout value in seconds for waiting for an API response. Valid range is 1 - 2,678,400 seconds. The default timeout value is 10 seconds.
Important: If CEEOPTS is specified for a message processing region, all outbound applications that run in the region use the same timeout value.

BAQURI

Specifies either an IPv4 or IPv6 address, or a hostname for the z/OS Connect Server to connect to. To configure secure connections with IMS, specify the server without the HTTPS prefix (URI scheme). You can use basic authentication or client certificate to authenticate your IMS applications.

The value cannot exceed 255 characters.

BAQUSERNAME

Specifies the user name for connections if basic authentication is used. BAQPASSWORD must be specified.

The value cannot exceed 255 characters.

BAQVERBOSE

An optional value to turn on verbose messages to assist debugging of runtime and configuration issues.
Trace messages are directed to the standard output for the application environment. By default, verbose messages are turned off.
CAUTION:
If you use the settings ON or ALL, the trace output might contain sensitive information.
Available levels and their usage are:

OFF

Turns off verbose trace messages (the default). No trace messages are produced.

ON

Turns on verbose trace messages. Most messages are written, including messages for entry, exit, errors, and auditing. To investigate any issues in the API requester stub code for IMS and z/OS applications, enable this level of trace.

ERROR

If an error occurs within the stub code, whether an internal error or by bad data being passed, messages are written to the output destination.

AUDIT

Records the entry and exit to stub and third-party libraries such as the HWT. This level is useful to track the timing of events such as entry and exit to the stub code, and timing of request and response through the HWT.

ALL

All diagnostic messages are written, including previous levels and intensive trace. This can include string conversions, setters, lookup tables, etc. This level may cause a performance impact so it is not advisable unless there is an issue in one of the areas that writes at this level.