ImqQueueManager

Figure 22. ImqQueueManager class

This class encapsulates a queue manager (a WebSphere MQ object of type MQOT_Q_MGR). It relates to the MQI calls listed in Table 23.

Other relevant classes

ImqAuthenticationRecord (see ImqAuthenticationRecord)

ImqChannel (see ImqChannel)

ImqObject (see ImqObject)

Class attributes

behavior

Controls the behavior of implicit connection and disconnection.

IMQ_EXPL_DISC_BACKOUT (0L)

An explicit call to the disconnect method implies backout. This attribute is mutually exclusive with IMQ_EXPL_DISC_COMMIT.

IMQ_EXPL_DISC_COMMIT (1L)

An explicit call to the disconnect method implies commit (the default). This attribute is mutually exclusive with IMQ_EXPL_DISC_BACKOUT.

IMQ_IMPL_CONN (2L)

Implicit connection is allowed (the default).

IMQ_IMPL_DISC_BACKOUT (0L)

An implicit call to the disconnect method, which can occur during object destruction, implies backout. This attribute is mutually exclusive with the IMQ_IMPL_DISC_COMMIT.

IMQ_IMPL_DISC_COMMIT (4L)

An implicit call to the disconnect method, which can occur during object destruction, implies commit (the default). This attribute is mutually exclusive with IMQ_IMPL_DISC_BACKOUT.

Object attributes

authority event

Controls authority events. This attribute is read-only.

begin options

Options that apply to the begin method. The initial value is MQBO_NONE.

channel auto definition

Channel auto definition value. This attribute is read-only.

channel auto definition event

Channel auto definition event value. This attribute is read-only.

channel auto definition exit

Channel auto definition exit name. This attribute is read-only.

channel reference

A reference to a channel definition for use during client connection. While connected, this attribute can be set to null, but cannot be changed to any other value. The initial value is null.

character set

Coded character set identifier (CCSID). This attribute is read-only.

cluster workload data

Cluster workload exit data. This attribute is read-only.

cluster workload exit

Cluster workload exit name. This attribute is read-only.

cluster workload length

Cluster workload length. This attribute is read-only.

command input queue name

System command input queue name. This attribute is read-only.

command level

Command level supported by the queue manager. This attribute is read-only.

connect options

Options that apply to the connect method. The initial value is MQCNO_NONE. The following additional values are possible:

MQCNO_STANDARD_BINDING

MQCNO_FASTPATH_BINDING

MQCNO_HANDLE_SHARE_NONE

MQCNO_HANDLE_SHARE_BLOCK

MQCNO_HANDLE_SHARE_NO_BLOCK

connection status

TRUE when connected to the queue manager. This attribute is read-only.

connection tag

A tag to be associated with a connection. This attribute can only be set when not connected. The initial value is null.

cryptographic hardware

Configuration details for cryptographic hardware. For MQ client connections (WebSphere MQ V5.3 and later, not Windows).

dead-letter queue name

Name of the dead-letter queue. This attribute is read-only.

default transmission queue name

Default transmission queue name. This attribute is read-only.

distribution lists

Specifies the capability of the queue manager to support distribution lists.

first authentication record

The first of one or more objects of class ImqAuthenticationRecord, in no particular order, in which the ImqAuthenticationRecord connection reference addresses this object. For MQ client connections (WebSphere MQ V5.3 and later).

first managed object

The first of one or more objects of class ImqObject, in no particular order, in which the ImqObject connection reference addresses this object. The initial value is zero.

inhibit event

Controls inhibit events. This attribute is read-only.

key repository

Specifies the location of the key database file in which keys and certificates are stored. For MQ client connections (WebSphere MQ V5.3 and later).

local event

Controls local events. This attribute is read-only.

maximum handles

Maximum number of handles. This attribute is read-only.

maximum message length

Maximum possible length for any message on any queue managed by this queue manager. This attribute is read-only.

maximum priority

Maximum message priority. This attribute is read-only.

maximum uncommitted messages

This is the maximum number of uncommitted messages within a unit or work. This attribute is read-only.

performance event

Controls performance events. This attribute is read-only.

platform

Platform on which the queue manager resides. This attribute is read-only.

remote event

Controls remote events. This attribute is read-only.

repository name

Repository name. This attribute is read-only.

repository namelist

Name of the repository namelist. This attribute is read-only.

start-stop event

Controls start-stop events. This attribute is read-only.

syncpoint availability

Availability⁴ of syncpoint participation. This attribute is read-only.

trigger interval

Trigger interval. This attribute is read-only.

Constructors

ImqQueueManager( );

The default constructor.

ImqQueueManager( const ImqQueueManager & manager );

The copy constructor. The connection status will be FALSE.

ImqQueueManager( const char * name );

Sets the ImqObject name to name.

Destructors

When an ImqQueueManager object is destroyed, it is automatically disconnected.

Class methods (public)

static MQLONG behavior( );

Returns the behavior.

