CICS with DFHCOMMAREA Calling Convention - In different to Out

This document describes using the COBOL Mapping Editor to extract from a CICS DFHCOMMAREA program where COBOL output parameters are different to COBOL input parameters, that is, the DFHCOMMAREA on output is overlaid with a data structure that is different to the data structure on input.

graphics/map-diff-dfh.png


Introduction

Depending on the programming style used in the CICS program and the various different techniques for accessing the CICS DFHCOMMAREA interface, finding the relevant COBOL data structures can be a complex and time-consuming task that may require CICS COBOL programming knowledge. Note the following:

  • A CICS program does not require a PROCEDURE DIVISION header, where parameters are normally defined. See PROCEDURE DIVISION Mapping.

  • The DFHCOMMAEA can be omitted in the linkage section.

  • If there is no DFHCOMMAREA in the linkage section or no PROCEDURE DIVISION header present in the PROCEDURE DIVISION, the CICS preprocessor completes the interface of the COBOL server and adds a DFHCOMMAREA and a PROCEDURE DIVISON header to the CICS program before compilation.

If you have selected an IDL file and opened the COBOL Mapping Editor with an existing COBOL to IDL mapping, continue with Mapping Editor User Interface.

Extracting from a CICS DFHCOMMAREA Program

This section assumes Input Message same as Output Message is not checked. COBOL output and COBOL input parameters are different, that is, the DFHCOMMAREA on output is overlaid with a data structure that is different to the data structure on input. See the examples provided under Programming Techniques.

If you are extracting IDL from a COBOL source or extending the IDL file by extracting an additional COBOL source with interface type CICS with DFHCOMMAREA calling convention, the Extractor Settings dialog appears (see also Step 4: Define the Extraction Settings and Start Extraction).

Make sure the interface type is correct and check box Input Message same as Output Message is cleared.

graphics/map-diff-dfh_extract.png

Press Next to open the COBOL Mapping Editor.

Start of instruction setTo select the COBOL interface data items of your COBOL server

  1. Add the COBOL data items of the CICS input message to Input Message by using the context menu or toolbar available in the COBOL Source View and COBOL Interface. See Notes.

  2. Add the COBOL data items of the CICS output message to Output Message by using the context menu and toolbars available in the COBOL Interface and IDL Interface. See Notes.

  3. Continue with COBOL to IDL Mapping.

Notes:

  1. If a DFHCOMMAREA is present, the DFHCOMMAREA COBOL data item itself cannot be selected. In this case, select the COBOL data items directly subordinated to DFHCOMMAREA and map to IDL. See Map to.
  2. It is very important to select the right COBOL data items describing the COBOL interface correctly. This means the COBOL data items used as parameters must match in number and in sequence of formats (COBOL usage clause).
  3. If your COBOL interface contains REDEFINEs, the first REDEFINE path is offered by default. Check manually whether this is the one you want. If not, correct it. You can select any other REDEFINE path.

The user interface of the COBOL Mapping Editor is described below.

Mapping Editor User Interface

This section assumes you have set the extraction settings as described above. The following areas of the COBOL Mapping Editor user interface are described here:

For COBOL interface types where COBOL input and COBOL output parameters are different, the user interface of the COBOL Mapping Editor looks like this:

graphics/map-diff-dfh_interface-small-1.png COBOL Program Selection. Currently selected program with interface type graphics/toc_closed.png More info
graphics/map-diff-dfh_interface-small-2.png COBOL Source View. Contains all related sources for the currently selected COBOL program graphics/toc_closed.png More info
graphics/map-diff-dfh_interface-small-3.png COBOL to IDL Mapping. Tree view of your selected COBOL data items and mapping buttons with which you can map these items to your IDL interface graphics/toc_closed.png More info

COBOL Program Selection

graphics/map-diff-dfh_interface_prog.png

The COBOL Program Selection displays the current selected COBOL program with its interface type. If you have extracted more than one COBOL program within the associated IDL file, you can switch to another COBOL program with its mapping by selecting the name in the combo box.

COBOL Source View

graphics/map-diff-dfh_interface_source.png

All COBOL data items contained in the LINKAGE and WORKING-STORAGE SECTION are offered in a text view for selection. The text view contains all related sources (including copybooks) for the currently selected COBOL program. It is used for selecting data items and retrieving information from the original COBOL sources. The light green bar indicates that the data item is already contained in the COBOL Interface; a dark green bar indicates the data item is selectable and can be added to the COBOL Interface. This section can be collapsed. If you open the Editor with Modify Interface it is collapsed by default. The toolbar provides the following actions:

graphics/icon_addToInterface-in.gif Add selected COBOL data item to COBOL Interface as Input Message.
graphics/icon_addToInterface-out.gif Add selected COBOL data item to COBOL Interface as Output Message.
graphics/icon_removeFromInterface.gif Remove selected COBOL data item from COBOL Interface.
graphics/icon_removeAllFromInterface.gif Remove all COBOL data items from COBOL Interface.
graphics/icon_restoreDefault.gif Reset COBOL Interface to initial state.
graphics/icon_settings.gif Show dialog to modify COBOL Source Characteristics. Not available for interface type COBOL Converter.
graphics/icon_search.gif Show dialog to find text in Source.

The same functionality is also available from the context menu.

COBOL to IDL Mapping

This section covers the following topics:

COBOL Interface

The COBOL Interface shows a tree view of your selected COBOL data items describing the interface of the COBOL server. A context menu is available for the COBOL data items, which provides mapping and other functions. On some COBOL data items, decision icons indicate where particular attention is needed, including mapping icons to visualize the COBOL data type and your current mapping.

The COBOL data item names are derived from the COBOL source from which they were extracted. If your COBOL interface contains parameters without a name (for example, the keyword FILLER is used) those COBOL data items are shown as [FILLER]. See FILLER Pseudo-Parameter.

