Calling COBOL DFHCOMMAREA (Minimal Footprint Using CICS Socket Listener) from REST

This scenario uses the tools IDL Extractor for COBOL and Integration Server Wrapper of the Designer.

This document covers the following topics:


Introduction

graphics/zos-cics-dfh-solution.png

graphics/blue_1.gif Extract the interface of the COBOL server program. See Using the IDL Extractor for COBOL - Overview.
graphics/blue_2.gif Generate REST resources, connection and adapter services in Integration Server.
graphics/blue_3.gif Execute the call from the REST client to the COBOL server program.

This scenario makes the following important assumptions:

For Task 1:

  • You have a working COBOL DFHCOMMAREA server. For illustration and examples on such a server, see CICS with DFHCOMMAREA Calling Convention.

  • You have access to the related COBOL sources and copybooks as files on your local machine. The minimum requirement is the DATA DIVISION of the interface. graphics/toc_closed.png More info

    graphics/intro-local.png

For Tasks 2 and 3:

Task 1: Extract the Interface of a COBOL Server

Introduction

Follow the instructions for extracting COBOL, see Using the IDL Extractor for COBOL - Overview and choose Scenario I: Create New IDL and Server Mapping Files if this is your first extraction. Learn how to invoke the IDL Extractor for COBOL, create a COBOL Extractor Environment and about the possibilities to select the COBOL source.

The extraction process creates the following EntireX metafiles:

  • IDL file. A Software AG IDL file contains definitions of the interface between client and server. See Software AG IDL File in the IDL Editor documentation.

  • Server mapping file (optional). The mapping file is a Designer file with extension .cvm that contains COBOL-specific mapping information. See Server Mapping Files for COBOL in the Designer documentation.

Sample COBOL Server used in the Examples

The following COBOL server is used to illustrate the features of the IDL Extractor for COBOL. Imagine an existing COBOL server called EMPLOYEE. It implements the access logic for a LIST and DETAILS function to a database view EMPLOYEE:

graphics/cob2many_extract_sample.png

Two approaches for extracting the COBOL server are described below:

  • Fast-track
    Learn how EntireX helps you to connect the COBOL Server with quick results.

  • User-defined Mapping
    The following features are among those available with a user-defined mapping:

    • Shape the interface to your COBOL server
      You can minimize the interface by suppressing COBOL server fields or by providing constant values. Renaming interfaces allows you to specify a readable long name. These two features together - constants and renaming of interfaces - are most powerful when multiple interfaces are implemented in a single COBOL server. Each function of the COBOL server triggered by an operation code or function code can be modelled as a separate REST resource method/operation.

    • Select alternative mappings
      You can select alternative mappings for COBOL data items (REDEFINEs, tables etc.) to enable scenarios with COBOL servers where data exchange is not fully described by the LINKAGE SECTION COBOL data items.

These approaches are described under Fast-track Method and Modern Method below.

Extracting a COBOL Server - Fast-track Method

Start of instruction setTo extract the COBOL Server

  1. Swich to the EntireX perspective.

  2. Call the IDL Extractor for COBOL.

  3. Set the correct interface type as described under Step 4: Define the Extraction Settings and Start Extraction under Scenario I: Create New IDL and Server Mapping Files in the IDL Extractor for COBOL documentation.

    graphics/cob2many_extract-vse-cics-dfh.png

  4. Set the correct value for checkbox Input Message same as Output Message.

    For our example, check the check box, because the COBOL layout for input is the same as the COBOL layout for output.

  5. Press Next to enter the COBOL Mapping Editor.

    graphics/cob2many_extract_fast-map.png

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

    • The upper window pane is the COBOL program source.

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

    • The window pane on the right-hand side is the IDL interface consisting of IDL parameters.

    What you select depends on check-box Input Message same as Output Message:

    • If there is a single COBOL data structure of the CICS message for input and output - check box Input Message same as Output Message is checked - you select a single COBOL data structure in the COBOL Mapping Editor. This structure is used for COBOL input as well as for COBOL output. For more information in this case see Mapping Editor User Interface in the IDL Extractor for COBOL documentation.

    • If there is a second COBOL data structure for the CICS output message - check box Input Message same as Output Message is cleared - you will select two COBOL data structures in the COBOL Mapping Editor. One is used for COBOL input and the other is for COBOL output. For more information in this case see Mapping Editor User Interface in the IDL Extractor for COBOL documentation.

    COBOL extraction is a two-step process:

    • First, select the COBOL parameters using the Add to and Remove from COBOL Interface 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.

    • Then map the COBOL parameters to IDL directions using the Map to In/Out/InOut buttons. 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. You also have the option to assign a meaningful name to an IDL parameter if the original COBOL data item is not self-explanatory.

    For our example:

    • Set Map to In for COBOL data item EMPLOYEE-ID as IDL direction (see screenshot in previous step). For EMPLOYEES-DETAILS and EMPLOYEES perform the similar Map to Out.

    • Use the function Rename from the context menu on the IDL parameters in the IDL Interface pane to rename COBOL parameter EMPLOYEES-ID to IDL parameter ID. Do the same for EMPLOYEE-DETAILS: Rename to EMPLOYEE.

    graphics/cob2many_extract_fast-5.png

  6. Press Finish. The default extraction settings ensure you get useful results. The outcome is a Software AG IDL file (interface definition language), a Designer file with extension .idl:

    graphics/cob2many_extract_fast-idl.png

    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 Server Mapping Files for COBOL in the Designer documentation. By default, the interface name EMPLOYEE is taken from the COBOL server program name.

