Handling large IMS data structures

IMS message segments have a size limit of 32 KB (32,767 bytes). If your application programs contain large data structures, the transaction must handle the decomposition of the large data structure into multiple segments, each within the 32 KB limit and then assemble multiple segments on the response.

zosConnect-2.0 Applies to zosConnect-2.0.

IMS transactions that are defined as MSGTYPE=(MULTSEG) are eligible to handle large IMS data structures. In existing IMS transactions, segmentation is most likely already implemented by GU and GN calls to process request messages that are larger than 32 KB. Segmentation refers to the process of decomposing a large data structure into multiple segments so each IMS message segment is within the 32 KB restriction. For response messages, de-segmentation is most likely implemented by multiple ISRT calls. The term de-segmentation refers to the process of assembling multiple segments for an IMS transaction message that contains a large data structure.

If your transaction already handles segmentation and de-segmentation of large data structures, no change is needed. If it does not, sample utilities are provided that your application can invoke instead of interacting with the IMS message queue directly. The sample utilities, BAQGETS and BAQSETS for COBOL, and BAQPGETS and BAQPSETS for PL/I, handle the segmentation and de-segmentation of large data structures by using a temporary storage in the message processing region.

To create a service from an IMS program with large data structures, in z/OS® Connect API toolkit, select IMS Large Data Structure Service as the project type. If you select IMS Service as the service type, the entire data structure would be imported into the first segment.

Important: By default, imported IMS large data structures are not expected to begin with an LLZZ or LLZZ<TRANCODE> prefix fields.
  • If large data structures do begin with LLZZ or LLZZ<TRANCODE> prefix fields, you must enable options in the Advanced Service Data Conversion Options dialog menu to support these fields. To open this dialog, go to the Definition tab of the Service Project Editor and click Advanced Options. To learn more about these options, see Service-level data conversion customization.
  • The advanced data conversion options allowing IMS large data structure services to support LLZZTRANCODE fields requires installation of the minimum IBM® z/OS Connect server and API toolkit versions that support this capability. To learn more about IBM z/OS Connect version requirements for the IMS large data structure support capabilities, see IBM z/OS Connect capabilities compatibility.
The following diagram demonstrates how a large IMS data structure in COBOL programs is processed. For PL/I, the process is the same except for the utility and sample names are different.
Figure 1. Handling large IMS data structure with the COBOL BAQGETS and BAQSETS utilities
This diagram shows how the BAQGETS and BAQSETS utilities are called to retrieve request structure from and write response structure to the IMS Message Queue and perform de-segmentation and segmentation.
To leverage these sample utilities, your IMS COBOL applications would invoke the supplied sample utilities BAQGETS and BAQSETS instead of interacting with the IMS message queue directly. IMS PL/I applications would invoke the supplied sample utilities BAQPGETS and BAQPSETS instead of interacting with the IMS message queue directly.
  1. BAQGETS/BAQPGETS performs de-segmentation by reading the large data structure from the IMS message queue.
  2. BAQGETS/BAQPGETS writes the de-segmented request structure to the temporary storage.
  3. BAQSETS/BAQPSETS performs segmentation by reading from the storage.
  4. BAQSETS/BAQPSETS writes the segmented response structure to the IMS message queue
To demonstrate detailed usage of these utilities, a sample COBOL IMS transaction BAQLDS and a sample PL/I IMS transaction BAQPLDS are provided. These utilities and the samples are provided in the SBAQSAMP data set. Two JSON documents for use with the samples are available in the <installation_path>/samples/imslds directory. Use a text editor to view the sample JSON documents.
  • requestBody.json is the request JSON to use to invoke the service that you create from the supplied BAQLDSC and BAQPLDSI copybooks. The copybooks contain comments that describe the data structure to select for input and output when you create the transaction metadata for your service in the z/OS Connect API toolkit. Increase or decrease the number of IO_RECORD array objects to change the size of the data structure sent to and received from IMS.
  • responseBody.json is the expected response JSON from your service that invokes the BAQLDS and BAQPLDS sample programs. The property I_TEXT_OK in the response indicates whether the JSON request body was converted correctly (Y) or not (N) based on what BAQLDS or BAQPLDS expects.
Important: When the structure's maximum length does not exceed 32 KB, do not use the BAQGETS, BAQSETS, BAQPGETS, or BAQPSETS sample utility. Use CBLTDLI or CEETDLI instead.

The following table lists the COBOL samples and utilities that are provided in the SBAQSAMP data set.

Table 1. COBOL samples and utilities for large IMS data structure support in the SBAQSAMP data set
Member name Source type Description
BAQLDS COBOL Sample IMS transaction that demonstrates usage of the BAQGETS and BAQSETS utilities. This transaction must be defined to IMS with MSGTYPE(MULTSEG).
BAQLDSC COBOL Copybook for the BAQLDS sample transaction. Import this copybook into the service interface editor in z/OS Connect API toolkit.
BAQGETS COBOL Sample utility that reads a large data structure from the IMS message queue and performs de-segmentation by getting each segment using CBLTDLI.
BAQSETS COBOL Sample utility that writes a large data structure to the IMS message queue by performing segmentation and inserting each segment using CBLTDLI.
BAQGETSJ JCL Sample JCL for building BAQGETS.
BAQSETSJ JCL Sample JCL for building BAQSETS.
BAQLDSJ JCL Sample JCL for building BAQLDS. BAQGETS and BAQSETS must be built before running this JCL to build the BAQLDS sample.

The following table lists the PL/I samples and utilities that are provided in the SBAQSAMP data set.

Table 2. PL/I samples and utilities for large IMS data structure support in the SBAQSAMP data set
Member name Source type Description
BAQPLDS PL/I Sample IMS transaction that demonstrates usage of the BAQPGETS and BAQPSETS utilities. This transaction must be defined to IMS with MSGTYPE(MULTSEG).
BAQPLDSI PL/I Include for the BAQPLDS sample transaction. Import this copybook into the service interface editor in the z/OS Connect API toolkit.
BAQPGETS PL/I Sample utility that reads a large data structure from the IMS message queue and performs de-segmentation by getting each segment using CBLTDLI.
BAQPSETS PL/I Sample utility that writes a large data structure to the IMS message queue by performing segmentation and inserting each segment using CBLTDLI.
BAQPGETJ JCL Sample JCL for building BAQPGETS.
BAQPSETJ JCL Sample JCL for building BAQPSETS.
BAQPLDSJ JCL Sample JCL for building BAQPLDS. BAQPGETS and BAQPSETS must be built before running this JCL to build the BAQPLDS sample.

The following table lists the content of the <installation_path>/samples/imslds directory.

Table 3. Samples for large IMS data structure support in the <installation_path>/samples/imslds directory
Member name Source type Description
requestBody.json JSON Sample request JSON body for services based on the BAQLDS and BAQPLDS sample IMS transaction programs. Increase or decrease the number of IO_RECORD array objects to change the size of the data structure sent to and received from IMS.
requestBody.json JSON Sample response JSON body for services based on the BAQLDS and BAQPLDS sample IMS transaction programs.