graphics/map-diff-dfh_interface_cob2idl_cob.png

You can modify the COBOL interface using context menu or toolbar; decision and mapping icons provide additional information.

Context Menu

The context menu on COBOL data items provides the following mapping and other functions, depending on the data item type, the COBOL level and the current mapping.

Map to A suppressed COBOL data item becomes visible in the IDL interface. Used also to select another REDEFINE path.
Suppress Suppress unneeded COBOL data items.
Set Constant Set COBOL data items to constant.
Set Array Mapping Map an array to a fixed sized or unbounded array.
Set Multiple Possible Output (MPO) Structures Set COBOL data items where the server program decides the output structure used on return. Specify the set of multiple possible output (MPO) structures and the criteria when a structure is used.
Map to Binary Map a COBOL data item as IDL parameter of type binary (Bn, BV) to exchange binary data (for example images). See Map to Binary and Revert Binary Mapping under Mapping Editor IDL Interface Mapping Functions.
Revert Binary Mapping Undo the Map to Binary operation and use the standard mapping.
Remove from COBOL Interface Remove the data item from the COBOL interface. This also removes the mapped IDL parameter from all IDL interfaces for the current COBOL program. See COBOL Program Selection.

See also Mapping Editor IDL Interface Mapping Functions.

Toolbar

The toolbar offers the following actions:

graphics/icon_plus.gif Create IDL Interface. Creates a new IDL interface based on the current COBOL interface: all IDL parameters are of IDL direction InOut; no IDL parameters are set to constant; for COBOL REDEFINE, the first REDEFINE path is mapped to IDL; FILLERs are suppressed according to your selection, see Step 4: Define the Extraction Settings and Start Extraction.
graphics/icon_duplicate.gif Copy current IDL Interface. Creates a duplicate of the current IDL interface: all modifications such as IDL directions, suppress, selection of REDEFINE paths etc. are kept.
graphics/icon_remove.gif Remove current IDL Interface.
graphics/icon_rename.gif Rename current IDL Interface.
graphics/icon_expand.png Expand the full tree.
graphics/icon_collapse.png Collapse the full tree.

See also Map to Multiple IDL Interfaces.

Decision Icons

The decision icons in the first column are set on COBOL data items where particular attention is needed:

graphics/icon_decisionRedefine.png This icon visualizes a COBOL REDEFINE. It is essential that you map the correct redefine path for your mapping to In, Out or InOut using the context menu. If you map a REDEFINE path, all other sibling REDEFINE paths are automatically set to "Suppress".
Mapping Icons

The following mapping icons on the COBOL data items indicate your current IDL mapping:

graphics/icon_in.png Scalar parameter, mapped to In.
graphics/icon_out.png Scalar parameter, mapped to Out.
graphics/icon_group-in.png Group parameter, here mapped to In.
graphics/icon_redefine-out.png REDEFINE parameter, here mapped to Out.
graphics/icon_constant.png Parameter set to Constant.

Mapping Buttons

The following buttons are available:

graphics/map-diff-dfh_interface_cob2idl_buttons.png

Map to  ->

A suppressed COBOL data item becomes visible in the IDL interface. Used also to select another REDEFINE path.

Suppress

See Suppress Unneeded COBOL Data Items.

Set Constant...

See Set COBOL Data Items to Constants.

IDL Interface

If you have mapped the COBOL interface to multiple IDL interfaces, select the IDL interface by choosing the tabs. In the IDL Interface tree view, a context menu is also available with the following possibilities:

  • Rename the IDL parameter.

  • Remove from COBOL Interface. This also removes the mapped IDL parameter from all IDL interfaces for the current COBOL program. See COBOL Program Selection above.

graphics/map-diff-dfh_interface_cob2idl_idl.png

Mapping Editor IDL Interface Mapping Functions

This section covers the following topics:

Map to

With the Map to functions you make a COBOL data item visible as an IDL parameter in the IDL interface, that is, you design the IDL interface by defining input and output parameters.

Start of instruction setTo map COBOL data items to IDL interface

  1. Go step-by-step through all top-level COBOL data items in the COBOL interface and use the Map to function available in the context menu of the COBOL interface and as mapping button to make a COBOL data item visible as an IDL parameter in the IDL interface:

    graphics/idlFunctions_mapTo.png

  2. Do the same for the output message of the COBOL interface.

Notes:

  1. If a COBOL group is mapped, all subordinate COBOL data items are also made visible in the IDL interface.
  2. With the inverse function Suppress Unneeded COBOL Data Items (see below) available in the context menu of the COBOL interface and as mapping button, a COBOL data item can be removed from the IDL interface.

Map OCCURS DEPENDING ON

You can make the COBOL ODO subject (here COBOL data item TABLE) of a variable-sized COBOL table (see COBOL Tables with Variable Size - DEPENDING ON Clause) visible as an IDL unbounded group (with maximum). The ODO object (here COBOL data item COUNTER-1) is suppressed and therefore not part of the IDL interface. This is because the number of elements of the IDL unbounded group is already implicitly available. See the following example:

01 COUNTER-1 PIC 99.
01 TABLE OCCURS 1 TO 10 DEPENDING ON COUNTER-1
 02 FIELD1 PIC XX.
 02 FIELD2 PIC 99.

Start of instruction setTo map OCCURS DEPENDING ON

  • Add the COBOL subject (here data item TABLE) and ODO object (here data item COUNTER-1) to the input message or to the output message, wherever they belong. It is important both data items are always together per message direction (input or output).

    graphics/idlFunctions_odo-diff.png

