MQeQMgrUnlockMsgs

Description
Unlock the messages on a queue identified by the LockID and the unique identifier (UID) of the message. The LockID is returned from an earlier , MQeQMgrBrowseMsgs with option MQE_QMGR_OPTION_BROWSE_LOCK.

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

Syntax
#include <hmq.h> 
MQEINT32 MQeQMgrUnlockMsgs( MQEHSESS hSess, MQECHAR * pQMName, 
                            MQECHAR * pQName,  MQEINT64 * pLockID, 
                            MQEHFIELDS pMsgs[], MQEINT32 nMsgs, 
                            MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQECHAR * pQMName - input
A null terminated string containing the name of the queue manager.

MQECHAR * pQName - input
A null terminated string containing the name of the queue.

MQEINT64 * pLockID - input
The 8-bytes LockID that was returned by the MQeQMgrBrowseMsgs() call with the MQE_QMGR_OPTION_BROWSE_LOCK option specified.

This parameter must be specified.

MQEINT32 pMsgs[] - input
An array of message object handles to be unlocked. These message object handles should be the same ones that were returned by the MQeQMgrBrowseMsgs() call. The queue manager extracts the unique identifier of each message object handle and uses it with the *pLockID value to unlock the locked message on the queue. The unique identifier of a message object is an 8-byte unique value and the string name of the origin queue manager. All other fields are ignored as they are not needed for the deletion operation.

If an entry in the pMsgs[] is a NULL, then this NULL entry is skipped and the unlock operation continues on to the next entry in the array. The unlock operation stops when it encounters an exception, and any remaining message object handles not processed are left as-is and remain locked on the queue.

Use the MQeFieldsFree() call to release MQeFields handles stored in this array.

MQEINT32 nMsgs - input
The number of array elements in the pMsgs[] array, including elements that are NULL.

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
  • pLockID is a NULL.

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
Could not find the message on the queue, and therefore, no message is deleted.

MQE_EXCEPT_NETWORK_ERROR_OPEN|READ|WRITE

Return Value

MQEINT32
The number of the array entries successfully processed, including the NULL entries.

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;
 
/* 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 Unlock                    */
/*--------------------------------------*/
/* 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[] */
   MQeQMgrUnlockMsgs( hSess, qm, q, 
								bmo.LockId, 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