The following APIs are used to interact with the WebSphere MQ Everyplace queue manager.
The general constraints listed in General constraints apply to all the queue manager APIs.
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. 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 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);
This function confirms only a single MQeQMgrGetMsg or MQeQMgrPutMsg operation and not a set of them, therefore this API is not a unit-of-work function.
#include <hmq.h> MQEVOID MQeQMgrConfirmMsg( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEINT32 Option, MQEHFIELDS hMsg, MQEINT32 * pCompCode, MQEINT32 * pReason)
If both options are set, then MQE_QMGR_OPTION_CONFIRM_GETMSG takes precedent.
The application has to call MQeFieldsFree() to free the message object handle.
#include <hmq.h> MQEHSESS hSess; MQCHAR * qm = "myQM"; MQCHAR * q = "QQ"; MQEHFIELDS hFilter = MQEHANDLE_NULL; MQEINT32 i, n, nMsgs; MQEINT32 compcode; MQEINT32 reason; MQEGMO gmo = MQEGMO_DEFAULT; hSess = MQeInitialize("MyAppsName", &compcode, &reason); /* Set up the GMO for confirm msg operation */ gmo.Options |= MQE_QMGR_OPTION_CONFIRMID; gmo.ConfirmId.hi = 0; gmo.ConfirmId.lo = 0x55aa; hMsg = MQeQMgrGetMsg( hSess, qm, q, &gmo, hFilter, &compcode, &reason); /* Process the message */ /* Confirms the message */ MQeQMgrConfirmMsg( hSess, qm, q, MQE_QMGR_OPTION_CONFIRM_GETMSG, hMsg, &compcode, &reason); MQeTerminate(hSess, &compcode, &reason);
#include <hmq.h> MQEINT32 MQeQMgrDeleteMsgs( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEHFIELDS pMsgs[], MQEINT32 nMsgs, MQEINT32 * pCompCode, MQEINT32 * pReason)
If an entry in the pMsgs[] is a NULL, this NULL entry is skipped and the delete operation continues on to the next entry in the array. The delete operation stops when it encounters an exception, and any remaining message object handles not processed are left as-is and remain on the queue.
MQeFieldsFree() is used to release MQeFields handles stored in this array.
#include <hmq.h> MQEHSESS hSess; MQCHAR * qm, *q; MQEHFIELDS hFilter = MQEHANDLE_NULL; MQEINT32 i, n, nMsgs; MQEINT32 compcode; MQEINT32 reason; MQEBMO bmo = MQEBMO_DEFAULT; MQEHFIELDS pMsgs[2]; qm = "aQM"; q = "QQ"; hSess = MQeInitialize("MyAppsName", &compcode, &reason); /* Max. number of messages to get at a time for this run */ nMsgs = 2; bmo.cookie.hi = bmo.cookie.lo = 0; bmo.lockId.hi = bmo.lockId.lo = 0; bmo.option |= MQE_QMGR_OPTION_BROWSE_LOCK; /* 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, &cookie, &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);
The application programmer is responsible for calling MQeFieldsFree to deallocate the returned message handle.
#include <hmq.h> MQEHFIELDS MQeQMgrGetMsg( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEVOID * pGetMsgOpts, MQEHFIELDS hFilter, MQEINT32 * pCompCode, MQEINT32 * pReason)
typedef struct tagMQeGetMsgOpts{ MQECHAR StrucId[4]; /* Input */ MQEINT32 Version; /* Input */ MQEINT32 Options; /* Input */ MQEINT64 ConfirmId; /* Input */ MQEHATTRB hAttrb; /* Input */ } MQEGMO;
The default value is MQE_QMGR_OPTION_NONE.
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.
If this parameter is NULL, then an MQEGMO data structure with the default values is used.
#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);
#include <hmq.h> MQEINT32 MQeQMgrGetName( MQEHSESS hSess, MQECHAR * pQMgrName, MQEINT32 qmNameLen, MQEINT32 * pCompCode, MQEINT32 * pReason)
#include <hmq.h> MQEHSESS hSess; MQEINT32 qmLen; MQECHAR * qm; MQEINT32 rc,len; MQEINT32 compcode; MQEINT32 reason; hSess = MQeInitialize("MyAppsName", &compcode, &reason); len = MQeQMgrGetName( hSess, NULL, 0, &compcode, &reason); qm = (MQECHAR *) malloc(len+1); rc = MQeQMgrGetName( hSess, qm, len, &compcode, &reason); qm[len] = '\0'; printf("The Queue Manager Name is \"%s\"\n", qm); MQeTerminate( hSess, &compcode, &reason);
When this API call returns, the unique identifier (UID) is set in the input message object, and it is set every time this API is called. So an application can call this API with the same input message object and the UID is set with a different value every time. This resetting mechanism guarantees that no message object with a duplicate UID enters the WebSphere MQ Everyplace network.
The application must call MQeFieldsFree to deallocate the message handle hMsg .
#include <hmq.h> MQEVOID MQeQMgrPutMsg( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEVOID * pPutMsgOpts, MQEHFIELDS hMsg, MQEINT32 * pCompCode, MQEINT32 * pReason)
typedef struct tagMQePutMsgOpts{ MQECHAR StrucId[4]; /* Input */ MQEINT32 Version; /* Input */ MQEINT32 Options; /* Input */ MQEINT64 ConfirmId; /* Input */ MQEHATTRB hAttrb; /* Input */ } MQEPMO;
The default value is MQE_QMGR_OPTION_NONE.
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.
If this parameter is NULL, then an MQEPMO data structure with the default values is used.
#include <hmq.h> static const MQECHAR pHello[] = "Hello world."; MQEHSESS hSess; MQEHFIELDS hMsg; MQEINT32 rc; MQEINT32 compcode; MQEINT32 reason; MQEPMO pmo = MQEPMO_DEFAULT; MQECHAR * qm, *q; qm = "aQM"; q = "QQ"; hSess = MQeInitialize("MyAppsName", &compcode, &reason); hMsg = MQeFieldsAlloc( hSess, MQE_OBJECT_TYPE_MQE_MSGOBJECT, &compcode, &reason); MQeFieldsPut(hSess, hMsg, "hi", MQE_TYPE_ASCII, pHello, sizeof(pHello), &compcode, &reason); /* Put msg with confirmID*/ pmo.ConfirmId.hi = 0x2222; pmo.ConfirmId.lo = 0x1111; pmo.Options |= MQE_QMGR_OPTION_CONFIRMID; MQeQMgrPutMsg( hSess, qm, q, &pmo, hMsg, &compcode, &reason); /* Confirms the message, i.e., delete it off the queue. */ MQeQMgrConfirmMsg( hSess, qm, q, MQE_QMGR_OPTION_CONFIRM_PUTMSG, hMsg, &compcode, &reason); /* Free the message handle */ MQeFieldsFree( hSess, hMsg, &compcode, &reason); MQeTerminate( hSess, &compcode, &reason);
#include <hmq.h> MQEVOID MQeQMgrUndo( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEINT64 * pConfirmId, MQEINT32 * pCompCode, MQEINT32 * pReason)
#include <hmq.h> static const MQECHAR pHello[] = "Hello world."; MQEHSESS hSess; MQEHFIELDS hMsg; MQEINT32 rc; MQEINT32 compcode; MQEINT32 reason; MQEPMO pmo = MQEPMO_DEFAULT; MQECHAR * qm, *q; qm = "aQM"; q = "QQ"; hSess = MQeInitialize("MyAppsName", &compcode, &reason); hMsg = MQeFieldsAlloc( hSess, MQE_OBJECT_TYPE_MQE_MSGOBJECT, &compcode, &reason); MQeFieldsPut(hSess, hMsg, "hi", MQE_TYPE_ASCII, pHello, sizeof(pHello), &compcode, &reason); /* Put msg with confirmID, the Undo*/ pmo.ConfirmId.hi = 0x2222; pmo.ConfirmId.lo = 0x1111; pmo.Options |= MQE_QMGR_OPTION_CONFIRMID; /* Put 200 messages onto the queue. */ for (i=0; i<200; i++) { MQeQMgrPutMsg( hSess, qm, q, &pmo, hMsg, &compcode, &reason); } /* Undo the 200 putmsg operations. */ MQeQMgrUndo( hSess, qm, q, pmo.ConfirmId, &compcode, &reason); /* Free the message handle */ MQeFieldsFree( hSess, hMsg, &compcode, &reason); MQeTerminate( hSess, &compcode, &reason);
The application programmer is responsible for calling MQeFieldsFree to deallocate the message handles.
#include <hmq.h> MQEINT32 MQeQMgrUnlockMsgs( MQEHSESS hSess, MQECHAR * pQMName, MQECHAR * pQName, MQEINT64 * pLockID, MQEHFIELDS pMsgs[], MQEINT32 nMsgs, MQEINT32 * pCompCode, MQEINT32 * pReason)
This parameter must be specified.
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.
#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);