Notes:

  1. The ODO subject can be mapped to the IDL interface.
  2. The ODO object is always suppressed, but is required to be part of the same message direction (Input Message or Output Message) of the COBOL interface.
  3. IDL directions are described in the direction-attribute in attribute-list under Software AG IDL Grammar in the IDL Editor documentation.

Map to Multiple IDL Interfaces

Assume the COBOL server program provides multiple functions or operations, in the following example ADD, SUBRACT, MULTIPLY. Some dispatcher front-end code executes the correct function, for example, depending on a function-code or operation-code parameter:

graphics/map-common_idlFunctions_multiple.png

COBOL snippet: The execution of the different functions ADD, SUBTRACT, MULTIPLY is controlled by the COBOL data item OPERATION. The contents of this decide on the function executed:

. . .

     01 OPERATION                      PIC X(1).
     01 OPERAND1                       PIC S9(9) BINARY.
     01 OPERAND2                       PIC S9(9) BINARY.
     01 FUNCTION-RESULT                PIC S9(9) BINARY.
     . . .
     MOVE 0 TO FUNCTION-RESULT.
     EVALUATE OPERATION
         WHEN "+"
            ADD OPERAND1 OPERAND2
            GIVING FUNCTION-RESULT
         WHEN "-"
            SUBTRACT OPERAND2 FROM OPERAND1
            GIVING FUNCTION-RESULT
         WHEN "*"
            MULTIPLY OPERAND1 BY OPERAND2
            GIVING FUNCTION-RESULT
         WHEN . . .

     END-EVALUATE.
. . .

If you have such a situation, a good approach is to expose each COBOL server program function separately as an IDL program. This gives advantages in further processing. See the following examples, depending on your target endpoint:

  • Integration Server
    Instead of having a single adapter service for the EntireX Adapter generated with the Integration Server Wrapper, you have separate adapter services, one for each COBOL function.

  • Web service
    Instead of having a Web service with a single operation generated with the Web Services Wrapper, you get a web service with multiple operations, one operation for each COBOL function.

  • DCOM, Java or .NET
    Instead having a class with a single method generated with the respective wrapper (DCOM | Java | .NET) you get a class with multiple methods, one method for each COBOL function.

Start of instruction setTo map a COBOL interface to multiple IDL interfaces

  1. Select the tab with COBOL to IDL Mapping. For each function, define a separate IDL interface with the toolbar functions graphics/icon_plus.gif or graphics/icon_duplicate.gif:

    graphics/idlFunctions_multiple-diff-1.png

  2. Give the IDL interfaces meaningful names with the toolbar function graphics/icon_rename.gif:

    graphics/idlFunctions_multiple-diff-2.png

  3. Define the required constant values to the function-code or operation-code parameter, see Set COBOL Data Items to Constants above:

    graphics/idlFunctions_multiple-diff-3.png

For the delivered Example 1: COBOL Server with Multiple Functions:

  • First, for step 1 above: Extract and define 3 separate IDL programs ADD, SUBTRACT, MULTIPLY.

  • Second, for step 2 above: Rename them to suitabable names, e.g. 'ADD', 'SUBTRACT', 'MULTIPLY'.

  • Third, for step 3 above: Define the constants '+', '-' and '*' to the parameter OPERATION respectively.

  • Press Finish to create the following IDL together with a server mapping file. See Server Mapping Files for COBOL.

    library 'EXAMPLE' is
    
     program 'ADD' is
      define data parameter
       1 OPERAND1 (I4) In
       1 OPERAND2 (I4) In
       1 FUNCTION-RESULT (I4) Out
      end-define
    
     program 'SUBTRACT' is
      define data parameter
       1 OPERAND1 (I4) In
       1 OPERAND2 (I4) In
       1 FUNCTION-RESULT (I4) Out
      end-define
    
     program 'MULTIPLY' is
      define data parameter
       1 OPERAND1 (I4) In
       1 OPERAND2 (I4) In
       1 FUNCTION-RESULT (I4) Out
      end-define
    

Notes:

  1. The following functions are offered to create further mappings from the COBOL interface, resulting in multiple IDL interfaces (IDL programs).
    Icon Function Description
    graphics/icon_plus.gif Create IDL Interface Creates a new IDL interface based on the current COBOL interface. All IDL parameters are of IDL direction InOut; no IDL parameters are set to constant; for COBOL REDEFINE, the first REDEFINE path is mapped to IDL; FILLERs are suppressed according to your selection, see Step 4: Define the Extraction Settings and Start Extraction.
    graphics/icon_duplicate.gif Copy current IDL Interface Creates a duplicate of current IDL interface. All modifications such as IDL directions, suppress, selection of REDEFINE paths etc. are kept.
    graphics/icon_rename.gif Rename current IDL Interface The default name for the IDL interface is based on the COBOL program name plus appended number. With this function you can give the IDL interface a suitable name.
    graphics/icon_remove.gif Remove current IDL Interface Deletes the current IDL interface.
  2. With the steps 1 thru 3 described here you can emulate the behavior of function Map to Operation of EntireX version 9.6 and earlier.

Select REDEFINE Paths

For COBOL server programs containing COBOL REDEFINEs, the correct REDEFINE path needs to be chosen for the IDL interface.

Start of instruction setTo select redefine paths

  • Use the Map to function available in the context menu of the COBOL interface and as mapping button to make the COBOL REDEFINE path available in the IDL interface.

    graphics/idlFunctions_redefine-diff.png

    Begin with the COBOL REDEFINE defined at the highest level first. Work through all inner COBOL REDEFINE data items, going from higher levels to lower levels.

Notes:

  1. Only one REDEFINE path of a COBOL REDEFINE can be mapped to the IDL interface. All COBOL REDEFINE siblings are suppressed.
  2. If a REDEFINE path is actively mapped to the IDL interface, all COBOL REDEFINE siblings are suppressed.
  3. You can suppress all REDEFINE paths of a COBOL REDEFINE. Simply suppress the active REDEFINE path, see Suppress Unneeded COBOL Data Items above.