Extracting a COBOL Server - Modern Method with User-defined Mapping

EntireX allows you to extract all implemented interfaces of the COBOL server separately. Instead of a large EMPLOYEE interface, separate interfaces getListOfEmployees and getDetailsOfEmployee are extracted. Each interface contains required parameters; obsolete parameters for an interface are suppressed, improving its usability.

Start of instruction setTo extract a COBOL server with a user-defined mapping

  1. Shape EMPLOYEE to getDetailsOfEmployee:

    graphics/cob2many_extract_user-1.png

    • Mark the OPERATION field in the COBOL Interface pane and press the Set Constant button. In the pop-up window, select OPERATION-DETAILS (red markers). The OPERATION-DETAILS value originates from COBOL level-88 data item (blue markers). If there is no COBOL level-88 enumeration type in the COBOL program defined, you can enter the function code manually in the pop-up window.

    • By default the IDL interface gets the same name as your COBOL server: EMPLOYEE. Use the Rename button graphics/icon_rename.png from the toolbar of the COBOL Mapping Editor and change the IDL interface name to getDetailsOfEmployee (blue markers). This name is used as the IS service name later.

  2. Continue shaping, making getDetailsOfEmployee easier to use:

    graphics/cob2many_extract_user-2.png

    • Use the context menu of the redefinition of the DETAIL field in the COBOL Interface pane, FILLER REDEFINES DETAIL and choose Map to Out (blue markers). A redefinition is a secondary layout (field types) of the same memory area. The redefinition contains more specific information (ANNUAL-SALARY, VACATION, etc.) than character buffer DETAIL. This is the reason why it is more useful in your interface.

    • Use the context menu of FILLER_1 in the IDL interface pane and rename FILLER_1 to DETAILS (green markers) for a readable IS service field name later.

    • The DETAILS function in the COBOL server does not make use of the EMPLOYEES field. Therefore you can leave it out of the interface: use the context menu of the EMPLOYEES field in the COBOL Interface pane and choose Suppress (red markers).

  3. Shape EMPLOYEE to getListOfEmployees Function:

    graphics/cob2many_extract_user-3.png

    The COBOL Mapping Editor allows you to define multiple IDL interfaces to the same COBOL server:

    • You create the additional IDL interface using the toolbar button Copy current IDL interface graphics/icon_copyIdl.png. (red markers). A new tab getDetailsOfEmployee1 is created. The previously extracted getDetailsOfEmployee interface still exists in the first tab. Once you reactivate the first tab, you will see the interface of getDetailsOfEmployee again.

    • Use the Rename button graphics/icon_rename.png from the toolbar of the COBOL Mapping Editor and change the IDL interface name to getListOfEmployees (blue markers). This name is used as the IS service name later.

    • For the LIST function you need the OPERATION-LIST value in the OPERATION field: Mark the OPERATION field in the COBOL Interface pane and press the Set Constant button. In the pop-up window, select OPERATION-LIST (similar to Step 1. above Shape EMPLOYEE to getDetailsOfEmployee; red markers).

    • Use the context menu of the EMPLOYEES field in the COBOL Interface pane, EMPLOYEES OCCURS 1 TO 99 and choose Map to Out (Similar to Step 2. above Continue shaping, making getDetailsOfEmployee easier to use; blue markers).

    • Because the EMPLOYEE and EMPLOYEE-DETAIL fields are not used in the COBOL server LIST function, you leave them out in the IDL interface: use the context menu of EMPLOYEE-DETAIL field in the COBOL Interface pane and choose Suppress (similar to Step 2. above Continue shaping, making getDetailsOfEmployee easier to use; red markers). Do the same for the EMPLOYEE-ID field.

  4. Press Finish to retrieve the extraction result in the form of a Software AG IDL file. At the same time, a server mapping file for COBOL (Designer file with extension .cvm) is created. See Server Mapping Files for COBOL. The Software AG IDL File describes the interfaces from the client point of view, while the server mapping file contains the mapping to the real COBOL server. Both of these files must be kept together and in sync, otherwise a call to the COBOL server may fail.

    graphics/cob2many_extract_user-4.png

    To summarize: We created two IDL interfaces. In the IDL file, these resulted in two IDL programs: getListOfEmployees and getDetailsOfEmployee. Both IDL programs were given readable names (Steps 1 and 3). Meaningful fields were kept, while superfluous fields were suppressed (Steps 1 and 3). The program getDetailsOfEmployee contains the redefined fields of parameter DETAILS (see below) mapped during extraction (Step 1).

    Note:
    During runtime, the RPC client generated with the extracted interface will send data for the redesigned interfaces, while your COBOL server still expects EMPLOYEE data. The EntireX runtime transforms the incoming data stream from the RPC client, using the server mapping file.

    graphics/cob2many_extract_user-4-note.png

