Configuring Websphere MQ Adapter Environment Properties

The WebSphere MQ Adapter parameters, accessed from the Environment Explorer tree, are organized into the following sections:

Inbound MQSeries Adapter — Inbound Adapter Environment Configuration

The Inbound MQSeries Adapter — Inbound Adapter Environment Configuration section of the WebSphere MQ Adapter Environment properties contains the top-level parameters displayed in the following table.

Table 26 Inbound MQSeries Adapter — Inbound Adapter Environment Configuration


Name	Description	Required Value
Host Name	Specifies name of the computer on which the queue manager resides. This property must be left blank to cause the Adapter to use Bindings mode rather than Client mode. Bindings mode allows the Adapter to communicate directly with queue manager without a TCP/IP connection. In this mode, the Adapter and the queue manager need to be installed on the same machine. When using a Client mode connection, the Adapter communicates with the queue manager using a TCP/IP-based connection.	The name of the specific queue manager host. Leave the value blank to cause the Adapter to use Bindings mode.
Port Number	Specifies the number of the listen port on which the queue manager is bound.	A number indicating the port on which the queue manager is bound.
Queue Manager Name	Specifies the name of the local queue manager to which the Adapter connects. Note – Use only a local queue manager name in the Adapter Environment Configuration, whether bindings or Client mode is used. See Accessing Non-Local Queue Managers and Non-Local Queues.	The name of the local queue manager.
Channel Name	Specifies the name of the channel being used.	The name of the channel.
Coded Character Set ID	Specifies the Client Coded Character Set ID (CCSID). When left blank, the Adapter uses a default, platform-dependent CCSID. The Adapter must use a Client CCSID compatible with the queue manager’s CCSID, in order that character-based data sent to or received from the queue manager is encoded/decoded properly. If, for any reason, it becomes necessary to send character data that utilizes a different CCSID than the one specified by this setting to a queue manager, then you may invoke the Adapter OTD’s MsgHeader.setCharacterSet method from the Collaboration to temporarily override the setting.	A supported CCSID (integer) value, or none at all (blank). For a table of supported CCSID, please see the entry for the variable, MQEnvironment.CCSID in IBM document SC34-6066-00, WebSphere MQ Using Java, of your WebSphere MQ software installation.
UserID	Specifies the user ID required to access the queue manager. If none is required, leave this parameter blank.	A User ID required to access the queue manager.
Password	Specifies the user password required to access the queue manager. If a password is not required, leave this parameter blank.	A user password that grants access to a specific queue manager.
SSL Enabled	When SSL is enabled, all communications are sent over a secure channel.	Yes or No. The configured default is No.

Outbound MQSeries Adapter (XA) — Outbound Adapter Environment Configuration

The Outbound MQSeries Adapter (XA) — Outbound Adapter Environment Configuration section of the WebSphere MQ Adapter Environment properties contains the top-level parameters displayed in the following table.

Table 27 Outbound MQSeries Adapter (XA) — Outbound Adapter Environment Configuration


