Once an administration request has been processed, a reply, if requested, is sent to the reply-to queue manager queue. The reply message has the same basic format as the request message with some additional fields.
Figure 14. Administration reply message
A reply is made up of:
The first three items are describe in The basic administration request message. The reply specific fields are described in the following sections.
This byte field contains the overall outcome of the request. This is a field of type int that is set to one of:
The following functions are available for getting some of the reply
fields:
Table 6. Getting administration reply fields
Administration field | Field type | get function |
---|---|---|
MQE_ADMIN_RC | int | mqeAdminMsg_getAction( MQeAdminMsgHndl hMsgObj , MQeExceptBlock * pErrStruct , MQEINT32 * pAction) |
MQE_ADMIN_REASON | unicode | mqeAdminMsg_getReason( MQeAdminMsgHndl hMsgObj , MQeExceptBlock * pErrStruct , MQeStringHndl * phReason) |
MQE_ADMIN_PARAMS | MQeFields | mqeAdminMsg_getOutputFields( MQeAdminMsgHndl hMsgObj , MQeExceptBlock * pErrStruct, MQeFieldsHndl * phFields) |
MQE_ADMIN_ERROR | MQeFields | mqeAdminMsg_getErrorFields( MQeAdminMsgHndl hMsgObj , MQeExceptBlock * pErrStruct , MQeFieldsHndl * phErrors) |
Depending on the action performed, the only fields of interest may be the return code and reason. This is the case for delete. For other actions such as inquire, more details may be required in the reply message. For instance, if an inquire request is made for fields MQE_QUEUE_DESCRIPTION and MQE_QUEUE_FILEDESC, the resultant MQeFields object would contain the values for the actual queue in these two fields.
The following table shows the MQE_ADMIN_PARAMS fields of a request message and a reply message for an inquire on
several parameters of a queue:
Table 7. Enquiring on queue parameters
Admin_Parms field name | Request message | Reply message | ||
---|---|---|---|---|
Type | Value | Type | Value | |
MQE_ADMIN_NAME | ascii | "TestQ" | ascii | "TestQ" |
MQE_QUEUE_MANAGER_NAME | ascii | "ExampleQM" | ascii | "ExampleQM" |
MQE_QUEUE_DESCRIPTION | Unicode | null | Unicode | "A test queue" |
MQE_QUEUE_FILEDESC | ascii | null | ascii | "c:\queues\" |
For actions where no additional data is expected on the reply, the MQE_ADMIN_PARAMS field in the reply matches that of the request message. This is the case for the create and update actions.
Some actions, such as create and update, may request
that several characteristic of a managed resource be set or updated. In
this case, it is possible for a return code of RC_Mixed to be
received. Additional details indicating why each update failed are
available from the Admin_Errors field. The
following table shows an example of the MQE_ADMIN_PARAMS field for a request to update a queue and the resultant MQE_ADMIN_ERROR field:
Table 8. Request and reply message to update a queue
Field name | Request message | Reply message | ||
---|---|---|---|---|
Type | Value | Type | Value | |
MQE_ADMIN_PARAMS field | ||||
MQE_ADMIN_NAME | ascii | "TestQ" | ascii | "TestQ" |
MQE_QUEUE_MANAGER_NAME | ascii | "ExampleQM" | ascii | "ExampleQM" |
MQE_QUEUE_DESCRIPTION | Unicode | null | Unicode | "ExampleQM" "A new description" |
MQE_QUEUE_FILEDESC | ascii | null | Unicode | "D:\queues" |
MQE_ADMIN_ERROR field | ||||
MQE_QUEUE_FILEDESC | n/a | n/a | ascii | "Code=4;com.ibm. mqe.MQeException: wrong field type" |
For fields where the update or set is successful there is no entry in the Admin_Errors field.
A detailed description of each error is returned in an ascii string. The example program Admin-Ex1 contains code showing how to look at the error string. (In the showReasons() function.)