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 2000, 2003. All Rights Reserved