This document covers the following topics:
Task 1: Generate Integration Server Connections and Listeners
Task 2: Generate Client Interface Objects and Build Client Application
This scenario uses the EntireX Workbench tools IDL Extractor for Integration Server and COBOL Wrapper of the Software AG Designer.
Use IDL Extractor for Integration Server to generate Integration Server connections and listeners from the Integration Server service to be called. | |
Generate client interface objects and build COBOL client application. | |
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:
This section covers the following topics:
Follow the instructions for extracting a webMethods Integration Server (IS) service under Using the IDL Extractor for Integration Server.
This process creates the following EntireX metafiles:
an IDL file, containing definitions of the interface between client and server; see Software AG IDL File in the IDL Editor documentation
a webMethods IS Connection
a webMethods IS Listener, depending on connection type:
an RPC Listener
a Reliable RPC Listener
a Direct RPC Listener
Connection types are described under Creating Listener Objects in Integration Server.
Imagine that a new order management system is being developed with webMethods Integration Server in your organization. A package OrderManagement with flow service is provided. From your existing COBOL application you would like to call the flow service placeOrder on the IS.
The following input is required:
ID of the item to be ordered (OrderItemID)
a quantity (OrderQuantity)
customer ID OrderCustomerID)
The following output is returned:
item name (OrderItemName)
unit and total price (OrderUnitPrice and OrderTotal)
etc.
First create a project in Software AG Designer. This project is the container into which all extracted and generated EntireX artifacts are placed. Name this project COBOL placeOrder client.
To start the IDL Extractor for Integration Server
Switch to the EntireX perspective.
Invoke the IDL Extractor for webMethods IS, which is a New Wizard in Eclipse. From the
menu, choose . Select IDL Extractor for webMethods IS in the following page.Or:
Choose from the toolbar or context menu of a view showing resources.
Or:
Press to start the selection of the New Wizards.
If you are using the wizard for the first time without any predefined Integration Server connections, enter the TCP/IP address of the webMethods IS to extract from. Otherwise select the connection to the Integration Server.
Press
.To extract the IDL from the selected package
Under Source (Integration Server), select the package you want to extract from.
For Target (Eclipse Workspace), specify project COBOL placeOrder client. Extraction results will be placed in this container. You can keep the IDL File Name as it has been derived from the package name by default. Since COBOL is your desired endpoint, select Optimize extracted IDL for usage with: COBOL.
Note:
COBOL only supports fixed-length data items, whereas webMethods IS has variable length types, often without any length restrictions
(constraints).
Parameters with no specified constraints will take the default fixed length. You can specify this default in field alphanumeric
with fixed length of. Use 256 for this example. You can see the effect of this default under
Viewing the Extracted IDL.
A listener is required for calling webMethods IS from an RPC client, so check Create Listener Objects in Integration Server.
Press
.To create Listener Objects in Integration Server
Select the connection type, one of EntireX RPC Listener, EntireX Reliable RPC Listener or EntireX Direct RPC Listener. Please note:
An EntireX RPC Listener connection is always available.
An EntireX Reliable RPC Listener connection is available if all IDL programs contain only In parameters.
An EntireX Direct RPC Listener connection is available if it is enabled by the license for the webMethods EntireX Adapter for Integration Server.
On this page, you set the properties for the listener objects to create; these objects will wait for the incoming COBOL requests. Select the package and specify the folder name into which the listener is generated. If the folder does not exist, it will be created automatically.
Keep the defaults given for RPC Listener Connection to EntireX. The Broker ID is a TCP/IP or SSL/TLS address and Server Address is an EntireX-specific namespace to locate a target server (here: OrderManagementListener).
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.
Press
. The listener and the connection appear in the package navigator. For the package navigator, switch to the service development perspective by choosing .To view the extracted the IDL
The Software AG IDL is saved in the target Eclipse workspace as selected: container COBOL placeOrder client and IDL file OrderManagement.idl:
The IDL placeOrder is a description of the interface of the flow service placeOrder. See Sample webMethods IS Service above.
Parameters with no constraints specified are given the specified default length of 256. During runtime, if concrete business data fits into the length given (either by constraint or by default), then you are on the safe side. However, if the runtime data length exceeds the data field length, then you will not be able to transport the full data length. Therefore you have to choose both the data length constraints and the default carefully. See also note under To extract the IDL from the selected package above.
For more information on data type mapping, see Mapping Integration Server Data Types to IDL in the IDL Extractor for Integration Server documentation.
This section covers the following topics:
To set generation options (properties) for the COBOL Wrapper
To generate suitable COBOL code for your environment, first set the correct target operating system. Make sure the EntireX perspective is active (
) and call the properties of the COBOL Wrapper.From the context menu of the IDL file, choose Properties page, set the Target Operating System
. On the COBOL WrapperAdapt the name of the generated COBOL program: Choose Customize automatically generated Client Names. Take ORDERCLT as the COBOL program's name.
To generate COBOL Code
For COBOL code generation, make sure the EntireX Perspective is active: Choose
. From context menu of the IDL file, choose . This generates the COBOL client ORDERCLT in folder client and a copybook in folder include:The copybook is the COBOL programmer's API to the flow service placeOrder. See Sample webMethods IS Service. It is for use in the COBOL application. .
As you would expect, the length of generated COBOL parameters exactly matches the lengths extracted. See Viewing the Extracted IDL. COBOL parameters always have a fixed length defined at compile time. They are not altered at runtime to reflect actual string length as in modern programming languages. This means that if you choose your default length (see Extracting the Interface of the webMethods IS Service) you have to choose the maximum possible data size to ensure all data can be transmitted. However, this may needlessly increase the message size if no constraints are set for fields of shorter data length. Choose your defaults and contstraints carefully.
In this scenario, the COBOL client program, every generated client interface object, generic RPC services module and the broker stub are linked together to the client application.
See Using the COBOL Wrapper for Micro Focus (UNIX and Windows).
For testing the extracted IDL File, activate the EntireX Perspective with , and from the context menu of the IDL file choose .
To execute the call
Make sure your EntireX Broker is running with the same TCP/IP address specified as Broker ID during webMethods IS Listener generation. See Creating Listener Objects in Integration Server.
Specify the same TCP/IP address for Broker in the Software AG IDL Tester: localhost:1971.
Also set the Server Address (see Creating Listener Objects in Integration Server) and the field Server in IDL Tester identically: RPC/SRV1/CALLNAT.
Looking at the results in the EntireX IDL Tester you can see that they are the same as when running the flow service in the Software AG Designer (see Sample webMethods IS Service).