Using IDL Unbounded Groups or Arrays without Maximum

This document explains how clients built with the COBOL Wrapper use IDL unbounded groups or arrays without maximum upper bounds. For illustration of IDL unbounded arrays, see Example of Arrays with Variable Upper-bounds under Software AG IDL Grammar in the IDL Editor documentation.

Usage of IDL unbounded groups or arrays without maximum is supported for:

The example below illustrates how IDL unbounded groups without maximum (/V) are used from COBOL. The client interface objects are generated from the IDL as described in Using the COBOL Wrapper (CICS with Call Interfaces | Batch | IMS). Storage allocation and pointer usage for unbounded arrays without maximum (for example (A100/V)) are the same as for unbounded groups. Both are mapped to OCCURS DEPENDING ON with keyword UNBOUNDED.

For writing the RPC client programs, the steps described Writing Standard Call Interface Clients are valid. Additionally the COBOL group on level 1 containing OCCURS DEPENDING ON with keyword UNBOUNDED originating from an IDL unbounded group or array is

  • defined in the LINKAGE SECTION. If no keyword UNBOUNDED is contained in the COBOL group on level 1, it is usually defined in the WORKING STORAGE SECTION. Compare (050) below and Step 2: Declare the Data Structures for RPC Stubs

  • allocated and freed manually, see (070) and (140) below. We strongly recommend using the IBM-specific COBOL ALLOCATE and FREE statements, because the storage is freed and reallocated inside the client interface object using same ALLOCATE and FREE statements

  • passed with a pointer to the client interface object, see (110) below.

Sample IDL Program

program 'UnboundedTables' is
        define data parameter
        1 UT-TA1             (/V)    In Out
          2 UT-FST           (A12)
          2 UT-TA2           (/V)
            3 UT-ELE         (A05)
          2 UT-LST           (A12)
        end-define

Sample COBOL RPC Client and Explanation of Statements

(010)   IDENTIFICATION DIVISION.
        PROGRAM-ID. UNBNDCLT.

        DATA DIVISION.
            . . . 
          WORKING-STORAGE SECTION.
            . . . 
(020)     01 SIZE-IN-BYTES                          PIC 9(4) BINARY.
(030)     01 ITERATION1                             PIC 9(4) BINARY.
          01 ITERATION2                             PIC 9(4) BINARY.
(040)     01 UT-TA1A-PTR                            POINTER.
            . . . 

          LINKAGE SECTION.
            . . . 
(050)       01 UT-TA1A.
             02 UT-TA1-41                           PIC 9(8) BINARY.
             02 UT-TA2-61                           PIC 9(8) BINARY.
             02 UT-TA1X OCCURS 1 TO UNBOUNDED DEPENDING ON UT-TA1-41.
              03 UT-FST                             PIC X(12).
              03 UT-TA2X OCCURS 1 TO UNBOUNDED DEPENDING ON UT-TA2-61.
               04 UT-ELE                            PIC X(5).
              03 UT-LST                             PIC X(12).
            . . . 

        PROCEDURE DIVISION.

            . . . 
      *     upper bound is 4 for UT-TA1-41 and 6 for UT-TA1-61
(060)        COMPUTE SIZE-IN-BYTES = LENGTH OF UT-FST * 4 
                                   + LENGTH OF UT-ELE * 4 * 6
                                   + LENGTH OF UT-LST * 4.
(070)        ALLOCATE SIZE-IN-BYTES CHARACTERS INITIALIZED RETURNING UT-TA1A-PTR.
(080)        SET ADDRESS OF UT-TA1A TO UT-TA1A-PTR.
(090)        MOVE 4 TO UT-TA1-41.
             MOVE 6 TO UT-TA1-61.
(100)        MOVE 0 TO ITERATION1.
             PERFORM UT-TA1-41 TIMES
                 ADD 1 TO ITERATION1
                 MOVE ... TO UT-FST(ITERATION1)
                 MOVE 0 TO ITERATION2
                 PERFORM UT-TA2-61 TIMES
                    ADD 1 TO ITERATION2
                    MOVE ... TO UT-ELE(ITERATION1 ITERATION2)
                 END-PERFORM 
                 MOVE ... TO UT-LST(ITERATION1)
             END-PERFORM.
(110)        CALL "UNBNDTAB" USING UT-TA1A-PTR ERX-COMMUNICATION-AREA.
(120)        SET ADDRESS OF UT-TA1A TO UT-TA1A-PTR.
(130)        MOVE 0 TO ITERATION1.
             PERFORM UT-TA1-41 TIMES
                 ADD 1 TO ITERATION1
                 MOVE UT-FST(ITERATION1) TO ...
                 MOVE 0 TO ITERATION2
                 PERFORM UT-TA2-61 TIMES
                    ADD 1 TO ITERATION2
                    MOVE UT-ELE(ITERATION1 ITERATION2) TO ...
                 END-PERFORM 
                 MOVE UT-LST(ITERATION1) TO ...
             END-PERFORM.
(140)        FREE UT-TA1A-PTR.
            . . . 
        END PROGRAM UNBNDCLT.

Explanation of Statements

(010)  COBOL RPC client UNBNDCLT to demonstrate IDL unbounded groups without maximum.
(020)  Variable to hold the result of the storage calculation in bytes for the COBOL structure (050).
(040)  POINTER variable to access the COBOL structure (050) describing the IDL interface (010).
(050)  COBOL structure describing the IDL interface (010) defined in LINKAGE SECTION.
(060)  Storage calculation for COBOL structure (050) assuming upper bound is 4 for UT-TA1-41 and 6 for UT-TA1-61.
(070)  Storage allocation using the calculated SIZE-IN-BYTES (060) with IBM-specific COBOL ALLOCATE statement; returned address is assigned to COBOL pointer UT-TA1A-PTR (040).
(080)  COBOL structure (050) is set to the address of the allocated storage (070).
(090)  Upper bounds are assigned to ODO objects of COBOL structure (050).
(100)  ODO subjects of COBOL structure (050) are filled with data.
(110)  Call to the client interface object; COBOL pointer UT-TA1A-PTR (040) is passed as parameter; The COBOL name of the client interface object UNBNDTAB is customized, see Customize Automatically Generated Client Names.
(120)  The client interface object may return a changed COBOL pointer UT-TA1A-PTR. So the COBOL structure (050) is set to the address returned from the client interface object.
(130)  Processing of returned data.
(140)  Storage allocated in (070) or returned by call to client interface object (110) is freed.