This document describes using the COBOL Mapping Editor to extract from a MicroFocus COBOL server with a standard COBOL call interface.
Because COBOL servers with a standard call interface always contain a
PROCEDURE DIVISION
header (see PROCEDURE DIVISION
Mapping) with all parameters,
the COBOL data items of the interface can be evaluated by the IDL Extractor for COBOL and are
already offered by the wizard. In most cases the offered COBOL data items will
be correct, but you should always check them manually.
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.
If you are extracting IDL from a COBOL source or extending the IDL file by extracting an additional COBOL source with interface type Micro Focus with standard linkage 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.
Press
to open the COBOL Mapping Editor.To select the COBOL interface data items of your COBOL server
Add the COBOL data items to COBOL Interface by using the context menu or toolbar available in the COBOL Source View and COBOL Interface. See Notes.
Continue with COBOL to IDL Mapping.
Notes:
PROCEDURE DIVISION
header available,
the parameters listed define exactly the COBOL interface.
These COBOL data items are within the LINKAGE SECTION
and are already selected
to the COBOL interface in initial state when you enter the COBOL Mapping Editor.
The PROCEDURE DIVISION
header might not be available if you are extracting from a copybook
or part of the COBOL source.
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 server programs with standard call interface types, the user interface of the COBOL Mapping Editor looks like this:
COBOL Program Selection. Currently selected program with interface type More info | |
COBOL Source View. Contains all related sources for the currently selected COBOL program More info | |
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 More info |
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. | |
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 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 InOut. Scalar parameter, mapped to Out. Group parameter, here mapped to InOut. REDEFINE
parameter, here mapped to InOut.Parameter set to Constant.
The following buttons are available:
- Map to In | Out | InOut ->
See Map to In, Out, InOut. 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.
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 In, Out, InOut functions you make a COBOL data item visible as an IDL parameter in the IDL interface. With correct IDL directions you design the IDL interface by defining input and output parameters. COBOL programs have no parameter directions, so you need to set IDL directions manually.
To provide IDL directions
Go step-by-step through all top-level COBOL data items in the COBOL interface and use the
, and functions available in the context menu of the COBOL interface and as mapping buttons to make the COBOL data items visible and provide IDL directions in the IDL interface:Notes:
attribute-list
under Software AG IDL Grammar in the IDL Editor documentation.
If you are using an RPC server such as the z/OS (CICS | Batch), z/VSE (CICS | Batch), Micro Focus or BS2000 RPC server, the amount of data to be transferred to/from the RPC client is reduced with correct IDL directions.
With the 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 ODO subject (here data item TABLE
) and ODO object (here data item COUNTER-1
)
to the COBOL interface. It is important both data items are in the COBOL interface.
Use the TABLE
):
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 of the IDL and COBOL mapping files (SVM and CVM). 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
If you are using an RPC server such as the z/OS (CICS | Batch), z/VSE (CICS | Batch), Micro Focus or BS2000 RPC server, the amount of data to be transferred to/from the RPC client is also reduced.
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:
With such a mapping you allow the COBOL server to deal with binary data (for example images).
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.
To undo the binary mapping, select the root COBOL data item (the first of the selection group) and from the context menu choose
.