Introduction to the EntireX Adapter

The EntireX Adapter is an add-on to the webMethods Integration Server that enables you to call remote procedures on mainframes and other hosts, using the EntireX RPC technique. The adapter provides seamless and real-time communication with EntireX RPC servers and clients, Natural RPC servers and clients, ACI Servers, ApplinX, IMS Connect, and CICS ECI. Using the EntireX Adapter, Integration Server applications can create and run services that can exchange messages with RPC servers and clients on mainframe and other hosts. This document covers the following topics:

See EntireX Adapter Prerequisites for supported versions of Integration Server and EntireX Workbench, and for supported platforms.


Architecture and Components

The EntireX Adapter enables you to configure the following components:

  • Adapter Connections
    Enable the webMethods Integration Platform to connect at runtime to EntireX RPC servers, Natural RPC servers, ACI servers, ApplinX, IMS Connect, and CICS ECI.

  • Adapter Services
    Perform operations on EntireX RPC servers and clients, using the built-in services provided with the EntireX Adapter.

  • Listener Notifications
    Provides synchronous notification of RPC messages that are called by EntireX RPC clients.

The following diagram illustrates how the EntireX Adapter interfaces with EntireX RPC servers and clients. The various architectural pieces involved in the integration process are described below the diagram.

graphics/intro_arch.png

  • webMethods Integration Server
    The EntireX Adapter is installed and runs on the Integration Server.

  • WmART Package
    The WmART package provides a common framework for webMethods Adapters to utilize the Integration Server functionality, making the Integration Server the runtime environment for the EntireX Adapter. The WmART package is installed with the Integration Server.

  • EntireX Adapter
    The EntireX Adapter is delivered as an adapter with the Software AG Installer. The package is called WmEntireX. The EntireX Adapter provides IS Administration Console and Software AG Designer user interfaces that enable you to configure and manage adapter connections, adapter services, and adapter notifications. However, it is recommended to use the Eclipse-based EntireX Workbench with the plug-ins for the EntireX Adapter to generate adapter connections and all other nodes for the Integration Server. The plug-in supports secure connections to the Integration Server and updating the nodes.

  • Adapter Connection Templates
    Adapter connections enable the EntireX Adapter to connect to EntireX RPC servers and clients. You must configure an adapter connection before you can configure adapter services or adapter notifications. The EntireX Adapter's connections are generated from a Software AG IDL file at design time with the EntireX Workbench (Eclipse-based). The IDL (Interface Definition Language) defines the interface of the remote procedures. Use the IS Administration Console to configure adapter connections. For a detailed description of adapter connections, see EntireX Adapter Connections.

  • Adapter Notification Template
    Adapter notifications enable the EntireX Adapter to listen to requests from EntireX RPC clients. These are used only for Reliable RPC Listener connections. The EntireX Adapter provides an adapter notification template that enables you to configure adapter notifications. You automatically create adapter notifications in the Eclipse plug-in when you create a Reliable RPC Connection with the Listener. However, you can use the Designer using the EntireX Adapter's notification templates. For a detailed description of adapter notifications, see Listeners and Adapter Notifications.

  • EntireX RPC Servers and Clients
    See RPC-based Components for details on EntireX RPC servers and clients. The following table gives an overview of the connection types discussed above:

    Connection Type Connects to Integration Server outbound Integration Server inbound IDL Additional Nodes Settings to generate IDL Parameters
    RPC Connection EntireX Broker x - one per IDL library one adapter service for each IDL program RPC Connection & Adapter Services In, InOut, Out
    Reliable RPC Connection EntireX Broker x - one per IDL library one adapter service for each IDL program Reliable RPC Connection & Adapter Services In
    RPC Listener Connection EntireX Broker - x one per IDL library one adapter listener per IDL library RPC Connection & Listener In, InOut, Out
    Reliable RPC Listener Connection EntireX Broker - x one per IDL library one adapter Listener per IDL library and for each IDL program a notification, a document type, a trigger, and a wrapping service Reliable RPC Connection & Listener In
    Connection to IMS Connect IMS Connect x - one per IDL library (with one IDL program) one adapter service for the IDL program IMS Connect In, InOut, Out
    CICS ECI Connection CICS ECI x - one per IDL library one adapter service for each IDL program CICS ECI Connection & Adapter Services In, InOut, Out
    ApplinX Connection ApplinX Server x - one per ApplinX procedure group one adapter service for each ApplinX path procedure ApplinX Connection & Adapter Services (invisible)
    Direct RPC Connection RPC Server x - one per IDL library one adapter service for each IDL program Direct RPC Connection & Adapter Services In, InOut, Out
    Direct RPC Listener Connection PRC Client - x one per IDL library one adapter per IDL library Direct RPC Connection & Listener In, InOut, Out
    ACI Server Connection EntireX BrokerXx x - one per IDL library one adapter service for each IDL program ACI Server Connection & Adapter Services In, InOut, Out

