MQeQMgr APIs

The following APIs are used to interact with the WebSphere MQ Everyplace queue manager.

MQeQMgrBrowseMsgs
Browses messages on a queue.

MQeQMgrConfirmMsg
Deletes a message already retrieved from a queue or makes a previously put message available.

MQeQMgrDeleteMsgs
Deletes an array of messages on the queue.

MQeQMgrGetMsg
Gets a message from a queue.

MQeQMgrGetName
Gets the name of the local queue manager.

MQeQMgrPutMsg
Puts a message onto a queue.

MQeQMgrUndo
Undoes one or more messages that were put, retrieved, or locked on a queue.

MQeQMgrUnlockMsgs
Unlocks an array of messages on the queue that were locked by MQeQMgrBrowseMsgs().

The general constraints listed in General constraints apply to all the queue manager APIs.

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. 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 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

MQeQMgrConfirmMsg

Description
This function is used to support the assured message delivery mechanism of WebSphere MQ Everyplace. This API call tells the queue manager to commit the previous MQeQMgrGetMsg or MQeQMgrPutMsg operation. The application must have supplied a ConfirmID with these previous calls. The input parameter hMsg must contain the unique identifier UID of the message object that is to be confirmed. The unique identifier of a message object is a 64 bit integer value and the string name of the origin queue manager.

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.

Syntax
#include <hmq.h> 
MQEVOID MQeQMgrConfirmMsg( MQEHSESS hSess, MQECHAR * pQMName, 
                           MQECHAR * pQName, MQEINT32 Option, 
                           MQEHFIELDS hMsg, MQEINT32 * pCompCode, 
                           MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
This 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.

MQEINT32 Option - input

MQE_QMGR_OPTION_CONFIRM_GETMSG
Confirms an earlier MQeQMgrGetMsg operation

MQE_QMGR_OPTION_CONFIRM_PUTMSG
Confirms an earlier MQeQMgrPutMsg operation.

If both options are set, then MQE_QMGR_OPTION_CONFIRM_GETMSG takes precedent.

MQEHFIELDS hMsg - input
An MQeFields object that contains the unique identifier of the message object to be confirmed. This could be the same messages object handle that was used earlier with the MQeQMgrGetMsg and MQeQMgrPutMsg function call with the MQE_QMGR_OPTION_CONFIRMID option set. The function extracts the unique identifier of the message object handle and uses it to confirm the message on the queue. All other fields in the hMsg are ignored.

The application has to call MQeFieldsFree() to free the message object handle.

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
hMsg does not contain the UID fields of a message object.

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_NOT_FOUND
No confirmID is associated with the UID supplied in the hMsg .

MQE_EXCEPT_NETWORK_ERROR_OPEN|READ|WRITE

Return Value

MQEVOID

Example
#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);

See Also

MQeQMgrDeleteMsgs

Description
Deletes the messages on a queue identified by the unique identifier of each message. The unique identifier is a combination of an 8 bytes integer unique ID and the origin queue manager name of the messages. The application is responsible for calling the MQeFieldsFree() to free the message object handles in the input array.

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

Parameters

MQEHSESS hSess - input
This 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.

MQEINT32 pMsgs[] - input
An array of message object handles to be deleted. To delete messages that are returned by a browse-and-lock function call, the messages object handles should be the input in this array. The queue manager extracts the unique identifier (UID) of each message object handle and sends it to the queue manager. The unique identifier of a message object is a 64 bit unique value and the string name of the origin queue manager. The rest of the fields in the message object are ignored.

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.

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

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;
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);

See Also

MQeQMgrGetMsg

Description
Get the first message on a queue that matches the filter. This API returns a fields object handle whose object type is MQeMsgObject_Type, on a specified queue manager and queue. The returned message is deleted from the queue. The queue may belong to a different WebSphere MQ Everyplace queue manager from the one to which the call was made. A filter can be specified, so that only messages that have matching attributes are returned.

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

