The Software AG IDL Extractor for COBOL inspects a COBOL source and its copybooks for COBOL data items to extract. It can also extract directly from copybooks. In a user-driven process supported by an Extractor Wizard, the interface of a COBOL server is extracted and - with various features offered by a Mapping Editor - modelled to a client interface.
 |
Start the wizard, select your server program and make COBOL-specific settings. |
 |
Optional. This step is not always necessary: it is possible that parameters have already been selected, for example as a result
of the COBOL USING clause.
|
 |
Optional. If necessary, you can modify the parameter selection from the Mapping Editor. |
 |
Fine-tune the COBOL to IDL mapping. |
 |
Generate an IDL file and a server mapping file. These two related files map the client interface to the COBOL server program and are described below: |
IDL File
The Software AG IDL file (interface definition language) contains the
modelled interface of the COBOL server. In a follow-up step the IDL file is the
starting point for the RPC client-side wrapping generation tools to generate
client interface objects. See EntireX Wrappers.
Server Mapping File
A server mapping file to complete the mapping is generated only if it
is required by the RPC server at runtime to call the COBOL server.
See Server Mapping Files for COBOL.
The extractor wizard guides you through the extraction process. The wizard supports the following tasks:
Accessing COBOL source files, either in the local file system where the Designer runs or remotely from the host computer with the RPC server extractor service. The wizard supports the following: z/OS partitioned data sets and CA Librarian data sets (including member archive levels) as well as BS2000 LMS libraries. See Extractor Service in the RPC Server documentation for Batch | IMS | BS2000. For this purpose, define a local or remote COBOL extractor environment. See COBOL Preferences.
Resolving of COBOL copybooks. If a relevant copybook from the COBOL
DATA DIVISON is missing, a browse dialog is offered where you can locate the
copybook - either a folder (local extractor environment) or data set (remote
extractor environment) - interactively. Copybook folder or data sets can also
be predefined in the COBOL extractor environment. See COBOL Preferences.
Resolving of COBOL copybooks with the REPLACE option.
CA Librarian (-INC) and CA Panvalet (++INCLUDE) control statements
are supported. They are handled in a similar way to copybooks.
Various COBOL server interface types, such as standard CICS
DFHCOMMAREA, CICS with different structures on input and output, CICS with a
large buffer compatible to webMethods WMTLSRVR, standard batch, and IMS BMP server with PCB pointers. See Supported COBOL Interface Types.
Selecting the COBOL server interface manually within the
COBOL Mapping Editor page. This allows you to extract from a
COBOL server where the interface definition is not completely given by the
parameters provided in the
PROCEDURE DIVISION Mapping, making it impossible to detect the
parameters automatically.
Defining the default COBOL to IDL mapping in the COBOL Preferences for the following fields:
COBOL pseudo-parameter FILLER fields. You can define whether they
should be part of the RPC client interface or not. By default, they are not
contained in the IDL.
The name prefix for FILLER and anonymous groups used for IDL parameters.
COBOL alphanumeric fields (PICTURE X, A, G, N). They can be mapped
either to variable-length or fixed-length strings in the IDL.
This option is provided for modern RPC clients that support variable-length strings, and also for legacy RPC clients
that support fixed-length strings only.
The extractor wizard is described in a step-by-step tutorial; see Using the IDL Extractor for COBOL - Overview.
The COBOL Mapping Editor is the tool to select and map the COBOL server interface to IDL. This section gives a short overview of the mapping features provided. These features are described in more detail in the documentation section for the respective interface type.
Add and remove the parameters of the COBOL server in the top window of the COBOL Mapping Editor page. The current selection is shown in the bottom window for fine tuning.
Provide IDL directions for parameters of the COBOL server. A COBOL server does not contain IDL direction information, so you can add this information manually in the Mapping Editor.
Select REDEFINE paths used in the IDL. The Mapping Editor allows you to select a
single REDEFINE path for every REDEFINE unit (all redefine paths addressing the same storage location).
Suppress unneeded fields in the IDL. This keeps the IDL client interface clean and also minimizes the amount of data transferred during runtime.
Define parameter constants as input for the COBOL server. Constant parameters are not contained in the IDL file, which means they are invisible for RPC clients. This makes the IDL client interface easier and safer to use, minimizing improper usage.
For one COBOL server program, you can create and model multiple interfaces. If the IDL is processed further with a wrapper of the Designer, the business functions are provided as
Web service operations if exposed as a web service instead of a web service with a single operation
methods if wrapped with the Java Wrapper or .NET Wrapper instead of a Java class with a single method
etc.
See COBOL Mapping Editor for more information.
The IDL Extractor for COBOL supports as input a COBOL server with various interface types. This section covers the following topics:
The interface type you are mostly working with can be set in the preferences. See COBOL Preferences.
Analyzing the technique used to access the interface with COBOL and CICS statements is the safest way to determine the interface type. The following CICS COBOL interface types are supported:
There is no clear and easy indication how to identify the interface type of a CICS COBOL server without COBOL and CICS knowledge. Below are some criteria that might help to determine the interface type. If you are unsure, consult a CICS COBOL specialist.
The payload size of the CICS COBOL server is greater than 32 KB:
In this case it is not a DFHCOMMAREA interface, because the DFHCOMMAREA is limited to 32 KB.
It could be a large buffer or channel container interface, which are only limited by the storage (memory) available to them.
The CICS COBOL server is located in a remote CICS region:
In this case it is not a large buffer interface, because large buffer programs must reside on the same CICS region as the caller, that is, the RPC Server for CICS.
It could be a DFHCOMMAREA or channel container interface, which can reside in a remote CICS region.
Note:
The most used interface type is the DFHCOMMAREA interface.
Large buffer and channel container interfaces are used much less frequently.
The IDL Extractor for COBOL supports CICS programs using the standard
DFHCOMMAREA calling convention.
The following illustrates roughly how you can determine whether a COBOL server follows the
DFHCOMMAREA calling convention standard:
LINKAGE SECTION. 01 DFHCOMMAREA. 02 OPERATION PIC X(1). 02 OPERAND-1 PIC S9(9) BINARY. 02 OPERAND-2 PIC S9(9) BINARY. 02 FUNCTION-RESULT PIC S9(9) BINARY. PROCEDURE DIVISION USING DFHCOMMAREA. . . .
Most DFHCOMMAREA programs have a DFHCOMMAREA data item in their LINKAGE SECTION
and may address this item in the PROCEDURE DIVISION header. If you find this in your COBOL source
it's a clear indication it is a DFHCOMMAREA server program. But even if this is missing,
it can be a DFHCOMMAREA program, because there are alternative programming styles.
If you are unsure, consult a COBOL CICS specialist or see
Supported CICS COBOL Interface Types for more information.
See Step 4: Define the Extraction Settings and Start Extraction and CICS with DFHCOMMAREA Calling Convention - In same as Out for more information on extracting COBOL servers with this interface type.
The IDL Extractor for COBOL supports CICS programs using the channel container calling convention.
The following illustrates roughly how you can determine whether a COBOL server follows the Channel Container standard.
WORKING-STORAGE SECTION. 01 WS-CONTAINER-IN-NAME PIC X(16) VALUE "CALC-IN". 01 WS-CONTAINER-OUT-NAME PIC X(16) VALUE "CALC-OUT". . . . LINKAGE SECTION. 01 LS-CONTAINER-IN-LAYOUT. 02 OPERATION PIC X(1). 02 OPERAND1 PIC S9(9) BINARY. 02 OPERAND2 PIC S9(9) BINARY. 01 LS-CONTAINER-OUT-LAYOUT. 02 FUNCTION-RESULT PIC S9(9) BINARY. PROCEDURE DIVISION. . . . EXEC CICS GET CONTAINER (WS-CONTAINER-IN-NAME) SET (ADDRESS OF LS-CONTAINER-IN-LAYOUT) ... . . . EXEC CICS PUT CONTAINER (WS-CONTAINER-OUT-NAME) FROM (ADDRESS OF LS-CONTAINER-OUT-LAYOUT) ... . . .
Channel Container programs use EXEC CICS GET CONTAINER in their program body
(PROCEDURE DIVISION) to read their input parameters.
Output parameters are written using EXEC CICS PUT CONTAINER.
There is no clear indication in the linkage or working storage section to identify a
channel container program.
If you are unsure, consult a COBOL CICS specialist for clarification.
See Step 4: Define the Extraction Settings and Start Extraction and CICS with Channel Container Calling Convention for more information on extracting COBOL servers with this interface type.
This type of program has a defined DFHCOMMAREA interface to access
more than 31 KB of data in CICS. The interface is the same as the
webMethods WMTLSRVR interface. This enables webMethods customers to migrate to
EntireX.
Technically,
the DFHCOMMAREA layout contains a structure with a length and a pointer to a large buffer.
The following illustrates this:
LINKAGE SECTION.
01 DFHCOMMAREA.
10 WM-LCB-MARKER PIC X(4).
10 WM-LCB-INPUT-BUFFER POINTER.
10 WM-LCB-INPUT-BUFFER-SIZE PIC S9(8) BINARY.
10 WM-LCB-OUTPUT-BUFFER POINTER.
10 WM-LCB-OUTPUT-BUFFER-SIZE PIC S9(8) BINARY.
10 WM-LCB-FLAGS PIC X(1).
88 WM-LCB-FREE-OUTPUT-BUFFER VALUE 'F'.
10 WM-LCB-RESERVED PIC X(3).
01 INOUT-BUFFER.
02 OPERATION PIC X(1).
02 OPERAND-1 PIC S9(9) BINARY.
02 OPERAND-2 PIC S9(9) BINARY.
02 FUNCTION-RESULT PIC S9(9) BINARY.
. . .
PROCEDURE DIVISION USING DFHCOMMAREA.
. . .
SET ADDRESS OF INOUT-BUFFER TO WM-LCB-INPUT-BUFFER.
* process the INOUT-BUFFER and provide result
EXEC CICS RETURN.
The fields subordinated under DFHCOMMAREA prefixed with WM-LCB
describe this structure. The field names themselves can be different, but the COBOL data types must
match exactly.
data is described by separate structures, here INOUT-BUFFER in the linkage section.
If you find this in your COBOL source, it's a clear indication it is a large buffer program. If you are unsure, consult a COBOL CICS specialist for clarification.
See Step 4: Define the Extraction Settings and Start Extraction and CICS with DFHCOMMAREA Large Buffer Interface - In same as Out for more information on extracting COBOL servers with this interface type.
Standard call interfaces with a given number of parameters are supported. Every parameter addresses a fixed COBOL structure.
Technically, the COBOL server contains
a parameter list: PROCEDURE DIVISION USING PARM1 PARM2 ...
PARMn
the parameters in the linkage section as COBOL data items on level 1
See Step 4: Define the Extraction Settings and Start Extraction and Batch with Standard Linkage Calling Convention for more information on extracting COBOL servers with this interface type.
IMS message processing programs (MPP) get their parameters through an IMS message and return the result by sending an output message to IMS. The IDL Extractor for COBOL enables extractions from such programs.
The COBOL server contains:
a structure in the working storage section for the input and the output message.
an IOPCB in the linkage section used to read input messages and
write output messages using an IMS system call (i.e. CALL
"CBLTDLI").
The message contains also technical fields specific to IMS (see fields LL, ZZ
and TRANCODE in the picture above).
See Step 4: Define the Extraction Settings and Start Extraction and IMS MPP Message Interface (IMS Connect) for more information on extracting COBOL servers with this interface type.
IMS batch message processing programs (BMP) with PCB parameters are directly supported. You have the option to specify a PSB list as input to the extractor to locate PCB parameters.
Technically, the COBOL server contains
a parameter list: PROCEDURE DIVISION USING PARM1 PCB
PARM2 ... PARMn
IMS-specific PCB pointers within the parameter list
the parameters in the linkage section as COBOL data items on level 1
See Step 4: Define the Extraction Settings and Start Extraction and IMS BMP with Standard Linkage Calling Convention for more information on extracting COBOL servers with this interface type.
A file containing valid COBOL data items can be used to extract a COBOL Converter for the EntireX Adapter. In most cases the COBOL layout during input and output will be same:
See Step 4: Define the Extraction Settings and Start Extraction and COBOL Converter - In same as Out for more information on extracting COBOL with this interface type.
If required, the COBOL layout during input can be different as on output. For example input and output are described with
different REDEFINES clauses.
See COBOL Converter - In different to Out for more information on extracting COBOL with this interface type.
Other interface types, for example CICS with non-DPL-enabled
DFHCOMMAREA, can be supported by means of a custom wrapper. If you have to
extract from such a COBOL server, proceed as follows:
Implement a custom wrapper, providing one of the supported interface types above.
Extract from this custom wrapper.
To call your server program successfully, the target RPC runtime component used must support the interface type. The table below gives an overview of possible combinations of an interface type and RPC server.
| Interface Type of your Server Program | z/OS | Linux/Windows | IBM i | BS2000 | |||||
|---|---|---|---|---|---|---|---|---|---|
| CICS | Batch | IMS | CICS IPIC | CICS ECI | CICS Socket Listener | IMS Connect | AS/400 | Batch | |
CICS with DFHCOMMAREA Calling Convention
|
x | x | x | x | |||||
CICS with DFHCOMMAREA Large Buffer Interface
|
x | x | |||||||
| CICS with Channel Container Calling Convention | x | x | x | ||||||
| Batch with Standard Linkage Calling Convention | x | x | x | x | |||||
| IMS BMP with Standard Linkage Calling Convention | x | ||||||||
| IMS MPP Message Interface (IMS Connect) | x | ||||||||
| COBOL Converter | |||||||||
The table below gives an overview of COBOL interface types and EntireX Adapter connection types.
| Interface Type of your Server Program | EntireX Adapter Connection Type | Note |
|---|---|---|
CICS with DFHCOMMAREA Calling Convention
|
CICS ECI Connection or CICS Socket Listener Connection or CICS IPIC Connection |
|
CICS with DFHCOMMAREA Large Buffer Interface
|
CICS Socket Listener Connection | |
| CICS with Channel Container Calling Convention | CICS Socket Listener Connection or CICS IPIC Connection |
|
| Batch with Standard Linkage Calling Convention | AS/400 Connection | |
| RPC Connection or Direct RPC Connection |
RPC Server for Batch (z/OS | BS2000) | |
| IMS BMP with Standard Linkage Calling Convention | RPC Connection or Direct RPC Connection |
Use the RPC Server for IMS as RPC server. |
| IMS MPP Message Interface (IMS Connect) | IMS Connect Connection | |
| COBOL Converter | COBOL Converter Connection |