The basic administration request message

Every request to administer an WebSphere MQ Everyplace resource takes the same basic form. Figure 13 shows the basic structure for all administration request messages:

A request is made up of:

  1. Base administration fields, that are common to all administration requests
  2. Administration fields, that are specific to the resource being managed
  3. Optional fields to assist with the processing of administration messages

Figure 13. Administration request message

top

Base administration fields

The base administration fields, that are common to all administration messages, are:

MQE_ADMIN_TARGET_QMGR
This field provides the name of the queue manager on which the requested action is to take place (target queue manager). The target queue manager can be either a local or a remote queue manager. As only one queue manager can be active at a time in a Java Virtual Machine, the target queue manager, and the one to which the message is put, are the same.

MQE_ADMIN_ACTION
This field contains the administration action that is to be performed. Each managed resource provides a set of administrative actions that it can perform. A single administration message can only request that one action be performed. The following common actions are defined:

Table 3. Administration actions

Administration action Purpose
MQE_ADMIN_ACTION_CREATE Create a new instance of a managed resource.
MQE_ADMIN_ACTION_DELETE Delete an existing managed resource
MQE_ADMIN_ACTION_INQUIRE Inquire on one or more characteristics of a managed resource
MQE_ADMIN_ACTION_INQUIREALL Inquire on all characteristics of a managed resource
MQE_ADMIN_ACTION_UPDATE Update one or more characteristics of a managed resource

All resources do not necessarily implement these actions. For instance, it is not possible to create a queue manager using an administration message. Specific administration messages can extend the base set to provide additional actions that are specific to a resource.

Each common action provides a function that sets the
MQE_ADMIN_ACTION field:

Table 4. Setting the administration action field

Administration action Setting function
MQE_ADMIN_ACTION_CREATE mqeAdminMsg_create(parameters)
MQE_ADMIN_ACTION_DELETE mqeAdminMsg_delete(parameters)
MQE_ADMIN_ACTION_INQUIRE mqeAdminMsg_inquire(parameters)
MQE_ADMIN_ACTION_INQUIREALL mqeAdminMsg_inquireAll(parameters)
MQE_ADMIN_ACTION_UPDATE mqeAdminMsg_update(parameters)
Where parameters is:
MQeAdminMsgHndl hMsgObj, 
MQeExceptBlock *pErrStruct, 
MQECONST MQeFieldsHndl hParms

MQE_ADMIN_MAXATTEMPTSAdmin_MaxAttempts

This field determines how many times an action can be retried if the initial action fails. The retry occurs either the next time that the queue manager restarts or at the next interval set on the administration queue.

Other fields
For most failures further information is available in the reply message. It is the responsibility of the requesting application to read and handle failure information. Refer to The basic administration reply message for more details on using the reply data.

A set of functions are available for setting some of the request fields:

Table 5. Setting administration request fields

Administration action Field type Set and get functions
MQE_ADMIN_PARAMS MQeFields mqeAdminMsg_getInputFields( MQeAdminMsgHndl hMsgObj , MQeExceptBlock * pErrStruct , MQeFieldsHndl * phFields)
MQE_ADMIN_ACTION int mqeAdminMsg_setAction( MQeAdminMsgHndl hMsgObj, MQeExceptBlock * pErrStruct, MQEINT32 action)
MQE_ADMIN_TARGET_QMGR ascii mqeAdminMsg_setTargetQMgr( MQeAdminMsgHndl hMsgObj, MQeExceptBlock * pErrStruct, MQECONST MQeStringHndl hName)
MQE_ADMIN_MAXATTEMPTS int mqeAdminMsg_setMaxAttempts( MQeAdminMsgHndl hMsgObj, MQeExceptBlock * pErrStruct, MQEINT32 maxAttempts)

Fields specific to the managed resource

MQE_ADMIN_PARAMS
This field contains the resource characteristics that are required for the action.

Every resource has a set of unique characteristics. Each characteristic has a name, type and value, and the name of each is defined by a constant in the administration message. The name of the resource is a characteristic that is common to all managed resources. The name of the resource is held in the MQE_ADMIN_NAME, and it has a type of ascii.

The full set of characteristics of a resource can be determined by using the mqeAdminMsg_characteristics() function against an instance of an administration message. This function returns an MQeFields object that contains one field for each characteristic. MQeFields functions can be used for enumerating over the set of characteristics to obtain the name, type and default value of each characteristic.

The action requested determines the set of characteristics that can be passed to the action. In all cases, at least the name of the resource, MQE_ADMIN_NAME, must be passed. In the case of MQE_ADMIN_ACTION_INQUIRE this is the only parameter that is required.

Other useful fields

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.

MQE_MSG_STYLE
A field of type int that can take one of three values:

MQE_MSG_STYLE_DATAGRAM
A command not requiring a reply

MQE_MSG_STYLE_REQUEST
A request that would like a reply

MQE_MSG_STYLE_REPLY
A reply to a request

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:

MQE_MSG_REPLYTO_Q
An ascii field used to hold the name of the queue for the reply

MQE_MSG_REPLYTO_QMGR
An ascii field used to hold the name of the queue manager for the reply

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:

MQE_MSG_MSGID
A byte array containing the message ID

MQE_MSG_CORRELID
A byte array containing the Correl ID of the message

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.



© IBM Corporation 2002. All Rights Reserved