Name	Description	Required Value
Host Name	Specifies name of the computer on which the queue manager resides. This property must be left blank to cause the Adapter to use Bindings mode rather than Client mode. Bindings mode allows the Adapter to communicate directly with queue manager, without a TCP/IP connection. In this mode, the Adapter and the queue manager need to be installed on the same machine. When the Adapter is configured to use a Client mode connection, the Adapter communicates with the queue manager using a TCP/IP-based connection.	The name of the specific queue manager host. Leave the value blank to cause the Adapter to use Bindings mode. Note – WebSphere MQ Adapter (outbound) support for XA requires Bindings mode. The Adapter’s HostName and Channel Name property values must be left blank for the Adapter to operate in Bindings mode.
Port Number	Specifies the number of the listen port on which the queue manager is bound.	A number indicating the port on which the queue manager is bound.
Queue Manager Name	Specifies the name of the local queue manager to which the Adapter connects. Note – Use only a local queue manager name in the Adapter Environment Configuration, whether bindings or Client mode is used. See Accessing Non-Local Queue Managers and Non-Local Queues.	The name of the local queue manager.
Channel Name	Specifies the name of the channel being used.	The name of the channel.
Coded Character Set ID	Specifies the Client Coded Character Set ID (CCSID). When left blank, the Adapter uses a default, platform-dependent CCSID. The Adapter must use a Client CCSID compatible with the queue manager’s CCSID, in order that character-based data sent to or received from the queue manager is encoded/decoded properly. If, for any reason, it becomes necessary to send character data that utilizes a different CCSID than the one specified by this setting to a queue manager, then you may invoke the Adapter OTD’s MsgHeader.setCharacterSet method from the Collaboration to temporarily override the setting.	A supported CCSID (integer) value, or none at all (blank). For a table of supported CCSID, please see the entry for the variable, MQEnvironment.CCSID in IBM document SC34-6066-00, WebSphere MQ Using Java, of your WebSphere MQ software installation.
User ID	Specifies the user ID required to access the queue manager. If none is required, leave this parameter blank.	A User ID required to access the queue manager.
Password	Specifies the user password required to access the queue manager. If a password is not required, leave this parameter blank.	A user password that grants access to a specific queue manager.
SSL Enabled	When SSL is enabled, all communications are sent over a secure channel.	Yes or No. The configured default is No.

Outbound MQSeries Adapter (XA) — Connection Retry Settings

The Outbound MQSeries Adapter (XA) — Connection Retry Settings section of the WebSphere MQ Adapter Environment properties provides parameters for retrying outbound Adapter connection establishment. This section contains the top-level parameters displayed in the following tables.

Table 28 Environment Configuration - Outbound MQSeries Adapter (XA) - Connection Retry Settings


Name	Description	Required Value
Connection Retry Count	Specifies the maximum number of attempts made to connect to the destination queue manager. If the queue manager cannot be accessed for any reason, this setting specifies how many reattempts are made to complete the processing.	An integer indicating the maximum number of connection attempts. The configured default is 0.
Connection Retry Interval	Specifies the amount of time (in milliseconds) between attempts to connect to the destination queue manager or queue. This is the pause between each reattempt to access the destination queue manager. Used in conjunction with the Connection Retry Count setting.	An integer indicating the wait time in milliseconds between connection attempts. The configured default is 1000.

Outbound MQSeries Adapter (XA) — Connection Pool Settings

The Outbound MQSeries Adapter (XA) — Connection Pool Settings section of the WebSphere MQ Adapter Environment properties provides parameters for controlling the outbound Adapter’s connection pool size. This section contains the top-level parameters displayed in the following table.

Table 29 Environment Configuration - Outbound MQSeries Adapter (XA) - Connection Pool Settings


Name	Description	Required Value
Steady Pool Size	Specifies the minimum number of physical connections the pool will keep available at all times. A value of 0 (zero) indicates that there will be no physical connections in the pool and that new connections will be created as needed.	An integer indicating the maximum number of connection kept available. The configured default is 2.
Max Pool Size	Specifies the maximum number of physical connections the pool can contain. A value of 0 (zero) indicates that there is no maximum.	An integer indicating the maximum pool size. The configured default is 10.
Max Idle Timeout	Specifies the amount of time, in seconds, before an unused connection is removed from the pool. When this is set to greater than 0, the container removes or destroys any connections that are idle for the specified duration. A value of 0 indicates that idle connections can remain in the pool indefinitely. 0 (zero) indicates that there is no maximum.	An integer indicating the idle time in seconds. The configured default is 300.

Outbound MQSeries Adapter — Outbound Adapter Environment Configuration

The Outbound MQSeries Adapter — Outbound Adapter Environment Configuration section of the WebSphere MQ Adapter Environment properties contains the top-level parameters displayed in the following table.

Table 30 Environment Configuration - Outbound MQSeries Adapter — Outbound Adapter Environment Configuration


