ImqQueue

Figure 21. ImqQueue class

This class encapsulates a message queue (a WebSphere MQ object of type MQOT_Q). It relates to the MQI calls listed in Table 22.

Other relevant classes

ImqCache (see ImqCache)

ImqDistributionList (see ImqDistributionList)

ImqGetMessageOptions (see ImqGetMessageOptions)

ImqMessage (see ImqMessage)

ImqMessageTracker (see ImqMessageTracker)

ImqObject (see ImqObject)

ImqPutMessageOptions (see ImqPutMessageOptions)

ImqQueueManager (see ImqQueueManager)

ImqString (see ImqString)

Object attributes

backout requeue name

Excessive backout requeue name. This attribute is read-only.

backout threshold

Backout threshold. This attribute is read-only.

base queue name

Name of the queue that the alias resolves to. This attribute is read-only.

cluster name

Cluster name. This attribute is read-only.

cluster namelist name

Cluster namelist name. This attribute is read-only.

creation date

Queue creation data. This attribute is read-only.

creation time

Queue creation time. This attribute is read-only.

current depth

Number of messages on the queue. This attribute is read-only.

default bind

Default bind. This attribute is read-only.

default input open option

Default open-for-input option. This attribute is read-only.

default persistence

The default message persistence. This attribute is read-only.

default priority

Default message priority. This attribute is read-only.

definition type

Queue definition type. This attribute is read-only.

depth high event

Control attribute for queue depth high events. This attribute is read-only.

depth high limit

High limit for the queue depth. This attribute is read-only.

depth low event

This is the control attribute for queue depth low events. This attribute is read-only.

depth low limit

This is the low limit for the queue depth. This attribute is read-only.

depth maximum event

Control attribute for queue depth maximum events. This attribute is read-only.

distribution list reference

An optional reference to an ImqDistributionList that can be used to distribute messages to more than one queue, including this one. The initial value is null.

Note:

When an ImqQueue object is opened, any open ImqDistributionList object that it references is automatically closed.

distribution lists

Specifies the capability of a transmission queue to support distribution lists. This attribute is read-only.

dynamic queue name

Dynamic queue name. The initial value is "AMQ.*" for all Personal Computer and UNIX platforms.

harden get backout

Determines whether to harden the backout count. This attribute is read-only.

index type

Index type. This attribute is read-only.

inhibit get

Determines whether get operations are allowed. The initial value is dependent on the queue definition. This attribute is valid for an alias or local queue only.

inhibit put

Determines whether put operations are allowed. The initial value is dependent on the queue definition.

initiation queue name

Name of the initiation queue. This attribute is read-only.

maximum depth

Maximum number of messages allowed on the queue. This attribute is read-only.

maximum message length

Maximum length for any message on this queue, which may be less than the maximum for any queue managed by the associated queue manager. This attribute is read-only.

message delivery sequence

Determines whether message priority is relevant. This attribute is read-only.

next distributed queue

Next object of this class, in no particular order, having the same distribution list reference as this object. The initial value is zero.

If an object in a chain is deleted, the previous object and next object are updated so that their distributed queue links no longer point to the deleted object.

open input count

Number of ImqQueue objects that are open for input. This attribute is read-only.

open output count

Number of ImqQueue objects that are open for output. This attribute is read-only.

previous distributed queue

Previous object of this class, in no particular order, having the same distribution list reference as this object. The initial value is zero.

If an object in a chain is deleted, the previous object and next object are updated so that their distributed queue links no longer point to the deleted object.

process name

Name of the process definition. This attribute is read-only.

queue manager name

Name of the queue manager (possibly remote) where the queue actually resides. The queue manager named here should not be confused with the ImqObject connection reference which references the (local) queue manager providing a connection. The initial value is null.

queue type

Queue type. This attribute is read-only.

remote queue manager name

Name of the remote queue manager. This attribute is read-only.

remote queue name

Name of the remote queue as known on the remote queue manager. This attribute is read-only.

resolved queue manager name

Resolved queue manager name. This attribute is read-only.

resolved queue name

Resolved queue name. This attribute is read-only.

retention interval

Queue retention interval. This attribute is read-only.

