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



© IBM Corporation 2002. All Rights Reserved