The basic administration reply message

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

top

A reply is made up of:

  1. Base administration fields. These are copied from the request message
  2. Administration fields that are specific to the resource being managed
  3. Optional fields to assist with the processing of administration messages. These are copied from the request message
  4. Administration fields detailing outcome of request
  5. Administration fields providing detailed results of the request that are specific to the resource being managed
  6. Administration fields detailing errors that are specific to the resource being managed

The first three items are describe in The basic administration request message. The reply specific fields are described in the following sections.

Outcome of request fields

MQE_ADMIN_RC_FIRLD

This byte field contains the overall outcome of the request. This is a field of type int that is set to one of:

MQE_ADMIN_RC_SUCCESS
The action completed successfully.

MQE_ADMIN_RC_FAIL
The request failed completely.

MQE_ADMIN_RC_MIXED
The request was partially successful. A mixed return code could result if a request is made to update four attributes of a queue and three succeed and one fails.

MQE_ADMIN_REASON
A unicode field containing the overall reason for the failure in the case of Mixed and Failed.

MQE_ADMIN_PARAMS
An MQeFields object containing a field for each characteristics of the managed resource.

MQE_ADMIN_ERROR
An MQeFields object containing one field for each update that failed. Each entry contained in the MQE_ADMIN_ERROR field is of type ascii or asciiArray.

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



© IBM Corporation 2002. All Rights Reserved