Package Management

The EntireX Adapter is provided as a package called WmEntireX. The adapter package is managed the same way as any package on the Integration Server. There are several considerations when you set up and manage your packages on the Integration Server:

Adapter Connections

The EntireX Adapter uses adapter connections to define how its adapter services and adapter notifications connect to EntireX RPC servers and clients. Each EntireX Adapter connection contains a set of connection parameters, including the logon parameters that the adapter requires to connect to the EntireX Broker. You configure extended properties of a connection using the IS Administration Console. For instructions on configuring and managing EntireX Adapter connections, see EntireX Adapter Connections. EntireX Adapter connections can be used only for adapter services or only for adapter notifications. A connection cannot be used simultaneously by services and notifications. If this is required, duplicate a connection and use one connection for services and the other for notifications.

This section covers the following topics:

Connection Pooling

The Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. All adapter services use connection pooling. A connection pool is a collection of connections with the same set of attributes. The Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections rather than opening new connections.

Runtime Behavior of Connection Pools

When you enable a connection, the Integration Server initializes the connection pool, creating the number of connection instances you specified in the connection's Minimum Pool Size field. Whenever an adapter service needs a connection, the Integration Server provides a connection from the pool. If no connection is available in the pool, and the Maximum Pool Size has not been reached, the server creates one or more new connections (according to the number specified in Pool Increment Size) and adds them to the connection pool. If the pool is full (as specified in Maximum Pool Size), the requesting service will wait for the Integration Server to obtain a connection, up to the length of time specified in the Block Timeout field, until a connection becomes available. Periodically, the Integration Server inspects the pool and removes inactive connections that have exceeded the expiration period specified in Expire Timeout. You can enable the system to retry the initialization any number of times, at specified intervals. For information on configuring connections, see EntireX Adapter Connections.

Built-in Services for Connections

Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics, the current state ("Enabled" or "Disabled") and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder. For details, see the webMethods Integration Server Built-in Services Reference.

Adapter Services

Adapter services enable the EntireX Adapter to initiate operations that interact with EntireX providers. You configure adapter services using adapter service templates, which are provided with the EntireX Adapter. Configuring a new service from an adapter service template is straightforward. There are two alternatives: use the EntireX Workbench or use the Designer. Using the EntireX Workbench is recommended. You create an adapter connection together with a set of adapter services, one for each IDL program in the IDL library you are using to create the connection. Using the Designer, you assign a default adapter connection to the service, select the adapter service template, and select the EntireX subprogram to call. This has to be done for each service separately.

After you configure a service, you can incorporate it into a flow or Java service to interact with an EntireX broker. For example, you can create a flow service that calls an EntireX RPC server.

Using Adapter Notifications

Adapter notifications are only needed for Reliable RPC Listener connections, sending RPC messages with only In parameters to the Integration Server. The EntireX Adapter provides a notification called Asynchronous Listener Notification, which monitors a specified Reliable RPC Listener connection and notifies the adapter when an RPC call arrives at that connection. You configure the notification to invoke a flow or Java service using the data from the notification. See Configuring Adapter Notifications for instructions.

Using the Eclipse plug-ins of the adapter will generate all the objects needed for a Reliable RPC Listener connection automatically, including the listener and adapter notifications.

Viewing the Adapter's Update Level

You can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the "About page" in the IS Administration Console.