Version 9.6 SEARCH   INDEX   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT
 —  EntireX Adapter Installation and User's Guide  —

EntireX Adapter Connections

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 which are used dynamically can be created with the IS Administration Console.

Before Configuring or Managing Adapter Connections

Start of instruction setTo prepare to configure or manage adapter connections

  1. Install the webMethods Integration Server and the EntireX Adapter on the same machine, using the Software AG Installer.

  2. 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.

  3. Start your Integration Server and the IS Administration Console, if they are not already running.

  4. Using the IS Administration Console, make sure the WmEntireX package is enabled. See Importing and Exporting Packages for instructions.

  5. If you have not already done so, use the Designer to create a user-defined package to contain the connection. For more information on managing packages for the adapter, see EntireX Adapter Package Management.

Top of page

Configuring Adapter Connections

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:

  1. EntireX RPC Connection

  2. EntireX Reliable RPC Connection

  3. EntireX Direct RPC Connection

  4. EntireX RPC Listener Connection

  5. EntireX Reliable RPC Listener Connection

  6. EntireX Direct RPC Listener Connection

  7. Connection to IMS Connect

  8. CICS ECI Connection

  9. ApplinX Connection

  10. ACI Server Connection

For connections of type "EntireX RPC", "EntireX Reliable RPC", "ApplinX", "EntireX Direct RPC", "IMS Connect ", "CICS ECI", and "ACI Server", the EntireX Workbench wizard additionally creates an EntireX Adapter service for each program of the IDL file; see EntireX Adapter Services for further information.

For connections of type "EntireX RPC Listener", "EntireX Direct RPC Listener" and "EntireX Reliable RPC Listener", the EntireX Workbench wizard additionally creates an EntireX Adapter listener; see also Listeners and Adapter Notifications.

Start of instruction setTo create a connection

  1. Start the EntireX Workbench.

  2. Navigate to the Software AG IDL file you want to use.

  3. On the IDL file, right-click and choose Generate webMethods IS Connection from Software AG IDL...

  4. 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".

Top of page

Viewing Adapter Connection Parameters

You can view a connection's parameters using the IS Administration Console or the Designer.

Start of instruction setTo view the parameters for a connection using the IS Administration Console

  1. In the Adapters menu in the IS Administration Console navigation area, click EntireX Adapter.

  2. 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.

  3. Click Return to EntireX Adapter Connections to return to the main connections screen.

Start of instruction setTo view the parameters for a connection using the Designer

  1. Start the Designer if it is not already running.

  2. From the Designer Package Navigator view, open the package and folder in which the connection is located.

  3. 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.

Top of page

Editing 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:

Editing a Connection

You edit (and modify) adapter connections using the IS Administration Console.

Start of instruction setTo edit a connection

  1. In the Adapters menu in the IS Administration Console navigation area, click EntireX Adapter.

  2. Make sure that the connection is disabled before editing it. See Disabling Adapter Connections for instructions.

  3. 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:

  4. 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.

  5. Click Save Changes to save the connection and return to the Connections screen.

Connection Parameters for RPC Connections

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 The level of broker encryption to be used for the RPC call. 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
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:
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

Notes:

  1. Depending on the server configuration, some Natural RPC servers need the RPC library name. See the documentation of the Natural RPC Server at https://empower.softwareag.com/Products/Documentation/default.asp for details.

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.

Connection Parameters for Reliable RPC Connections

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 The level of broker encryption to be used for the RPC call 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:
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

Connection Parameters for RPC Listener Connections and Reliable RPC Listener Connections

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 The level of broker encryption to be used for the RPC call. 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:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  Generated

Connection Parameters for Direct RPC Connections

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.

Connection Parameters for Direct RPC Listener Connections

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:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  Generated

Connection Parameters for ACI Server Connections

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 which 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 The level of broker encryption to be used for the RPC call. 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:
See Writing ACI Servers for the RPC-ACI Bridge in COBOL/Natural in the EntireX RPC-ACI Bridge documentation for restrictions concerning ACI servers.

COBOL No
Metadata Information

Caution:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  Generated

Connection Parameters for Connections to IMS Connect

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:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  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:

  1. The socket timeout value is used to set the IMS Connect timer value. The timer value specifies the delay that IMS Connect will wait until IMS returns data to IMS Connect, which in turn will be sent to the adapter. If the socket timeout is less than one minute, the IMS timer value is one second less than the socket timeout. If the socket timeout is less than one hour, the IMS timer value is one minute less than the socket timeout. The maximum IMS timer value is 60 minutes.

Connection Parameters for CICS ECI Connections

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:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  Generated No

Connection Parameters for ApplinX Connections

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:
Do not change this generated property. It contains timestamp, IDL file name, library name, and version of the EntireX Workbench.

  Generated

Common Connection Management Properties (for all Connection Types)

Parameter Description
Enable Connection Pooling Enables the adapter to use connection pooling. Default: true. See 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:
The adapter will never violate the Minimum Pool Size parameter. These connections remain in the pool regardless of how long they are inactive.

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.

Top of page

Deleting Adapter Connections

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.

Start of instruction setTo delete a connection

  1. In the Adapters menu in the IS Administration Console navigation area, click EntireX Adapter.

  2. Make sure that the connection is disabled before deleting. To disable the connection, click Yes in the Enabled column and click OK to confirm. The Enabled column now shows "No" (Disabled) for the connection.

  3. 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.

Top of page

Enabling Adapter Connections

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.

Start of instruction setTo enable a connection

  1. In the Adapters menu in the IS Administration Console navigation area, click EntireX Adapter.

  2. On the Connections screen, click No 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.

Top of page

Disabling Adapter Connections

EntireX Adapter connections must be disabled before you can edit or delete them. You disable adapter connections using the IS Administration Console.

Start of instruction setTo disable a connection

  1. In the Adapters menu in the IS Administration Console navigation area, click EntireX Adapter.

  2. On the Connections screen, click Yes 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.

Top of page

 www.softwareag.com  Copyright © 2007-2014 Software AG, Darmstadt, Germany.   SEARCH   INDEX   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT