Overriding the URIMAP in a CICS application

When a CICS® application is developed to call a RESTful service, the IBM® z/OS® Connect server that is used to process the request can be chosen at run time within the CICS application. This option allows for splitting of workloads between servers, for example, based on business area. This dynamic routing capability is available for CICS applications only.

Overview

Figure 1 illustrates how CICS applications can choose which IBM z/OS Connect server to route the request.
Figure 1. Routing requests from CICS applications
Diagram shows how two applications running in CICS can use different URIMAPs to select which IBM z/OS Connect server handles the request.

The two IBM z/OS Connect servers shown in Figure 1 can have different configurations and support different API requesters. You can still configure multiple servers with the same configuration behind shared ports for work load management.

Parameters for dynamic routing in the request

IBM z/OS Connect provides a data structure to specify the dynamic routing parameters in the request. Two versions of the data structure are provided, a COBOL version called BAQRINFO in <hlq>.SBAQCOB and a PL/I version called BAQRINFP in <hlq>.SBAQPLI.

Ensure that the communication stub request information structure is set with a compatibility level of 3 or higher. The compatibility level value is defined for COBOL by the BAQ-REQUEST-INFO-COMP-LEVEL variable and for PL/I by the BAQ_REQUEST_INFO_COMP_LEVEL variable.

The following table shows the parameters that are defined for dynamic routing. For COBOL, these parameters are defined in BAQ-REQUEST-INFO. For PL/I, these parameters are defined in BAQ_REQUEST_INFO. You can specify values for the parameters as required.
Table 1. Parameter defined for dynamic routing
Variables for COBOL Variables for PL/I Description
BAQ-ZCON-SERVER-URI BAQ_ZCON_SERVER_URI A URIMAP resource name used to route to a particular IBM z/OS Connect server. The name must be a valid URIMAP resource name of 1 - 8 characters in length. The field size is 256 characters, but this is to accommodate future enhancements.

The BAQ-ZCON-SERVER-URI field is optional. If the field is left initialized with spaces, then the default URIMAP of BAQURIMP is used to route the request. If the field is populated, the URIMAP resource name is validated and used to route the request. If there is a problem with the URIMAP resource name, or the URIMAP is unknown, unavailable, or links to an unknown host then an appropriate error message is returned and the request is not processed.

All URIMAP resources to be used must be installed in the CICS region.

Example: Developing a COBOL application to dynamically route to a IBM z/OS Connect server.

The following example demonstrates how to develop a COBOL application to dynamically route to a particular server.

In this example, the names of the generated artifacts are as follows:
  • The request copybook: API00Q01
  • The response copybook: API00P01
  • The API information file: API00I01
Include the BAQRINFO data structure.
COPY BAQRINFO
Include copybooks.

01 REQUEST.
      COPY API00Q01.
01 RESPONSE.
      COPY API00P01.
01 API-INFO.
      COPY API00I01.
Declare variables for the request and response.

01 BAQ-REQUEST-PTR             USAGE POINTER.
01 BAQ-REQUEST-LEN             PIC S9(9) COMP-5 SYNC.
01 BAQ-RESPONSE-PTR            USAGE POINTER.
01 BAQ-RESPONSE-LEN            PIC S9(9) COMP-5 SYNC.
77 COMM-STUB-PGM-NAME          PIC X(8) VALUE 'BAQCSTUB'.
Enter values for the dynamically routed request.

MOVE 'Req Data' TO Xtext.

MOVE "URIMAP11" TO BAQ-ZCON-SERVER-URI.
Prepare the data for call.

SET BAQ-REQUEST-PTR TO ADDRESS OF REQUEST.
MOVE LENGTH OF REQUEST TO BAQ-REQUEST-LEN.
SET BAQ-RESPONSE-PTR TO ADDRESS OF RESPONSE.
MOVE LENGTH OF RESPONSE TO BAQ-RESPONSE-LEN.
Call the communication stub.

CALL COMM-STUB-PGM-NAME USING
      BY REFERENCE API-INFO
      BY REFERENCE BAQ-REQUEST-INFO
      BY REFERENCE BAQ-REQUEST-PTR
      BY REFERENCE BAQ-REQUEST-LEN
      BY REFERENCE BAQ-RESPONSE-INFO
      BY REFERENCE BAQ-RESPONSE-PTR
      BY REFERENCE BAQ-RESPONSE-LEN.