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. The property view to which the editor is connected supports you in mapping the COBOL server to the client interface.
The results of this process are two related files mapping the client interface to the COBOL server:
IDL File
The Software AG IDL (interface definition language) file 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.
SVM File
An SVM File (server mapping file) to complete the mapping is only generated if it
is required by the RPC server during runtime to call the COBOL server. A
SVM File Deployment
integrated in the Workbench assists you to deploy the server mapping to the RPC
server.
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 EntireX Workbench 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/OSD LMS libraries. See Extractor Service in the Batch | IMS | BS2000/OSD Batch RPC Server documentation. For this purpose, define a local or remote COBOL extractor environment. See IDL Extractor for 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 IDL Extractor for 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, Micro Focus
standard calling conventions, and IMS BMP server with PCB pointers. See Supported COBOL Interface Types.
Selecting the COBOL server interface manually with the
COBOL Parameter Selection 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 IDL Extractor for 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.
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 map the COBOL server interface selected in the Extractor Wizard to IDL. This section gives a short overview of the mapping features provided:
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.
See Providing IDL Directions (IN OUT INOUT).
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).
See Selecting REDEFINE Paths.
Suppress or hide unneeded fields in the IDL. This keeps the IDL client interface lean and also minimizes the amount of data transferred during runtime. See Suppressing or Hiding Unneeded Fields of the COBOL Server.
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. See Mapping COBOL Data Items to Constants.
For a COBOL server implementing multiple business functions controlled by an operation or function code field, multiple interfaces can be selected and modelled with the feature . See Mapping COBOL Functions to Multiple IDL Programs. If the IDL is processed further with a wrapper of the EntireX Workbench, 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 IDL Extractor for COBOL Preferences.
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. . . .
Typically DFHCOMMAREA programs have a DFHCOMMAREA data item in their Linkage Section
and 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 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
CICS DFHCOMMAREA under
COBOL Parameter Selection for more information.
See Step 4: Define the Extraction Settings and Start Extraction 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 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.
. . .
SET ADDRESS OF INOUT-BUFFER TO WM-LCB-OUTPUT-BUFFER.
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 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 generated COBOL server skeleton 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 Standard Linkage under COBOL Parameter Selection 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 Standard Linkage under COBOL Parameter Selection 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) in COBOL Parameter Selection 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 Standard Linkage under COBOL Parameter Selection for more information on extracting COBOL servers 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.
The SVM file (Server Mapping File) completes the Software AG IDL file with a mapping from the programming-language-neutral parameter definition in the IDL file to the parameters and data types expected by the COBOL server. In contrast to a CVM file, an SVM file is deployed to the server environment, see Server Mapping Deployment.
The SVM file contains
special COBOL constructs such as REDEFINE and
OCCURS DEPENDING ON
FILLER pseudo-parameters
map to constants
map to operation bindings to the COBOL server
IDL program names to be mapped to customized COBOL names; see Customize Automatically Generated Server Names
other information ...
SVM files obtained using the extraction process are required by the RPC server for correct mapping from the language-neutral parameter definition in the IDL file to the COBOL server. Therefore, the SVM file has to be deployed to the RPC server.
The RPC server can be batch (z/OS, z/VSE); CICS (z/OS, z/VSE); IMS (z/OS); Micro Focus (UNIX, Windows); BS2000/OSD.
A deployment wizard integrated in the EntireX Workbench supports in deploying the server mapping to the RPC server. See Server Mapping Deployment Wizard. Most RPC servers work together with the deployment wizard to receive server mappings.
Alternatively, depending on the RPC server, the server mapping can be deployed manually. See Deploying a Server Mapping File.