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.
#include <hmq.h> MQEINT32 MQeQMgrBrowseMsgs( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEVOID * pBrowseMsgOpts, MQEHFIELDS hFilter, MQEHFIELDS pMsgs[ ], MQEINT32 nMsgs, MQEINT32 * pCompCode, MQEINT32 * pReason)
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;
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.
The above three options can be used together in any combination.
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.
Version 2.0.0.5 Note: Message-level security is not supported, so this parameter is ignored.
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.
The implementation of this cookie may hold resource. These resources are released when
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.
The default value is zero.
If pBrowseMsgOpts is a NULL, then an MQEBMO data structure with the default values is used.
Default value is MQEHANDLE_NULL.
#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);