webMethods EntireX
Authored by Jürgen Lind, Senior Product Manager, Software AG and
Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG
Calling webMethods Integration Server from COBOL is easy and straightforward with EntireX. Read how EntireX builds the bridge between these irreconcilable technologies, and how constraints in the flow service interface can optimize the COBOL API.
COBOL is still relevant
Even if new investments are made in new technologies like webMethods Integration Server (IS), COBOL applications may continue to play a significant role in supporting your core business. This is not surprising given the huge investment your organization has poured into them.
Today, new business opportunities typically require a considerable digital representation, Internet-oriented interfaces, and business-to-business and business-to-consumer scenarios. Nevertheless, your existing COBOL applications need to connect to these new kinds of applications, which is preferable to reinventing them at high cost.
Using EntireX makes integrating these technologies easier than you think.
Order management example
Imagine that a new order management system is being developed with webMethods IS in your organization. A package OrderManagement with flow service placeOrder is provided. From your existing COBOL application, you’d like to call the flow service placeOrder on the IS.
Figure 1: webMethods IS flow service placeOrder
Look at the flow service placeOrder in Figure 1—the required inputs are the ID of the item to be ordered, a quantity and a customer ID. On output, the item name, unit and total price, customer address together with confirmation information are returned.
How can you call this flow service from COBOL? How do you establish a connection? How do you convert COBOL data to a webMethods IS data representation. Where can you find a developer with both COBOL and webMethods IS skills?
Fortunately, you do not need both skills at once. You only need EntireX! Figure 2 provides a sketch of how EntireX helps you connect COBOL with webMethods IS.
1 Extract
2 Generate
3 Test
Figure 2: Development Steps for Connecting COBOL to webMethods IS
EntireX supports many platforms with its COBOL code. On Windows® and UNIX®, you can use EntireX to generate code for Micro Focus® COBOL.
Extract the interface of webMethods IS Flow Service 1
To start, let’s create a project in Software AG Designer. The project is the container into which all extracted and generated EntireX artefacts are placed. Name this project COBOL placeOrder client.
Switch to the EntireX perspective to have EntireX menus directly available: Select Window > Perspective > Open Perspective > EntireX.
Then invoke the extractor: Select File > New > IDL Extractor for webMethods IS.
On the first page of the extraction step 1 enter the TCP/IP address of the webMethods IS to extract from. Press Next.
Figure 3: Extract Software AG IDL
For Source (Integration Server), select the package you want to extract from.
Next, select project COBOL placeOrder client as Target (Eclipse Workspace). Extraction results will be placed in that 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.
There is a technical gap going from COBOL to webMethods IS: COBOL only supports fixed-length data items, whereas webMethods IS has variable length types, often without any length restrictions. Parameters with no specified constraints will take the default fixed length. You can specify this default in field alphanumeric with fixed length of. For this example you’ll take: 256 as shown in Figure 3. You will again see the effect of this default later in this article.
Figure 4: Define Adapter Services for EntireX RPC Listener Connection
For calling webMethods IS from an RPC client, a listener is required. That’s why you check Create Listener Objects in Integration Server. Press Next.
On this page, you set the properties for the webMethods IS Listener that is waiting 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: your OrderManagementListener). Press Finish.
The listener and the connection appear in the package navigator as shown in Figure 4. For the package navigator, switch to the service development perspective (Select Window > Perspective > Open Perspective > Service Development).
The Software AG IDL is saved in the target eclipse workspace as selected: container COBOL placeOrder client and IDL File name OrderManagement.
Figure 5: Extracted Software AG IDL
The IDL placeOrder in Figure 5 is a description of the interface of the flow service placeOrder from Figure 1. 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 as shown in Figure 6. For more information on data type mapping, refer to IDL Extractor for Integration Server in the EntireX documentation.
Figure 6: Content Type Customized String
Generate COBOL Client Interface Object 2
To generate suitable COBOL code for your environment, select the correct target operating system first. Make sure the EntireX perspective is active: Select Window > Perspective > Open Perspective > EntireX; invoke the properties for the COBOL Wrapper: on the context menu of the IDL file select Properties > EntireX COBOL Wrapper; on the COBOL Wrapper property page set the Target Operating System; adapt the name of the generated COBOL program: select Customize automatically generated Client Names. Take ORDERCLT as the COBOL program’s name as shown in Figure 7.
Figure 7: Properties for COBOL Wrapper
For COBOL code generation, make sure the EntireX perspective is active: Select Window > Perspective > Open Perspective > EntireX; from context menu of the IDL file, select COBOL > Generate RPC Client. This generates the COBOL client ORDERCLT in folder client and a copybook in folder include as shown in Figure 8. The copybook is the COBOL programmer’s API to the flow service placeOrder (see Figure 1). It is for use in the COBOL application.
Figure 8: Generated COBOL Client
Not astonishingly, the length of generated COBOL parameters (see Figure 8) exactly matches the lengths extracted (see Figures 5 and 6). COBOL parameters always have a fixed length defined at compile time. They are not altered at runtime in reflection of actual string length as in modern programming languages. This means, that if you choose your default length (see Figure 3) you have to choose the maximum possible data size to ensure all data can be transmitted. On the other hand, doing so may needlessly increase the message size, if no constraints are set for fields of shorter data length. Therefore a good choice of default and of constraints is important.
Test extracted artifacts against IS flow service 3
For testing the extracted Software AG IDL from Figure 5, use the Software AG IDL Tester. Activate the EntireX perspective: Select Window > Perspective > Open Perspective > EntireX; on the context menu of the Software AG IDL file, select Software AG IDL Tester, shown in Figure 9.
Figure 9: Test Software AG IDL
Make sure your EntireX Broker is running with the same TCP/IP address specified as Broker ID during webMethods IS Listener generation (see Figure 4). Specify the same TCP/IP address for Broker in the Software AG IDL Tester (Figure 9): localhost:1971.
The same applies to the server address (Figure 4) and the field server (Figure 9). Set both of them identically to RPC/SRV1/CALLNAT.
Looking at the results in the Software AG IDL Tester in Figure 9, you can see that they are the same as when running the flow service in Software AG Designer in Figure 1.
Summary
As demonstrated, it is quite easy to develop a scenario where COBOL calls webMethods Integration Server. Constraints defined for the input and output parameters of the flow service help to get a tidy and practical COBOL interface. Other than the typical mainframe constraints (mostly eight characters in length), there is no further restriction on the name of the generated COBOL programs, so you can freely choose its name.
To learn more, read Common Integration Scenarios from webMethods EntireX documentation.