ImqObject C++ class

This class is abstract. When an object of this class is destroyed, it is automatically closed, and its ImqQueueManager connection severed.

Figure 1. ImqObject class

This class relates to the MQI calls listed in ImqObject cross-reference.


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
    The 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
    Options that apply when an object is closed. 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 is the object itself. The initial value is zero. Note: Do not confuse this with the 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. 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
    Options that apply when an object is opened. 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. IBM MQ automatically adjusts the open options and automatically opens, reopens, and closes objects as required. This can result in unnecessary reopen operations, because IBM MQ uses the openFor method, and this adds open options incrementally only.
    2. Set the open options before using any methods that result in an MQI call (see C++ and MQI cross-reference ). This ensures that unnecessary reopen operations do not occur. Set open options explicitly if any of the potential reopen problems are likely to occur (see Reopen ).

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

    Zero is not a valid value; set the appropriate value before attempting to open the object. This can be done using either setOpenOptions (lOpenOptions) followed by open ( ), or openFor (lRequiredOpenOption). Note:
    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, it is good practice always to set MQOO_OUTPUT explicitly in application programs that use the open method.
    2. Specify MQOO_RESOLVE_NAMES if you want to use the resolved queue manager name and resolved queue name attributes of the class.

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

    previous managed object
    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
    The 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 MQBYTE* token = 0);
    Sets the alternate security id. token can 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, you might need 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 among 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, input is required, and any input option suffices. So, if the open options already contain one of:

    • MQOO_INPUT_AS_Q_DEF
    • MQOO_INPUT_SHARED
    • MQOO_INPUT_EXCLUSIVE

    the open options are already satisfactory and are not changed; if the open options do not already contain any of these options, 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 these options, 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 before 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 Manager 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 these 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, IBM MQ C++ does not provide this facility and you must 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 before an MQOPEN call, and returns TRUE if successful.

    ImqBoolean set ( const MQLONG int-attr, const MQLONG value );
    Sets an IBM MQ integer attribute.

    ImqBoolean set ( const MQLONG char-attr, const char * buffer, const size_t required-length );
    Sets an IBM 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 IBM 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 can be accessed.

      MQOD_VERSION_2
      All other fields in omqod can be accessed.

      MQOD_VERSION_3
      omqod.pmqod is a pointer to a dynamically allocated, larger, MQOD. No other fields in omqod can be accessed. All fields addressed by omqod.pmqod can be accessed. Note: omqod.pmqod.Version can be less than omqod.Version, indicating that the IBM MQ MQI client has more functionality than the IBM 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)