Suppress Unneeded COBOL Data Items

COBOL data items without any relevant information can be made invisible in the IDL interface. The IDL interface is simplified - it becomes shorter and tidier. This is useful, for example

  • for FILLER data items

  • if the consuming RPC client or IS service does not need an Out parameter

  • if the COBOL data item is an In parameter and a low value can be provided

If you are using an RPC server such as the z/OS (CICS | Batch) or BS2000 RPC server, the amount of data to be transferred to/from the RPC client is also reduced.

Start of instruction setTo suppress unneeded COBOL data items

  • Use the Suppress function available in the context menu of the COBOL interface and as mapping button to make the COBOL data item invisible in the IDL interface:

    graphics/idlFunctions_suppress-diff.png

Notes:

  1. The COBOL data item is not part of the IDL interface. It is invisible for consuming RPC clients or IS services.
  2. The RPC server or EntireX Adapter provides the COBOL data item to your COBOL server with low value, managing the offset to the next COBOL data item.
  3. If a COBOL group is suppressed, all subordinate COBOL data items are suppressed as well.
  4. With the inverse function Map to (see above) available in the context menu of the COBOL interface and as a mapping button, a COBOL data item can be made visible in the IDL interface again.

Set COBOL Data Items to Constants

COBOL data items that always require fixed constant values on input to the COBOL interface can be made invisible in the IDL interface and initialized with the required constant values. This is useful for keeping the IDL interface short and tidy. Consuming RPC clients or IS services are not bothered with IDL parameters that always contain constants, such as RECORD-TYPES. This function is often used in conjunction with Map to Multiple IDL Interfaces (see above).

Start of instruction setTo set COBOL data items to constants

  1. Use the Set Constant function available in the context menu of the COBOL interface and as mapping button to define a constant value for a COBOL data item:

    graphics/idlFunctions_constant-1-diff.png

  2. You are prompted with a window to enter the constant value:

    graphics/idlFunctions_constant-2.png

Notes:

  1. The COBOL data item is not part of the IDL interface. It is invisible for consuming RPC clients or IS services.
  2. The RPC server or EntireX Adapter provides the defined constant in the COBOL data item to your COBOL server.
  3. With the function Map to (see above) available in the context menu of the COBOL interface and as a mapping button, a COBOL data item can be made visible in the IDL interface again.

Set Arrays (Fixed <-> Unbounded)

A COBOL server defines in its interface as the last parameter a COBOL Tables with Fixed Size (fixed-size array). In contrast - as the syntax implies - a variable number of elements is transferred in this fixed-size array (input only, output only or both directions are possible). Array elements at the end of the array are unused. Their content is undefined. The current number of elements is transferred directly or implicitly outside the array. There are multiple options to specify how the receiver calculates the number of array elements.

With this mapping you map the fixed-size array of the COBOL interface with the usage described above to an IDL unbounded array in the IDL interface. A consuming RPC client or IS service can use it then as any other IDL unbounded array.

Start of instruction setTo set arrays from fixed to unbounded or vice versa

  1. Select the COBOL table and use the function Set Array Mapping (fixed<->unbounded) available in the context menu. The following window is displayed:

    graphics/idlFunctions_array-1.png

  2. Select Unbounded Array and the technique for determining the number of elements.

    graphics/map-dfh_idlFunctions_array-2.png