scope

Scope of the queue definition. This attribute is read-only.

service interval

Service interval. This attribute is read-only.

service interval event

Control attribute for service interval events. This attribute is read-only.

shareability

Determines whether the queue can be shared. This attribute is read-only.

storage class

Storage class. This attribute is read-only.

transmission queue name

Name of the transmission queue. This attribute is read-only.

trigger control

Trigger control. The initial value depends on the queue definition. This attribute is valid for a local queue only.

trigger data

Trigger data. The initial value depends on the queue definition. This attribute is valid for a local queue only.

trigger depth

Trigger depth. The initial value depends on the queue definition. This attribute is valid for a local queue only.

trigger message priority

Threshold message priority for triggers. The initial value depends on the queue definition. This attribute is valid for a local queue only.

trigger type

Trigger type. The initial value depends on the queue definition. This attribute is valid for a local queue only.

usage

Usage. This attribute is read-only.

Constructors

ImqQueue( );

The default constructor.

ImqQueue( const ImqQueue & queue );

The copy constructor. The ImqObject open status will be FALSE.

ImqQueue( const char * name );

Sets the ImqObject name.

Object methods (public)

void operator = ( const ImqQueue & queue );

Performs a close if necessary, and then copies instance data from queue. The ImqObject open status will be FALSE.

ImqBoolean backoutRequeueName( ImqString & name );

Provides a copy of the backout requeue name. It returns TRUE if successful.

ImqString backoutRequeueName( );

Returns the backout requeue name without any indication of possible errors.

ImqBoolean backoutThreshold( MQLONG & threshold );

Provides a copy of the backout threshold. It returns TRUE if successful.

MQLONG backoutThreshold( );

Returns the backout threshold value without any indication of possible errors.

ImqBoolean baseQueueName( ImqString & name );

Provides a copy of the base queue name. It returns TRUE if successful.

ImqString baseQueueName( );

Returns the base queue name without any indication of possible errors.

ImqBoolean clusterName( ImqString & name );

Provides a copy of the cluster name. It returns TRUE if successful.

ImqString clusterName( );

Returns the cluster name without any indication of possible errors.

ImqBoolean clusterNamelistName( ImqString & name );

Provides a copy of the cluster namelist name. It returns TRUE if successful.

ImqString clusterNamelistName( );

Returns the cluster namelist name without any indication of errors.

ImqBoolean creationDate( ImqString & date );

Provides a copy of the creation date. It returns TRUE if successful.

ImqString creationDate( );

Returns the creation date without any indication of possible errors.

ImqBoolean creationTime( ImqString & time );

Provides a copy of the creation time. It returns TRUE if successful.

ImqString creationTime( );

Returns the creation time without any indication of possible errors.

ImqBoolean currentDepth( MQLONG & depth );

Provides a copy of the current depth. It returns TRUE if successful.

MQLONG currentDepth( );

Returns the current depth without any indication of possible errors.

ImqBoolean defaultInputOpenOption( MQLONG & option );

Provides a copy of the default input open option. It returns TRUE if successful.

MQLONG defaultInputOpenOption( );

Returns the default input open option without any indication of possible errors.

ImqBoolean defaultPersistence( MQLONG & persistence );

Provides a copy of the default persistence. It returns TRUE if successful.

MQLONG defaultPersistence( );

Returns the default persistence without any indication of possible errors.

ImqBoolean defaultPriority( MQLONG & priority );

Provides a copy of the default priority. It returns TRUE if successful.

MQLONG defaultPriority( );

Returns the default priority without any indication of possible errors.

ImqBoolean defaultBind( MQLONG & bind );

Provides a copy of the default bind. It returns TRUE if successful.

MQLONG defaultBind( );

Returns the default bind without any indication of possible errors.

ImqBoolean definitionType( MQLONG & type );

Provides a copy of the definition type. It returns TRUE if successful.

MQLONG definitionType( );

Returns the definition type without any indication of possible errors.

ImqBoolean depthHighEvent( MQLONG & event );

Provides a copy of the enablement state of the depth high event. It returns TRUE if successful.

MQLONG depthHighEvent( );

