Administration of the WebSphere MQ-bridge

This section contains information on the tasks associated with the administration of the WebSphere MQ-bridge

WebSphere MQ-bridge administration actions

Run state

Each administered object has a run state. This can be 'running' or 'stopped' indicating whether the administered object is active or not.

When an administered object is 'stopped', it cannot be used, but its configuration parameters can be queried or updated.

If the WebSphere MQ-bridge queue references a bridge administered object that is 'stopped', it is unable to convey an WebSphere MQ Everyplace message onto the WebSphere MQ network until the bridge, WebSphere MQ queue manager proxy, and client connection objects are all 'started'.

The run state of administered objects can be changed using the start and stop actions from the MQeMQBridgeAdminMsg, MQeMQQMgrProxyAdminMsg, MQeClientConnectionAdminMsg or MQeListenerAdminMsg administration message classes.

The actions supported by the WebSphere MQ-bridge administration objects are described in the following sections.

Start action

An administrator can send a start action to any of the administered objects.

The affect children boolean flag affects the results of this action. The start action starts the administered object and all its children (and children's children) if the affect children boolean field is in the message and is set to true. If the flag is not in the message or is set to false, only the administered object receiving the start action changes its run-state. For example, sending start to a bridge object with affect children as true causes all proxy, client connection, and listeners that are ancestors, to start. If affect children is not specified, only the bridge is started. An object cannot be started unless its parent object has already been started. Sending a start event to an administered object attempts to start all the objects higher in the hierarchy that are not already running.

Stop action

An administered object can be stopped by sending it a stop action. The receiving administered object always makes sure all the objects below it in the hierarchy are stopped before it is stopped itself.

Inquire action

The inquire action queries values from an administered object.

If the administered object is running, the values returned on the inquire are those that are currently in use. The values returned from a stopped object reflect any recent changes to values made by an update action. Thus, a sequence of start, update, inquire, returns the values configured before the update, while start, update, stop, inquire, returns the values configured after the update.

You may find it less confusing if you stop any administered object before updating variable values.

Update action

The update action changes one or more values for characteristics for an administered object. The values set by an update action do not become current until the administered object is next stopped. (See Inquire action.)

Delete action

The delete action permanently removes all current and persistent information about the administered object. The affect children boolean flag affects the outcome of this action. If the affect children flag is present and set to true the administered object receiving this action issues a stop action, and then a delete action to all the objects below it in the hierarchy, removing a whole piece of the hierarchy with one action. If the flag is not present, or it is set to false, the administered object deletes only itself, but this action cannot take place unless all the objects in the hierarchy below the current one have already been deleted.

Create action

The create action creates an administered object. The run state of the administered object created is initially set to stopped.

WebSphere MQ-bridge considerations when shutting down a WebSphere MQ queue manager

We recommend that before you stop a WebSphere MQ queue manager, you issue a stop administration message to all the WebSphere MQ queue-manager-proxy bridge objects. This stops the WebSphere MQ Everyplace network from trying to use the WebSphere MQ queue manager and possibly interfering with the shutdown of the WebSphere MQ queue manager. (This can also be achieved by issuing a single stop administration message to the MQebridges object.)

If you choose not to stop the WebSphere MQ queue-manager-proxy bridge object before you shut the WebSphere MQ queue manager, the behavior of the WebSphere MQ shutdown and the WebSphere MQ-bridge depends on the type of WebSphere MQ queue manager shutdown you choose, immediate shutdown or controlled shutdown.

Immediate shutdown

Stopping a WebSphere MQ queue manager using immediate shutdown severs any connections that the WebSphere MQ-bridge has to the WebSphere MQ queue manager (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). The WebSphere MQ system shuts down as normal.

This causes all the WebSphere MQ-bridge transmission queue listeners to stop immediately, each one warning that it has shut down due to the WebSphere MQ queue manager stop.

Any WebSphere MQ-bridge queues that are active retain a (broken) connection to the WebSphere MQ queue manager until:

When an WebSphere MQ-bridge queue has no connection, the next operation on that queue causes a new connection to be obtained. If the WebSphere MQ queue manager is not available, the operation on the queue fails synchronously. If the WebSphere MQ queue manager has been restarted after the shutdown, and a queue operation, such as putMessage, acts on the bridge queue, then a new connection to the active WebSphere MQ queue manager is established, and the operation executes as expected.

Controlled shutdown

Stopping a WebSphere MQ queue manager using the controlled shutdown does not sever any connections immediately, but waits until all connections are closed (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). Any active WebSphere MQ-bridge transmission queue listeners notice that the WebSphere MQ system is quiescing, and stop with a relevant warning.

Any WebSphere MQ-bridge queues that are active retain a connection to the WebSphere MQ queue manager until:

The bridge client-connection object maintains a pool of connections, that are awaiting use. If there is no bridge activity, the pool retains WebSphere MQ client connections until the connection idle time exceeds the idle time-out period (as specified on the client connection object configuration), at which point the connections in the pool are closed.

When the last client connection to the WebSphere MQ queue manager is closed, the WebSphere MQ controlled shutdown completes.

Administered objects and their characteristics

This section describes the characteristics of the different types of administered objects associated with the WebSphere MQ Everyplace WebSphere MQ-bridge. Characteristics are object attributes that can be queried using an inquireAll() administration message. The results can be read and used by the application, or they can be sent in an update or create administration message to set the values of the characteristics. Some characteristics can also be set using the create and update administration messages. Each characteristic has a unique label associated with it and this label is used to set and get the characteristic value.

The following lists show the attributes that apply to each administered object. The attributes are described in detail in alphabetical order in Attribute details. The label constants are defined in the header file published/MQe_MQBridge_Constants.h. If you include published/MQe_API.h in you installation, this file is included automatically.

Characteristics of bridges objects

Characteristics of bridge objects

Characteristics of WebSphere MQ queue manager proxy objects

Characteristics of client connection objects

Characteristics of WebSphere MQ transmission queue listener objects

Attribute details

AdapterClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_ADAPTER

Valid actions
Inquire, create, update

Description
Either a Java class name, or an alias that can be resolved into a Java class name. The client connection uses this attribute to determine which class to use to manipulate the WebSphere MQ system. Different versions of WebSphere MQ may recognize different adapter classes.

If this attribute is not specified, a default value of com.ibm.mqe.mqbridge.MQeMQAdapter is used.

This parameter is not validated

AdministeredObjectClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_ADMINISTERED_OBJECT

Valid actions
Inquire, create, update

Description
The name of a Java class, or an alias that resolves into a Java class name using the WebSphere MQ Everyplaceclass aliasing technique. The '.class' extension is not required.

This attribute describes the Java class that is used to provide the function for the bridge administered object. The value set depends on the type of administered object being configured.

This field should not be set, or changed without detailed instructions from IBM staff.

If this parameter is not specified when the object is created, it defaults to the following allowable values:

Object being configured Value
A bridge object com.ibm.mqe.mqbridge.MQeMQBridge
WebSphere MQ queue manager proxy object com.ibm.mqe.mqbridge.MQeMQQMgrProxy
WebSphere MQ client connection object com.ibm.mqe.mqbridge.MQeClientConnection
WebSphere MQ transmission queue listener object com.ibm.mqe.mqbridge.MQeListener

Valid characters are: '0-9' 'A-Z' 'a-z' - . % /

BridgeName

Type:
Unicode

Label:
MQE_FIELD_LABEL_BRIDGE_NAME

Valid actions
Inquire, create, update, delete, start, stop

Description
If you use a symbolic name, it may take longer to detect that this machine is not switched on, or that the name server is not working. If this causes a problem, you can use the actual I/P address in this field instead.
Note:
This characteristic can be set only once, with the create administration message. Thereafter it is used to identify which bridge administered object should be inquired on, updated, deleted, started, or stopped.

CCSID

Type:
Int

Label:
MQE_FIELD_LABEL_CCSID

Valid actions
Inquire, create, update

Description
See the WebSphere MQ Using Java documentation for a description of this parameter.

Valid values are: 0 to MAXINT. The default is 0.

Child

Type:
Unicode

Label:
MQE_FIELD_LABEL_CHILD

Valid actions
Inquire

Description
A field containing the name of an WebSphere MQ-bridge administered object.

Children

Type:
MQeFields array

Label:
MQE_FIELD_LABEL_CHILDREN

Valid actions
Inquire

Description
An array of Child fields, each element containing a Child attribute.

ClientConnectionName

Type:
Unicode

Label:
MQE_FIELD_LABEL_CLIENT_CONNECTION_NAME

Valid actions
Inquire, create, update, delete, start, stop

Description
Note:
This characteristic can be set only once, with the create administration message. Thereafter it is used to identify which bridge administered object should be inquired on, updated, deleted, started, or stopped.

DeadLetterQName

Type:
Unicode

Label:
MQE_FIELD_LABEL_DEAD_LETTER_Q_NAME

Valid actions
Inquire, create, update

Description
If the gateway finds it cannot deliver a message from WebSphere MQ to WebSphere MQ Everyplace, the message cannot be processed by the gateway, and it is placed on a dead letter queue on the WebSphere MQ system. This parameter defines which queue the erroneous message is delivered to.

The default value is SYSTEM.DEAD.LETTER.QUEUE.

DefaultTransformer

Type:
Unicode

Label:
MQE_FIELD_LABEL_DEFAULT_TRANSFORMER

Valid actions
Inquire, create, update

Description
The classname specified here is used as the default transformer class. When a message is sent from WebSphere MQ to WebSphere MQ Everyplace, the target queue may have a transformer class defined. If a transformer is not defined, this class is used to transform the WebSphere MQ message into the WebSphere MQ Everyplace format.

When a message is sent from WebSphere MQ Everyplace to WebSphere MQ, the transmission queue listener moving the message onto WebSphere MQ Everyplace may have a transformer class defined. If a transformer is not defined, this class is used to transform the WebSphere MQ Everyplace message into the WebSphere MQ format.

No validation of the value in this field is performed.

The default value is com.ibm.mqebridge.MQeBaseTransformer

Description

Type:
Unicode

Label:
MQE_FIELD_LABEL_DESCRIPTION

Valid actions
Inquire, create, update

Description
A free-format Unicode string, used by an administrator to describe the configured object. WebSphere MQ Everyplace does not use the contents of this field. The contents of this field are not validated by WebSphere MQ Everyplace.

HeartBeatInterval

Type:
Int

Label:
MQE_FIELD_LABEL_HEARTBEAT_INTERVAL

Valid actions
Inquire, create, update

Description
A time interval, expressed in units of 1 minute, with values between 1 and 60. The bridge uses a heartbeat internally to provide a regular stimulus to other administered objects. The administered objects perform small tasks when the heartbeat event arrives, such as 'The client connection will reap old or stale WebSphere MQ connections' or 'the sync queue will be purged'. The heartbeat provides an interval for the timers that is indivisible. The lower this value is set, the more accurate any timer related actions will be. For instance, if you say 'reap all WebSphere MQ connections if they have been idle for more than 10 minutes', but set the heartbeat interval tor 3 minutes, then an idle WebSphere MQ connection is checked after 3,6,9 and 12 minutes, but is only reaped on the 12th minute. Setting this value lower increases the accuracy of the timer-related heartbeat events, but does so at the cost of efficiency. The more heartbeat events created, the more work is done.

The default value is 5 minutes.

Hostname

Type:
Unicode

Label:
MQE_FIELD_LABEL_HOST_NAME

Valid actions
Inquire, create, update

Description
Used to create connections to this WebSphere MQ queue manager using the WebSphere MQ Classes for Java. If this characteristic is not specified, the WebSphere MQ queue manager is assumed to be on the same machine as the JVM, so the Java bindings mode is used to communicate with the WebSphere MQ system.
Note:
A blank value is not the same as specifying localhost. If a blank value is used, then the WebSphere MQ-bridge uses the WebSphere MQ Classes for Java in bindings mode which communicates directly with WebSphere MQ. If you specify localhost, the WebSphere MQ-bridge uses the WebSphere MQ Classes for Java in client mode. This means that all communication with WebSphere MQ is through the network (TCP/IP) stack.
The value specified here is not validated. If you use a symbolic name, it may take longer to detect that this machine is not switched on, or if the name server is not working. You can use the I/P address notation in this field if a symbolic name causes problems.

ListenerName

Type:
Unicode

Label:
MQE_FIELD_LABEL_LISTENER_NAME

Valid actions
Inquire, create, update, delete, start, stop

Description
The name of this listener. The listener name is the name of the transmission queue on WebSphere MQ that the listener takes messages from. The combination of MQ_queue_manager_name and MQ_transmission_queue_name pair must be unique across all the gateways that exist.
Note:
This characteristic can be set only once, with the create administration message. Thereafter it is used to identify which WebSphere MQ-bridge administered object should be inquired on, updated, deleted, started, or stopped.

ListenerStateStoreAdapter

Type:
Unicode

Label:
MQE_FIELD_LABEL_LISTENER_STATE_STORE_ADAPTER

Valid actions
Inquire, create, update

Description
In order to provide assured message delivery of persistent messages, the listener class uses an adapter to store state information. This is the class name (or alias of the classname) of the adapter that is loaded to manage the storing and recovery of the state information to and from disk. Two adapters are currently supported-
  • com.ibm.mqe.adapters.MQeDiskFieldsAdapter, which stores state information on the local file system.
  • com.ibm.mqe.mqbridge.MQeMQAdapter, which stores state information on the WebSphere MQ server.

The disk adapter is generally quicker than using the WebSphere MQ-based adapter. The classname can be followed by a colon separated list of arguments, although only the MQeDiskFieldsAdapter uses them. In this case the MQeDiskFieldsAdapter can be followed by a colon and a fully qualified path name to a file that contains the state information. For example, in order to use the disk fields adapter to store the listener's state information in the file c:\folder\state.sta, the listener-state-store-adapter field should contain the value
com.ibm.mqe.Adapters.MQeDiskFieldsAdapter:c:\folder\state.sta
A file specified by this parameter need not currently exist. If the supplied path name ends in a folder separator, for example '\' in DOS. It is assumed that the supplied parameter is a directory, and a state file called
<ListenerName>-listener.sta is created inside it, where <ListenerName> is the name of the listener, from the registry entry. If no path name is supplied, the listener uses a file called
<ListenerName>-listener.sta inside the current Java working directory If the MQeMQAdapter is being used, no additional arguments are required.

The default value of the ListenerStateStoreAdapter field is
com.ibm.mqe.Adapters.MQeDiskFieldsAdapter.

MaxConnectionIdleTime

Type:
Int

Label:
MQE_FIELD_LABEL_MAX_CONNECTION_IDLE_TIME

Valid actions
Inquire, create, update

Description
Each client connection object in the bridge maintains a pool of WebSphere MQ Java client connections to its WebSphere MQ system.

When a WebSphere MQ connection becomes idle through lack of use, a timer is started. If the timer reaches the current value of this parameter, then the idle connection is thrown away. This is known as reaping the connection. This saves resources when the connection is idle. The connection pool is an efficiency device that is used within the WebSphere MQ-bridge. The creation of new WebSphere MQ client connections is a resource intensive operation. If there are idle connections in the pool, one of these is reused, thus avoiding a creation operation. The higher the MaxConnectionIdleTime value, the more likely it is that an idle connection will be waiting in the pool, but idle client connections consume resources in the JVM. Setting this value lower, decreases the likelihood of an idle connection being available, but also decreases the number of idle connections , so less resources are consumed.

The time is expressed in units of 1 minute.

The Valid range: Between 0 and 720 (12 hours). The default is 5 (minutes).

Setting this value to 0 is not recommended as it effectively means 'don't use a connection pool', and whenever a WebSphere MQ client connection is idle, it is reaped or discarded.

This time-out is only checked at the interval set by the
heartbeatInterval parameter.

MaxConnectionIdleTime can have a direct effect on the length of time it takes to shut down an WebSphere MQ Everyplace system. Refer to
WebSphere MQ-bridge considerations when shutting down a WebSphere MQ queue manager for more details.

MQPassword

Type:
Unicode

Label:
MQE_FIELD_LABEL_PASSWORD

Valid actions
Inquire, create, update

Description
Used by the MQSeries Classes for Java. If this attribute is not specified, the password field on the WebSphere MQ calls is set to "" . The value you specify here overrides any defaults. This parameter is not validated.

MQQMgrProxyName

Type:
Unicode

Label:
MQE_FIELD_LABEL_MQ_Q_MGR_PROXY_NAME

Valid actions
Inquire, create, update, delete, start, stop

Description
The name of the queue manager proxy object. (In other words, the name of the target WebSphere MQ queue manager.)
Note:
This characteristic can be set only once, with the create administration message. Thereafter it is used to identify which bridge administered object should be inquired on, updated, deleted, started, or stopped.

MQUserID

Type:
Unicode

Label:
MQE_FIELD_LABEL_USER_ID

Valid actions
Inquire, create, update

Description
Used by the MQSeries Classes for Java. If this parameter is not specified. the user-id field on the WebSphere MQ calls is set to "" . The value you specify here overrides any defaults. This parameter is not validated.

Port

Type:
Int

Label:
MQE_FIELD_LABEL_PORT

Valid actions
Inquire, create, update

Description
Used to create connections to this WebSphere MQ queue manager using the WebSphere MQ Classes for Java. If this parameter is not specified, the WebSphere MQ queue manager is assumed to be on the same machine as the JVM. In this case, the bindings mode of the WebSphere MQ Classes for Java is used to communicate with the WebSphere MQ system.

Valid range 0 to MAXINT.

ReceiveExit

Type:
Unicode

Label:
MQE_FIELD_LABEL_RECEIVE_EXIT

Valid actions
Inquire, create, update

Description
Used to match the exit used at the other end of the Client connection.

This parameter is not validated.

Run-state

Type:
Int

Label:
MQE_FIELD_LABEL_RUN_STATE

Valid actions
Inquire

Description
Indicates whether the administered object is running (value=1), or stopped (value=0). When an object is stopped it can have its properties changed.

SecurityExit

Type:
Unicode

Label:
MQE_FIELD_LABEL_SECURITY_EXIT

Valid actions
Inquire, create, update

Description
Used to match the exit used at the other end of the Client connection.

This parameter is not validated.

SendExit

Type:
Unicode

Label:
MQE_FIELD_LABEL_SEND_EXIT

Valid actions
Inquire, create, update

Description
Used to match the exit used at the other end of the Client connection.

This parameter is not validated.

StartupRuleClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_STARTUP_RULE_CLASS

Valid actions
Inquire, create, update

Description
This is a rule class that is used when the administered object is loaded at system startup, or when the object is created. The rule class name is not validated.

The rule class dictates whether the administered object is started, and whether or not its children are started. The default rule is com.ibm.mqe.mqbridge .MQeStartupRule This default causes the administered object and all its parents to start. If this field is set to "" (blank) , the administered object is not started.Rules are not directly supported by the C Bindings. SeeWebSphere MQ Everyplace Application Programming Guide for information about writing rules in Java.

SyncQName

Type:
Unicode

Label:
MQE_FIELD_LABEL_SYNC_Q_NAME

Valid actions
Inquire, create, update

Description
The name of the sync queue on the WebSphere MQ queue manager that is used by the WebSphere MQ-bridge . Valid characters forming the name are: '0-9' 'A-Z' 'a-z' _ . % / .The sync queue is a WebSphere MQ queue that is used to keep track of which messages are in the process of moving from WebSphere MQ Everyplace to WebSphere MQ. If a message is part way through the logic that assures the once-only delivery of a message, there is another message on the sync queue, indicating how far through the logic the message has progressed. If the WebSphere MQ Everyplace system is shut down cleanly, the sync queue should be empty. If the connection between the systems is broken, some persistent state information is left in the sync queue. The WebSphere MQ Everyplace system uses this information when it restarts and continues from where the process failed. The name of the sync queue can be the same for client connections on the same bridge, or on different bridges, providing the send, receive and security exits used when talking to that sync queue are the same. The sync queues must exist on the WebSphere MQ queue manager for WebSphere MQ Everyplace to WebSphere MQ message transfer to work. If the listener state class is the MQeMQAdapter, this sync queue is also used for storing persistent state information about the listeners. The listener does not use this parameter if the state information is being stored by an MQeDiskFieldsAdapter. We recommended a naming scheme of: MQE.SYNCQ.<ClientConnectionName> so that you know which client connection is using which sync queue.

The default is MQE.SYNCQ.DEFAULT.

SyncQPurgeInterval

Type:
int

Label:
MQE_FIELD_LABEL_SYNC_Q_PURGE_INTERVAL

Valid actions
Inquire, create, update

Description
The time interval between successive purges of the sync queue, expressed in minutes.

When this interval elapses, the sync queue is scanned. If a message that has not been confirmed is found on the Sync queue, then the SyncQPurgerRules class is invoked to deal with this situation.

Zero indicates that the sync queue should never be purged.

The default is 60 minutes.

The actual granularity of the purging operation is dictated by the heartbeat-interval of the owning bridge definition. For example: If the hearbeat interval is set to 10 minutes, but the purge interval is set to 9 minutes, then the purge operation occurs after 10 minutes. If, however, the purge interval is changed to 11 minutes, the purge operation still occurs after 10 minutes.

SyncQPurgerRulesClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_SYNC_Q_PURGER_RULES_CLASS

Valid actions
Inquire, create, update

Description
The name of the rules class used when a message on the sync queue indicates a failure of WebSphere MQ Everyplace to confirm a message.

The default is a classname that just reports the condition in the WebSphere MQ Everyplace trace.

This parameter is not validated.

TransformerClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_TRANSFORMER

Valid actions
Inquire, create, update

Description
This is the name of the Java class that is used to convert the WebSphere MQ message into an WebSphere MQ Everyplace message. When a message is taken from WebSphere MQ by the listener, it is transformed into an WebSphere MQ Everyplace format message using the specified transformer. If the transformer class is specified as null or a blank string, then the DefaultTransformer parameter provided on the bridge configuration parameters is used as the transformer. If the default is also set to null or blank, messages cannot be transferred.

The default value is ""

Transformers are not directly supported by the C Bindings. SeeWebSphere MQ Everyplace Application Programming Guide for information about writing transformers in Java.

UndelivedMessageRuleClass

Type:
Unicode

Label:
MQE_FIELD_LABEL_UNDELIVERED_MESSAGE_RULE_CLASS

Valid actions
Inquire, create, update

Description
The name of the MQeUndeliveredMessageRule class. When a message moving from WebSphere MQ to WebSphere MQ Everyplace cannot be delivered, this rule class is consulted to decide what action the listener should take. The rule tells the listener to wait and retry, shut down, or deal with the message as defined in the MQMessage report options.

The default value is: com.ibm.mqe.mqbridge.MQeUndeliveredMessageRule. Rules are not directly supported by the C Bindings. SeeWebSphere MQ Everyplace Application Programming Guide for information about writing rules in Java.



© IBM Corporation 2002. All Rights Reserved