By default, no reply is generated, when an administration request is processed. If a reply is required, then the request message must be setup to ask for a reply message. The following fields are defined in the MQe class and are used to request a reply.
If MQE_MSG_STYLE is set to MQE_MSG_STYLE_REQUEST (a reply is required) then the location that the reply is to be sent to must be set into the request message. The two fields used to set the location are:
If the reply-to queue manager is not the queue manager that processes the request then the queue manager that processes the request must have a connection defined to the reply-to queue manager.
For an administration request message to be correlated to its reply message the request message needs to contain fields that uniquely identify the request, and that can then be copied into the reply message. WebSphere MQ Everyplace provides two fields that can be used for this purpose:
Any other fields can be used but these two have the added benefit that they are used by the queue manager to optimize searching of queues and message retrieval. The following code fragment provides an example of how to prime a request message:
MQERETURN primeAdminMsg(MQeQueueAdminMsgHndl hMsg, MQeExceptBlock *pErrorBlock, MQeFieldsHndl * phMsgTest, MQeStringHndl hQueueManagerName) { MQERETURN rc; /* Set the target queue manager that will process this message */ rc = mqeAdminMsg_setTargetQMgr((MQeAdminMsgHndl)hMsg, pErrorBlock, hQueueManagerName); if (MQERETURN_OK == rc) { /* Ask for a reply message */ rc = mqeFields_putInt32((MQeFieldsHndl)hMsg, pErrorBlock, MQE_MSG_STYLE, MQE_MSG_STYLE_REQUEST); if (MQERETURN_OK == rc) { rc = mqeFields_putAscii((MQeFieldsHndl)hMsg, pErrorBlock, MQE_MSG_REPLYTO_Q, MQE_ADMIN_REPLY_QUEUE_NAME); if (MQERETURN_OK == rc) { rc = mqeFields_putAscii((MQeFieldsHndl)hMsg, pErrorBlock, MQE_MSG_REPLYTO_QMGR, hQueueManagerName); if (MQERETURN_OK == rc) { rc = mqeFields_new(pErrorBlock, phMsgTest); if (MQERETURN_OK == rc) { MQEINT64 v; MQeStringHndl hFieldName; /* create some identical data fields in both hMsg and *phMsgTest so that the replay message can be matched against when it is returned to the replyToQ. */ rc = mqe_uniqueValue(pErrorBlock, &v); if (MQERETURN_OK == rc) { rc = mqeString_newChar8(pErrorBlock, &hFieldName, "IDField" ); if (MQERETURN_OK == rc) { rc = mqeFields_putInt64(*phMsgTest, pErrorBlock, hFieldName, v); if (MQERETURN_OK == rc) { rc = mqeFields_putInt64((MQeFieldsHndl)hMsg, pErrorBlock, hFieldName, v); if (MQERETURN_OK != rc) { displayError("mqeFields_putInt64 error (in primeAdminMsg, hMsg)", pErrorBlock); } } else { displayError("mqeFields_putInt64 error (in primeAdminMsg, phMsgTest)", pErrorBlock); } (void)mqeString_free(hFieldName, NULL); } else { displayError("mqeString_newChar8 error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqe_uniqueValue error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqeFields_new error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqeFields_putAscii (2) error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqeFields_putAscii (1) error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqeAdminMsg_Int32 error (in primeAdminMsg)", pErrorBlock); } } else { displayError("mqeAdminMsg_setTargetQMgr error (in primeAdminMsg)", pErrorBlock); } return rc; }
When the administration request message has been created, it is sent to the target queue manager using standard WebSphere MQ Everyplace message processing APIs. Depending on how the destination administration queue is defined, delivery of the message can be either synchronous or asynchronous.
Standard WebSphere MQ Everyplace message processing APIs are also used to wait for a reply, or notification of a reply. There is a time lag between sending the request and receiving the reply message. The time lag may be small if the request is being processed locally or may be long if both the request and reply messages are delivered asynchronously. Administration example Ex1 contains code that demonstrates these functions.