ImqObject

Figure 18. ImqObject class

This class is abstract. When an object of this class is destroyed, it is automatically closed, and its ImqQueueManager connection severed. This class relates to the MQI calls listed in Table 19.

Other relevant classes

ImqBinary (see ImqBinary)

ImqError (see ImqError)

ImqNamelist (see ImqNamelist)

ImqQueue (see ImqQueue)

ImqQueueManager (see ImqQueueManager)

ImqString (see ImqString)

Class attributes

behavior

Controls the behavior of implicit opening.

IMQ_IMPL_OPEN (8L)

Implicit opening is allowed. This is the default.

Object attributes

alteration date

The alteration date. This attribute is read-only.

alteration time

The alteration time. This attribute is read-only.

alternate user id

Up to MQ_USER_ID_LENGTH characters. The initial value is a null string.

alternate security id

The alternate security id. A binary value (MQBYTE40) of length MQ_SECURITY_ID_LENGTH. The initial value is MQSID_NONE.

close options

The initial value is MQCO_NONE. This attribute is ignored during implicit reopen operations, where a value of MQCO_NONE is always used.

connection reference

A reference to an ImqQueueManager object that provides the required connection to a (local) queue manager. For an ImqQueueManager object, it will be the object itself. The initial value is zero.

Note:

Do not confuse this with the ImqQueue queue manager name that identifies a queue manager (possibly remote) for a named queue.

description

The descriptive name (up to 64 characters) of the queue manager, queue, namelist, or process. This attribute is read-only.

name

The name (up to 48 characters) of the queue manager, queue, namelist, or process, as appropriate. The initial value is a null string. The name of a model queue changes after an open to the name of the resulting dynamic queue.

Note:

An ImqQueueManager can have a null name, representing the default queue manager. The name changes to the actual queue manager after a successful open. An ImqDistributionList is dynamic and must have a null name.

next managed object

This is the next object of this class, in no particular order, having the same connection reference as this object. The initial value is zero.

open options

The initial value is MQOO_INQUIRE. There are two ways to set appropriate values:

1. Do not set the open options and do not use the open method. WebSphere MQ automatically adjusts the open options and automatically opens, reopen and closes objects as required. This may result in unnecessary reopen operations, because WebSphere MQ uses the openFor method, and this adds open options incrementally only.
2. Set the open options as appropriate before using any methods that result in an MQI call (see Appendix B, MQI cross reference). This ensures that unnecessary reopen operations do not occur. It is strongly recommended that the open options be set explicitly if any of the potential reopen problems are likely to occur (see Reopen).

   If you use the open method, you must ensure that the open options are appropriate first. However, using the open method is not mandatory; WebSphere MQ still exhibits the same behavior as in case 1, but in this circumstance, the behavior is efficient.

Zero is not a valid value, and so the appropriate value must be set before attempting to open the object. This can be done either using setOpenOptions( lOpenOptions ) followed by open( ), or by using openFor( lRequiredOpenOption ).

Notes:

1. MQOO_OUTPUT is substituted for MQOO_INQUIRE during the open method for a distribution list, as MQOO_OUTPUT is the only valid open option at this time. However, this substitution may not occur in any future release, so you are recommended to set MQOO_OUTPUT explicitly in application programs that use the open method.

2. MQOO_RESOLVE_NAMES is an option that can be specified if the resolved queue manager name and resolved queue name attributes of the ImqQueue class are of interest.

open status

Indicates whether the object is open (TRUE) or closed (FALSE). The initial value is FALSE. This attribute is read-only.

previous managed object

This is the previous object of this class, in no particular order, having the same connection reference as this object. The initial value is zero.

queue manager identifier

Queue manager identifier. This attribute is read-only.

Constructors

ImqObject( );

The default constructor.

ImqObject( const ImqObject & object );

The copy constructor. The open status will be FALSE.

Class methods (public)

static MQLONG behavior( );

Returns the behavior.

void setBehavior( const MQLONG behavior = 0 );

Sets the behavior.

Object methods (public)

void operator = ( const ImqObject & object );

Performs a close if necessary, and copies the instance data from object. The open status will be FALSE.

ImqBoolean alterationDate( ImqString & date );

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

ImqString alterationDate( );

Returns the alteration date without any indication of possible errors.

ImqBoolean alterationTime( ImqString & time );

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

ImqString alterationTime( );

Returns the alteration time without any indication of possible errors.

ImqString alternateUserId( ) const ;

Returns a copy of the alternate user id.

ImqBoolean setAlternateUserId( const char * id );

Sets the alternate user id. The alternate user id can be set only while the open status is FALSE. This method returns TRUE if successful.

ImqBinary alternateSecurityId( ) const ;

Returns a copy of the alternate security id.

ImqBoolean setAlternateSecurityId( const ImqBinary & token );

Sets the alternate security id. The alternate security id can be set only while the open status is FALSE. The data length of token must be either zero or MQ_SECURITY_ID_LENGTH. It returns TRUE if successful.

ImqBoolean setAlternateSecurityId( const MQBYTE32 token = 0);

Sets the alternate security id. token may be zero, which is the same as specifying MQSID_NONE. If token is nonzero, it must address MQ_SECURITY_ID_LENGTH bytes of binary data. When using predefined values such as MQSID_NONE, it may be necessary to make a cast to ensure signature match; for example, (MQBYTE *)MQSID_NONE.

The alternate security id can be set only while the open status is TRUE. It returns TRUE if successful.

ImqBoolean setAlternateSecurityId( const unsigned char * id = 0);

