Configuring other z/OS applications to access IBM z/OS Connect 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

Restriction: Depending on the type of programs used, some restrictions apply to accessing IBM z/OS Connect for API calls. Consider the following restrictions before you configure your API requester communication stub:
  • IBM 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.

The IBM 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 IBM z/OS Connect server.

The load module for the communication stub must be added to the STEPLIB concatenation. In addition, the IBM 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 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.

Procedure

  1. 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.
  2. In your batch job, specify the URI and port number for the IBM z/OS Connect server in the CEEOPTS DD statement.
  3. 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 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 defined and associated with it.
    • Persistent connections are automatically enabled between the IBM z/OS Connect server and the communication stub in the non-CICS z/OS applications, which requires IBM z/OS Connect V3.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 IBM 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 IBM 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 IBM 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 batch, 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.