| Quick Reference |
This document describes how to configure and manage EntireX Adapter connections. It covers the following topics:
Tip:
It is recommended to create connections with the webMethods Integration Server Wrapper of the Designer.
Connections that are used dynamically can be created with the IS Administration Console.
To prepare to configure or manage adapter connections
Install the webMethods Integration Server and the EntireX Adapter on the same machine, using the Software AG Installer.
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.
Start your Integration Server and the IS Administration Console, if they are not already running.
Using the IS Administration Console, make sure the WmEntireX package is enabled. See Importing and Exporting Packages for instructions.
If you have not already done so, use the Designer to create a user-defined package to contain the connection. See Package Management.
When you configure EntireX Adapter connections, you specify information that the Integration Server uses to connect to an EntireX RPC server or client, or to IMS Connect or CICS ECI. You create EntireX Adapter connections using the Designer. This ensures that the information generated from the interface definition stored in the Software AG IDL file is present. A wizard inside the Designer allows you to configure the most common parameters of the connection. Using the IS Administration Console, you have access to all parameters of a connection.
The EntireX Adapter supports the following connection types:
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 |
Supports Transactions of Type |
Integration Server inbound |
Note |
|---|---|---|---|---|---|
| RPC Connection | RPC Server via EntireX Broker | x | local | - | 1,6 |
| Direct RPC Connection | RPC Server | x | local | - | 1,6 |
| Reliable RPC Connection | RPC Server via EntireX Broker | x | local | - | 1,6 |
| RPC Listener Connection | RPC Client via EntireX Broker | - | n/a | x | 2 |
| Direct RPC Listener Connection | RPC Client | - | n/a | x | 2 |
| Reliable RPC Listener Connection | RPC Client via EntireX Broker | - | n/a | x | 2 |
| Direct Reliable RPC Listener Connection | RPC Client | - | n/a | x | 2 |
| IMS Connect Connection | IMS Connect | x | - | - | 1 |
| CICS ECI Connection | CICS ECI | x | - | - | 1 |
| CICS Socket Listener Connection | CICS Socket Listener | x | local | - | 1,6 |
| ApplinX Connection | ApplinX Server | x | - | - | 3 |
| ACI Server Connection | ACI Server via EntireX Broker | x | - | - | 1 |
| COBOL Converter Connection | Integration Server (internal) | - | n/a | - | 1 |
| AS/400 Connection | AS/400 | x | - | - | 1,4 |
| Adabas Replication Listener Connection | Adabas Replication Server via EntireX Broker | - | n/a | x | 5 |
| Adabas Replication Direct Listener Connection | Adabas Replication Server | - | n/a | x | 5 |
Notes:
The Designer wizard additionally creates an EntireX Adapter service for each program of the IDL file; see EntireX Adapter Services.
The Designer wizard additionally creates an EntireX Adapter listener; see also Listeners.
The ApplinX Designer additionally creates an EntireX Adapter service for each ApplinX path procedure.
After installation of the EntireX Adapter, the AS/400 connection type is not visible and not usable. To access the AS/400 system you need the IBM ToolBox for Java (JTOpen). See Post-installation Steps for AS/400.
These connection types are used by the product "Adabas Replication Service for webMethods Integration Server". For details see the documentation of this product.
For transaction support, refer to the respective connection parameters under Editing Adapter Connections and Appendix B in webMethods Adapter Development Kit User's Guide Version 6.5.
To create a connection
Start the Designer.
Navigate to the Software AG IDL file you want to use.
On the IDL file, right-click and choose
Follow the wizard (Integration Server Wrapper), which guides you through the creation of the adapter connection and the adapter services or adapter listener.
As a result, the connection you created appears on the adapter's connections screen and in the Designer Package Navigator view.
Note:
It is not possible to generate new connections using
Configure New Connection on the Connections
screen of the EntireX Adapter in the
IS Administration Console because such connections would not have any
metadata. Only connections generated by the Designer have the
mandatory metadata. However, you can create a new connection by
copying an existing connection on the Connections screen.
This is useful for dynamically selected connections where the metadata is not
generated from the interface definition (Software AG IDL file). To use
dynamically selected connections with $connectionName, see chapter
8 in webMethods Adapter Development Kit User's Guide Version
6.5, see
https://empower.softwareag.com/Products/Documentation/default.asp
under "webMethods" > "Adapters".
You can view a connection's parameters using the IS Administration Console or the Designer.
To view the parameters for a connection using the
IS Administration Console
In the menu in the IS Administration Console navigation area, click .
On the Connections screen, click the View icon for the connection you want to see. The View Connection screen displays the parameters for the connection. For descriptions of the connection parameters, see Configuring Adapter Connections.
Click to return to the main connections screen.
To view the parameters for a connection using the
Designer
Start the Designer if it is not already running.
From the Designer Package Navigator view, open the package and folder in which the connection is located.
Click the connection you want to view. The parameters for the connection appear on the Connection Information tab. For descriptions of the connection parameters, see Configuring Adapter Connections.
If the login information for a server changes, or if you want to redefine parameters that a connection uses when connecting to a server, you can update the connection's parameters. This section describes how to edit a connection and lists parameter settings for the connection types covered. The following topics are covered:
Connection Parameters for RPC and Reliable RPC Listener Connections
Connection Parameters for Direct RPC and Direct Reliable RPC Listener Connections
Common Connection Management Properties (for all Connection Types)
You edit (and modify) adapter connections using the IS Administration Console.
To edit a connection
In the menu in the IS Administration Console navigation area, click .
Make sure that the connection is disabled before editing it. See Disabling Adapter Connections for instructions.
On the Connections screen, click the Edit icon for the connection you want to edit. The Edit Connection screen displays the current parameters for the connection. Update the connection's parameters by typing or selecting the values you want to specify. The tables below give a complete listing of parameters for the following connection types:
On the Connections screen, edit the connection management properties (connection pooling). The tables in Common Connection Management Properties (for all Connection Types) give a complete listing of parameters.
Click to save the connection and return to the Connections screen.
| Parameter | Description | Default | Can be set from the Designer |
Can be set dynamically with service |
|---|---|---|---|---|
| Broker ID | The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971". | localhost | Yes | No |
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
|
RPC/SRV1/CALLNAT | Yes | Yes |
| Logon User | The name of the user to log on to the broker. | Yes | Yes | |
| Logon Password | The password for the user above. | Yes | Yes | |
| Retype Logon Password | Verification of the password. | Not applicable | Not applicable | |
| Encryption | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX. | |||
| Encoding | The character encoding used for the RPC connection to the EntireX Broker. Default: the encoding of the Integration Server.
Enable character conversion in the broker by setting the service-specific attribute |
Yes | No | |
| Compression Level | The level of broker data compression. | NO_COMPRESSION |
No | No |
| Timeout | The number of seconds to wait for a response from the RPC server. | 60S | No | No |
| RPC Library Name | The name of the RPC library. Default: the library name used to generate the connection. Mainly used to override the library name for Natural RPC servers. (1) | No | Yes | |
| RPC User | The RPC user ID sent to the RPC server. (3) | No | Yes | |
| RPC Password | The password for the user above. (3) | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type (2) | Transaction types "none" (no transactions) and "local" (local transactions) are supported. | none | No | No |
Notes:
| Parameter | Description | Default | Can be set from the Designer |
|---|---|---|---|
| Broker ID | The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971". | localhost | Yes |
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
|
RPC/SRV1/CALLNAT |
Yes |
| Logon User | The name of the user to log on to the broker. | Yes | |
| Logon Password | The password for the user above. | Yes | |
| Retype Logon Password | Verification of the password. | Not applicable | |
| Encryption | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX. | No_Encryption | No |
| Encoding | The character encoding used for the RPC connection to the EntireX Broker. Default: the encoding of the Integration Server.
Enable character conversion in the broker by setting the service-specific attribute |
Yes | |
| Compression Level | The level of broker data compression. | NO_COMPRESSION |
No |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description | Default | Can be set from the Designer |
Can be set dynamically with service |
|---|---|---|---|---|
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
|
RPC/SRV1/CALLNAT | Yes | Yes |
| Timeout | The number of seconds to wait for a response from the RPC server. | 60S | No | No |
| RPC Library Name | The name of the RPC library. Default: the library name used to generate the connection. Mainly used to override the library name for Natural RPC servers. (2) | No | Yes | |
| RPC User | The RPC user ID sent to the RPC server. (3) | No | Yes | |
| RPC Password | The password for the user above. (3) | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type (1) | Transaction types "none" (no transactions) and "local" (local transactions) are supported. | none | No | No |
Notes:
| Parameter | Description | Default | Can be set from the Designer |
Can be set dynamically with service |
|---|---|---|---|---|
| Broker ID | The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971". | localhost | Yes | No |
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
|
Yes | Yes | |
| Logon User | The name of the user to log on to the broker. | Yes | Yes | |
| Logon Password | The password for the user above. | Yes | Yes | |
| Retype Logon Password | Verification of the password. | Not applicable | Not applicable | |
| Encryption | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX. | No_Encryption | No | No |
| Encoding | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX. | Yes | No | |
| Compression Level | The level of broker data compression. | NO_COMPRESSION | No | No |
| RPC Library Name | The name of the RPC library. Default: the library name used to generate the connection. Mainly used to override the library name for Natural RPC servers. (2) | No | Yes | |
| RPC User | The RPC user ID sent to the RPC server. (3) | No | Yes | |
| RPC Password | The password for the user above. (3) | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type (1) | Transaction types "none" (no transactions) and "local" (local transactions) are supported. | none | No | No |
Notes:
| Parameter | Description | Default | Can be set from the Designer |
|---|---|---|---|
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
|
RPC/SRV1/CALLNAT |
Yes |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description | Default | Can be set from Designer | Can be set dynamically with service |
|---|---|---|---|---|
| Host | Hostname of IMS Connect. | Yes | No | |
| Port | IMS Connect port. | Yes | No | |
| IMS Connect Data Store ID | Name of the data store, as defined in the IMS Connect configuration member. | Yes | Yes | |
| Encoding | Specify the appropriate EBCDIC encoding used by your IMS Connect. | cp037 | Yes | No |
| Socket Timeout (1) | 10000 | No | No | |
| Check for DFS Errors | true | No | No | |
| Logical Terminal ID | No | Yes | ||
| Use old Exit | true | No | No | |
| Exit Name | Default name for old exit is "*SAMPLE*", for new exit "*SAMPL1*" | No | No | |
| RACF User ID | The name of the user to log on to IMS Connect. | Yes | Yes | |
| RACF Password / PassTicket | The password of the user above. | Yes | Yes | |
| Retype RACF Password / PassTicket | Verification of the password above. | Not applicable | Not applicable | |
| RACF Group Name | Security setting. | No | Yes | |
| RACF Application Name | Defined to RACF on the PKTDATA definition. | No | Yes | |
| Secured Signon Key | Secured signon key used to generate the PassTicket. | No | No | |
| SSL Parameters | Truststore and optional certificate. Example: trust_store=CACerts.jks See also Support for SSL/TLS. |
No | No | |
| Metadata Information |
Caution: |
Generated | No | |
| Use IDL program as transaction name | Automatically use the IDL program name as transaction name. If set to "true" or "yes", 10 bytes are used for the transaction name. If set to a number, this number of bytes is used for the transaction name. | false | No | No |
Notes:
This connection type uses the External Call Interface (ECI) within CICS. For more information see Preparing IBM CICS for ECI.
| Parameter | Description | Default | Can be set from Designer | Can be set dynamically with service |
|---|---|---|---|---|
| Host | Hostname of CICS. | Yes | No | |
| Port | CICS port. | Yes | No | |
| CICS Mirror Transaction ID | Name of the CICS mirror transaction. Default is "CPMI", which is the default dispatching transaction for ECI. | CPMI | Yes | Yes |
| Encoding | Specify the appropriate EBCDIC encoding used by your CICS ECI. | cp037 | Yes | No |
| Socket Timeout | Socket timeout (in milliseconds). | 10000 | No | No |
| RACF User ID | The name of the RACF user to log on to CICS ECI. | Yes | Yes | |
| RACF Password / PassTicket | The password for the user above. See Note. | Yes | Yes | |
| Retype RACF Password / PassTicket | Verification of the password above. | No | No | |
| Application Name | Application name used to generate the PassTicket. | No | No | |
| Secured Signon Key | Secured signon key used to generate the PassTicket. | No | No | |
| SSL Parameters | Truststore and optional certificate. Example:trust_store=CACerts.jksSee also Support for SSL/TLS. |
No | No | |
| Metadata Information |
Caution: |
Generated | No |
Note:
By default the password is translated to uppercase.
To use mixed-case passwords, set watt.com.softwareag.entirex.wmadapter.cics.eci.mixedcase.password=true under Settings > Extended on the Integration Server administration page.
This connection type uses the CICS Socket Listener. For more information see Preparing for CICS Socket Listener.
| Parameter | Description | Default | Can be set from Designer | Can be set dynamically with service |
|---|---|---|---|---|
| Host | Hostname of CICS Socket Listener. | Yes | No | |
| Port | CICS Socket Listener Port. | Yes | No | |
| Encoding | Specify the appropriate EBCDIC encoding used by your CICS Socket Listener. | cp037 | Yes | No |
| CICS Transaction ID | Name of the CICS transaction. Default is "XRFE", which is the default dispatching transaction for CICS Socket Listener. | XRFE | Yes | No |
| Socket Timeout | Socket timeout (in seconds). | 10 | No | No |
| RACF User ID | The name of the user to log on to CICS Socket Listener. | Yes | Yes | |
| RACF Password | The password for the user above. | Yes | Yes | |
| Retype RACF Password | Verification of the password above. | No | No | |
| Application Name (1) | Application name used to generate the PassTicket. | No | No | |
| Secured Signon Key (1) | Secured signon key used to generate the PassTicket. | No | No | |
| SSL Parameters | Truststore and optional certificate. Example: trust_store=CACerts.jksSee also Support for SSL/TLS. |
No | No | |
| User Transaction ID | Optional. The CICS transaction identifier (max. 4 characters) that will be used to run CICS programs in separate user transactions. See User Transaction Support. | No | Yes | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type (2) | Transaction types "none" (no transactions) and "local" (local transactions) are supported. | None | No | No |
| Sync on Return (3) | Optional. If true, the CICS program is called with the CICS LINK option SYNCONRETURN.
Refer to the IBM CICS Transaction Server for z/OS documentation for more information on the SYNCONRETURN option. This option is only useful if the CICS program is defined as DPL. See note.
|
false | No | No |
| User Exit | Optional. Class name of user exit implementation. See User Exit. | No | No | |
| User Exit Class Path | Optional. URL of the classpath for user exit implementation, for example file://myexit.jar or http://host/path/to/my/exit.
|
No | No |
Notes:
true with DPL impacts the syncpoint handling of the EntireX CICS Socket Listener.
Usually the syncpoint is performed after a reply has been sent to the request.
Using this option, the syncpoint is now performed after program execution. This means that if the reply fails, the syncpoint
has already been performed.
Using conversational requests (multiple requests with one syncpoint after the last request) the SyncOnReturn option is just ignored without further notice.
| Parameter | Description | Default | Can be set from the Designer |
|---|---|---|---|
| Broker ID | The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971". | localhost | Yes |
| Server Address | The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>. The address may contain an asterix ( '*') as a wildcard that is substituted by the IDL program name at runtime. This helps
you to use only one connection for multiple IDL programs or adapter services.
|
RPC/SRV1/CALLNAT | Yes |
| Logon User | The name of the user to logon on to the broker. | Yes | |
| Logon Password | The password for the user above. | Yes | |
| Retype Logon Password | Verification of the password above. | Not applicable | |
| Encryption | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS, HTTP(S), and Certificates with EntireX. | No_Encryption | No |
| Encoding | The character encoding used for the ACI connection to the EntireX Broker. Default: the encoding of the Integration Server.
Enable character conversion in the broker by setting the service-specific attribute |
No | |
| Timeout | The number of seconds to wait for a response from the RPC server. | 60S | No |
| Server Type | Defines how arrays of groups are marshalled.
Allowed values are "COBOL" and
"Natural".
Note: |
COBOL | No |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description | Default | Can be set from Designer |
|---|---|---|---|
| Host | Hostname of ApplinX server. | Yes | |
| Port | Port of ApplinX server. | Yes | |
| Secure connection | Set to "true" for a secure connection. | false | No |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description | Default | Can be set from Designer | Can be set dynamically with service |
|---|---|---|---|---|
| Encoding | The character encoding of the COBOL binary data. | Cp037 | Yes | No |
| Metadata Information |
Caution: |
Generated | No |
Note:
After installation of the EntireX Adapter, the AS/400 connection type is not visible and not usable.
To access the AS/400 system you need the IBM ToolBox for Java (JTOpen). See Post-installation Steps for AS/400.
| Parameter | Description | Default | Can be set from Designer | Can be set dynamically with service |
|---|---|---|---|---|
| Host | Hostname of the AS/400 (IBM i) system. | Yes | No | |
| User ID | The user profile name to use to authenticate to the system. | Yes | No | |
| Password | The user profile password to use to authenticate to the system. | Yes | No | |
| Retype Password | Verification of the password above. | Not applicable | ||
| Encoding | The character encoding used for the RPC connection to the EntireX Broker. Default: the encoding of the Integration Server.
Enable character conversion in the broker by setting the service-specific attribute |
cp037 | Yes | No |
| Timeout | Maximum time to run the program in seconds. | 60 | No | |
| Program Path | The fully qualified integrated file system path name to the program. %library% is replaced by the IDL file library name and %program% is replaced by the IDL file program name. The library and program name must each be 10 characters or less.
|
/QSYS.LIB/%library%.LIB/%program%.PGM | No | |
| Metadata Information |
Caution: |
Generated | Generated |
| Parameter | Description |
|---|---|
| Enable Connection Pooling | Enables the adapter to use connection pooling.
Default: true. See Connection Pooling for more information on connection pooling.
|
| Minimum Pool Size | If connection pooling is enabled, this field
specifies the minimum number of connection objects that remain in the
connection pool at all times. When the adapter creates the pool, it creates
this number of connections. Default: 1.
|
| Maximum Pool Size | The maximum number of connection objects that
can exist in the connection pool. The adapter will reuse any inactive
connections in the pool or, if all connections are active and the connection
pool has reached its maximum size, the adapter will wait for a connection to
become available. Default: 10.
|
| Pool Increment Size | If connection pooling is enabled, this field
specifies the number of connections by which the pool will be incremented if
connections are needed, up to the maximum pool size. Default:
1.
|
| Block Timeout | If connection pooling is enabled, this field
specifies the number of milliseconds that the Integration Server will
wait to obtain a connection before it times out and returns an error. Default:
1000.
|
| Expire Timeout | If connection pooling is enabled, this field
specifies the number of milliseconds that an inactive connection can remain in
the pool before it is closed and removed from the pool. For example, to specify
10 seconds, specify 10000. Enter 0 to specify no timeout. Default:
1000.
Note: |
| Startup Retry Count | The number of times that the system should
attempt to initialize the connection pool at startup if the initial attempt
fails. Default: 0.
|
| Startup Backoff Timeout | The number of seconds that the system should wait between attempts to initialize the connection pool. |
If you no longer want to use a particular EntireX Adapter connection, you can delete it by following the instructions in this section. You delete adapter connections using the IS Administration Console. If you delete an EntireX Adapter connection, the adapter services that are defined to use the connection will no longer work. You can change the connection an adapter service uses. Therefore, if you delete an EntireX Adapter connection, you can assign a different connection to an adapter service and reuse the service.
To delete a connection
In the menu in the IS Administration Console navigation area, click .
Make sure that the connection is disabled before deleting. To disable the connection, click in the Enabled column and click to confirm. The Enabled column now shows "No" (Disabled) for the connection.
On the Connections screen, click the Delete icon for the connection you want to delete.
As a result, the Integration Server deletes the adapter connection.
An EntireX Adapter connection must be enabled before you can configure any adapter service using the connection, or before an adapter service can use the connection at runtime. You enable adapter connections using the IS Administration Console.
Note:
When you reload a package that contains enabled connections, the
connections will automatically be enabled when the package reloads. If the
package contains connections that are disabled, they will remain disabled when
the package reloads.
To enable a connection
In the menu in the IS Administration Console navigation area, click .
On the Connections screen, click in the Enabled column for the connection you want to enable.
As a result, the IS Administration Console enables the adapter connection and displays a tick (✓) and "Yes" in the Enabled column.
Note:
The EntireX broker configured in the Connections does not
need to be running to enable a connection. Only the parameters are checked for
correctness while enabling a connection.
EntireX Adapter connections must be disabled before you can edit or delete them. You disable adapter connections using the IS Administration Console.
To disable a connection
In the menu in the IS Administration Console navigation area, click .
On the Connections screen, click in the Enabled column for the connection you want to disable.
As a result, the adapter connection becomes disabled and you see a "No" in the Enabled column.
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.
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.