# How to call webMethods Integration Server from Natural - mainframe outbound **URL:** \ **Category:** Knowledge base\ **Tags:** Adabas-Natural, EntireX\ **Created:** [January 10, 2017, 2:31pm UTC](https://techcommunity.softwareag.com/t/how-to-call-webmethods-integration-server-from-natural-mainframe-outbound/237723 "2017-01-10T14:31:11Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Gadi](https://sea1.discourse-cdn.com/techcommunity/user_avatar/techcommunity.softwareag.com/gadi/32/16051_2.png) [@Gadi](https://techcommunity.softwareag.com/u/Gadi)\ **Post date:** [January 10, 2017, 2:31pm UTC](https://techcommunity.softwareag.com/t/how-to-call-webmethods-integration-server-from-natural-mainframe-outbound/237723/1 "2017-01-10T14:31:11Z")
## 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](http://techcommunity.softwareag.com/techniques-blog/-/blogs/how-to-call-webmethods-integration-server-from-cobol-mainframe-outbound) in TECHniques Issue 4, 2016.) ![](https://global.discourse-cdn.com/techcommunity/original/2X/0/036ed8c104fef9a32cbc10ed72c69a614fbc7832.png) **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_. **![](https://global.discourse-cdn.com/techcommunity/original/2X/3/3ddeb884ca752df1d37ba7459d32c3fc42e18913.png) 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: ![](https://global.discourse-cdn.com/techcommunity/original/2X/7/715469c7691879793504377fd0b5571a9f498b79.png) **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_: **![](https://global.discourse-cdn.com/techcommunity/original/2X/2/281253784849f84f67573f37903af0df6763abd1.png) 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)_](http://documentation.softwareag.com/natural/nat826mf/rpc/rpc-over.htm) _\>_ [_APIs for Providing an RPC Context from the Natural RPC Client Side_](http://documentation.softwareag.com/natural/nat826mf/rpc/apis.htm#apis) _\> RPC-CNTX._ You may also set connection parameters via a service directory. See [_Service Directory Maintenance_](http://documentation.softwareag.com/natural/nat826mf/utis/sysrpc_sm.htm#sysrpc_sm_Invoking_Service_Directory_Maintenance) in the Natural SYSRPC utility documentation for more information.  ## Test Natural Client  3   **![](https://global.discourse-cdn.com/techcommunity/original/2X/f/f819336615f5f6ae41dd2159f29b7021c617e8d7.png) 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](http://documentation.softwareag.com/webmethods/wmsuites/wmsuite9-9/EntireX/9-9_EntireX/scenarios/overview.htm) from webMethods EntireX documentation.  * * * **Glossary of terms** **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)