Extract the interface of the COBOL server subprogram      1 

For extraction, you first need an Eclipse™ project in Software AG Designer Copy or import the COBOL program and required copybooks into your Eclipse project. Switch to EntireX perspective and invoke the IDL Extractor for COBOL on the context menu of the COBOL program.

On the “Extraction Setting” page, use the correct interface type for your end-point (CICS®, IMS™, Micro Focus™, Batch, etc.). For this purpose, set the Operating System in the preferences first. This restricts interface types to those valid for this Operating System, which leaves you with a shorter list to search through. For an overview of interface types, refer to the EntireX documentation page Introduction to the IDL Extractor for COBOL.

As our COBOL server runs in z/OS® CICS® and uses the standard COMMAREA mechanism, we set “z/OS” and “CICS with DFHCOMMAREA calling convention” as the interface type (see Fig. 1). Press Next to enter the COBOL Mapping Editor:

Fig. 2: Designer snapshot on mapping COBOL data items to IDL parameters

The purpose of the COBOL Mapping Editor is to map COBOL data items to Interface Definition Language (IDL) parameters. It consists of three main areas:

1. The upper window pane is the COBOL program source.
2. The window pane on the left-hand side is the COBOL interface, consisting of COBOL data items representing the parameters in your COBOL server program.
3. The window pane on the right-hand side is the IDL interface consisting of IDL parameters.

You may ask why there are two interfaces: a COBOL interface and an IDL interface? There are very good reasons for this, as you will see below.

1. COBOL extraction is a two-step process:
   • First, select the COBOL parameters using the Add to and Remove from COBOL Interface (see Fig. 2) from the context menu on the COBOL data items in the upper window pane (COBOL source); in many situations the COBOL interface is detected by the Mapping Editor directly and you can omit this step. This is possible if there is a DFHCOMMAREA verb in the LINKAGE SECTION as it is for the most commonly used interface type “CICS with DFHCOMMAREA calling convention.”
   • Then map the COBOL parameters to IDL directions using the Map to In/Out/InOut buttons (see Fig. 2). COBOL parameters do not have directions, they are always INOUT. This step can be left out for a quick test in non-production scenarios; for real production it is recommended to set IDL directions to reduce data transfer.
     
2. There are alternative mappings available from COBOL data types (e.g., for REDEFINEs or tables) to IDL data types, which can be selected by the scenario developer. These possibilities enable scenarios with COBOL servers which do not exchange data in the usual way. In most situations, the default mapping set with the Map to In/Out/InOut buttons (see Fig. 2), fits. For more information, refer to EntireX documentation:
   COBOL> Software AG IDL Extractor for COBOL > COBOL to IDL Mapping > User-decided Mapping.
   
3. With the two interfaces, you see at a glance the current mapping from COBOL to IDL.
   
4. COBOL data items often have unpronounceable names; IDL parameters can be renamed (see Fig. 3).

For our example:

• Set Map to In for COBOL data item EMPLOYEE-ID as IDL direction (see Fig. 2). For EMPLOYEES-DETAILS and EMPLOYEES do similar Map to Out.

Use the function Rename from the context menu on the IDL parameters in the IDL interface pane (see Fig. 3) to rename COBOL Parameter EMPLOYEES-ID to IDL Parameter ID. Do the same for EMPLOYEE-DETAILS: Rename to EMPLOYEE.

Fig. 3: Designer snapshot on rename IDL parameter

Press Finish. The outcome is a Software AG IDL workbench file with the extension .idl (see Fig. 4):

Fig. 4: A Software AG IDL is the extraction result of a COBOL server extraction

If required, a server mapping file with the same name as the IDL file but the extension .cvm or .svm may be generated too, for technical reasons. This file must always be stored together with the concomitant IDL file. For more information, see the EntireX documentation: EntireX Workbench > Server Mapping Files for COBOL.

The Software AG IDL file can be treated as an intermediate result for further processing. It is the central starting point for all EntireX wrappers. EntireX generates communication source code for target RPC endpoints from Software AG IDL. An IDL to programming language binding exists for every EntireX supported RPC endpoint. In EntireX terminology and documentation, the runtime objects built from this generated code are called interface objects. For a deep dive into Software AG IDL, refer to the EntireX documentation: Reference > IDL File.

In our scenario, the COBOL server subprogram EMPLOYEE and the extracted interface EMPLOYEE match 1:1, field by field, see Figs. 1 and 4. By default, the IDL program name or interface name EMPLOYEE (see Fig. 4) and the IS Service name (see Fig. 9) are taken from the COBOL server program name (see Fig. 1).

Generate IS service and IS connection  2 

Generating the IS service and the IS connection is straightforward. Important settings are highlighted in the following designer snapshot (see Fig. 5). If you have not already done so, please switch to the EntireX perspective. Use the context menu of the Software AG IDL file to start the EntireX webMethods Integration Server Wrapper:

784×465 53.9 KB

On the first page Create or Update an Adapter Connection of the IS wrapper (see Fig.5), select the radio-button Create a new Integration Server connection; to connect to CICS® ECI select type CICS® ECI Connection too. Press Next for the second page. On the second page of the IS wrapper, you specify target package, target folder, connection name and CICS® ECI host / port parameters (see Fig.5).

Press Finish to get the IS service EMPLOYEE (see Fig. 6) and IS Connection EmployeesConnection as the result:

Fig. 6: Designer snapshot on generated EntireX adapter service Input/Output signature

You can use the generated EntireX adapter service like any other IS service; there is no difference. As the webMethods Integration Server developer, EntireX takes care of mapping COBOL-specific data types automatically to suitable Integration Server data types. For example: the COBOL OCCURS DEPENDING ON table EMPLOYEES (1:*) (Fig. 1), a variable-length array with EMPLOYEES-COUNT as the COBOL data item containing the upper-boundary, is mapped to the Integration Server document list EMPLOYEES (Figs. 6-7).

The input/output signature (structures inRec and outRec) is the result of using the Map to In/Out/Inout buttons (compare Fig. 2 and Fig. 6). Note also the renamed IS fields ID and EMPLOYEE (see Fig. 3 and Fig.6).

Test IS service to COBOL server subprogram  3 

For testing, use the service development perspective, as you do for every other IS service test.

Fig. 7: Designer snapshots on execution results of generated EntireX adapter service signature

For our IS service example EMPLOYEE, specify ‘L’ to invoke the LIST operation (Fig. 7). Similarly, you specify ‘D’ to call the DETAILS operation (Fig. 7). The interface requires exactly the same input as the original COBOL server (Fig. 1). Likewise, the output corresponds to the COBOL server too.

Summary

As demonstrated, it is quite easy to develop a scenario where webMethods Integration Server calls COBOL. You do not need any COBOL know-how. You can rely on EntireX to do all of the work for you from the design phase through runtime. COBOL-specific data types are mapped automatically to suitable Integration Server data types.