webMethods Entirex
Authored by Jürgen Lind, Senior Product Manager, Software AG and Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG
There is no doubt that calling webMethods Integration Server (IS) from Software AG’s own programming language Natural is supported best with EntireX. Read how easy it is to develop a Natural to webMethods IS scenario with EntireX.
Use Natural in your Digital Transformation
Natural plays a significant role in supporting your core business and we strongly believe it will continue to play a role in your Digital Transformation.
To meet the demands of today’s consumers and business users, you must address business-to-business and business-to-consumer scenarios that demand access via the web, mobile, the cloud and the Internet of Things. Fortunately, agile development methodologies are available to help you quickly build business applications for the digital age. You likely invested in new applications and technologies like webMethods IS to accomplish these objectives.
EntireX makes integrating new technologies with your existing Adabas & Natural applications 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 Natural application, you’d like to call the flow service placeOrder on the IS. (You may recognize that this OrderManagement example was used in How to call webMethods Integration Server from COBOL – mainframe outbound in TECHniques Issue 4, 2016.)
Figure 1: Connecting Natural to webMethods IS
1 Extract 2 Generate 3 Test
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.
Using the development pattern extract to generate and test EntireX frees you from data conversion, connection establishment and Application Programming Interface (API) implementation tasks—even a Natural client is generated. This generated Natural client can be used for testing and as a starting point to extend an existing Natural application. The Natural client works in any Natural supported environment and can be re-hosted easily (copy, move, FTP and catalog) to any operating system (z/OS®, z/VSE®, BS2000®, Windows®, UNIX®).
A developer with both webMethods IS and Natural skills is not needed.
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 artifacts are placed. Name this project Natural placeOrder client.
Switch to the EntireX perspective. This way you’ll have the EntireX menus directly available: Select Window > Perspective > Open Perspective > EntireX.
Then invoke the extractor for the RPC Interface Description Language (IDL): 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 2: Extract Software AG IDL and generate listener.
Select the package from webMethods IS you want to extract from, as shown in Figure 2. Then, select project Natural placeOrder client as Target (Eclipse™ Workspace). Extraction results will be placed in this container. You can keep the IDL file name as it was derived from the package name by default. Since Natural is your desired endpoint, select Optimize extracted IDL for usage with Natural.
With Map Integration Server data type to IDL (see Figure 2), you define the default for webMethods IS variable length types with no specified constraints. For historic reasons, you have two options:
- Map them to Natural variable-length strings—these are called Natural DYNAMIC variables
- Map them to classical Natural fixed-length strings
We will shed light on various aspects of both options later in this article.
To call webMethods IS from a Remote Procedure Call (RPC) client, a listener is required. That’s why you check Create Listener Objects in Integration Server. Press Next.
On the following page, you set the properties for the webMethods IS Listener that is waiting for the incoming Natural requests. Select the package and specify the folder name where you wish the listener to be generated. After pressing Finish, the listener and the connection appear in the package navigator as shown in Figure 2. For the package navigator, switch to the service development perspective (Select Window > Perspective > Open Perspective > Service Development).
The Software AG IDL with program placeOrder is saved in the target Eclipse workspace as selected: container Natural placeOrder client and IDL file name OrderManagement.idl as shown in Figure 3:
Figure 3: Extracted Software AG IDL – IDL types depend on IS parameter constraints and mapping defaults.
The IDL file is the central artifact from which Natural code is generated later in Generate Natural client 2 . Extracted Software AG IDL data and resulting Natural types in the generated API, as shown in Figure 4, depend on the existence of constraints and on concrete extraction settings such as: Map Integration Server data type to IDL option fixed-length and variable-length as shown in Figure 2.
It is best if the Natural types fit to your data, meaning:
- Numeric data should be mapped to numeric Natural types, of the appropriate range. In our example this is the case for OrderItemID, OrderQuantity and OrderCustomerID.
- For string data where the length is known, set a length constraint. This is the case for OrderUnitPrice, OrderTotal, ZipCode and CountryCode. For fixed-length short fields (one to four bytes), this shortens the message length and improves performance.
- We recommend that you set the option variable-length (Figure 2) as the default to be used for string data where the length is unknown and no length constraint could be set as for IS parameter OrderShippingDate and OrderConfirmationFlag. This result is IDL type AV (Figure 3, left IDL example) and last, but not least, in Natural type A DYNAMIC in the generated API (Figure 4). You have more freedom and no limitations on the length of the string being transferred.
The option fixed-length is available for historic reasons. All IS string parameters without constraints will be mapped to the classical fixed-length Natural type A with a specific length. In our example, A256 is set as both Natural and IDL type (Figure 3, right IDL example). This limits the possible transferred length to a maximum of 256 characters.
Generate Natural Client
For Natural code generation, make sure the EntireX perspective is active: Select Window > Perspective > Open Perspective > EntireX. Invoke the Natural Wrapper on the context menu of the IDL file by selecting Natural > Generate RPC Client:
Figure 4: Natural Wrapper Page and Generated Natural Source Files
In the Natural Wrapper, you can specify the names of the generated Natural files to fit with your specific naming convention (Figure 4). The following three Natural files will be generated:
- A client subprogram—also named CALLNAT (a statement to execute a subprogram in Natural)—that, in EntireX terminology, acts as the client interface object with a filename extension of NSN;
- A client Parameter Data Area (PDA), the interface of Natural subprogram that contains the data description of the API with a filename extension of PDA;
- A test program that calls the client interface object and has a filename extension of NSP—note that generation of test programs can be switched off.
Often Natural developers use a single character on a fixed position in the eight-character Natural name to visualize the object type of the Natural object. Typically used indicators are ”P” for a program, ”N” for a subprogram, ”A” for a PDA. This indication can also be seen in the last character of the names from our example (Figure 4).
The test program can also be used as an example of how to code an RPC client in Natural. It makes use of the Natural API RPC-CNTX. Parameters like host, port, server address and user ID can be set for the RPC communication. Especially for a quick test, this is the simplest way to set the connection parameters.
For more information on API RPC-CNTX refer to the Natural documentation: Natural RPC (Remote Procedure Call) > APIs for Providing an RPC Context from the Natural RPC Client Side > RPC-CNTX.
You may also set connection parameters via a service directory. See Service Directory Maintenance in the Natural SYSRPC utility documentation for more information.
Test Natural Client 3
Figure 5: Test Natural Client to webMethods IS
For testing, use the generated test program. Make sure your EntireX Broker, the central EntireX communication hub, is running. In addition, you need to enable the generated webMethods IS Listener before you run the Natural client. Look at the results in the Natural client in Figure 5: Did you recognize that they are the same as when running the flow service in Software AG Designer in Figure 1?
Alternatively, you can 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.
Summary
As demonstrated, it is quite easy to develop a scenario where Natural calls webMethods IS. Constraints defined for the input and output parameters of the flow service help to create a practical and useful Natural interface.
To learn more, read Common Integration Scenarios from webMethods EntireX documentation.
PDA – Parameter Data Area, interface of subprogram (Natural)
RPC Client – A sender using RPC as protocol
RPC Server – A receiver using RPC as protocol
Server – A receiver of messages
Server Address – EntireX-specific namespace for service, i.e. the class/server/service triple
Subprogram – Procedure (Natural)