This section contains information on the tasks associated with the administration of the WebSphere MQ-bridge
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.
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.
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.
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.
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.)
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.
The create action creates an administered object. The run state of the administered object created is initially set to stopped.
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.
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.
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.
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.
MQE_FIELD_LABEL_ADAPTER
If this attribute is not specified, a default value of com.ibm.mqe.mqbridge.MQeMQAdapter is used.
This parameter is not validated
MQE_FIELD_LABEL_ADMINISTERED_OBJECT
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' - . % /
MQE_FIELD_LABEL_BRIDGE_NAME
MQE_FIELD_LABEL_CCSID
Valid values are: 0 to MAXINT. The default is 0.
MQE_FIELD_LABEL_CHILD
MQE_FIELD_LABEL_CHILDREN
MQE_FIELD_LABEL_CLIENT_CONNECTION_NAME
MQE_FIELD_LABEL_DEAD_LETTER_Q_NAME
The default value is SYSTEM.DEAD.LETTER.QUEUE.
MQE_FIELD_LABEL_DEFAULT_TRANSFORMER
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
MQE_FIELD_LABEL_DESCRIPTION
MQE_FIELD_LABEL_HEARTBEAT_INTERVAL
The default value is 5 minutes.
MQE_FIELD_LABEL_HOST_NAME
MQE_FIELD_LABEL_LISTENER_NAME
MQE_FIELD_LABEL_LISTENER_STATE_STORE_ADAPTER
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.
MQE_FIELD_LABEL_MAX_CONNECTION_IDLE_TIME
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.
MQE_FIELD_LABEL_PASSWORD
MQE_FIELD_LABEL_MQ_Q_MGR_PROXY_NAME
MQE_FIELD_LABEL_USER_ID
MQE_FIELD_LABEL_PORT
Valid range 0 to MAXINT.
MQE_FIELD_LABEL_RECEIVE_EXIT
This parameter is not validated.
MQE_FIELD_LABEL_RUN_STATE
MQE_FIELD_LABEL_SECURITY_EXIT
This parameter is not validated.
MQE_FIELD_LABEL_SEND_EXIT
This parameter is not validated.
MQE_FIELD_LABEL_STARTUP_RULE_CLASS
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.
MQE_FIELD_LABEL_SYNC_Q_NAME
The default is MQE.SYNCQ.DEFAULT.
MQE_FIELD_LABEL_SYNC_Q_PURGE_INTERVAL
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.
MQE_FIELD_LABEL_SYNC_Q_PURGER_RULES_CLASS
The default is a classname that just reports the condition in the WebSphere MQ Everyplace trace.
This parameter is not validated.
MQE_FIELD_LABEL_TRANSFORMER
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.
MQE_FIELD_LABEL_UNDELIVERED_MESSAGE_RULE_CLASS
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.