ImqQueue C++ class

This class encapsulates a message queue (an IBM MQ object of type MQOT_Q).

Figure 1. ImqQueue class
This class relates to the MQI calls listed in Table 1.


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.

    cluster workload rank
    Cluster workload rank. This attribute is read-only.

    cluster workload priority
    Cluster workload priority. This attribute is read-only.

    cluster workload use queue
    Cluster workload use queue value. 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
    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
    Control attribute for queue depth low events. This attribute is read-only.

    depth low limit
    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
    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
    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 Windows, UNIX, and Linux platforms.

    harden get backout
    Whether to harden the backout count. This attribute is read-only.

    index type
    Index type. This attribute is read-only.

    inhibit get
    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
    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 can be less than the maximum for any queue managed by the associated queue manager. This attribute is read-only.

    message delivery sequence
    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.

    non-persistent message class
    Level of reliability for non-persistent messages put to this queue. This attribute is read-only.

    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 accounting
    Level of accounting information for queues. This attribute is read-only.

    queue-manager-name
    Name of the queue manager (possibly remote) where the queue resides. Do not confuse the queue manager named here with the ImqObject connection reference, which references the (local) queue manager providing a connection. The initial value is null.

    queue monitoring
    Level of monitoring data collection for the queue. This attribute is read-only.

    queue statistics
    Level of statistics data for the queue. This attribute is read-only.

    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
    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 clusterWorkLoadPriority ( MQLONG & priority );
    Provides a copy of the cluster workload priority value. It returns TRUE if successful.

    MQLONG clusterWorkLoadPriority ( );
    Returns the cluster workload priority value without any indication of possible errors.

    ImqBoolean clusterWorkLoadRank ( MQLONG & rank );
    Provides a copy of the cluster workload rank value. It returns TRUE if successful.

    MQLONG clusterWorkLoadRank ( );
    Returns the cluster workload rank value without any indication of possible errors.

    ImqBoolean clusterWorkLoadUseQ ( MQLONG & useq );
    Provides a copy of the cluster workload use queue value. It returns TRUE if successful.

    MQLONG clusterWorkLoadUseQ ( );
    Returns the cluster workload use queue value without any indication of possible 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. Invokes the ImqObject openFor method if necessary to ensure that the ImqObject open options include either one of the MQOO_INPUT_* values, or 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 before 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 nonPersistentMessageClass ( MQLONG & monq );
    Provides a copy of the non persistent message class value. It returns TRUE if successful.

    MQLONG nonPersistentMessageClass ( );
    Returns the non persistent message class value without any indication of possible errors.

    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 is opened, if necessary, to provide a context.

    ImqBoolean queueAccounting ( MQLONG & acctq );
    Provides a copy of the queue accounting value. It returns TRUE if successful.

    MQLONG queueAccounting ( );
    Returns the queue accounting value without any indication of possible errors.

    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 queueMonitoring ( MQLONG & monq );
    Provides a copy of the queue monitoring value. It returns TRUE if successful.

    MQLONG queueMonitoring ( );
    Returns the queue monitoring value without any indication of possible errors.

    ImqBoolean queueStatistics ( MQLONG & statq );
    Provides a copy of the queue statistics value. It returns TRUE if successful.

    MQLONG queueStatistics ( );
    Returns the queue statistics value without any indication of possible errors.

    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 we 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 we 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)

Parent topic: IBM MQ C++ classes