MQQueue.NET class

Use MQQueue to send and receive messages, and query attributes of an IBM® MQ queue. Create an MQQueue object using a constructor, or an MQQueueManager.AccessProcess method.

Class


System.Object
        |
        └─ IBM.WMQ.MQBase
                |
                └─ IBM.WMQ.MQBaseObject
                        |
                        └─ IBM.WMQ.MQManagedObject
                                |
                                └─ IBM.WMQ.MQDestination
                                        |
                                        └─ IBM.WMQ.MQQueue

public class IBM.WMQ.MQQueue extends IBM.WMQ.MQDestination;

Properties
Methods
Constructors

Properties

Test for MQException being thrown when getting properties.

public int ClusterWorkLoadPriority {get;}

Specifies the priority of the queue. This parameter is valid only for local, remote, and alias queues.

public int ClusterWorkLoadRank {get;}

Specifies the rank of the queue. This parameter is valid only for local, remote, and alias queues.

public int ClusterWorkLoadUseQ {get;}

Specifies the behavior of an MQPUT operation when the target queue has a local instance and at least one remote cluster instance. This parameter does not apply if the MQPUT originates from a cluster channel. This parameter is valid only for local queues.

public DateTime CreationDateTime {get;}

The date and time that this queue was created.

public int CurrentDepth {get;}

Gets the number of messages currently on the queue. This value is incremented during a put call, and during backout of a get call. It is decremented during a non-browse get and during backout of a put call.

public int DefinitionType {get;}

How the queue was defined. The possible values are:

MQC.MQQDT_PREDEFINED
MQC.MQQDT_PERMANENT_DYNAMIC
MQC.MQQDT_TEMPORARY_DYNAMIC

public int InhibitGet {get; set;}

Controls whether you can get messages on this queue or for this topic. The possible values are:

MQC.MQQA_GET_INHIBITED
MQC.MQQA_GET_ALLOWED

public int InhibitPut {get; set;}

Controls whether you can put messages on this queue or for this topic. The possible values are:

MQQA_PUT_INHIBITED
MQQA_PUT_ALLOWED

public int MaximumDepth {get;}

The maximum number of messages that can exist on the queue at any one time. An attempt to put a message to a queue that already contains this many messages fails with reason code MQC.MQRC_Q_FULL.

public int MaximumMessageLength {get;}

The maximum length of the application data that can exist in each message on this queue. An attempt to put a message larger than this value fails with reason code MQC.MQRC_MSG_TOO_BIG_FOR_Q.

public int NonPersistentMessageClass {get;}

The level of reliability for non-persistent messages put to this queue.

public int OpenInputCount {get;}

The number of handles that are currently valid for removing messages from the queue. OpenInputCount is the total number of valid input handles known to the local queue manager, not just handles created by the application.

public int OpenOutputCount {get;}

The number of handles that are currently valid for adding messages to the queue. OpenOutputCount is the total number of valid output handles known to the local queue manager, not just handles created by the application.

public int QueueAccounting {get;}

Specifies whether you can enable the collection of accounting information for the queue.

public int QueueMonitoring {get;}

Specifies whether you can enable the monitoring for the queue.

public int QueueStatistics {get;}

Specifies whether you can enable the collection of statistics for the queue.

public int QueueType {get;}

The type of this queue with one of the following values:

MQC.MQQT_ALIAS
MQC.MQQT_LOCAL
MQC.MQQT_REMOTE
MQC.MQQT_CLUSTER

public int Shareability {get;}

Whether the queue can be opened for input multiple times. The possible values are:

MQC.MQQA_SHAREABLE
MQC.MQQA_NOT_SHAREABLE

public string TPIPE {get;}

The TPIPE name used for communication with OTMA using the IBM MQ IMS bridge.

public int TriggerControl {get; set;}

Whether trigger messages are written to an initiation queue, to start an application to service the queue. The possible values are:

MQC.MQTC_OFF
MQC.MQTC_ON

public string TriggerData {get; set;}

The free-format data that the queue manager inserts into the trigger message. It inserts TriggerData when a message arriving on this queue causes a trigger message to be written to the initiation queue. The maximum permissible length of the string is given by MQC.MQ_TRIGGER_DATA_LENGTH.

public int TriggerDepth {get; set;}

The number of messages that must be on the queue before a trigger message is written when trigger type is set to MQC.MQTT_DEPTH.

public int TriggerMessagePriority {get; set;}

The message priority under which messages do not contribute to the generation of trigger messages. That is, the queue manager ignores these messages when deciding whether to generate a trigger. A value of zero causes all messages to contribute to the generation of trigger messages.

public int TriggerType {get; set;}

The conditions under which trigger messages are written as a result of messages arriving on this queue. The possible values are:

MQC.MQTT_NONE
MQC.MQTT_FIRST
MQC.MQTT_EVERY
MQC.MQTT_DEPTH

Methods

public void Get(MQMessage message);

public void Get(MQMessage message, MQGetMessageOptions getMessageOptions);

public void Get(MQMessage message, MQGetMessageOptions getMessageOptions, int MaxMsgSize);

