When you wish to create a communication path from the Integration Server or the PCK to a program or subprogram on the remote host, some configuration steps are required, as described below.
You use the Software AG PI Adapter for EntireX to connect the Integration Server to back-end applications. It enables messages to be exchanged by converting the PI message format to an EntireX RPC call and converting the result of the RPC call back to a PI message. You configure the adapter in the configuration part of the Integration Builder or the PCK.
To convert PI messages from the Integration Server/PCK to an EntireX RPC call, you configure the Receiver Adapter.
To convert calls from a Software AG RPC client to PI messages for the Integration Server or the PCK, you configure the Sender Adapter.
Note the following restrictions:
Only the payload of a received PI message is evaluated. Additional attachments are ignored and not forwarded.
Each message contains one RPC call; conversational RPC calls are not possible.
You need to configure the receiver adapter to be able to convert PI messages from the Integration Server or the PCK into EntireX RPC calls to the corresponding RPC Server.
You configure the adapter on the Integration Builder or in the PCK.
tab page during the definition of a communication channel in theYou have created a new communication channel or have opened an existing one.
On the EntireX.
tab page you have selected the adapter typeYou have selected the
radio button to define the adapter as a receiver adapter.You have created an XMM file using the EntireX Workbench and stored it in a location accessible (either via file or HTTP access) by the machine which runs the Integration Server or the PCK.
To configure the adapter, make sure the following values are specified:
Protocol | Value |
---|---|
Transport Protocol | TCP/IP |
Message Protocol | EntireX RPC EntireX Reliable RPC |
Select "EntireX Reliable RPC" to use asynchronous reliable messaging for RPC. The RPC server needs to support Reliable RPC.
Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.
Parameter | Selection |
---|---|
Host | IP name or address of the host machine where the broker is running. This parameter is mandatory. |
Port | The corresponding port number. If omitted the default port 1971 is used. |
Use Logon Authentication | Set this indicator if the broker is running with security. |
Logon User | The user ID used for authentication. This parameter is mandatory if Use Logon Authentication is enabled. |
Logon Password | The corresponding password for this user ID. This parameter is mandatory if Use Logon Authentication is enabled. |
Parameter | Selection |
---|---|
Location of XMM File |
Specify the location of the XMM file (generated by the EntireX Workbench). The location can be either an absolute file name, or a file URL or an HTTP URL. Note that this location is evaluated during adapter runtime so it must be accessible by the machine where the Adapter Engine is running. If you are running the Adapter Engine in a clustered environment, make sure that the XMM file is accessible at the same location on all machines in the cluster. This parameter is mandatory. |
RPC Server Address |
The address the EntireX RPC server used to register itself. The server address can be specified either:
This parameter is mandatory and is case sensitive! |
RPC User | The user ID used for authentication. This parameter is mandatory if Use EntireX RPC Server Authentication is enabled. |
RPC Password | The corresponding password for this user ID. This parameter is mandatory if Use EntireX RPC Server Authentication is enabled. |
The following parameters are only used when the PI message which is received by the Adapter has one of the Quality of Service attributes Exactly Once or Exactly Once in Order.
Parameter | Selection |
---|---|
First Parameter of RPC Program is used as Message ID (UUID / GUID) | The called RPC program will receive the unique message ID of the PI message in the first parameter. The format of this parameter has to be A36. The RPC program may use this parameter for duplicate message detection. This parameter is not available for Reliable RPC. |
Time Period for Duplicate Check for EO(IO) (secs) | To check for duplicate messages, message IDs must be saved in the database. To prevent the database from getting unnecessarily large, these message IDs must be deleted after a certain amount of time. Specify in seconds the time period after which you want message IDs to be deleted (after one day, for example, if you check message monitoring daily). The default is 86400 seconds (1 day). |
Set the adapter to Active to enable messages to be exchanged.
To specify additional parameters, set the Advanced Mode indicator.
Parameter | Selection |
---|---|
EntireX RPC Library Name | The RPC Library Name is used by many RPC Servers to locate the called subprogram. The default is the library name specified in the IDL file. Use this parameter to specify a library name different from the default one. |
Timeout | Override the default for the wait timeout for the RPC call. The default is 60s. Values can be specified in hours, minutes, or seconds (e.g. 1h, 10m, 30s). |
Transport Compression | Specify if transport compression should be used. For details see the EntireX documentation. |
Table |
Enter the parameter names and parameter values in the Additional Parameters table. Use the parameter Use the parameter |
You need to configure the sender adapter to be able to receive calls from an EntireX RPC client and convert them to PI messages for the Integration Server or the PCK.
You configure the adapter on the Integration Builder or in the PCK.
tab page during the definition of a communication channel in theThe adapter determines the payload of the PI message according to how it is configured. However, the message header information is determined from the sender agreement corresponding to the communication channel.
The following conditions apply to the adapter for the definition of the sender agreement:
The communication channel defined here must have exactly one sender agreement.
At least the interface name and the sender service must be qualified in the sender agreement. All other fields are optional in accordance with the general rules for defining sender agreements.
You have created a new communication channel or have opened an existing one.
On the EntireX.
tab page you have selected the adapter typeYou have selected the
radio button to define the adapter as a sender adapter.You have created an XMM file using the EntireX Workbench and stored it in a location accessible (either via file or HTTP access) by the machine which runs the Integration Server or the PCK.
To configure the adapter, make sure the following values are specified:
Protocol | Value |
---|---|
Transport Protocol | TCP/IP |
Message Protocol | EntireX RPC EntireX Reliable RPC |
Select "EntireX Reliable RPC" to use asynchronous reliable messaging for RPC. The RPC client needs to support Reliable RPC and must use Reliable RPC when sending messages to the PI Adapter.
Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.
Parameter | Selection |
---|---|
Host | IP name or address of the host machine where the EntireX Broker is running. This parameter is mandatory. |
Port | The corresponding port number. If omitted the default port 1971 is used. |
Use Logon Authentication | Set this indicator if the EntireX Broker is running with security. |
Logon User | The user ID used for authentication. This parameter is mandatory if Use Logon Authentication is enabled. |
Logon Password | The corresponding password for this user ID. This parameter is mandatory if Use Logon Authentication is enabled. |
Parameter | Selection |
---|---|
Location of XMM File |
Specify the location of the XMM file (generated by the EntireX Workbench). The location can be either an absolute file name or a file URL or an HTTP URL. Note that this location is evaluated during adapter runtime so it must be accessible by the machine where the Adapter Engine is running. If you are running the Adapter Engine in a clustered environment, make sure that the XMM file is accessible at the same location on all machines in the cluster. This parameter is mandatory. |
RPC Server Address |
The EntireX RPC Server used to register itself. The server address can be specified either:
This parameter is mandatory and is case sensitive. |
Processing Type |
With this parameter you can define a generic channel which will process all programs (RPC client requests) for this server address. Alternatively you can define a specific channel which will process only the defined RPC program.
|
RPC Program |
The program name if this channel is defined as a specific channel.
This parameter is mandatory if the processing type |
In general, multiple communication channels can be defined for the same server address. Two server addresses are identical if the combination of host, port and RPC server address are identical. The sender adapter routes an incoming request from an RPC client to the appropriate channel. If an appropriate channel cannot be found an error is returned to the RPC client application.
Routing is based on the program name in the RPC request. Note that the library name is ignored for routing. There is no need for the library name specified in the RPC client request to match the library name in the XMM file (or the IDL file from which the XMM file is generated).
The adapter first checks if a specific channel configuration for the program name exists. If a specific channel exists it is routed to this channel. Multiple channel configurations for the same program result in a configuration error.
A generic channel definition will process all RPC client requests for this server address independent of the program name. As a consequence more than one generic channel definition cannot be defined for the same server address. It is possible to process multiple different programs by the same generic channel definition. In this case a Sender Agreement has to be defined for each RPC program where the Interface Name is identical to the program name.
If both specific and generic channel configurations are defined for the same server address the adapter will first look for a specific channel to process the RPC call. If no specific definition is found the adapter routes the call to the generic channel configuration.
Parameter | Selection |
---|---|
Quality of Service | Specifies how the message is to be processed by
the Integration Engine/PCK:
Execution exactly once can be guaranteed only if Reliable RPC is used or if the client application sends a unique message ID. This parameter is mandatory. "Best Effort" is not available for Reliable RPC. |
First Parameter of RPC Program is used as Message ID (UUID / GUID) | The first parameter of the RPC program is used
as a unique message ID. The format of this parameter has to be A36. The
parameter has to be unique for a specific RPC program only (uniqueness is
guaranteed within Adapter, Host/Port, and RPC Server Address).
If the RPC Client application sends a new message it must use a new message ID, if it resends a message it must reuse the same message ID. This parameter is used for Quality of Service "Exactly Once" or "Exactly Once in Order". This parameter is not available for Reliable RPC. |
Time Period for Duplicate Check for EO(IO) (secs) | To check for duplicate messages, message IDs
must be saved in the database. To prevent the database from getting
unnecessarily large, these message IDs must be deleted after a certain amount
of time.
Specify in seconds the time period after which you want message IDs to be deleted (after one day, for example, if you check message monitoring daily). The default is 86400 seconds (1 day). This parameter is used for Quality of Service "Exactly Once" or "Exactly Once in Order". |
Queue Name | Specify the queue name. This parameter is mandatory for Quality of Service "Exactly Once in Order". Maximum length is 16 characters (uppercase). |
Set the adapter to Active to enable messages to be exchanged. If the adapter status is set to "Inactive" the adapter will not forward received messages to this channel. If all channels for one server address are either inactive or have a configuration error the adapter will deregister the internal RPC server.
To specify additional parameters, set the "Advanced Mode" indicator.
Parameter | Selection |
---|---|
Transport Compression | Specify if transport compression should be used. For details, see the EntireX documentation. |
Table |
Enter the parameter names and parameter values in the "Additional Parameters" table. Use the parameter Use the parameter Use the parameter Use the parameter Use the parameter Use the parameter |
To use SSL/TLS instead of TCP/IP, add the following information to the Host and Port parameters:
Parameter | Selection |
---|---|
Host | "ssl://hostname" or "ssl://ipaddress". |
Port | "portnumber?ssl_parameters" A description of the SSL parameters can be found in the webMethods EntireX documentation. A typical examples is: "1958?trust_store=/usr/whatever/trust.jks&verify_server=no". |