This document describes how to configure and manage EntireX Adapter services. EntireX Adapter services allow clients to interact with EntireX RPC servers, Natural RPC servers, ACI servers, ApplinX, IMS Connect, and CICS ECI using a configured adapter connection. EntireX Adapter services are available for synchronous and asynchronous RPC calls (RPC and reliable RPC).
The following topics are covered:
To prepare configuration and management of EntireX Adapter
services
Start your Integration Server and the IS Administration Console, if they are not already running.
Make sure you have webMethods administrator privileges so that you can access the EntireX Adapter's administrative screens. See the Administering webMethods Integration Server for information on setting user privileges.
Using the IS Administration Console, make sure the WmEntireX package is enabled. See Enabling and Disabling Packages for instructions.
Start the Designer if it is not already running.
Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer help.
Using the Designer, create a user-defined package to contain the service, if you have not already done so. Add a dependency on WmEntireX package (version *.*) to your user-defined package. When you configure adapter services, you should always define them in user-defined packages rather than in the WmEntireX package. See Package Management.
Generate the adapter connection with the EntireX Workbench.
Or:
Using the IS Administration Console, configure an adapter connection
to use with the adapter service. See EntireX Adapter Connections for instructions.
The EntireX Adapter service enables you to send RPC calls to an EntireX RPC server or Natural RPC server. You configure EntireX Adapter services using a specific adapter connection. After you follow the steps in this section to configure the adapter service, you can invoke it from a flow or Java service. To use EntireX Adapter services, you provide values for the service's input signature in the pipeline. See Using Adapter Services.
To create EntireX Adapter services
In the EntireX Workbench, select the Software AG IDL file to use.
In the context menu, choose .
To enable the EntireX Adapter service to send an RPC call to
an EntireX RPC server
Provide values for the parameters in the service's input signature when configuring the adapter service within a flow service in the Designer. You can either map in values from the pipeline, or you can set constant values using the Pipeline View.
This has the following effect on the input and output signature:
The input signature of an adapter service wraps all input
parameters of the EntireX subprogram in the
inRec.
A parameter throwException is added to the
signature. If this optional parameter is set to
"true", errors are returned as exceptions and not by
means of parameters in the output signature. A parameter
$connectionname is added to the signature. If this optional
parameter
A parameter throwException is added to the
signature. If this optional parameter is set to
"true", errors are returned as exceptions and not by
means of parameters in the output signature.
A parameter $connectionname is added to the signature.
If this optional parameter, is set to a connection name, it overrides the
default connection name of the service.
Depending on the connection type, adapter services have optional parameters that can be used to overwrite the corresponding values of the connection. These optional parameters are:
RACF user ID
RACF password/PassTicket
CICS Mirror Transaction ID
RPC library name
RPC user
RPC password
Server address
Logon user
Logon password
RPC library name
RPC user
RPC password
Server address
Logical terminal ID
RACF user ID
RACF password/PassTicket
RACF group name
RACF application name
IMS datastore ID
Maximum segment length
Logon user
Logon password
See EntireX Adapter Connections for details on the parameters.
The output signature of an adapter service wraps all output
parameter of the EntireX subprogram in the
outRec. Three parameters
errorFlag, errorMessage
(optional), and errorCode are added to the signature. If
errorFlag is true, errorMessage
contains the error message. errorCode contains
"00000000" for a successful call, otherwise the
EntireX message class (4 digits) and message code (4 digits).
Use the Designer to view adapter services. Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer online help.
To view a service
In the Designer Package Navigator view, expand the package and folder that contain the service you want to view.
Select the service you want to view. The Designer displays the service in the Service Editor.
As a result, the Adapter Service Editor for the EntireX Adapter service appears.
Notes:
Use the Designer to delete adapter services. Make sure you are viewing the Designer in the Service Development perspective, as described in Switching Perspectives in the Designer online help.
To delete a service
In the Designer Package Navigator view, expand the package and folder that contain the service you want to delete.
Right-click the service and then click .
Adapter services of the EntireX Adapter are enabled for
dynamically selecting a connection node. The connection name may be specified
on the pipeline in the $connectionName field. This field has to be
part of the services input signature. If $connectionName is not
specified, the default connection name is used, usually the connection used to
create the service.
See chapter 8 in webMethods Adapter Development Kit User's Guide , version 6.5 for more details on connection selection.
Connection selection is applicable to services that are generated with the EntireX Adapter (version 8.0 or higher) and helps to:
Generate the connections and services as usual.
Design your services that call the adapter services to set
$connectionName to one single connection.
Then you can switch to a different environment by changing this single connection to a different resource.
Generate the connections and services as usual.
Then for each IDL library one connection is generated and one connection pool is used at runtime.
Design your services that call the adapter services to set
$connectionName to one single connection.
This reduces the connection pools to a single pool associated with this connection.
Adapter services have two parameters to configure the formatting of
decimal parameters (IDL data types N, NU,
P and PU, and alphanumeric parameters of fixed length
(IDL data types A, K, and U).
To set these options, use the Designer and open the adapter service for the EntireX Adapter. In RPC Call, select Parameters for Decimal Numbers (N/P) or Parameters for fixed length Strings (A/K/U).
The following tables give an overview of parameters to be configured:
Parameters for Decimal Numbers (N/P)
(As an example, we use the value "3.14 "
for a parameter defined as N7.2 in the IDL.)
| Parameter | Example |
|---|---|
| Remove leading zeros & keep decimal point (default) | 3.14 |
| Remove leading zeros & remove decimal point | 314 |
| Keep leading zeros & keep decimal point | 0000003.14 |
| Keep leading zeros & remove decimal point | 000000314 |
Note:
This parameter is highly deprecated and should be only used for
compatibility with webMethods Mainframe.
| Parameter | Explanation |
|---|---|
| not justified (default) | The field formatting is unchanged. |
| left justified | The numeric field is left justified. |
| right justified | The numeric field is right justified. |
| Parameter | Explanation |
|---|---|
| Remove whitespace characters (default) | Trim leading and trailing whitespace characters. |
| Keep whitespace characters | Format the string with the defined number of characters. |
Note:
This parameter is highly deprecated and should be only used for
compatibility with webMethods Mainframe.
| Parameter | Explanation |
|---|---|
| not justified (default) | The field formatting is unchanged. |
| left justified | The string field is left justified. |
| right justified | The string field is right justified. |
Null value suppression (NVS) allows you to suppress parameters with no specified value. Suppressed parameters will not appear in the result of the adapter service call. Null value suppression is available for the following IDL data types:
all string data types
groups and structures
arrays
To activate NVS in the context of adapter services, modify each adapter service separately, using Designer. For each adapter service, select Null Value Suppression in RPC Call. You can fine-tune NVS with the following suppression modes:
| Suppression Mode | Explanation |
|---|---|
| No suppression (default) | No suppression, all parameters are present in the output structure. |
| Suppress null elements | String parameters with empty strings are suppressed, empty structures and arrays are suppressed. |
| Suppress null elements and trim array cells at end | Same as above. In addition, all empty array elements at the end of the array will be removed from the array. |
| Suppress null elements and trim array cells at end containing null elements and zero numbers | Same as above. In addition, numbers of numeric/decimal type (I1, I2, I4, N, P) with the value zero are treated as an empty value. |
A string parameter is suppressed if the assigned string is:
of type variable length (AV/KV/UV) and the string is empty (same for variable length strings with a maximum length).
of type fixed length (A/K/V) and the parameter Remove whitespace characters is enabled, and trimming the leading and the trailing whitespace characters would result in an empty string.