Returns the enablement state of the depth high event without any indication of possible errors.

ImqBoolean depthHighLimit( MQLONG & limit );

Provides a copy of the depth high limit. It returns TRUE if successful.

MQLONG depthHighLimit( );

Returns the depth high limit value without any indication of possible errors.

ImqBoolean depthLowEvent( MQLONG & event );

Provides a copy of the enablement state of the depth low event. It returns TRUE if successful.

MQLONG depthLowEvent( );

Returns the enablement state of the depth low event without any indication of possible errors.

ImqBoolean depthLowLimit( MQLONG & limit );

Provides a copy of the depth low limit. It returns TRUE if successful.

MQLONG depthLowLimit( );

Returns the depth low limit value without any indication of possible errors.

ImqBoolean depthMaximumEvent( MQLONG & event );

Provides a copy of the enablement state of the depth maximum event. It returns TRUE if successful.

MQLONG depthMaximumEvent( );

Returns the enablement state of the depth maximum event without any indication of possible errors.

ImqDistributionList * distributionListReference( ) const ;

Returns the distribution list reference.

void setDistributionListReference( ImqDistributionList & list );

Sets the distribution list reference.

void setDistributionListReference( ImqDistributionList * list = 0 );

Sets the distribution list reference.

ImqBoolean distributionLists( MQLONG & support );

Provides a copy of the distribution lists value. It returns TRUE if successful.

MQLONG distributionLists( );

Returns the distribution lists value without any indication of possible errors.

ImqBoolean setDistributionLists( const MQLONG support );

Sets the distribution lists value. It returns TRUE if successful.

ImqString dynamicQueueName( ) const ;

Returns a copy of the dynamic queue name.

ImqBoolean setDynamicQueueName( const char * name );

Sets the dynamic queue name. The dynamic queue name can be set only while the ImqObject open status is FALSE. It returns TRUE if successful.

ImqBoolean get( ImqMessage & msg, ImqGetMessageOptions & options );

Retrieves a message from the queue, using the specified options. The ImqObject openFor method is invoked if necessary to ensure that the ImqObject open options include either (a) one of the MQOO_INPUT_* values, or (b) the MQOO_BROWSE value, depending on the options. If the msg object has an ImqCache automatic buffer, the buffer grows to accommodate any message retrieved. The clearMessage method is invoked against the msg object prior to retrieval.

This method returns TRUE if successful.

Note:

The result of the method invocation is FALSE if the ImqObject reason code is MQRC_TRUNCATED_MSG_FAILED, even though this reason code is classified as a warning. If a truncated message is accepted, the ImqCache message length reflects the truncated length. In either event, the ImqMessage total message length indicates the number of bytes that were available.

ImqBoolean get( ImqMessage & msg );

As for the previous method, except that default get message options are used.

ImqBoolean get( ImqMessage & msg, ImqGetMessageOptions & options, const size_t buffer-size );

As for the previous two methods, except that an overriding buffer-size is indicated. If the msg object employs an ImqCache automatic buffer, the resizeBuffer method is invoked on the msg object prior to message retrieval, and the buffer does not grow further to accommodate any larger message.

ImqBoolean get( ImqMessage & msg, const size_t buffer-size );

As for the previous method, except that default get message options are used.

ImqBoolean hardenGetBackout( MQLONG & harden );

Provides a copy of the harden get backout value. It returns TRUE if successful.

MQLONG hardenGetBackout( );

Returns the harden get backout value without any indication of possible errors.

ImqBoolean indexType( MQLONG & type );

Provides a copy of the index type. It returns TRUE if successful.

MQLONG indexType( );

Returns the index type without any indication of possible errors.

ImqBoolean inhibitGet( MQLONG & inhibit );

Provides a copy of the inhibit get value. It returns TRUE if successful.

MQLONG inhibitGet( );

Returns the inhibit get value without any indication of possible errors.

ImqBoolean setInhibitGet( const MQLONG inhibit );

Sets the inhibit get value. It returns TRUE if successful.

ImqBoolean inhibitPut( MQLONG & inhibit );

Provides a copy of the inhibit put value. It returns TRUE if successful.

MQLONG inhibitPut( );

