Creating an IMS LDS z/OS Asset

Understand the considerations involved when creating an IMS large data structure (LDS) z/OS Asset.

Before you begin

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

Ensure that z/OS Connect Designer is running as described in Starting the z/OS Connect Designer with Docker Desktop and importing an OpenAPI definition and that the flow diagram for your API is displayed.

An IMS z/OS Asset describes the formats of the request and response data structures from an IMS program, and specific characteristics such as the codepage, transid, and transid usage.

See the instructions in Creating a z/OS Asset to add a z/OS Asset in the z/OS Connect Designer and display the Operation flow diagram as shown in Figure 1.

Figure 1. Add z/OS Asset button locations
Screen capture to show the Add z/OS Asset button locations in z/OS Connect Designer.

About this task

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.

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 use these sample utilities, your IMS COBOL applications 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.

Procedure

  1. Click Add new z/OS Asset then Next.
    Figure 2. Selecting a new or existing z/OS Asset
    Screen capture to show how to select a new or existing z/OS Asset in the Add z/OS Asset menu option.
  2. Click Choose an option to expand the list, and click IMS large data structure transaction.
  3. Input the mandatory IMS z/OS Asset information.
    1. Select the Program language.
    2. Input the IMS transaction name.
    3. Select an IMS Connection from available connections. Click Next once complete
      For more information on how to connect to IMS, see Configuring a z/OS Connect zosConnect-3.0 connection to IMS.
      Figure 3. Specify IMS connection information
      Screen capture to show adding the IMS connection information when created a new IMS z/OS Asset.

      The mandatory fields that are needed for the z/OS Asset are complete. If you do not need the optional configuration, click Next and go to step 4.

  4. Define request LDS for your IMS program.
    Figure 4. Select a data structure to import
    Screen capture to show how to import a data structure for the IMS z/OS Asset request.
    1. Click Import data structure.
    2. Select a file or drag and drop a copybook, COBOL, or PL/I file.
      Figure 5. Choosing a file to import
      Screen capture to show how to add the file with which you want to import your IMS LDS response data structure
      Note:

      When you import a COBOL structure, you must add a file extension (.cop, .cob, .ccp, .cpy). Files with extensions .cop, .cob, and .ccp are treated as complete programs. Files with a .cpy extension are treated as a copybook.

      When you import a PL/I structure, you must add a file extension (.pli , .inc). Files with the extension .pli are treated as complete programs. Files with .inc extensions are treated as include files.

    3. Select the data structures that you want to include in your request LDS and click the Add.
      Figure 6. Selecting data request LDS data structures
      Screen capture to show how to select data for the request IMS LDS data structures.
    4. Review your request LDS data structure then click Next.
      Figure 7. The IMS z/OS Asset request LDS
      Screen capture to show the IMS request LDS.
  5. Define your response LDS data structure for your IMS program.
    Figure 8. IMS LDS response
    Screen request to show the step in the Add z/OS Asset to add the response IMS message
    To build your response LDS, complete one of the following steps:
    • Repeat the same actions as described in Step 6 to build the response LDS structure.
    • Click Replicate request structure.
    Figure 9. Populated response LDS
    Screen capture to show the populated response IMS message.
  6. Input z/OS Asset name.
    Figure 10. The z/OS Asset name
    Screen capture to show step 5 or 5 to Add a z/OS Asset. Add the name of the z/OS Asset to be created.
  7. Optional: Input z/OS Asset description.
  8. Review the z/OS Asset and click Add z/OS Asset.
    Figure 11. Add the z/OS Asset
    Screen capture to show how the Add z/OS Asset wizard displays a summary of the name and description for the user to review before they click add.

Results

You now have an IMS LDS z/OS Asset for use in your API project.

Figure 12. The new z/OS Asset
Screen capture to show the newly created IMS LDS z/OS Asset with details such as Name, Description, Type, Transaction code, Program language and Connection profile.