The number of array elements is calculated using one of the following options:

  • COBOL data item contains array length (bytes)
    The COBOL server program inspects a numeric COBOL data item (ZONED, PACKED or BINARY COBOL type) for the request and sets it accordingly for the reply. This COBOL data item contains the array length. To determine the number of array elements, the contents of the COBOL data item are divided by the length of one array element. All lengths are in bytes. The following COBOL snippet shows how the COBOL interface CONTRACT-DATA is filled by the COBOL server on reply. The length of the fixed-size array PACKETI is contained in COBOL data item C-BYTES.

           WORKING-STORAGE SECTION.
             77 II                                      PIC S9(4).
           . . .
           LINKAGE SECTION.
             01 DFHCOMMAREA.
               03 CONTRACT-DATA.
                04 CONTRACT.
                 05 C-ID                                PIC X(8).
                 05 C-BYTES                             PIC S9(4).
                 05 C-ACTION                            PIC X(4).
                04 ZONE.
                 05 Z-NUMBER                            PIC 9(2).
                 05 Z-ID                                PIC X(20).
                04 PACKETI                              OCCURS 99.
                 05 P-ITEM.
                  06 P-ID                               PIC X(8).
                  06 P-TEXT                             PIC X(30).
                  06 P-NUMBER                           PIC 9(2).
           . . .
    
          *  Fill variable output array
             MOVE 0 TO II.
             PERFORM RANDOMNUM TIMES
                ADD 1 TO II
                MOVE ... TO P-ID    (II)
                MOVE ... TO P-TEXT  (II)
                MOVE ... TO P-NUMBER(II)
             END-PERFORM.
          *  Set table length
             COMPUTE C-BYTES = (LENGTH OF P-ITEM) * II.
  • COBOL data item contains length of valid data within messages (bytes)
    The COBOL server program inspects a numeric COBOL data item (ZONED, PACKED or BINARY COBOL type) for the request and sets it accordingly for the reply. To determine the number of array elements, the contents of the COBOL data item are subtracted first to calculate the array length. The result is then divided by the length of one array element. The length of the transferred application data within the message can be shorter than the respective message length. All lengths are in bytes. The following COBOL snippet shows how the COBOL interface CONTRACT is filled by the COBOL server on reply. COBOL data item C-APPDATA contains the length of the valid data of the reply message. The number of array elements of the fixed-size array PACKETI is implicitly contained in COBOL data item C-APPDATA.

            WORKING-STORAGE SECTION.
             77 II                                      PIC S9(4).
             77 EPARM                                   PIC  9(2).
             77 EPARM2                                  PIC  9(4).
           . . .
           LINKAGE SECTION.
             01 DFHCOMMAREA.
                04 CONTRACT.
                 05 C-ID                                PIC X(8).
                 05 C-APPDATA                           PIC S9(4).
                 05 C-ACTION                            PIC X(4).
                 05 Z-ID                                PIC X(20).
                 05 Z-NUMBER                            PIC 9(2).
                04 PACKETI                              OCCURS 99.
                 05 P-ITEM.
                  06 P-ID                               PIC X(8).
                  06 P-TEXT                             PIC X(30).
                  06 P-NUMBER                           PIC 9(2).
           . . .
          *  Fill variable output array
             MOVE 0 TO II.
             PERFORM RANDOMNUM TIMES
                ADD 1 TO II
                MOVE ... TO P-ID    (II)
                MOVE ... TO P-TEXT  (II)
                MOVE ... TO P-NUMBER(II)
             END-PERFORM.
          *  Set length
             COMPUTE C-APPDATA = (LENGTH OF P-ITEM) * II
                               +  LENGTH OF CONTRACT.
  • COBOL data item contains number of array elements directly
    The COBOL server program inspects a numeric COBOL data item (ZONED, PACKED or BINARY COBOL type) for the request and sets it accordingly for the reply. The content of the COBOL data item is the number of array elements. The following COBOL snippet shows how the COBOL interface CONTRACT-DATA is filled by the COBOL server on reply. The number of array elements of the fixed-size array PACKETI is directly contained in COBOL data item C-NUM.

           WORKING-STORAGE SECTION.
             77 II                                      PIC S9(4).
           . . .
           LINKAGE SECTION.
             01 DFHCOMMAREA.
               03 CONTRACT-DATA.
                04 CONTRACT.
                 05 C-ID                                PIC X(8).
                 05 C-NUM                               PIC S9(4).
                 05 C-ACTION                            PIC X(4).
                04 ZONE.
                 05 Z-NUMBER                            PIC 9(2).
                 05 Z-ID                                PIC X(20).
                04 PACKETI                              OCCURS 99.
                 05 P-ITEM.
                  06 P-ID                               PIC X(8).
                  06 P-TEXT                             PIC X(30).
                  06 P-NUMBER                           PIC 9(2).
           . . .
    
          *  Fill variable output array
             MOVE 0 TO II.
             PERFORM RANDOMNUM TIMES
                ADD 1 TO II
                MOVE ... TO P-ID    (II)
                MOVE ... TO P-TEXT  (II)
                MOVE ... TO P-NUMBER(II)
             END-PERFORM.
          *  Set occurrences
             MOVE II TO C-NUM.

    Press OK to change the IDL array parameter from fixed array /number to an unbounded array /Vnumber. See array-definition under Software AG IDL Grammar in the IDL Editor documentation. If a COBOL data item is used, it will be set to suppressed because it is superfluous for RPC clients.

    See Suppress Unneeded COBOL Data Items.

Notes:

  1. This option should be used carefully and requires knowledge of the COBOL interface. Be aware that an incorrect mapping results in runtime errors.
  2. The COBOL table used in this manner must be the last parameter of the COBOL interface; it must not be a subparameter of any other COBOL table and must not contain any DEPENDING ON clause (see COBOL Tables with Variable Size - DEPENDING ON Clause).
  3. If a COBOL data item is used, it must be physically located before the COBOL table. The IDL directions must also match.

Set Multiple Possible Output (MPO) Structures

A COBOL server program produces more than one type of output. The layout of the output can therefore take two or more dissimilar shapes. The COBOL server program decides at runtime the output structure returned, that is, the COBOL layout on output varies.

Multiple Possible Output with REDEFINES

A COBOL REDEFINES Clause is often used to describe the possible output structures. In COBOL this is the standard way to describe multiple possible output:

Similar to COBOL data item PAYMENT-DATA in the example below; for this purpose, PAYMENT-DATA is redefined; each redefinition represents an output structure (MPO case); on return exactly one output structure is used; by inspecting COBOL data item PAYMENT-TYPE (MPO selector) first, a caller can determine the returned output structure; the caller then uses the correct redefinition to access the data.

  . . .
    01 INPUT-DATA.
       02 ORDER-NUMBER                            PIC 9(10).

    . . .
    01 OUTPUT-DATA.
        02 <some fields>                          PIC <clause>.
       . . .

        02 PAYMENT-TYPE                           PIC X(2).
           88 PAYMENT-TYPE-VOUCHER                VALUE "VO".
           88 PAYMENT-TYPE-CREDITCARD             VALUE "CC".
           88 PAYMENT-TYPE-TRANSFER               VALUE "TR".
           88 PAYMENT-TYPE-DIRECTDEBIT            VALUE "DB".
          . . .
        02 <preceding data items>                 PIC <clause>.
       . . .
        02 PAYMENT-DATA                           PIC X(256).
        02 PAYMENT-DATA-VOUCHER     REDEFINES PAYMENT-DATA.
           04 VOUCHER-ORIGIN                      PIC X(128).
           04 VOUCHER-SERIES                      PIC X(128).
        02 PAYMENT-DATA-CREDITCARD  REDEFINES PAYMENT-DATA.
           04 CREDITCARD-NUMBER                   PIC 9(18).
           04 CREDITCARD-COMPANY                  PIC X(128).
           04 CREDITCARD-CODE                     PIC 9(12).
           04 CREDITCARD-VALIDITY                 PIC X(8).
        02 PAYMENT-DATA-TRANSFER    REDEFINES PAYMENT-DATA.
           04 TRANSFER-NAME                       PIC X(128).
           04 TRANSFER-IBAN                       PIC X(34).
           04 TRANSFER-BIC                        PIC X(11).
        02 PAYMENT-DATA-DIRECTDEBIT REDEFINES PAYMENT-DATA.
           04 DIRECTDEBIT-IBAN                    PIC X(34).
           04 DIRECTDEBIT-NAME                    PIC X(128).
           04 DIRECTDEBIT-EXPIRES                 PIC 9(8).
          . . .
        02 <subsequent data items>                PIC <clause>.
       . . .

    . . .