Returns the inhibit put value without any indication of possible errors.

ImqBoolean setInhibitPut( const MQLONG inhibit );

Sets the inhibit put value. It returns TRUE if successful.

ImqBoolean initiationQueueName( ImqString & name );

Provides a copy of the initiation queue name. It returns TRUE if successful.

ImqString initiationQueueName( );

Returns the initiation queue name without any indication of possible errors.

ImqBoolean maximumDepth( MQLONG & depth );

Provides a copy of the maximum depth. It returns TRUE if successful.

MQLONG maximumDepth( );

Returns the maximum depth without any indication of possible errors.

ImqBoolean maximumMessageLength( MQLONG & length );

Provides a copy of the maximum message length. It returns TRUE if successful.

MQLONG maximumMessageLength( );

Returns the maximum message length without any indication of possible errors.

ImqBoolean messageDeliverySequence( MQLONG & sequence );

Provides a copy of the message delivery sequence. It returns TRUE if successful.

MQLONG messageDeliverySequence( );

Returns the message delivery sequence value without any indication of possible errors.

ImqQueue * nextDistributedQueue( ) const ;

Returns the next distributed queue.

ImqBoolean openInputCount( MQLONG & count );

Provides a copy of the open input count. It returns TRUE if successful.

MQLONG openInputCount( );

Returns the open input count without any indication of possible errors.

ImqBoolean openOutputCount( MQLONG & count );

Provides a copy of the open output count. It returns TRUE if successful.

MQLONG openOutputCount( );

Returns the open output count without any indication of possible errors.

ImqQueue * previousDistributedQueue( ) const ;

Returns the previous distributed queue.

ImqBoolean processName( ImqString & name );

Provides a copy of the process name. It returns TRUE if successful.

ImqString processName( );

Returns the process name without any indication of possible errors.

ImqBoolean put( ImqMessage & msg );

Places a message onto the queue, using default put message options. Uses the ImqObject openFor method if necessary to ensure that the ImqObject open options include MQOO_OUTPUT.

This method returns TRUE if successful.

ImqBoolean put( ImqMessage & msg, ImqPutMessageOptions & pmo );

Places a message onto the queue, using the specified pmo. Uses the ImqObject openFor method as necessary to ensure that the ImqObject open options include MQOO_OUTPUT, and (if the pmo options include any of MQPMO_PASS_IDENTITY_CONTEXT, MQPMO_PASS_ALL_CONTEXT, MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT) corresponding MQOO_*_CONTEXT values.

This method returns TRUE if successful.

Note:

If the pmo includes a context reference, the referenced object will be opened if necessary to provide a context.

ImqString queueManagerName( ) const ;

Returns the queue manager name.

ImqBoolean setQueueManagerName( const char * name );

Sets the queue manager name. The queue manager name can be set only while the ImqObject open status is FALSE. This method returns TRUE if successful.

ImqBoolean queueType( MQLONG & type );

Provides a copy of the queue type value. It returns TRUE if successful.

MQLONG queueType( );

Returns the queue type without any indication of possible errors.

ImqBoolean remoteQueueManagerName( ImqString & name );

Provides a copy of the remote queue manager name. It returns TRUE if successful.

ImqString remoteQueueManagerName( );

Returns the remote queue manager name without any indication of possible errors.

ImqBoolean remoteQueueName( ImqString & name );

Provides a copy of the remote queue name. It returns TRUE if successful.

ImqString remoteQueueName( );

Returns the remote queue name without any indication of possible errors.

ImqBoolean resolvedQueueManagerName( ImqString & name );

Provides a copy of the resolved queue manager name. It returns TRUE if successful.

Note:

This method fails unless MQOO_RESOLVE_NAMES is among the ImqObject open options.

ImqString resolvedQueueManagerName( ) ;

Returns the resolved queue manager name, without any indication of possible errors.

ImqBoolean resolvedQueueName( ImqString & name );

Provides a copy of the resolved queue name. It returns TRUE if successful.

Note:

This method fails unless MQOO_RESOLVE_NAMES is among the ImqObject open options.

ImqString resolvedQueueName( ) ;

Returns the resolved queue name, without any indication of possible errors.