Throws MQException.

Gets a message from a queue.

If the get fails, the MQMessage object is unchanged. If it succeeds, the message descriptor and message data portions of the MQMessage are replaced with the message descriptor and message data from the incoming message.

All calls to IBM MQ from a particular MQQueueManager are synchronous. Therefore, if you perform a get with wait, all other threads using the same MQQueueManager are blocked from making further IBM MQ calls until the Get call is accomplished. If you need multiple threads to access IBM MQ simultaneously, each thread must create its own MQQueueManager object.

message

Contains the message descriptor and the returned message data. Some of the fields in the message descriptor are input parameters. It is important to ensure that the MessageId and CorrelationId input parameters are set as required.

A reconnectable client returns the reason code MQRC_BACKED_OUT after successful reconnection, for messages received under MQGM_SYNCPOINT.

getMessageOptions

Options controlling the action of the get.

Using option MQC.MQGMO_CONVERT might result in an exception with reason code MQC.MQRC_CONVERTED_STRING_TOO_BIG when converting from single-byte character codes to double byte codes. In this case, the message is copied into the buffer without conversion.

If getMessageOptions is not specified, the message option used is MQGMO_NOWAIT.

If you use the MQGMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

MaxMsgSize

The largest message this message object is to receive. If the message on the queue is larger than this size, one of two things occurs:

If the MQGMO_ACCEPT_TRUNCATED_MSG flag is set in the MQGetMessageOptions object, the message is filled with as much of the message data as possible. An exception is thrown with the MQCC_WARNING completion code and MQRC_TRUNCATED_MSG_ACCEPTED reason code.
If the MQGMO_ACCEPT_TRUNCATED_MSG flag is not set, the message remains on the queue. An exception is thrown with the MQCC_WARNING completion code and MQRC_TRUNCATED_MSG_FAILED reason code.

If MaxMsgSize is not specified, the whole message is retrieved.

public void Put(MQMessage message);

public void Put(MQMessage message, MQPutMessageOptions putMessageOptions);

Throws MQException.

Puts a message to a queue.

Modifications to the MQMessage object after the Put call has been accomplished do not affect the actual message on the IBM MQ queue or publication topic.

Put updates the MessageId and CorrelationId properties of the MQMessage object and does not clear message data. Further Put or Get calls refer to the updated information in the MQMessage object. For example, in the following code snippet, the first message contains a and the second ab.


msg.WriteString("a");
q.Put(msg,pmo);
msg.WriteString("b");
q.Put(msg,pmo);

message

An MQMessage object containing the message descriptor data, and message to be sent. The message descriptor can be altered as a consequence of this method. The values in the message descriptor immediately after the completion of this method are the values that were put to the queue or published to the topic.

The following reason codes are returned to a reconnectable client:

MQRC_CALL_INTERRUPTED if the connection is broken while running a Put call on a persistent message and the reconnection is successful.
MQRC_NONE if the connection is successful while running a Put call on a non-persistent message (see Application Recovery ).

putMessageOptions

Options controlling the action of the put.

If putMessageOptions is not specified the default instance of MQPutMessageOptons is used.

If you use the MQPMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

Note: For simplicity and performance, if you want to put a single message to a queue, use MQQueueManager.Put object. You should have an MQQueue object for this.

public void PutForwardMessage(MQMessage message);

public void PutForwardMessage(MQMessage message, MQPutMessageOptions putMessageOptions);

Throws MQException

Put a message being forwarded onto the queue, where message is the original message.

message

The following reason codes are returned to a reconnectable client:

MQRC_CALL_INTERRUPTED if the connection is broken while running a Put call on a persistent message and the reconnection is successful.
MQRC_NONE if the connection is successful while running a Put call on a non-persistent message (see Application Recovery ).

putMessageOptions

Options controlling the action of the put.

If putMessageOptions is not specified the default instance of MQPutMessageOptons is used.

If you use the MQPMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

public void PutReplyMessage(MQMessage message)

public void PutReplyMessage(MQMessage message, MQPutMessageOptions putMessageOptions)

Throws MQException.

Put a reply message onto the queue, where message is the original message.

message: Contains the message descriptor and the returned message data. Some of the fields in the message descriptor are input parameters. It is important to ensure that the MessageId and CorrelationId input parameters are set as required.; A reconnectable client returns the reason code MQRC_BACKED_OUT after successful reconnection, for messages received under MQGM_SYNCPOINT.
putMessageOptions: Options controlling the action of the put.; If putMessageOptions is not specified the default instance of MQPutMessageOptons is used.; If you use the MQPMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

public void PutReportMessage(MQMessage message)

public void PutReportMessage(MQMessage message, MQPutMessageOptions putMessageOptions)

Throws MQException.

Put a report message onto the queue, where message is the original message.

message: Contains the message descriptor and the returned message data. Some of the fields in the message descriptor are input parameters. It is important to ensure that the MessageId and CorrelationId input parameters are set as required.; A reconnectable client returns the reason code MQRC_BACKED_OUT after successful reconnection, for messages received under MQGM_SYNCPOINT.
putMessageOptions: Options controlling the action of the put.; If putMessageOptions is not specified the default instance of MQPutMessageOptons is used.; If you use the MQPMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