void setBehavior( const MQLONG behavior = 0 );

Sets the behavior.

Object methods (public)

void operator = ( const ImqQueueManager & mgr );

Disconnects if necessary, and copies instance data from mgr. The connection status is be FALSE.

ImqBoolean authorityEvent( MQLONG & event );

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

MQLONG authorityEvent( );

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

ImqBoolean backout( );

Backs out uncommitted changes. It returns TRUE if successful.

ImqBoolean begin( );

Begins a unit of work. The begin options affect the behavior of this method. It returns TRUE if successful; but note that it also returns TRUE even if the underlying MQBEGIN call returned MQRC_NO_EXTERNAL_PARTICIPANTS or MQRC_PARTICIPANT_NOT_AVAILABLE (which are both associated with MQCC_WARNING).

MQLONG beginOptions( ) const ;

Returns the begin options.

void setBeginOptions( const MQLONG options = MQBO_NONE );

Sets the begin options.

ImqBoolean channelAutoDefinition( MQLONG & value );

Provides a copy of the channel auto definition value. It returns TRUE if successful.

MQLONG channelAutoDefinition( );

Returns the channel auto definition value without any indication of possible errors.

ImqBoolean channelAutoDefinitionEvent( MQLONG & value );

Provides a copy of the channel auto definition event value. It returns TRUE if successful.

MQLONG channelAutoDefinitionEvent( );

Returns the channel auto definition event value without any indication of possible errors.

ImqBoolean channelAutoDefinitionExit( ImqString & name );

Provides a copy of the channel auto definition exit name. It returns TRUE if successful.

ImqString channelAutoDefinitionExit( );

Returns the channel auto definition exit name without any indication of possible errors.

ImqBoolean channelReference( ImqChannel * & pchannel );

Provides a copy of the channel reference. If the channel reference is invalid, pchannel is set to null. This method returns TRUE if successful.

ImqChannel * channelReference( );

Returns the channel reference without any indication of possible errors.

ImqBoolean setChannelReference( ImqChannel & channel );

Sets the channel reference. This method returns TRUE if successful.

ImqBoolean setChannelReference( ImqChannel * channel = 0 );

Sets or resets the channel reference. This method returns TRUE if successful.

ImqBoolean characterSet( MQLONG & ccsid );

Provides a copy of the character set. It returns TRUE if successful.

MQLONG characterSet( );

Returns a copy of the character set, without any indication of possible errors.

ImqBoolean clusterWorkloadData( ImqString & data );

Provides a copy of the cluster workload exit data. It returns TRUE if successful.

ImqString clusterWorkloadData( );

Returns the cluster workload exit data without any indication of possible errors.

ImqBoolean clusterWorkloadExit( ImqString & name );

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

ImqString clusterWorkloadExit( );

Returns the cluster workload exit name without any indication of possible errors.

ImqBoolean clusterWorkloadLength( MQLONG & length );

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

MQLONG clusterWorkloadLength( );

Returns the cluster workload length without any indication of possible errors.

ImqBoolean commandInputQueueName( ImqString & name );

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

ImqString commandInputQueueName( );

Returns the command input queue name without any indication of possible errors.

ImqBoolean commandLevel( MQLONG & level );

Provides a copy of the command level. It returns TRUE if successful.

MQLONG commandLevel( );

Returns the command level without any indication of possible errors.

ImqBoolean commit( );

Commits uncommitted changes. It returns TRUE if successful.

ImqBoolean connect( );

Connects to the queue manager with the given ImqObject name, the default being the local queue manager. If you want to connect to a specific queue manager, use the ImqObject setName method before connection. If there is a channel reference, it will be used to pass information about the channel definition to MQCONNX in an MQCD. The ChannelType in the MQCD is set to MQCHT_CLNTCONN. channel reference information, which is only meaningful for client connections, is ignored for server connections. The connect options affect the behavior of this method. This method sets the connection status to TRUE if successful. It returns the new connection status.

If there is a first authentication record, the chain of authentication records is used to authenticate digital certificates for secure client channels.

You can connect more than one ImqQueueManager object to the same queue manager. All use the same MQHCONN connection handle and share UOW functionality for the connection associated with the thread. The first ImqQueueManager to connect obtains the MQHCONN handle. The last ImqQueueManager to disconnect performs the MQDISC.

For a multithreaded program, each thread must use a separate ImqQueueManager object. Connections in different threads have different MQHCONN connection handles.

ImqBinary connectionTag ( ) const ;

Returns the connection tag.

ImqBoolean setConnectionTag ( const MQBYTE128 tag = 0 );

Sets the connection tag. If tag is zero then the connection tag is cleared. This method returns TRUE if successful.

ImqBoolean setConnectionTag ( const ImqBinary & tag );

Sets the connection tag. The data length of tag must be either zero (to clear the connection tag) or MQ_CONN_TAG_LENGTH. This method returns TRUE if successful.

MQLONG connectOptions( ) const ;