Name	Description	Required Value
Host Name	Specifies name of the computer on which the queue manager resides. This property must be left blank to cause the Adapter to use Bindings mode rather than Client mode. Bindings mode allows the Adapter to communicate directly with queue manager, without a TCP/IP connection. In this mode, the Adapter and the queue manager need to be installed on the same machine. When the Adapter is configured to use a Client mode connection, the Adapter communicates with the queue manager using a TCP/IP-based connection.	The name of the specific queue manager host. Leave the value blank to cause the Adapter to use Bindings mode. Note – WebSphere MQ Adapter (outbound) support for XA requires Bindings mode. The Adapter’s HostName and Channel Name property values must be left blank for the Adapter to operate in Bindings mode.
Port Number	Specifies the number of the listen port on which the queue manager is bound.	A number indicating the port on which the queue manager is bound.
Queue Manager Name	Specifies the name of the queue manager to which the Adapter connects. Note – Use only a local queue manager name in the Adapter Environment Configuration, whether bindings or Client mode is used. See Accessing Non-Local Queue Managers and Non-Local Queues.	The name of the local queue manager.
Channel Name	Specifies the name of the channel being used.	The name of the channel.
Coded Character Set ID	Specifies the Client Coded Character Set ID (CCSID). When left blank, the Adapter uses a default, platform-dependent CCSID. The Adapter must use a Client CCSID compatible with the queue manager’s CCSID, in order that character-based data sent to or received from the queue manager is encoded/decoded properly. If, for any reason, it becomes necessary to send character data that utilizes a different CCSID than the one specified by this setting to a queue manager, then you may invoke the Adapter OTD’s MsgHeader.setCharacterSet method from the Collaboration to temporarily override the setting.	A supported CCSID (integer) value, or none at all (blank). For a table of supported CCSID, please see the entry for the variable, MQEnvironment.CCSID in IBM document SC34-6066-00, WebSphere MQ Using Java, of your WebSphere MQ software installation.
UserID	Specifies the user ID required to access the queue manager. If none is required, leave this parameter blank.	A User ID required to access the queue manager.
Password	Specifies the user password required to access the queue manager. If a password is not required, leave this parameter blank.	A user password that grants access to a specific queue manager.
SSL Enabled	When SSL is enabled, all communications are sent over a secure channel.	Yes or No. The configured default is No.

Outbound MQSeries Adapter — Connection Retry Settings

The Outbound MQSeries Adapter — Connection Retry Settings section of the WebSphere MQ Adapter Environment properties provides parameters for retrying outbound Adapter connection establishment. This section contains the top-level parameters displayed in the following table.

Table 31 Environment Configuration - Outbound MQSeries Adapter - Connection Retry Settings


Name	Description	Required Value
Connection Retry Count	Specifies the maximum number of attempts made to connect to the destination queue manager. If the queue manager cannot be accessed for any reason, this setting specifies how many reattempts are made to complete the processing.	An integer indicating the maximum number of connection attempts. The configured default is 0.
Connection Retry Interval	Specifies the amount of time (in milliseconds) between attempts to connect to the destination queue manager. This is the pause between each reattempt to access the destination queue manager or queue. Used in conjunction with the Connection Retry Count setting.	An integer indicating the wait time in milliseconds between connection attempts. The configured default is 1000.

Outbound MQSeries Adapter — Connection Pool Settings

The Outbound MQSeries Adapter — Connection Pool Settings section of the WebSphere MQ Adapter Environment properties provides parameters for controlling the outbound Adapter’s connection pool size. This section contains the top-level parameters displayed in the following table.

Table 32 Environment Configuration - Outbound MQSeries Adapter - Connection Pool Settings