Comparison Chart: Fast-track versus User-defined Mapping

The following table highlights the differences when shaping an interface with a user-defined mapping compared with a fast-path extraction.

  Interface Shaping with User-defined Mapping Fast-path Extraction
General User-defined interface with dedicated mapping. For our example, the interfaces are small and tidy and more self-explanatory with long, readable interface names. They are easier to use with the hidden OPERATION field and the suppressed COBOL fields, which are not needed. Automatic, quick result extraction with COBOL-like interfaces on IS. For our example, the IS interface EMPLOYEE matches exactly 1:1, field by field.
IS service(s) Multiple small and handy IS services; each OPERATION code is mapped to a separate IS service. One big IS service.
IS service name Readable long name. Short Subprogram name; up to 8 characters.
IS fields Usage of Suppress and Set Constant reduces the message length. This keeps focus on relevant data items and keeps the client's interface clean. It may also improve performance. The IS fields and COBOL server parameters match 1:1. As COBOL layout descriptions are sometimes used for many different purposes, irrelevant data items appear and clutter up the IS interface.
OPERATION parameter Suppressed: the OPERATION parameter does not exist in the IS service as an IS field. The OPERATION parameter exists in the IS service as an IS field and needs to be filled-in by the client endpoint.
OPERATION code The OPERATION code is provided internally by EntireX runtime in the OPERATION field. The OPERATION code needs to be specified in the IS service in the OPERATION field by the client endpoint.
REDEFINE parameters Either the parameter that is redefined or one of its redefinitions is available as an IS field. Only the parameter that is redefined is available as an IS field. Redefinitions of the parameter are not available as IS fields.

A user-defined mapping enables you also to define alternative mappings for COBOL data items (REDEFINEs, tables etc.). These enable scenarios with COBOL servers where data exchange is not fully described by the LINKAGE SECTION COBOL data items. For more information refer to the IDL Extractor for COBOL documentation:

Testing the Extraction Results

The following pictures use the extraction results described under Extracting a COBOL Server - Modern Method with User-defined Mapping.

Start of instruction setTo test the extraction results (optional)

  1. You can test the results of the extraction operation and the REST server back end, using the EntireX IDL Tester. From the context menu of the IDL file in the Designer, choose Software AG IDL Tester.

    graphics/many2many_extract_test-1.png

  2. Select getDetailsOfEmployee.

    graphics/cob2many_extract_test-2.png

    Note that the broker and server parameters contain the explicit route to call the server program, and you can optionally ping the connection from this client. With the File > Options dialog, you can set:

    • User and Password for broker authentication

    • RPC User ID and RPC Password for server authentication

    See EntireX IDL Tester in the Designer documentation.

  3. Check the Integration Server log, the EntireX Adapter log or the RPC logs. Applies to all connection methods.

