This document describes using the COBOL Mapping Editor to extract a COBOL converter where COBOL output parameters are different to COBOL input parameters, that is, the output is overlaid with a data structure that is different to the data structure on input.
A file containing valid COBOL data items describing the COBOL payload can be used to extract a COBOL converter for the EntireX Adapter. 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.
This section assumes Input Message same as Output Message is not checked. COBOL output and COBOL input parameters are different, that is, the output is overlaid with a data structure that is different to the data structure on input.
If you are extracting IDL from a COBOL source or extending the IDL file by extracting an additional COBOL source with interface type COBOL Converter, 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.
Press
to open the COBOL Mapping Editor.To select the COBOL interface data items of your COBOL server
Add the COBOL data items of the input message to COBOL Source View and COBOL Interface. See Notes.
by using the context menu or toolbar available in theAdd the COBOL data items of the output message to COBOL Interface and IDL Interface. See Notes.
by using the context menu and toolbars available in theContinue with COBOL to IDL Mapping.
Notes:
REDEFINE
s, 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.
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:
![]() |
COBOL Program Selection. Currently selected program with interface type
![]() |
![]() |
COBOL Source View. Contains all related sources for the currently selected COBOL program
![]() |
![]() |
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
![]() |
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.
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:
![]() |
Add selected COBOL data item to COBOL Interface as Input Message. |
![]() |
Add selected COBOL data item to COBOL Interface as Output Message. |
![]() |
Remove selected COBOL data item from COBOL Interface. |
![]() |
Remove all COBOL data items from COBOL Interface. |
![]() |
Reset COBOL Interface to initial state. |
![]() |
Show dialog to modify COBOL Source Characteristics. Not available for interface type COBOL Converter. |
![]() |
Show dialog to find text in Source. |
The same functionality is also available from the context menu.
This section covers the following topics:
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.
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.
A suppressed COBOL data item becomes visible in the IDL interface. Used also to select another REDEFINE
path.Suppress unneeded COBOL data items. Set COBOL data items to constant. Map an array to a fixed sized or unbounded array. 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 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. Undo the operation and use the standard mapping.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. - Toolbar
The toolbar offers the following actions:
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 firstREDEFINE
path is mapped to IDL;FILLER
s are suppressed according to your selection, see Step 4: Define the Extraction Settings and Start Extraction.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.Remove current IDL Interface. Rename current IDL Interface. Expand the full tree. 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:
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 aREDEFINE
path, all other siblingREDEFINE
paths are automatically set to "Suppress".- Mapping Icons
The following mapping icons on the COBOL data items indicate your current IDL mapping:
Scalar parameter, mapped to In. Scalar parameter, mapped to Out. Group parameter, here mapped to In. REDEFINE
parameter, here mapped to Out.Parameter set to Constant.
The following buttons are available:
- 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.
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.
Ungroup an IDL group parameter. This removes the selected mapped IDL group parameter from the IDL interface and moves up the IDL group elements.
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.
This section covers the following topics:
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.
To map COBOL data items to IDL interface
Go step-by-step through all top-level COBOL data items in the COBOL interface and use the
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:Do the same for the output message of the COBOL interface.
Notes:
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.
To 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).
Notes:
attribute-list
under Software AG IDL Grammar in the IDL Editor documentation.
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:
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.
To map a COBOL interface to multiple IDL interfaces
Select the tab with COBOL to IDL Mapping. For each function, define a separate IDL interface with the toolbar functions or
:
Give the IDL interfaces meaningful names with the toolbar function :
Define the required constant values to the function-code or operation-code parameter, see Set COBOL Data Items to Constants above:
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 Server Mapping Files for COBOL.
to create the following IDL together with a server mapping file. Seelibrary '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:
Icon | Function | Description |
---|---|---|
![]() |
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; FILLER s are suppressed according to your selection, see Step 4: Define the Extraction Settings and Start Extraction.
|
![]() |
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.
|
![]() |
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. |
![]() |
Remove current IDL Interface | Deletes the current IDL interface. |
For COBOL server programs containing COBOL REDEFINE
s, the correct REDEFINE
path needs to be chosen for the IDL interface.
To select redefine paths
Use the REDEFINE
path available in the IDL interface.
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:
REDEFINE
path of a COBOL REDEFINE
can be mapped to the IDL interface. All COBOL REDEFINE
siblings are suppressed.
REDEFINE
path is actively mapped to the IDL interface, all COBOL REDEFINE
siblings are suppressed.
REDEFINE
paths of a COBOL REDEFINE
. Simply suppress the active REDEFINE
path, see Suppress Unneeded COBOL Data Items above.
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
To suppress unneeded COBOL data items
Use the
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:Notes:
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 (see above).
To set COBOL data items to constants
Use the
function available in the context menu of the COBOL interface and as mapping button to define a constant value for a COBOL data item:You are prompted with a window to enter the constant value:
Notes:
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.
To set arrays from fixed to unbounded or vice versa
Select the COBOL table and use the function
available in the context menu. The following window is displayed:Select Unbounded Array and the technique for determining the number of elements.
The number of array elements is calculated using one of the following options:
COBOL Converter length (bytes)
For input, the COBOL Converter uses the length of byte array cobolInput
as COBOL Converter length.
For output, the length of byte array cobolOutput
has to be used accordingly.
To determine the number of array elements, the length of the byte array is subtracted first to calculate the array length.
The result is then divided by the length of one array element. All lengths are in bytes.
The following COBOL snippet shows the layout of a COBOL interface with fixed-size array PACKETI
used in this manner:
01 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).
Assume the array PACKETI
is filled with 15 occurrences.
The length of byte array cobolInput
is calculated then as follows: (LENGTH OF ZONE
) + (LENGTH OF CONTRACT
) + (LENGTH OF P-ITEM
) * 15.
The number of array elements of the fixed-size array PACKETI
is implicitly contained in the COBOL converter length.
COBOL data item contains array length (bytes)
For input, The COBOL Converter inspects the COBOL data item in byte array cobolInput
and sets it accordingly for output in byte array cobolOutput
.
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 the layout of a COBOL interface with fixed-size array PACKETI
and C-BYTES
as the COBOL data item used in this manner:
01 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).
Assume the array PACKETI
is filled with 7 occurrences. The contents of COBOL data item C-BYTES
are calculated as follows: (LENGTH OF P-ITEM) * 7
.
The number of array elements of the fixed-size array PACKETI
is implicitly contained in COBOL data item C-BYTES
.
COBOL data item contains length of valid data within messages (bytes)
For input, The COBOL converter inspects the COBOL data item in byte array cobolInput
and sets it accordingly for output in byte array cobolOutput
.
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 COBOL converter length.
All lengths are in bytes. The following COBOL snippet shows the layout of a COBOL interface with fixed-size array PACKETI
and C-APPDATA
as the COBOL data item used in this manner:
01 CONTRACT-DATA. 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).
Assume the array PACKETI
is filled with 31 occurrences.
The contents of COBOL data item C-APPDATA
are calculated as follows: (LENGTH OF CONTRACT) + (LENGTH OF P-ITEM) * 31
.
The number of array elements of the fixed-size array PACKETI
is implicitly contained in COBOL data item C-APPDATA
.
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 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.
Notes:
DEPENDING ON
clause (see COBOL Tables with Variable Size - DEPENDING ON
Clause).
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.
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.
This abstract concept is known as multiple possible output (MPO) EntireX bundles all MPO structures into an MPO group. See MPO Terminology below.
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:
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
.
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:
To map a complex MPO selection
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.
Implement MPO case detection in your RPC client, using the binary mapping from step 1.
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.
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
REDEFINE
s, 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.
To set multiple possible output (MPO) structures with
REDEFINES
or groups
Use the
function available in the context menu of the COBOL interface to create new or modify existing MPO groups.Set the top-level COBOL data item where the MPO structures are contained to IDL direction Out. Use the
function for this purpose:From the context menu of the COBOL interface of the COBOL REDEFINE
, choose .
Set Multiple Possible Output (MPO) Structures into MPO Group.
Create a new MPO group.
Set MPO selector values for MPO Structures.
Use the functions to delete and
to add MPO selector values:
Notes:
PAYMENT-DATA
).
PAYMENT-DATA-TRANSFER
).
Press Server Mapping Files for COBOL.
to create the following IDL together with a server mapping file. Seelibrary '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
With such a mapping you allow the COBOL server to deal with binary data (for example images). You can also manage Complex MPO Selections.
The menu entry
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.
Note:
The last COBOL data items are mapped to IDL data type BV instead of Bn (PACKETI (BV)
in this example).
To undo the binary mapping, select the root COBOL data item (the first of the selection group) and from the context menu choose
.This function flattens an IDL group. It removes the selected IDL group from the IDL interface and moves up the IDL group elements. By repeating this function, IDL group elements can be moved to IDL level 1, where the correct IDL direction (IN, OUT) can be set.
A COBOL group PAYMENT-DATA
contains input as well as output parameters.
ORDER-NUMBER
and PAYMENT-TYPE
are input; PAYMENT-VALIDITY
is an output parameter.
01 PAYMENT-DATA. 02 ORDER-NUMBER PIC 9(10). 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 PAYMENT-VALIDITY PIC X(256).
IDL directions can be set on IDL level 1 only. Therefore, if PAYMENT-DATA
is in the IDL, you need to map it to direction INOUT
.
It is not possible to set it to direction IN
, because the direction of PAYMENT-VALIDITY
would be wrong.
The same applies if you set PAYMENT-DATA
to direction OUT
; ORDER-NUMBER
and PAYMENT-TYPE
would then be wrong.
To solve this conflict
Remove the group data item PAYMENT-DATA
with function from the IDL Parameters context menu.
Map ORDER-NUMBER
and PAYMENT-TYPE
to direction IN
. See IDL mapping function Map to.
Map PAYMENT-VALIDITY
to direction OUT
. See IDL mapping function Map to.
Restriction: It is not possible to ungroup COBOL data items with the OCCURS
clause (IDL arrays).