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 EntireX Workbench. 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 EntireX Workbench. This ensures that the information generated from the interface definition stored in the Software AG IDL file is present. A wizard inside the EntireX Workbench 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:
| Connection Type | Note |
|---|---|
| EntireX RPC | 1 |
| EntireX Reliable RPC | 1 |
| EntireX Direct RPC | 1 |
| EntireX RPC Listener | 2 |
| EntireX Reliable RPC Listener | 2 |
| EntireX Direct RPC Listener | 2 |
| IMS Connect | 1 |
| CICS ECI | 1 |
| ApplinX | 1 |
| ACI Server | 1 |
Notes:
The EntireX Workbench wizard additionally creates an EntireX Adapter service for each program of the IDL file; see EntireX Adapter Services.
The EntireX Workbench wizard additionally creates an EntireX Adapter listener; see also Listeners and Adapter Notifications.
To create a connection
Start the EntireX Workbench.
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, it is possible to 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 Listener Connections and 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 EntireX Workbench | Can be set 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 and Certificates with EntireX. | |||
| Encoding | The character encoding to be used for the RPC connection in the Integration Server. Default: the encoding of the Integration Server. | 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 for Natural Security.(1) | No | Yes | |
| RPC Password | The password for the user above.(1) | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type | The transaction type, "local transactions" and "no transactions" are supported. | none | No | No |
Notes:
The transaction type "local" of the Integration Server is mapped to conversational RPC for RPC connections and Reliable RPC with client-commit for Reliable RPC connections. See Appendix B in webMethods Adapter Development Kit User's Guide Version 6.5 for transactions of the Integration Server. XA transactions are not supported by the EntireX Adapter.
| Parameter | Description | Default | Can be set from the EntireX Workbench | 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 and Certificates with EntireX. | No_Encryption | No | No |
| Encoding | The character encoding to be used for the RPC connection in the Integration Server. Default: the encoding of the Integration Server. | 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. | No | Yes | |
| RPC User | The RPC user for Natural Security. | No | Yes | |
| RPC Password | The password for the user above | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information |
Caution: |
Generated | No | |
| Transaction Type | The transaction type. "local transactions "and "no transactions" are supported. | none | No | No |
| Parameter | Description | Default | Can be set from the EntireX Workbench |
|---|---|---|---|
| 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 and Certificates with EntireX. | No_Encryption | No |
| Encoding | The character encoding to be used for the RPC connection in the Integration Server. Default: the encoding of the Integration Server. | Yes | |
| Compression Level | The level of broker data compression. | NO_COMPRESSION | No |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description | Default | Can be set from the EntireX Workbench | Can be set dynamically with service |
|---|---|---|---|---|
| Server Address | The address of the RPC server. 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. | No | Yes | |
| RPC User | The RPC user for Natural Security. | No | Yes | |
| RPC Password | The password for the user above. | No | Yes | |
| Retype RPC Password | Verification of the password above. | Not applicable | Not applicable | |
| Metadata Information | Caution: Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench. | Generated | No | |
| Transaction Type | The transaction type "local transactions" and "no transactions" are supported. | none | No | No |
The transaction type "local" of the EntireX Adapter connection is mapped to conversational RPC for RPC connections and Reliable RPC with client-commit for Reliable RPC connections. See Appendix B in webMethods Adapter Development Kit User's Guide, Version 6.5 for transactions of the Integration Server. XA transactions are not supported by the EntireX Adapter.
| Parameter | Description | Default | Can be set from the EntireX Workbench |
|---|---|---|---|
| Server Address | The address of the RPC server. 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 the EntireX Workbench |
|---|---|---|---|
| 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 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 and Certificates with EntireX. | No_Encryption | No |
| Encoding | The character encoding to be used for the RPC connection in the Integration Server. Default: the encoding of the Integration Server. | 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 EntireX Workbench | Can be set dynamically with service |
|---|---|---|---|---|
| Host | Hostname of IMS Connect. | Yes | No | |
| Port | IMS Connect Port. | Yes | No | |
| IMS Connect Datastore ID | Name of the data store, as defined in the IMS Connect configuration member. | Yes | Yes | |
| Encoding | The character encoding used to call IMS Connect. It is recommended to specify the appropriate EBCDIC encoding. | cp037 | Yes, default value is cp037 | No |
| Socket Timeout (1) | Socket timeout (in milliseconds). The minimum value is 2.000 ms. If a lower value is specified, it will be changed to 2.000. | 10000 | No | No |
| Check for DFS Errors | Return an error and do not return the message if it might contain a DFS error message. | true | No | No |
| Logical Terminal ID | IMS Connect logical terminal ID, maximal 8 bytes (optional). | No | Yes | |
| Use old Exit | Use old IMS Connect user message exit if set to "true". The old exit name is "*SAMPLE*", the new exit name is "*SAMPL1*". | true | No | No |
| Exit Name | Optional name of the IMS Connect user message exit. | 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 | |
| SSL Parameters | Truststore and optional certificate. Example:
trust_store=CACerts.jks |
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:
| Parameter | Description | Default | Can be set from EntireX Workbench | 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 | The character encoding used to call CICS ECI. It is recommended to specify the appropriate EBCDIC encoding | cp037 | Yes | No |
| Socket Timeout | Socket timeout (in milliseconds) | 10000 | No | No |
| RACF User ID | The name of the user to log on to CICS ECI. | Yes | Yes | |
| RACF Password / PassTicket | The password for the user above. | Yes | Yes | |
| Retype RACF Password / PassTicket | Verification of the password above | No | No | |
| SSL Parameters | Truststore and optional certificate. Example:
trust_store=CACerts.jks |
No | No | |
| Metadata Information |
Caution: |
Generated | No |
| Parameter | Description | Default | Can be set from EntireX Workbench |
|---|---|---|---|
| Host | Hostname of ApplinX server. | Yes | |
| Port | ApplinX server Port. | Yes | |
| Secure connection | Set to "true" for a secure connection. | false | No |
| Metadata Information |
Caution: |
Generated |
| Parameter | Description |
|---|---|
| Enable Connection Pooling | Enables the adapter to use connection pooling.
Default: true. See Common Connection Management Properties (for all Connection Types) under EntireX Adapter Connections 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.