*   read order record using ORDER-NUMBER
    . . .

*  set value indicating type of reply (MPO selector)
    IF <some-condition> THEN
      SET PAYMENT-TYPE-VOUCHER TO TRUE
    ELSE IF <some-other-condition> THEN
      SET PAYMENT-TYPE-CREDITCARD TO TRUE
    ELSE IF <some-further-condition> THEN
      SET PAYMENT-TYPE-TRANSFER TO TRUE
    ELSE
      SET PAYMENT-TYPE-DIRECTDEBIT TO TRUE
    END-IF.
   . . .

*   set fields (MPO case) depending on type of reply
    INITIALIZE PAYMENT-DATA.
    EVALUATE TRUE
         WHEN PAYMENT-TYPE-VOUCHER
            MOVE . . . TO VOUCHER-ORIGIN
            MOVE . . . TO VOUCHER-SERIES
         WHEN PAYMENT-TYPE-CREDITCARD
            MOVE . . . TO CREDITCARD-NUMBER
            MOVE . . . TO CREDITCARD-CODE
            MOVE . . . TO CREDITCARD-VALIDITY
         WHEN PAYMENT-TYPE-TRANSFER
            MOVE . . . TO TRANSFER-NAME
            MOVE . . . TO TRANSFER-IBAN
            MOVE . . . TO TRANSFER-BIC
         WHEN PAYMENT-TYPE-DIRECTDEBIT
            MOVE . . . TO DIRECTDEBIT-IBAN
            MOVE . . . TO DIRECTDEBIT-NAME
            MOVE . . . TO DIRECTDEBIT-EXPIRES
         WHEN
            . . .
    END-EVALUATE.
    . . .

In addition, the COBOL interface

  • limits the number of possible output structures returned

  • defines all possible output structures, that is, they are known during extraction. In the example these are the structures PAYMENT-DATA-VOUCHER, PAYMENT-DATA-CREDITCARD and PAYMENT-DATA-TRANSFER. These are the MPO structures.

  • contains an additional COBOL data item carrying a value related to the returned output structure. By inspecting this data item first, the appropriate output structure can be selected to address the data correctly. In the example it is PAYMENT-TYPE. This item is the MPO selector.

  • always occupies memory to be able to transfer the longest output structure. If the actual returned output structure is shorter than the longest possible output structure, there is a gap (space) between the multiple possible output and the subsequent data item.

graphics/idlFunctions_mpo.png

This abstract concept is known as multiple possible output (MPO) EntireX bundles all MPO structures into an MPO group. See MPO Terminology below.

Optional Output with Groups

COBOL group data items can be used to describe optional output structures. The contents of a COBOL data item define under which circumstances COBOL groups are part of the returned data or not. Optional output with group data items are a variant of multiple possible output (MPO).

In addition, the COBOL interface

  • limits the number of possible output structures returned

  • defines all optional output structures, that is, they are known during extraction. In the COBOL snippet below these are the structures OPTIONAL-OUTPUT-STRUCTURE1 and OPTIONAL-OUTPUT-STRUCTURE2. These are the MPO structures.

  • contains an additional COBOL data item carrying an indication which optional output is present. By inspecting this data item first, the appropriate optional output structure can be selected to address the data correctly. If its value does not match, the optional output is not present. In the COBOL snippet it is COBOL data item OPTIONAL-OUTPUT. This item is the MPO selector.

  • If the optional output is not present no memory is occupied. There is no gap between the optional output and the subsequent data item, as opposed to Multiple Possible Output with REDEFINES above.

In the COBOL snippet below there are three different shapes of output:

graphics/idlFunctions_mpo_groups.png

COBOL snippet:

WORKING-STORAGE SECTION.

   01 INPUT-AREA.
      02 FIX-INPUT-ITEM1                      PIC X(4).
      02 <some fields>                        PIC <clause>.
      . . .

   01 OUTPUT-OFFSET                           PIC  S9(9) BINARY.
   01 OUTPUT-AREA                             PIC X(32000).
      . . .

   01 CONTROL-AREA.
      02 OPTIONAL-OUTPUT                      PIC X(1).
         88 OPTIONAL-OUTPUT-1                 VALUE "1".
         88 OPTIONAL-OUTPUT-2                 VALUE "2".
         88 OPTIONAL-OUTPUT-NONE              VALUE "N".
      . . .

   01 OPTIONAL-OUTPUT-STRUCTURE1.
      02 OPTIONAL-OUTPUT-ITEM11               PIC X(10).
      02 OPTIONAL-OUTPUT-ITEM12               PIC X(100).
      02 OPTIONAL-OUTPUT-ITEM13               PIC X(20).
      . . .

   01 OPTIONAL-OUTPUT-STRUCTURE2.
      02 OPTIONAL-OUTPUT-ITEM21               PIC X(4).
      02 OPTIONAL-OUTPUT-ITEM22               PIC X(50).
      02 OPTIONAL-OUTPUT-ITEM23               PIC X(50).
      . . .

   01 FIX-OUTPUT-STRUCTURE1.
      02 FIX-OUTPUT-ITEM11                    PIC X(4).
      02 FIX-OUTPUT-ITEM12                    PIC X(20).
      02 FIX-OUTPUT-ITEM13                    PIC X(8).
      . . .

   01 FIX-OUTPUT-STRUCTURE2.
      02 FIX-OUTPUT-ITEM21                    PIC X(2).
      02 FIX-OUTPUT-ITEM22                    PIC X(10).
      02 FIX-OUTPUT-ITEM23                    PIC X(10).
      . . .


      IF <some-condition> THEN
         SET OPTIONAL-OUTPUT-1 TO TRUE
      ELSE IF <some-other-condition> THEN
         SET OPTIONAL-OUTPUT-2 TO TRUE
      ELSE
         SET OPTIONAL-OUTPUT-NONE TO TRUE
      END-IF.

      . . .

*     provide control area for optional output
      MOVE 1 TO OUTPUT-OFFSET.
      STRING CONTROL-AREA DELIMITED BY SIZE
      INTO OUTPUT-AREA WITH POINTER OUTPUT-OFFSET.

*     provide data items before optional output
      STRING FIX CONTROL-AREA DELIMITED BY SIZE
      INTO OUTPUT-AREA WITH POINTER OUTPUT-OFFSET.

*     provide optional output
      EVALUATE TRUE
          WHEN OPTIONAL-OUTPUT-1
             STRING OPTIONAL-OUTPUT-STRUCTURE1 DELIMITED BY SIZE
             INTO OUTPUT-AREA WITH POINTER OUTPUT-OFFSET
          WHEN OPTIONAL-OUTPUT-2
             STRING OPTIONAL-OUTPUT-STRUCTURE2 DELIMITED BY SIZE
             INTO OUTPUT-AREA WITH POINTER OUTPUT-OFFSET
      END-EVALUATE.

*     provide data items after optional output
      STRING FIX-OUTPUT-STRUCTURE2 DELIMITED BY SIZE
      INTO OUTPUT-AREA WITH POINTER OUTPUT-OFFSET.
      . . .

The returned data is built by copying the necessary COBOL structures into an output area. The optional output is one of OPTIONAL-OUTPUT-STRUCTURE1, OPTIONAL-OUTPUT-STRUCTURE2 or nothing. The presence of the optional output is controlled by a structure named CONTROL-AREA.

Complex MPO Selections

If the MPO case detection is complicated and cannot be defined by available Extractor features (for example the MPO selector and its values), perform the following steps:

Start of instruction setTo map a complex MPO selection

  1. Map the complete MPO group to binary. See Map to Binary and Revert Binary Mapping.

    Note:
    If an MPO group is already defined, you cannot map it to binary. Decide first whether MPO case detection is covered by available extractor features.

  2. Implement MPO case detection in your RPC client, using the binary mapping from step 1.

  3. Implement MPO case parsing in your RPC client, using the binary mapping from step 1. For the EntireX Adapter, use the COBOL Converter for this purpose. See Converting IS Data Structures with the COBOL Converter in the EntireX Adapter documentation.

MPO Terminology

The following terminology is used with MPOs:

MPO structure

A COBOL group describing the output layout used in an MPO case. All alternative layouts in an MPO group are often described with COBOL REDEFINEs.

MPO group

Bundles together all MPO structures that can be used alternatively. A COBOL interface can contain more than one MPO group.

MPO case

An MPO structure together with its MPO selector values (one or more).

MPO selector

A COBOL data item containing a specific value (MPO selector value) where the actual MPO case can be determined.

  • For MPOs based on REDEFINEs, the MPO selector can be placed before, inside or after the MPO group.

  • For optional output with groups, the MPO selector precedes the MPO group and is located outside the MPO group.

  • Only for MPP Message Interface (IMS Connect): Instead of determining the position of the MPO selector from beginning of the message, you can calculate the position using a fixed offset starting from the end of the message. This alternative is limited to one MPO group per program. See check box MPO Selector determined from message end in step Create a new MPO group below.

MPO selector value

Each value indicates exactly one output structure. An output structure can be indicated by further values.

Steps

Start of instruction setTo set multiple possible output (MPO) structures with REDEFINES or groups

Use the Set Multiple Possible Output (MPO) Structures function available in the context menu of the COBOL interface to create new or modify existing MPO groups.

  1. Set the top-level COBOL data item where the MPO structures are contained to IDL direction Out. Use the Map to Out function for this purpose:

    graphics/idlFunctions_mpo-set-topLevel.png

  2. From the context menu of the COBOL interface of the COBOL REDEFINE, choose Set Multiple Possible Output (MPO) Structures.

    graphics/idlFunctions_mpo-set-structs-same.png

  3. Set Multiple Possible Output (MPO) Structures into MPO Group.

    graphics/idlFunctions_mpo-set-group.png

  4. Create a new MPO group.

    graphics/idlFunctions_mpo-new-group.png

  5. Set MPO selector values for MPO Structures.

    graphics/idlFunctions_mpo-set-selectorValues-1.png

    Use the functions graphics/icon_mpo-delete.gif to delete and graphics/icon_plus.gif to add MPO selector values:

    graphics/idlFunctions_mpo-set-selectorValues-2.png

    Notes:

    1. To add multiple MPO selector values per MPO structure, use the function graphics/icon_plus.gif multiple times for the same MPO structure (see value 10 and 20 for structure PAYMENT-DATA).
    2. MPO structures without any MPO selector value are unused and suppressed in the IDL interface value (e.g. see structure PAYMENT-DATA-TRANSFER).
    3. Each MPO selector value must uniquely identify an MPO structure. The same value cannot be used more than once for different MPO structures.
    4. If no defined MPO selector value matches at runtime, an empty MPO group is delivered to the RPC client, that is, none of the MPO cases contain any data. No runtime error is produced.
  6. Press Finish to create the following IDL together with a server mapping file. See Server Mapping Files for COBOL.

    library 'PAYMENT' is
    
     program 'PAYMENT' is
      define data parameter
       1 INPUT              In
        2 ORDER-NUMBER             (NU10)
       1 OUTPUT             Out
        2 PAYMENT-TYPE             (A2)
        2 PAYMENT-DATA-MPO  Choice
         3 PAYMENT-DATA            (/V1)
          4 PAYMENT-DATA           (AV256)
         3 PAYMENT-DATA-VOUCHER    (/V1)
          4 VOUCHER-ORIGIN         (AV128)
          4 VOUCHER-SERIES         (AV128)
         3 PAYMENT-DATA-CREDITCARD (/V1)
          4 CREDITCARD-NUMBER      (NU18)
          4 CREDITCARD-CODE        (NU12)
          4 CREDITCARD-VALIDITY    (AV8)
      end-define
    