Returns the connect options.

void setConnectOptions( const MQLONG options = MQCNO_NONE );

Sets the connect options.

ImqBoolean connectionStatus( ) const ;

Returns the connection status.

ImqString cryptographicHardware ( );

Returns the cryptographic hardware (WebSphere MQ V5.3 and later, not Windows).

ImqBoolean setCryptographicHardware ( const char * hardware = 0 );

Sets the cryptographic hardware (WebSphere MQ V5.3 and later, not Windows). This method returns TRUE if successful.

ImqBoolean deadLetterQueueName( ImqString & name );

Provides a copy of the dead-letter queue name. It returns TRUE if successful.

ImqString deadLetterQueueName( );

Returns a copy of the dead-letter queue name, without any indication of possible errors.

ImqBoolean defaultTransmissionQueueName( ImqString & name );

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

ImqString defaultTransmissionQueueName( );

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

ImqBoolean disconnect( );

Disconnects from the queue manager and sets the connection status to FALSE. All ImqProcess and ImqQueue objects associated with this object are closed and their connection reference severed prior to disconnection. If more than one ImqQueueManager object is connected to the same queue manager, only the last to disconnect performs a physical disconnection; others perform a logical disconnection. Uncommitted changes are committed on physical disconnection only.

This method returns TRUE if successful. If it is called on an object that is not already connected, success is guaranteed.

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.

ImqAir * firstAuthenticationRecord ( ) const ;

Returns the first authentication record (WebSphere MQ V5.3 and later).

void setFirstAuthenticationRecord ( const ImqAir * air = 0 );

Sets the first authentication record (WebSphere MQ V5.3 and later).

ImqObject * firstManagedObject( ) const ;

Returns the first managed object.

ImqBoolean inhibitEvent( MQLONG & event );

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

MQLONG inhibitEvent( );

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

ImqString keyRepository ( );

Returns the key repository (WebSphere MQ V5.3 and later).

ImqBoolean setKeyRepository ( const char * repository = 0 );

Sets the key repository (WebSphere MQ V5.3 and later). It returns TRUE if successful.

ImqBoolean localEvent( MQLONG & event );

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

MQLONG localEvent( );

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

ImqBoolean maximumHandles( MQLONG & number );

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

MQLONG maximumHandles( );

Returns the maximum handles 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 maximumPriority( MQLONG & priority );

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

MQLONG maximumPriority( );

Returns a copy of the maximum priority, without any indication of possible errors.

ImqBoolean maximumUncommittedMessages( MQLONG & number );

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

MQLONG maximumUncommittedMessages( );

Returns the maximum uncommitted messages without any indication of possible errors.

ImqBoolean performanceEvent( MQLONG & event );

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

MQLONG performanceEvent( );

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

ImqBoolean platform( MQLONG & platform );

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

MQLONG platform( );

Returns the platform without any indication of possible errors.

ImqBoolean remoteEvent( MQLONG & event );

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

MQLONG remoteEvent( );

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

ImqBoolean repositoryName( ImqString & name );

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

ImqString repositoryName( );

Returns the repository name without any indication of possible errors.

ImqBoolean repositoryNamelistName( ImqString & name );

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

ImqString repositoryNamelistName( );

Returns a copy of the repository namelist name without any indication of possible errors.

ImqBoolean startStopEvent( MQLONG & event );

Provides a copy of the enablement state of the start-stop event. It returns TRUE if successful.

MQLONG startStopEvent( );

Returns the enablement state of the start-stop event without any indication of possible errors.

ImqBoolean syncPointAvailability( MQLONG & sync );

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

MQLONG syncPointAvailability( );

Returns a copy of the syncpoint availability value, without any indication of possible errors.

ImqBoolean triggerInterval( MQLONG & interval );

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

MQLONG triggerInterval( );

Returns the trigger interval without any indication of possible errors.

Object methods (protected)

void setFirstManagedObject( const ImqObject * object = 0 );

Sets the first managed object.

Object data (protected)

MQHCONN ohconn

The WebSphere MQ connection handle (meaningful only while the connection status is TRUE).

Reason codes

MQRC_ATTRIBUTE_LOCKED

MQRC_ENVIRONMENT_ERROR

MQRC_FUNCTION_NOT_SUPPORTED

MQRC_REFERENCE_ERROR

(reason codes for MQBACK)

(reason codes for MQBEGIN)

(reason codes for MQCMIT)

(reason codes for MQCONNX)

(reason codes for MQDISC)

(reason codes for MQCONN)

⁴

Queue manager-coordinated global units of work are not supported on the OS/400^(R) platform. You can program a unit of work, externally coordinated by OS/400, using the "_Rcommit" and "_Rback" native system calls. This type of unit of work is started by starting the WebSphere MQ application under job-level commitment control using the STRCMTCTL command. See the WebSphere MQ Application Programming Guide for further details. Backout and commit are supported on the OS/400 platform for local units of work coordinated by a queue manager.