Calling Integration Server from COBOL under z/VSE CICS

This document covers the following topics:

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

Introduction

graphics/is2cob-common_intro.png

graphics/blue_1.gif Use IDL Extractor for Integration Server to generate Integration Server connections and listeners from the Integration Server service to be called.
graphics/blue_2.gif Generate client interface objects and build COBOL client application.
graphics/blue_3.gif Execute the call from the COBOL client to the Integration Server service.

This scenario makes the following important assumptions:

For Task 1:

  • You have an Integration Server with the EntireX Adapter installed.

For Task 3:

  • You have an Integration Server with the EntireX Adapter installed.

  • You can call the Integration Server service at runtime using different methods:

    • EntireX RPC
      For the EntireX RPC connection method you need EntireX Broker on one of the supported platforms: z/OS | UNIX | Windows | BS2000/OSD | z/VSE.

      graphics/is2cob-common_intro_assume.png

    • EntireX Direct RPC
      For the EntireX Direct RPC connection method there are no additional prerequisites.

      graphics/is2cob-common_intro_assume-directRpc.png

Task 1: Generate Integration Server Connections and Listeners

This section describes your first steps to create a new Integration Server connection. This process creates the following:

  • a Software AG IDL file (metafile) in the EntireX Workbench; an IDL file contains definitions of the interfaces between client and server. See Software AG IDL File in the IDL Editor documentation and Mapping Software AG IDL to Integration Server Data Types in the Integration Server Wrapper documentation

  • a server connection

  • one of the following in Integration Server, depending on connection type specified in Step 4: Select the Connection Type below:

    • an RPC Listener

    • a Reliable RPC Listener

    • a Direct RPC Listener

The following steps are described in more detail under IDL Extractor for Integration Server.

Step 1: Start the IDL Extractor for Integration Server

Start of instruction setTo start the IDL Extractor for Integration Server

  1. The IDL Extractor is a New Wizard in Eclipse. Choose New from the file menu, select IDL Extractor for webMethods IS in the following page and choose Next.

    Note:
    You can also choose New from the toolbar or context menu of a view showing resources. Also Ctrl-N starts the selection of the New Wizards.

  2. If you are using the wizard for the first time without any predefined Integration Server connections, continue with Step 2: Connect EntireX Workbench with Integration Server below.

graphics/using_startExtractor.png

Step 2: Connect EntireX Workbench with Integration Server

Start of instruction setTo create a new Integration Server connection

  1. Define the new Integration Server connection on the following wizard page. The only required field is Server. graphics/toc_closed.png More info

    graphics/using_createNewConnection.png

  2. Choose Next and continue with Step 3: Select the Integration Server Package to Extract.

Step 3: Select the Integration Server Package to Extract

graphics/using_selectPackage.png

Start of instruction setTo extract the IDL from the selected package

  1. Select the package to extract (from the list indicated by Source), for example the package "Default" in the screen above.

  2. Specify the target. By default, the wizard tries to find a valid container based on your position in the Navigator or Package Explorer View.

    Or:
    Choose Browse... to select a container from your workspace.

    Notes:

    1. The IDL file name is based on the selected Integration Server package from the list below, but this is only a proposal and can be changed.
    2. If the file name already exists in your container, a warning will be displayed in the title area of the wizard page.
    3. If the extension "idl" is not specified, it will be added automatically.

  3. Optimize the extracted IDL. Use the combo-box and select the target programming language:

    • COBOL
      For usage with the COBOL Wrapper. Enter the default length for IDL type A(default-length) fields which map then to COBOL alphanumeric data items PIC X(default-length).

  4. For this scenario, make sure Create Listener Objects in Integration Server is checked.

  5. Choose Next to store the IDL file in the selected container in the Eclipse workspace. When you go to the next page, the Back button is disabled, because the IDL file has already been created and this step cannot be reverted.

Step 4: Select the Connection Type

graphics/using_selectConnection.png

Start of instruction setTo select the connection type

As a prerequisite, the IDL file has been stored in the workspace and the Back button is now disabled.

  • Select a Connection type and click Next.

    Notes:

    1. An EntireX RPC Listener connection is always available.
    2. An EntireX Reliable RPC Listener connection is available if all IDL programs contain only IN parameters.
    3. An EntireX Direct RPC Listener connection is available if it is enabled by the license for the webMethods EntireX Adapter.

Step 5: Define a Listener

graphics/using_defineListener.png