Map to Binary and Revert Binary Mapping

With such a mapping you allow the COBOL server to deal with binary data (for example images). You can also manage Complex MPO Selections.

graphics/idlFunctions_map2bin-1.png

The menu entry Map to Binary appears only on COBOL data items were it makes sense, for example in Channel Container interface types it is not allowed to map the container reference itself as binary, but inner items can be mapped as binary. Redefine groups will be handled as a block, that means the largest redefine path or redefine base defines the binary length.

When the binary IDL parameter is selected, all corresponding COBOL data items are selected as well.

graphics/idlFunctions_map2bin-2.png

To undo the binary mapping, select the root COBOL data item (the first of the selection group) and from the context menu choose Revert Binary Mapping.

graphics/idlFunctions_map2bin-3.png

Programming Techniques

Example 1: Redefines

The output data is described with a REDEFINE that overlays the input data as in the following example. In this case you need to select IN-BUFFER for the input message and OUT-BUFFER for the output message of the COBOL interface. This technique is often used to allow full 32K input and full 32K completely different output, thus circumventing CICS 32K restrictions somewhat.

 LINKAGE SECTION.
 01 DFHCOMMAREA.

 02 IN-BUFFER.
    03 OPERATION                      PIC X(1).
    03 OPERAND-1                      PIC S9(9) BINARY.
    03 OPERAND-2                      PIC S9(9) BINARY.
 02 OUT-BUFFER REDEFINES IN-BUFFER.
    03 FUNCTION-RESULT                PIC S9(9) BINARY.
  . . .
 PROCEDURE DIVISION USING DFHCOMMAREA.
* process the IN-BUFFER and provide result in OUT-BUFFER
    EXEC CICS RETURN.

REDEFINEs can also be used to describe a single buffer used for input and output, that is, the CICS input message is the same as the CICS output message. For more information see Example 1: Redefines in the section CICS with DFHCOMMAREA Calling Convention - In same as Out.

Example 2: Buffer Technique

On entry, the server moves linkage section field(s) - often an entire buffer - into the working storage and processes the input data inside the working storage field(s). Before return, it moves the working storage field(s) - often an entire buffer - back to the linkage section. In this case, the relevant COBOL data items are described within the working storage section. You need to select IN-BUFFER for the input message and OUT-BUFFER for the output message of the COBOL interface. This technique can be used to allow full 32K input and full 32K completely different output, thus circumventing CICS 32K restrictions somewhat.

 WORKING STORAGE SECTION
 01 IN-BUFFER.
    02 OPERATION                      PIC X(1).
    02 OPERAND-1                      PIC S9(9) BINARY.
    02 OPERAND-2                      PIC S9(9) BINARY.
 01 OUT-BUFFER.
    02 FUNCTION-RESULT                PIC S9(9) BINARY. 
 LINKAGE SECTION
 01 DFHCOMMAREA.
    02 IO-BUFFER                      PIC X(9).
  . . .
 PROCEDURE DIVISION USING DFHCOMMAREA.
    MOVE IO-BUFFER TO IN-BUFFER.
* process the IN-BUFFER and provide result in OUT-BUFFER
    MOVE OUT-BUFFER TO IO-BUFFER.
    EXEC CICS RETURN.

The buffer technique can also be used to describe a single buffer used for input and output, that is, the CICS input message is the same as the CICS output message. For more information see Example 2: Buffer Technique in the section CICS with DFHCOMMAREA Calling Convention - In same as Out.

Example 3: COBOL SET ADDRESS Statements

COBOL SET ADDRESS statements are used to manipulate the interface of the CICS server. On entry, the server addresses the input data with a (dummy) structure IN-BUFFER defined in the linkage section. Upon return, the server addresses the output data again with a different (dummy) structure OUT-BUFFER defined in the linkage section. You need to select IN-BUFFER for the input message and OUT-BUFFER for the output message of the COBOL interface. This technique can be used to allow full 32K input and full 32K completely different output, thus circumventing CICS 32K restrictions somewhat.

 LINKAGE SECTION.
 01 IN-BUFFER.
    02 OPERATION                      PIC X(1).
    02 OPERAND-1                      PIC S9(9) BINARY.
    02 OPERAND-2                      PIC S9(9) BINARY.
 01 OUT-BUFFER.
    02 FUNCTION-RESULT                PIC S9(9) BINARY.
  . . .
 PROCEDURE DIVISION.
    SET ADDRESS OF IN-BUFFER TO DFHCOMMAREA.
* process the IN-BUFFER and provide result in OUT-BUFFER
    SET ADDRESS OF OUT-BUFFER TO DFHCOMMAREA.
    EXEC CICS RETURN.

COBOL SET ADDRESS statements can also be used to describe a single buffer used for input and output, that is, the CICS input message is the same as the CICS output message. For more information see Example 3: COBOL SET ADDRESS Statements in the section CICS with DFHCOMMAREA Calling Convention - In same as Out.