Name	Description	Required Value
Steady Pool Size	Specifies the minimum number of physical connections the pool will keep available at all times. A value of 0 (zero) indicates that there will be no physical connections in the pool and that new connections will be created as needed.	An integer indicating the maximum number of connection kept available. The configured default is 2.
Max Pool Size	Specifies the maximum number of physical connections the pool can contain. A value of 0 (zero) indicates that there is no maximum.	An integer indicating the maximum pool size. The configured default is 10.
Max Idle Timeout	Specifies the amount of time, in seconds, before an unused connection is removed from the pool. When this is set to greater than 0, the container removes or destroys any connections that are idle for the specified duration. A value of 0 indicates that idle connections can remain in the pool indefinitely. 0 (zero) indicates that there is no maximum.	An integer indicating the idle time in seconds. The configured default is 300.

Outbound MQSeries Adapter — Connection Establishment Mode

The Outbound MQSeries Adapter — Connection Establishment Mode section of the WebSphere MQ Adapter Environment properties contains the top-level parameters displayed in the following table.

Table 33 Environment Configuration - Outbound MQSeries Adapter - Connection Establishment Mode


Name	Description	Required Value
Connection Mode	Specifies whether the Adapter automatically connects to the external system upon startup or connects using manual mode. When set to Manual, the Adapter will not connect to the external system on startup, and instead expects the user to initiate the connection by invoking the MQ Adapter OTD’s connectToQueueManager method. Manual mode is only available when using Java Collaboration Definitions. This allows you to dynamically connect to different Queue Managers. Any parameters assigned in the Java Collaboration will override the same parameters specified in the Connectivity Map or Environment properties.	Automatic or Manual. The configured default is Automatic.

Accessing Non-Local Queue Managers and Non-Local Queues

When used with alias queues and remote queues, the WebSphere MQ Adapter functions with several restrictions. Alias queues and remote queues with local queue definitions may be accessed in the same way as actual local queues, through the use of the Adapter OTD’s accessQueue(String) method. Remote queues without local queue definitions need to use the accessQueue(String, String) method instead.

Also, when alias queues or remote queues are used, the Adapter cannot proactively verify the connection (and reconnect, if necessary) before each OTD operation. This is because the Adapter verifies connections by querying queue objects, and it is not possible to query alias queues and remote queues. This means that when alias queues or remote queues are used with the Adapter, the Collaboration is responsible for recovering connection failures itself, including reestablishing the queue manager and queue connections as needed. For more information, refer to the WebSphere MQ Adapter Javadoc.

Connecting to a Remote WebSphere MQ Queue

When an Adapter connects to a local queue manager and accesses one of its queues, that queue is a local queue. When an Adapter connects to a remote queue manager and accesses one of its queues, then that queue, is also a local queue. In WebSphere MQ terms, a remote queue is a queue that is managed by a queue manager other than the one to which the application (in this case, the Adapter) is connected.

For example, say that there are two queue managers, QM1 and QM2. QM1 manages a queue (Q1) and runs on Host1. QM2 manages a queue (Q2) and runs on Host2.

Furthermore, say that need to send messages to Q2, but the Adapter may only communicate with Host1 (that is, Host2 is unreachable from the system in which the Adapter is executing). By creating the appropriate channels and a remote queue definition (R1 on QM1), messages sent to R1 can be shuttled automatically to Q2 on QM2.

For this example, the Queues and the Adapter are configured as follows:

Creating a Channel and Remote Queue Definition

If either QM1 or QM2 do not have a transmission queue defined, create one. Both queue managers require one transmission queue each. In this example, assume that both queue managers have the transmission queue ’xmit’.

Create a Sender Channel for QM1 that points to Host2 and transmission queue xmit. The name of the channel must match the Receiver Channel created in the next step.

Create a Receiver Channel for Q2. The name of the channel must match the Sender Channel created in the previous step.

In QM1, create a Remote Queue Definition (R1). Designate Q2 as its remote queue, QM2 as its remote queue manager, and xmit as its transmission queue.

Configure the MQ Adapter to connect to Host1, QM1, and have it put messages into queue R1.

Note –
Messages cannot be read/GET from remote queues, only PUT. In the example situation above, to read the messages placed in QM2:Q2 through R1, an Adapter needs to connect directly to QM2 (Host2), thereby interacting with Q2 as a local queue.

Previous: SWIFT AG Adapter Environment Properties