ImqBoolean retentionInterval( MQLONG & interval );

Provides a copy of the retention interval. It returns TRUE if successful.

MQLONG retentionInterval( );

Returns the retention interval without any indication of possible errors.

ImqBoolean scope( MQLONG & scope );

Provides a copy of the scope. It returns TRUE if successful.

MQLONG scope( );

Returns the scope without any indication of possible errors.

ImqBoolean serviceInterval( MQLONG & interval );

Provides a copy of the service interval. It returns TRUE if successful.

MQLONG serviceInterval( );

Returns the service interval without any indication of possible errors.

ImqBoolean serviceIntervalEvent( MQLONG & event );

Provides a copy of the enablement state of the service interval event. It returns TRUE if successful.

MQLONG serviceIntervalEvent( );

Returns the enablement state of the service interval event without any indication of possible errors.

ImqBoolean shareability( MQLONG & shareability );

Provides a copy of the shareability value. It returns TRUE if successful.

MQLONG shareability( );

Returns the shareability value without any indication of possible errors.

ImqBoolean storageClass( ImqString & class );

Provides a copy of the storage class. It returns TRUE if successful.

ImqString storageClass( );

Returns the storage class without any indication of possible errors.

ImqBoolean transmissionQueueName( ImqString & name );

Provides a copy of the transmission queue name. It returns TRUE if successful.

ImqString transmissionQueueName( );

Returns the transmission queue name without any indication of possible errors.

ImqBoolean triggerControl( MQLONG & control );

Provides a copy of the trigger control value. It returns TRUE if successful.

MQLONG triggerControl( );

Returns the trigger control value without any indication of possible errors.

ImqBoolean setTriggerControl( const MQLONG control );

Sets the trigger control value. It returns TRUE if successful.

ImqBoolean triggerData( ImqString & data );

Provides a copy of the trigger data. It returns TRUE if successful.

ImqString triggerData( );

Returns a copy of the trigger data without any indication of possible errors.

ImqBoolean setTriggerData( const char * data );

Sets the trigger data. It returns TRUE if successful.

ImqBoolean triggerDepth( MQLONG & depth );

Provides a copy of the trigger depth. It returns TRUE if successful.

MQLONG triggerDepth( );

Returns the trigger depth without any indication of possible errors.

ImqBoolean setTriggerDepth( const MQLONG depth );

Sets the trigger depth. It returns TRUE if successful.

ImqBoolean triggerMessagePriority( MQLONG & priority );

Provides a copy of the trigger message priority. It returns TRUE if successful.

MQLONG triggerMessagePriority( );

Returns the trigger message priority without any indication of possible errors.

ImqBoolean setTriggerMessagePriority( const MQLONG priority );

Sets the trigger message priority. It returns TRUE if successful.

ImqBoolean triggerType( MQLONG & type );

Provides a copy of the trigger type. It returns TRUE if successful.

MQLONG triggerType( );

Returns the trigger type without any indication of possible errors.

ImqBoolean setTriggerType( const MQLONG type );

Sets the trigger type. It returns TRUE if successful.

ImqBoolean usage( MQLONG & usage );

Provides a copy of the usage value. It returns TRUE if successful.

MQLONG usage( );

Returns the usage value without any indication of possible errors.

Object methods (protected)

void setNextDistributedQueue( ImqQueue * queue = 0 );

Sets the next distributed queue.

Attention: Use this function only if you are sure it will not break the distributed queue list.

void setPreviousDistributedQueue( ImqQueue * queue = 0 );

Sets the previous distributed queue.

Attention: Use this function only if you are sure it will not break the distributed queue list.

Reason codes

MQRC_ATTRIBUTE_LOCKED

MQRC_CONTEXT_OBJECT_NOT_VALID

MQRC_CONTEXT_OPEN_ERROR

MQRC_CURSOR_NOT_VALID

MQRC_NO_BUFFER

MQRC_REOPEN_EXCL_INPUT_ERROR

MQRC_REOPEN_INQUIRE_ERROR

MQRC_REOPEN_TEMPORARY_Q_ERROR

(reason codes from MQGET)

(reason codes from MQPUT)