Creating a CICS COMMAREA z/OS Asset

Understand the considerations involved when creating a CICS COMMAREA z/OS Asset.

Before you begin

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.

A CICS z/OS Asset describes the formats of the request and response data structures from a CICS program, and specific characteristics such as the CCSID, 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 in the Operation Viewer as shown in Figure 1.

Figure 1. Add z/OS Asset button locations.
Add z/OS Asset button locations.

Procedure

  1. Click Add new z/OS Asset then Next.
    Figure 2. Selecting a new or existing z/OS Asset.
    Selecting a new or existing z/OS Asset.
  2. Click Choose an option.
    Figure 3. Selecting the type of z/OS Asset.
    Selecting the type of z/OS Asset.
  3. Expand the list and click CICS COMMAREA program.
  4. Input the mandatory CICS z/OS Asset information.
    1. Input the CICS program name.
    2. Select the Program language.
    3. Input the CCSID.

      Specifies the CCSID that is used at run time to encode character data in application data structures.

    4. Select a CICS Connection from available connections.
      For more information on how to connect to CICS, see Configuring an IPIC connection to CICS.
      Figure 4. CICS z/OS Asset mandatory input.
      CICS z/OS Asset mandatory input.

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

  5. Optional: Input the optional CICS z/OS Asset information.
    1. Input Transaction ID.

      Specifies the CICS transaction name. The Transaction ID value specifies how the transaction ID value is used. If this parameter is not specified, the Transaction ID value in the connection is used.

    2. Select Transaction ID usage.
      Specifies how the transaction ID value is used. Valid values are EIB_ONLY and EIB_AND_MIRROR. If this value is not specified, the Transaction ID usage value in the connection is used.

      Optional fields are now complete. Click Next.

  6. Define request COMMAREA for your CICS program.
    Figure 5. Select a data structure to import.
    An empty CICS Request COMMAREA.
    1. Click Import data structure button.
    2. Select a file or drag and drop a copybook, COBOL, or PL/I file.
      Figure 6. Choosing a file to import.
      Choosing a file to import.
      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 you wish to include in your request COMMAREA and click the Add button.
      Figure 7. Selecting data request COMMAREA data structures.
      Selecting data request COMMAREA data structures.
    4. Review your Request COMMAREA then click Next.
      Figure 8. The CICS z/OS Asset Request COMMAREA.
      The CICS z/OS Asset Request COMMAREA.
  7. Define response COMMAREA for your CICS program.
    Figure 9. CICS COMMAREA response.
    CICS COMMAREA response.
    1. To build your response COMMAREA either:
      • Repeat the same actions as described in Step 6 to build the response COMMAREA structure.
      • Click the Replicate request structure button.
    2. Click Next.
      Figure 10. Populated response COMMAREA.
      Populated response COMMAREA.
  8. Input z/OS Asset name.
    Figure 11. The z/OS Asset name.
    The z/OS Asset name.
  9. Optional: Input z/OS Asset description.
  10. Review the z/OS Asset and click Add.
    Figure 12. Add the z/OS Asset.
    Add the z/OS Asset.

Results

You now have a CICS COMMAREA z/OS Asset for use in your API project.

Figure 13. The newz/OS Asset for use.
The new z/OS Asset for use.