Sets the alternate security id.

ImqBoolean close( );

Sets the open status to FALSE. It returns TRUE if successful.

MQLONG closeOptions( ) const ;

Returns the close options.

void setCloseOptions( const MQLONG options );

Sets the close options.

ImqQueueManager * connectionReference( ) const ;

Returns the connection reference.

void setConnectionReference( ImqQueueManager & manager );

Sets the connection reference.

void setConnectionReference( ImqQueueManager * manager = 0 );

Sets the connection reference.

virtual ImqBoolean description( ImqString & description ) = 0 ;

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

ImqString description( );

Returns a copy of the description without any indication of possible errors.

virtual ImqBoolean name( ImqString & name );

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

ImqString name( );

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

ImqBoolean setName( const char * name = 0 );

Sets the name. The name can only be set while the open status is FALSE, and, for an ImqQueueManager, while the connection status is FALSE. It returns TRUE if successful.

ImqObject * nextManagedObject( ) const ;

Returns the next managed object.

ImqBoolean open( );

Changes the open status to TRUE by opening the object as necessary, using amongst other attributes the open options and the name. This method uses the connection reference information and the ImqQueueManager connect method if necessary to ensure that the ImqQueueManager connection status is TRUE. It returns the open status.

ImqBoolean openFor( const MQLONG required-options = 0 );

Attempts to ensure that the object is open with open options, or with open options that guarantee the behavior implied by the required-options parameter value..

If required-options is zero, it is assumed that input is required, and that any input option will suffice. So, if the open options already contain one of:

MQOO_INPUT_AS_Q_DEF

MQOO_INPUT_SHARED

MQOO_INPUT_EXCLUSIVE

then the open options are already satisfactory and are not changed; if the open options do not already contain any of the above, then MQOO_INPUT_AS_Q_DEF is set in the open options.

If required-options is nonzero, the required options are added to the open options; if required-options is any of the above, the others are reset.

If any of the open options are changed and the object is already open, the object is closed temporarily and reopened in order to adjust the open options.

It returns TRUE if successful. Success indicates that the object is open with appropriate options.

MQLONG openOptions( ) const ;

Returns the open options.

ImqBoolean setOpenOptions( const MQLONG options );

Sets the open options. The open options can be set only while the open status is FALSE. It returns TRUE if successful.

ImqBoolean openStatus( ) const ;

Returns the open status.

ImqObject * previousManagedObject( ) const ;

Returns the previous managed object.

ImqBoolean queueManagerIdentifier( ImqString & id );

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

ImqString queueManagerIdentifier( );

Returns the queue manager identifier without any indication of possible errors.

Object methods (protected)

virtual ImqBoolean closeTemporarily( );

Closes an object safely prior to reopening. It returns TRUE if successful. This method assumes that the open status is TRUE.

MQHCONN connectionHandle( ) const ;

Returns the MQHCONN associated with the connection reference. This value is zero if there is no connection reference or if the ImqQueueManager is not connected.

ImqBoolean inquire( const MQLONG int-attr, MQLONG & value );

Returns an integer value, the index of which is an MQIA_* value. In case of error, the value is set to MQIAV_UNDEFINED.

ImqBoolean inquire( const MQLONG char-attr, char * & buffer, const size_t length );

Returns a character string, the index of which is an MQCA_* value.

Note:

Both of the above methods return only a single attribute value. If a "snapshot" is required of more than one value, where the values are consistent with each other for an instant, WebSphere MQ C++ does not provide this facility and it is necessary to use the MQINQ call with appropriate parameters.

virtual void openInformationDisperse( );

Disperses information from the variable section of the MQOD data structure immediately after an MQOPEN call.

virtual ImqBoolean openInformationPrepare( );

Prepares information for the variable section of the MQOD data structure immediately prior to an MQOPEN call, and returns TRUE if successful.

ImqBoolean set( const MQLONG int-attr, const MQLONG value );

Sets a WebSphere MQ integer attribute.

ImqBoolean set( const MQLONG char-attr, const char * buffer, const size_t required-length );

Sets a WebSphere MQ character attribute.

void setNextManagedObject( const ImqObject * object = 0 );

Sets the next managed object.

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

void setPreviousManagedObject( const ImqObject * object = 0 );

Sets the previous managed object.

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

Object data (protected)

MQHOBJ ohobj

The WebSphere MQ object handle (valid only when open status is TRUE).

MQOD omqod

The embedded MQOD data structure. The amount of storage allocated for this data structure is that required for an MQOD Version 2. Inspect the version number (omqod.Version) and access the other fields as follows:

MQOD_VERSION_1

All other fields in omqod may be accessed.

MQOD_VERSION_2

All other fields in omqod may be accessed.

MQOD_VERSION_3

omqod.pmqod is a pointer to a dynamically allocated, larger, MQOD. No other fields in omqod may be accessed. All fields addressed by omqod.pmqod may be accessed.

Note:

omqod.pmqod.Version may be less than omqod.Version, indicating that the WebSphere MQ client has more functionality than the WebSphere MQ server.

Reason codes

MQRC_ATTRIBUTE_LOCKED

MQRC_INCONSISTENT_OBJECT_STATE

MQRC_NO_CONNECTION_REFERENCE

MQRC_STORAGE_NOT_AVAILABLE

MQRC_REOPEN_SAVED_CONTEXT_ERR

(reason codes from MQCLOSE)

(reason codes from MQCONN)

(reason codes from MQINQ)

(reason codes from MQOPEN)

(reason codes from MQSET)