MQeQMgrBrowseMsgs

Description
Browses messages on a queue without removing the messages from the queue. The browse returns an array of message object handles. The application can then interrogate the message objects. A filter can be used to make the browse more specific. For example, message object fields (for example, MessageId and Priority), could be specified so that only messages that have matching fields are returned.

The application specifies the size of the array into which the results are returned. This application programmer can therefore control the number of matched messages returned on a single browse call. The array size has a maximum limit in the WebSphere MQ Everyplace system and is set at 13 concurrent handles in Version 2.0.0.5. This is important for devices that have limited resources and, therefore, may not be able to store all the matching messages. To retrieve the rest of the matched messages, the application can subsequently make repeated calls to this function passing the same pBrowseMsgOpts as on the first call. pBrowseMsgOpts points to an MQEBMO type which maintains the context information for the browse.

Once a browse operation has been initiated, all subsequent MQeBrowseMsgs() calls that use the same MQEBMO structure are directed to the queue manager and queue specified on the first call. Any changes to these parameters on subsequent calls are ignored. Once the resources assigned to an MQEBMO structure are released, the structure can be reused for a new browse operation to a different queue manager and queue.

The application is responsible for calling MQeFieldsFree to deallocate the returned message object handles.

Syntax
#include <hmq.h> 
MQEINT32 MQeQMgrBrowseMsgs( MQEHSESS hSess, MQECHAR * pQMName, 
                            MQECHAR * pQName, MQEVOID * pBrowseMsgOpts, 
                            MQEHFIELDS hFilter, MQEHFIELDS pMsgs[ ], 
                            MQEINT32 nMsgs, MQEINT32 * pCompCode, 
                            MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle returned by MQeInitialize.

MQECHAR * pQMName - input
A null terminated ASCII string containing the name of the queue manager. An empty string name "" defaults to the local queue manager. A null is invalid input.

MQECHAR * pQName - input
A null terminated ASCII string containing the name of the queue. A null or an empty string is invalid.

MQEVOID * pBrowseMsgOpts - input
A pointer to a data structure that contains the following elements:
typedef struct tagMQeBrowseMsgOpts{
   MQECHAR    StrucId[4];         /* Input  */
   MQEINT32   Version;            /* Input  */
   MQEINT32   Options;            /* Input  */
   MQEINT64   ConfirmId;          /* Input  */
   MQEHATTRB  hAttrb;             /* Input  */
   MQEINT64   LockId;             /* Output */
   MQEINT64   Cookie;             /* Output */
} MQEBMO;

MQECHAR StrucId[4] - input
The Structure ID for the GetMsgOpts which is BRWS .

MQEINT32 Version - input
The version number of this data structure. The current version number is 1.

MQEINT32 Options - input

MQE_QMGR_OPTION_BROWSE_LOCK
Browse the messages that match the hFilter. Lock all these messages on the queue to make them inaccessible to future MQeQMgrBrowseMsgs() or MQeQMgrGetMsg() operations. The locked messages can either be deleted with MQeQMgrDeleteMsgs or unlocked with MQeQMgrUnlockMsgs. If a confirmID is supplied, MQeQMgrUndo can be used to unlock the messages on the queue.

If you are browsing a remote queue synchronously, it is highly recommended that your application also sets the MQE_QMGR_OPTION_CONFIRMID option when using the MQE_QMGR_OPTION_BROWSE_LOCK option. This is because a network communication error can cause the returned data packet that contains the LockID field to be lost, and without this LockID, the locked messages on the queue cannot be unlocked by the application. In this case, WebSphere MQ Everyplace system administrative intervention would be required. However, with a ConfirmID, the application can recover from this error condition by calling the MQeQMgrUndo function to unlock the messages on the remote queue and make these messages available to the application again.

MQE_QMGR_OPTION_BROWSE_JUST_UID
Browse the messages that match the hFilter and return message objects that contain only the unique IDs

MQE_QMGR_OPTION_CONFIRMID
Include the confirmID in the BrowseMsg operation.

The above three options can be used together in any combination.

MQEINT64 ConfirmId
A 64 bit integer that the application supplies to tag the returned message object on the queue. The tagged message object is made inaccessible for subsequentMQeQMgrBrowseMsgs() calls and forMQeQMgrGetMsg() calls without the UID of the message. These messages are made accessible again after MQeQMgrUndo() is called with this ConfirmID.

This ConfirmID value must be different for different devices, so that no two devices can put, get or browse locked messages on the same queue with the same ConfirmID. Otherwise an undo operation issued by one device could affect the messages of another device with the same confirmID.

The default value is '0'.

If MQE_QMGR_OPTION_CONFIRMID is set and ConfirmID is '0', or if ConfirmID is nonzero and MQE_QMGR_OPTION_CONFIRMID is not set, the call fails.

This ConfirmID is intended to be used with the MQeQMgrUndo function, and should not be used with the MQeQMgrConfirmMsg function.

MQEHATTRB hAttrb - input
The handle to the MQeAttribute object that is used to decode the message objects on the queue before it is returned by this function. This parameter is used for message-level security. The default value is MQEHANDLE_NULL.

Version 2.0.0.5 Note: Message-level security is not supported, so this parameter is ignored.

MQEINT64 LockId - output
A 64 bit integer returned by the queue manager when the MQE_QMGR_OPTION_BROWSE_LOCK option is set. If this option is not set, the return value of this parameter is undefined. This value is associated with the message object handles that are copied into the pMsgs[] array. The value returned in this parameter may be different for each call to this function.

The returned LockID is used by MQeQMgrUnlockMsgs to unlock the locked message.

A locked message remains locked until one of the following occurs:

Otherwise locked messages can only be unlocked by the WebSphere MQ Everyplace system utility.

MQEINT64 Cookie - output and input
A queue manager generated number that the application must pass back to this function on subsequent calls to retrieve the next set of message handles. This number serves as a bookmark that the queue manager uses to find the starting point in the queue to start the browse operation. The application need not understand the meaning of this value except to pass it back on subsequent calls. The first time this function is called, Cookie must be zero. To browse the remaining messages, the same input parameters <pQMName,pQName,hFilter,hAttrb> must be supplied on subsequent calls. If any of these four parameters differs from the original ones that the queue manager used to generate the Cookie , then the "book mark" is still used as the starting point to return the message. If Cookie is zero, then a new browse operation is initiated.

The implementation of this cookie may hold resource. These resources are released when

  • The last message that satisfies the hFilter is browsed.
  • pMsgs[] is a NULL.

    If an application has completed the required browse operation before the last message is browsed, it can release any resource held by the cookie by setting pMsgs[] to NULL in the subsequent browse call.

  • MQeTerminate is called.

The default value is zero.

If pBrowseMsgOpts is a NULL, then an MQEBMO data structure with the default values is used.

MQEHFIELDS hFilter - input
A handle to the filter that contains the matching fields for the messages on the queue. If no filter is provided, then all currently unlocked messages up to nMsgs on the queue are returned. If the MQE_QMGR_OPTION_BROWSE_LOCK option is set, at least nMsgs matching messages, and possibly all the matching messages on the queue are locked. The number of messages locked depends on the implementation.

Default value is MQEHANDLE_NULL.

MQEHFIELDS pMsgs[] - output
An array to hold returned message object handles. If this is NULL, then zero is returned. If pCookie is not NULL, then its resources are released. Users are expected to call MQeFieldsFree() to release MQeFields handles held by this array.

MQEINT32 nMsgs - input
The number of message to browse for this call.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_QMGR_INVALID_QMGR_NAME

MQE_EXCEPT_QMGR_INVALID_Q_NAME

MQE_EXCEPT_QMGR_UNKNOWN_QMGR

MQE_EXCEPT_QMGR_Q_DOES_NOT_EXIST

MQE_EXCEPT_Q_NO_MSG_AVAILABLE

MQE_EXCEPT_Q_NO_MATCHING_MSG

MQE_EXCEPT_NETWORK_ERROR_OPEN|READ|WRITE

Return Value

MQEINT32
The number of message object handles returned in the pMsgs[] array. This number is less than or equal to nMsgs.

Example
#include <hmq.h>
MQEHSESS   hSess;
MQEHFIELDS hFilter = MQEHANDLE_NULL;
MQEINT32   i, n, nMsgs;
MQEINT32   compcode;
MQEINT32   reason;
MQEBMO     bmo = MQEBMO_DEFAULT;
MQEHFIELDS pMsgs[2];
MQECHAR   *qm, *q;
 
qm = "MyQM";
q  = "QQ";
hSess  = MQeInitialize("MyAppsName", &compcode, &reason);
nMsgs  = 2;
 
/*--------------------------------------*/
/* Browse with no locking or confirm ID */
/*--------------------------------------*/
n = MQeQMgrBrowseMsgs( hSess, qm, q, &bmo, hFilter,  
                        pMsgs, nMsgs, &compcode, &reason );
 
/* Now set the browse option for lock and confirm */
bmo.Option = MQE_QMGR_BROWSE_LOCK | MQE_QMGR_CONFIRMID;
/* Set the confirm ID */
bmo.ConfirmId.hi = bmo.ConfirmId.lo = 0x12345678;
 
/*--------------------------------------*/
/* Browse and undo                      */
/*--------------------------------------*/
n = MQeQMgrBrowseMsgs( hSess, qm, q, &bmo, hFilter,  
                     pMsgs, nMsgs, &compcode, &reason );
 
MQeQMgrUndo(hSess, qm, q, bmo.ConfirmId, &compcode, &reason, );
 
/*--------------------------------------*/
/* Browse and delete                    */
/*--------------------------------------*/
/* Browse nMsgs at a time until no messages are left */
while (1) { /* do forever */
   /* Browse the nMsgs matching messages */
   n = MQeQMgrBrowseMsgs( hSess, qm, q, &bmo, hFilter,  
                        pMsgs, nMsgs, &compcode, &reason );
 
   if (n==0) {  
      /* Any resources held by the cookie has been released already */
      break;
   }
 
   for(i=0; i<n; i++) {
      /******************************************/
      /* Process the message objects in pMsgs[] */
      /******************************************/
   } 
 
   /* Delete the n locked messages in pMsgs[] */
   MQeQMgrDeleteMsgs( hSess, qm, q, pMsgs, n, &compcode, &reason );
 
   /* free pMsgs[] handle resources */
   for(i=0; i<n; i++) {
      MQeFieldsFree(hSess, pMsgs[i], &compcode, &reason);
   }
};
 
MQeTerminate(hSess, &compcode, &reason);

See Also


© IBM Corporation 2002. All Rights Reserved