Retrieving messages from a queue

MQeQMgrGetMsg and MQeQMgrBrowseMsgs are used to retrieve message object from a remote queue. Like MQeQMgrPutMsg(), these calls support the ConfirmId option. MQeQMgrBrowseMsgs also has a Browse_Lock option. One major difference between these two APIs is that MQeQMgrGetMsg returns only one message object, while MQeQMgrBrowseMsgs can return more than one message object as an array of message objects. These functions and their options are described below.

MQeQMgrGetMsg()
This is the basic get message call. It returns the first available message on the queue, and the message is deleted from the queue.

MQeQMgrGetMsg() with Filter
A filter constructed from an MQeFields object can be given to MQeQMgrGetMsg(), so that the first message on the queue that matches the filter is returned.

MQeQMgrGetMsg() with ConfirmId
The message object is returned to the caller, but, unlike the previous case, the message is not deleted from the queue. An MQeQMgrConfirmMsg() deletes the message from the queue, and an MQeQMgrUndo() makes the message object reappear on the queue again. When the returned message is on the queue it is accessible to subsequent MQeQMgrGetMsg and MQeQMgrDeleteMsgs() calls only if they contain the UID of the message object. The message is inaccessible to subsequent MQeQMgrBrowseMsgs.

A filter can be specified with this option.

MQeQMgrBrowseMsgs()
An array of message objects is returned to the caller. The messages are not deleted from the queue and they are accessible to subsequent MQeQMgrBrowseMsgs and MQeQMgrGetMsg() operations.

MQeQMgrBrowseMsgs() with Filter
A filter constructed from an MQeFields object can be given to this function call, so that only the messages that match the filter are returned. The messages are not deleted from the queue, and they are accessible to future operations.

MQeQMgrBrowseMsgs() with BROWSE_LOCK
With this option, an array of message objects is returned to the caller, together with a lockID. This lockID is returned in the option data structure struct tagBrowseMsgOpts. The lockID and UID of the message object are used as an input parameter to the MQeQMgrUnlockMsgs API to unlock one or more message object on the queue and make them accessible again.

A filter can be specified with this option.

Messages locked on the queue are accessible to a subsequent MQeQMgrGetMsg() call only if it includes a filter that contains the lockID of the message. The messages are also accessible to an MQeQMgrDeleteMsgs() call only if it contains the message UID as an input parameter. Locked messages are inaccessible to future MQeQMgrBrowseMsgs() operations.

MQeQMgrBrowseMsgs() with BROWSE_LOCK and ConfirmId
Using these two options in combination gives the application programmer the flexibility of using either MQeQMgrUnlockMsgs() to unlock a specific message or MQeQMgrUndo() to unlock a group of messages.

A filter can be specified with this option.

These procedures are shown in the following code fragments:

MQeQMgrGetMsg() sample code fragment
#include <hmq.h>
MQEHSESS   hSess;
MQEHFIELDS hMsg, hFilter;
MQEINT32   compcode;
MQEINT32   reason;
MQEGMO     gmo = MQEGMO_DEFAULT;
MQECHAR  * aKey = "aKey", * qm, *q;
 
qm = "aQM";
q  = "QQ";
 
hSess = MQeInitialize("MyAppsName", 
								&compcode, &reason);
 
/* Get msg with filter and confirmID*/
 
gmo.ConfirmId.hi = 0x2222;
gmo.ConfirmId.lo = 0x1111;
gmo.Options     |= MQE_QMGR_OPTION_CONFIRMID;
 
hFilter = MQeFieldsAlloc( hSess, MQE_OBJECT_TYPE_MQE_FIELDS, 
                         &compcode, &reason);
MQeFieldsPut( hSess, hFilter, "FindThis", 
					MQE_TYPE_ASCII, aKey, strlen(aKey), 
             &compcode, &reason);
 
/* Get a message that contains the 
	field-name "FindThis", field-type of ASCII, and */
/* a field-value of "aKey". */
hMsg  = MQeQMgrGetMsg( hSess, qm, q, &gmo, hFilter, 
                      &compcode, &reason);
 
if (compcode==MQECC_OK) {
   /* Do something with the message. */
 
   /* Confirms the message, i.e., delete it off the queue. */
   MQeQMgrConfirmMsg( hSess, qm, q, 
								MQE_QMGR_OPTION_CONFIRM_GETMSG, hMsg, 
								&compcode, &reason);
 
   /* Free the message handle */
   MQeFieldsFree( hSess, hMsg, 
						&compcode, &reason);
}
 
MQeFieldsFree( hSess, hFilter, 
					&compcode, &reason);
MQeTerminate( hSess, &compcode, 
					&reason);
 

MQeQMgrBrowseMsgs() sample code fragment
/*========================================*/
#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);
   }
};
 
/* Deallocate the filter fields object handle */
MQeTerminate(hSess, &compcode, &reason);


© IBM Corporation 2002. All Rights Reserved