Start of instruction setTo define a listener

  1. Select an Integration Server package where the listener will be stored.

  2. Specify the names for Folder Name (default: library name), Connection Name (default: library nameConnection) and Listener Name (default: library nameListener).

  3. Advanced users: You can alter the Integration Server services in the table headed by the RPC Program Name and IS Service Name. Note that a selected service must exist in some package of the Integration Server! This step is not recommended. Only perform it if required.

  4. If necessary, edit the Broker settings for the Listener (Broker ID, Server Address, User ID, Password, and Encoding).

  5. The check box Overwrite existing Objects in Integration Server can be used to re-generate the objects after you have changed the IDL file.

    Notes:

    1. The check box Overwrite existing Objects in Integration Server is useful for re-generating objects created previously. However, you cannot overwrite an RPC Listener Connection or a reliable RPC Listener Connection with a connection of a different type. If the connection is deleted with the Adapter Administration UI, it is not possible to overwrite the objects. In this case, you have to delete the adapter services in the Designer.
    2. 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.

  6. Choose Finish.

    As a result, the following objects will be created:

    • one connection of type EntireX RPC Listener, EntireX Reliable RPC Listener or EntireX Direct RPC Listener

    • one listener object

    For a connection of type EntireX Reliable RPC Listener the following objects will be created in addition for each IDL program:

    • one notification object

    • one trigger object

    • one document type object

Task 2: Generate Client Interface Objects and Build Client Application

This section covers the following topics:

Set Generation Options (Properties) for the COBOL Wrapper

From the context menu on the IDL file extracted as described under Task 1: Generate Integration Server Connections and Listeners above, choose Properties > EntireX COBOL Wrapper and set the following properties:

  • Set the Target Operating System to "z/VSE".

  • Set the Client Interface Type to one of the following:

    • DFHCOMMAREA Calling Convention
      In this scenario, the generic RPC services module and the broker stub are linked together to a CICS program. The COBOL client program, every generated client interface object and the generic RPC services module together with the broker stub are installed each as separate individual CICS programs.

      Use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention in the following situations:

      • You want to have an EXEC CICS LINK DFHCOMMAREA interface to your client interface object(s).

      • The restriction of the COMMAREA length suits your purposes. Because the RPC communication area is also transferred in the COMMAREA, the effective length that can be used for IDL data is shorter than the CICS COMMAREA length. Nearly 31 KB can be used for IDL data.

      • You wish to separate the generic RPC service module and the broker stub from the client interface object(s).

      • You require a program link to the client interface object(s).

    • Standard Linkage Calling Convention
      The COBOL Wrapper can be used with a call interface, even in CICS. This means you can build a client application where the COBOL client program, every generated client interface object, the generic RPC services module and the broker stub are linked together, similar to the batch scenario. See Using the COBOL Wrapper for Batch (z/OS, BS2000/OSD, z/VSE and IBM i).

      Using a call interface within CICS may be useful if

  • Clear the option Generate Generic RPC Service Module COBSRVI.

graphics/is2cob-common_generate-client_props.png

Depending on your choice of calling convention, continue with

Build the Client Application with DFHCOMMAREA Calling Convention to Client Interface Objects

The steps are described in more detail under Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE):

Start of instruction setTo use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention

  1. Generate the client interface object for the target operating system, and use interface type "CICS with DFHCOMMAREA calling convention". See Generating COBOL Source Files from Software AG IDL Files. You do not need to generate the generic RPC service module COBSRVI because this is already installed on the mainframe, so clear the check box. graphics/toc_closed.png More info

  2. If necessary, use FTP to transfer the client interface object(s) to the target platform where you write your client application.

  3. If you have generated the generic RPC service module and you plan to (re)install it within CICS, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL client program. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile:

    • the generated client interface object(s)

    • your COBOL client program.

    Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. See your compiler documentation.

  6. Using the standard linker (binder) of the target platform, link (bind) the following programs to separate CICS programs:

    • every generated client interface object

    • your COBOL client program.

  7. Install every client interface object and your COBOL client program as separate CICS programs.

  8. Make sure the correct broker stub is used and can be called dynamically by the CICS generic RPC service module COBSRVIC.

    See the broker installation documentation and use a broker stub for CICS (for example BKIMC), see sublibrary EXX960.

Build the Client Application with a Call Interface to Client Interface Objects

graphics/is2cob-common_generate-client_build-call.png

The following steps are described in more detail under Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE):

Start of instruction setTo use the COBOL Wrapper with a call interface within CICS

  1. Generate the client interface object(s) for the target operating system, and use the interface type "CICS with standard calling convention". See Generating COBOL Source Files from Software AG IDL Files. You do not need to generate the generic RPC service module COBSRVI, so clear the check box. graphics/toc_closed.png More info

  2. If necessary, use FTP to transfer the client interface object(s) to the target platform where you write your client application.

  3. If you have generated the generic RPC service module and you plan to (re)install it within CICS, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL client program. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile:

    • the generated client interface object(s)

    • your COBOL client program

    Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. See your compiler documentation.

  6. Using the standard linker (binder) of the target platform, link (bind) all translated and compiled modules, and, if required, the broker stub, together to the client application (that is, a CICS program), using the standard linker (binder) of the target platform.

  7. Install the client application within CICS.

  8. Make sure the correct broker stub is used and can be called dynamically by the generic RPC service module COBSRVI.

    See the broker installation documentation and use a broker stub for CICS (for example BKIMC), see sublibrary EXX960.

Task 3: Execute the Call from COBOL to Integration Server

After building your client application in Task 2 above, you can test your scenario.