Introduction to the IDL Extractor for COBOL


Introduction

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.

graphics/intro.png

graphics/blue_1.gif Start the wizard, select your server program and make COBOL-specific settings.
graphics/blue_2.gif 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.
graphics/blue_3.gif Optional. If necessary, you can modify the parameter selection from the Mapping Editor.
graphics/blue_4.gif Fine-tune the COBOL to IDL mapping.
graphics/blue_5.gif 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 during runtime to call the COBOL server. See Server Mapping Files for COBOL.

Extractor Wizard

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 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, Micro Focus standard calling conventions, 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.

Mapping Editor

graphics/common_mappingEditor.png

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 lean 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 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.

Supported COBOL Interface Types

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.

Supported CICS COBOL Interface Types

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 (z/OS | z/VSE).

    • 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.

CICS with DFHCOMMAREA Calling Convention

The IDL Extractor for COBOL supports CICS programs using the standard DFHCOMMAREA calling convention.

graphics/intro_interfaces_dfh.png

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.

CICS with Channel Container Calling Convention

The IDL Extractor for COBOL supports CICS programs using the channel container calling convention.

graphics/intro_interfaces_channel.png

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.

CICS with DFHCOMMAREA Large Buffer Interface

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.

graphics/intro_interfaces_large.png

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.

Micro Focus with Standard Linkage Calling Convention

Standard call interfaces with a given number of parameters are supported. Every parameter addresses a fixed COBOL structure.

graphics/intro_interfaces_batch.png

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 Micro Focus with Standard Linkage Calling Convention for more information on extracting COBOL servers with this interface type.

Batch with Standard Linkage Calling Convention

Standard call interfaces with a given number of parameters are supported. Every parameter addresses a fixed COBOL structure.

graphics/intro_interfaces_batch.png

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 MPP Message Interface (IMS Connect)

graphics/intro_interfaces_mpp.png

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 BMP with Standard Linkage Calling Convention

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.

graphics/intro_interfaces_bmp.png

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.

COBOL Converter

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:

graphics/intro_interfaces_cob-1.png

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.

graphics/intro_interfaces_cob-2.png

See COBOL Converter - In different to Out for more information on extracting COBOL with this interface type.

What to do with other Interface Types?

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:

  1. Implement a custom wrapper, providing one of the supported interface types above.

  2. Extract from this custom wrapper.

Compatibility between COBOL Interface Types and RPC Server / EntireX Adapter

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. For the EntireX Adapter, the appropriate connection is required.

Interface Type of your Server Program RPC Server EntireX Adapter Note
z/OS UNIX/Windows IBM i BS2000 z/VSE
CICS Batch IMS CICS ECI Micro Focus IMS Connect AS/400 Batch CICS Batch
CICS with DFHCOMMAREA Calling Convention x     x         x   CICS ECI Connection 1
CICS with DFHCOMMAREA Large Buffer Interface x               x     2
CICS with Channel Container Calling Convention x                     2
Batch with Standard Linkage Calling Convention   x x       x x   x AS/400 Connection 3
Micro Focus with Standard Linkage Calling Convention         x             2
IMS BMP with Standard Linkage Calling Convention     x                 2
IMS MPP Message Interface (IMS Connect)           x         IMS Connect Connection 1
COBOL Converter                     COBOL Converter Connection  

Notes:

  1. Alternatively if your scenario requires Reliable RPC, see Connection Parameters for Reliable RPC Connections in the EntireX Adapter documentation.
  2. The interface type is not supported directly with the EntireX Adapter. Use one of the RPC connection types (see EntireX Adapter Connections) to an appropriate RPC server (see table).
  3. To call your server program on a platform other than IBM i, see Note 2.