Constructors

public MQQueue MQQueueManager.AccessQueue(string queueName, int openOptions);

public MQQueue MQQueueManager.AccessQueue(string queueName, int openOptions, string queueManagerName, string dynamicQueueName, string alternateUserId);

Throws MQException.

Accesses a queue on this queue manager.

You can get or browse messages, put messages, inquire about the attributes of the queue or set the attributes of the queue. If the queue named is a model queue, a dynamic local queue is created. Query the name attribute of the resultant MQQueue object to find out the name of the dynamic queue.

queueName

Name of queue to open.

openOptions

Options that control the opening of the queue.

MQC.MQOO_ALTERNATE_USER_AUTHORITY: Validate with the specified user identifier.
MQC.MQOO_BIND_AS_QDEF: Use default binding for queue.
MQC.MQOO_BIND_NOT_FIXED: Do not bind to a specific destination.
MQC.MQOO_BIND_ON_OPEN: Bind handle to destination when queue is opened.
MQC.MQOO_BROWSE: Open to browse message.
MQC.MQOO_FAIL_IF_QUIESCING: Fail if the queue manager is quiescing.
MQC.MQOO_INPUT_AS_Q_DEF: Open to get messages using queue-defined default.
MQC.MQOO_INPUT_SHARED: Open to get messages with shared access.
MQC.MQOO_INPUT_EXCLUSIVE: Open to get messages with exclusive access.
MQC.MQOO_INQUIRE: Open for inquiry - required if you want to query properties.
MQC.MQOO_OUTPUT: Open to put messages.
MQC.MQOO_PASS_ALL_CONTEXT: Allow all context to be passed.
MQC.MQOO_PASS_IDENTITY_CONTEXT: Allow identity context to be passed.
MQC.MQOO_SAVE_ALL_CONTEXT: Save context when message retrieved.
MQC.MQOO_SET: Open to set attributes - required if you want to set properties.
MQC.MQOO_SET_ALL_CONTEXT: Allows all context to be set.
MQC.MQOO_SET_IDENTITY_CONTEXT: Allows identity context to be set.

queueManagerName

Name of the queue manager on which the queue is defined. A name that is entirely blank or null denotes the queue manager to which the MQQueueManager object is connected.

dynamicQueueName

dynamicQueueName is ignored unless queueName specifies the name of a model queue. If it does, dynamicQueueName specifies the name of the dynamic queue to be created. A blank or null name is not valid if queueName specifies the name of a model queue. If the last nonblank character in the name is an asterisk, *, the queue manager replaces the asterisk with a string of characters. The characters guarantee that the name generated for the queue is unique on this queue manager.

alternateUserId

If MQC.MQOO_ALTERNATE_USER_AUTHORITY is specified in the openOptions parameter, alternateUserId specifies the alternate user identifier that is used to check the authorization for the open. If MQC.MQOO_ALTERNATE_USER_AUTHORITY is not specified, alternateUserId can be left blank, or null.

public MQQueue(MQQueueManager queueManager, string queueName, int openOptions, string queueManagerName, string dynamicQueueName, string alternateUserId);

Throws MQException.

Accesses a queue on queueManager.

queueManager: Queue manager to access queue on.

queueName

Name of queue to open.

openOptions

Options that control the opening of the queue.

MQC.MQOO_ALTERNATE_USER_AUTHORITY: Validate with the specified user identifier.
MQC.MQOO_BIND_AS_QDEF: Use default binding for queue.
MQC.MQOO_BIND_NOT_FIXED: Do not bind to a specific destination.
MQC.MQOO_BIND_ON_OPEN: Bind handle to destination when queue is opened.
MQC.MQOO_BROWSE: Open to browse message.
MQC.MQOO_FAIL_IF_QUIESCING: Fail if the queue manager is quiescing.
MQC.MQOO_INPUT_AS_Q_DEF: Open to get messages using queue-defined default.
MQC.MQOO_INPUT_SHARED: Open to get messages with shared access.
MQC.MQOO_INPUT_EXCLUSIVE: Open to get messages with exclusive access.
MQC.MQOO_INQUIRE: Open for inquiry - required if you want to query properties.
MQC.MQOO_OUTPUT: Open to put messages.
MQC.MQOO_PASS_ALL_CONTEXT: Allow all context to be passed.
MQC.MQOO_PASS_IDENTITY_CONTEXT: Allow identity context to be passed.
MQC.MQOO_SAVE_ALL_CONTEXT: Save context when message retrieved.
MQC.MQOO_SET: Open to set attributes - required if you want to set properties.
MQC.MQOO_SET_ALL_CONTEXT: Allows all context to be set.
MQC.MQOO_SET_IDENTITY_CONTEXT: Allows identity context to be set.

queueManagerName

Name of the queue manager on which the queue is defined. A name that is entirely blank or null denotes the queue manager to which the MQQueueManager object is connected.

dynamicQueueName

alternateUserId