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


© IBM Corporation 2002. All Rights Reserved