Task 2: Generate the REST Resources, Connection and Adapter Services in Integration Server

This section describes your first steps to create a new Integration Server connection. This is described in more detail under Using the Integration Server Wrapper, for example working with existing Integration Server connections. This section covers the following topics:

Step 1: Start the Integration Server Wrapper Wizard

Start of instruction setTo start the Integration Server Wrapper wizard

  1. In the context menu of a Software AG IDL file, choose Integration Server > Generate webMethods IS Connection.

    This starts the wizard with a list of existing Integration Server Wrapper connections.

    Note:
    If the selected IDL file is not valid because of a syntax error, an error dialog comes up and the wizard does not start.

  2. Continue with Step 2: Create a New Integration Server Connection.

Step 2: Create a New Integration Server Connection

graphics/using_createNew.png

Start of instruction setTo create a new Integration Server connection

  1. Define the new Integration Server connection on the wizard page.

    Notes:

    1. The only required field is Server. Enter the hostname of the Integration Server including an optional port number. If no port number is specified, port number defaults to "5555". The Integration Server Authentication can be passed with the User and Password fields.
    2. Optional settings are for secure connections. The Truststore for HTTPS contains all signed certificates and must be a valid truststore.
    3. The check box Verify host name checks that the hostname is entered in the stored certificate.
    4. When the Integration Server has Client Authentication enabled, you can specify your Keystore file and keystore Password.
    5. For managing Integration Server connections, see Integration Server Preferences in the Integration Server Wrapper documentation.
  2. Choose Next and continue with Step 3: Select the Connection Type.

Step 3: Select the Connection Type

graphics/generate_connectionType-socket.png

Start of instruction setTo create a new connection

  1. Select a connection type from the drop down list. Connection types are described under EntireX Adapter Connections in the EntireX Adapter documentation and Introduction to the Integration Server Wrapper.

    Note:
    The list of connection types is filtered: connection types that require a license are only shown if a corresponding license file is available. Reliable RPC connections are only shown if all IDL programs contain only IN parameters. Also, if a server mapping file is available, only those connection types that support the interface type specified in the server mapping file are shown.

  2. Check the box Create or Update REST resource.
  3. Click Next and continue with Step 4: Define Adapter Services for a CICS Socket Listener Connection.

Step 4: Define Adapter Services for a CICS Socket Listener Connection

graphics/generate_define-socket.png

Start of instruction setTo create a connection and related adapter services

  1. Select a package for the created objects.

  2. Define a folder name. If the folder does not exist, it will be created.

  3. Define a connection name.

  4. Define the parameters of the connection type. For details, see the EntireX and your webMethods Integration Server Applications.

    As a result, the folder will contain the connection and the adapter services (one for each IDL program). The name of a service is the same as the respective IDL program.

The default settings for the adapter services are:

  • the Default package; if not available, the first package

  • the IDL library name for the Folder Name

  • the IDL library name with the suffix "Connection" for the Connection Name

Note:
When creating a connection, a package dependency is added such that the selected package depends on webMethods EntireX (the package WmEntireX) with the version currently used.

Step 5: Create or Update a REST Resource

Start of instruction setTo create or update a REST resource

Make sure checkbox Create or Update REST resource is checked.

  1. Select a package.

    graphics/using_define-rpc-rest.png

  2. Define a folder name. If the folder does not exist, it will be created.

  3. Define the REST Resource name.

  4. Check Update existing Resource if you want to add additional services to an existing resource.

Step 6: Edit the REST Resource

Start of instruction setTo edit the REST resource

  1. Switch to the Service Development perspective of Software AG Designer.

    graphics/generate_edit-rest.png

  2. Refresh the package where you generated the REST Resource in the previous step.

  3. Open the REST Resource.

  4. Edit the REST URLs and HTTP Methods to match the functionality of your application.

For more information see:

  • REST Developer's Guide in the webMethods Integration Server documentation for information on using the generated REST resources

  • Configuring a REST Resource Using the URL Template-Based Approach in the online help provided under Software AG Designer Guides > webMethods Service Development Help > Working with REST

Task 3: Execute the Call from the REST Client to COBOL

Use an appropriate REST client, specify URL, Method and Headers and invoke your REST resource:

graphics/many2rest_test.png