Syntax
#include <hmq.h>
MQEHFIELDS MQeQMgrGetMsg( MQEHSESS hSess, 
				MQECHAR * pQMName, MQECHAR * pQName, 
           MQEVOID * pGetMsgOpts, MQEHFIELDS hFilter, 
           MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

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

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

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

MQEVOID * pGetMsgOpts - input
This parameter is a pointer to a data structure that contains the following elements:
typedef struct tagMQeGetMsgOpts{
   MQECHAR   StrucId[4];         /* Input  */
   MQEINT32  Version;      /* Input  */
   MQEINT32  Options;      /* Input  */
   MQEINT64  ConfirmId;    /* Input  */
   MQEHATTRB hAttrb;       /* Input  */
} MQEGMO;

MQECHAR StrucId[4] - input
The structure ID for the GetMsgOpts which is GETM .

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

MQEINT32 Options - input

MQE_QMGR_OPTION_CONFIRMID
Include the ConfirmIDwith the GetMsg operation. The retrieved message becomes inaccessible to subsequent MQeQMgrBrowseMsg() and MQeQMgrGetMsg() calls. It is not deleted from the queue until the MQeQMgrConfirmMsg is called with the UID of this message object or the message is made accessible again with MQeQMgrUndo call.

The default value is MQE_QMGR_OPTION_NONE.

MQEINT64 ConfirmId - input
A 64 bit integer that the application programmer supplies to mark the returned message object on the queue. The marked message object is made inaccessible to subsequent MQeQMgrBrowseMsg() and MQeQMgrGetMsg() calls until MQeQMgrUndo is called with this ConfirmId.

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.

MQEHATTRB hAttrb - input
The handle to the attribute object that is used to decode the message object on the queue before it is returned by this API. The default value is MQEHANDLE_NULL.
Note:
Version 2.0 does not support message-level security so this parameter is ignored.

If this parameter is NULL, then an MQEGMO data structure with the default values is used.

MQEHFIELDS hFilter - input
A handle to the filter that has the matching criteria for the messages on the queue.

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_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

MQEHFIELDS hMsgObj
The handle to a message object (an MQefields object with type MQE_OBJECT_TYPE_MQE_MSGOBJECT).

Example
#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);
 

See Also

MQeQMgrGetName

Description
Get the string name of the local queue manager.

Syntax
#include <hmq.h> 
MQEINT32 MQeQMgrGetName( MQEHSESS hSess, 
							MQECHAR * pQMgrName, 
                   	MQEINT32 qmNameLen,  MQEINT32 * pCompCode, 
                   MQEINT32 * pReason) 

Parameters

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

MQECHAR * pQMgrName - output
The output field into which the string name of the local queue manager is copied. If the buffer is NULL, the length of the local queue manager name is returned.

MQEINT32 qmNameLen - input
The buffer size of pQMName. If pQMgrName is NULL, then this parameter is ignored.

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

Return Value

MQEINT32 qmnLen
The length of the queue manager name.

Example
#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);

MQeQMgrPutMsg

Description
Put a message on a queue. If the destination queue manager name is the same as the local queue manager name, then the message is put on a local queue (With the exception of AdminQ, local queue is not supported on the Palm in Version 2.0). If the destination queue manager name is a remote queue manager, then for synchronous messaging, a communication connection is made to the remote queue manager and the message is transmitted to that queue manager. This call is blocked until the message is transmitted to the remote queue manager.

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 .

Syntax
#include <hmq.h> 
MQEVOID MQeQMgrPutMsg( MQEHSESS hSess, 
					MQECHAR * pQMName, MQECHAR * pQName, 
              MQEVOID * pPutMsgOpts, MQEHFIELDS hMsg, 
              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.

MQEVOID * putMsgOpts - input and output
This parameter is a pointer to a data structure that contains the following elements:
typedef struct tagMQePutMsgOpts{
   MQECHAR   StrucId[4];         /* Input  */
   MQEINT32  Version;            /* Input  */
   MQEINT32  Options;            /* Input  */
   MQEINT64  ConfirmId;          /* Input  */
   MQEHATTRB hAttrb;             /* Input  */
} MQEPMO;

MQECHAR StrucId[4] - input
The structure ID for the GetMsgOpts that is PUTM .

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

MQEINT32 Options - input

MQE_QMGR_OPTION_CONFIRMID
Include the ConfirmIDwith the PutMsg operation. The put message is inaccessible to subsequent MQeQMgrBrowseMsg() and MQeQMgrGetMsg() calls until MQeQMgrConfirmMsg is called with the UID of the hMsg or the message is deleted from the queue with MQeQMgrUndo.

The default value is MQE_QMGR_OPTION_NONE.

MQEINT64 ConfirmId - input
A 64 bit integer that the application programmer supplies to tag the returned message object on the queue.

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.

MQEHATTRB hAttrb - input
The handle to the attribute object that is use to decode the message object on the queue before it is returned by this API. Default value is MQEHANDLE_NULL.
Note:
Version 2.0 does not support message-level security so this parameter is ignored.

If this parameter is NULL, then an MQEPMO data structure with the default values is used.

MQEHFIELDS hMsg - input and output
The message object to put on the queue. If this message object is one of the following types, which may have a request-reply messaging type, then for synchronous WebSphere MQ Everyplace client that do not have a local AdminReplyQ queue, the reply message is returned in this parameter.
  • com.ibm.mqe.MQeAdminMsg
  • com.ibm.mqe.MQeQueueAdminMsg
  • com.ibm.mqe.MQeQueueManagerAdminMsg

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_NETWORK_ERROR_OPEN|READ|WRITE

Return Value
None

Example
#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);
 

See Also

MQeQMgrUndo

Description
Undo the previous MQeQMgrBrowseMsgs(), or MQeQMgrGetMsg() or MQeQMgrPutMsg(), or combination of these operations on a message, or a set of messages that have the same ConfirmID value. If the previous operation on the message objects was MQeQMgrBrowseMsgs() with lock, the messages objects are unlocked and made accessible again. If the previous operation on the message objects was MQeQMgrGetMsg(), the message object is put back onto the queue. If the previous operation was MQeQMgrPutMsg(), the message object is deleted from the queue.

Syntax
#include <hmq.h>
MQEVOID MQeQMgrUndo( MQEHSESS hSess, MQECHAR * pQMName,
                     MQECHAR * pQName,  MQEINT64 * pConfirmId, 
                     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 * pConfirmId - input
A 64 bit integer ConfirmID that was used on previous operations on the message objects.

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_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_NOT_FOUND

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_NETWORK_ERROR_OPEN|READ|WRITE

Return Value

MQEVOID

Example
#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);

See Also

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