Administration messages convey the administration action required by a combination of data fields stored in the message. These fields have well defined names, types, and values, and you can set up the administration message using low level fields API. In Java, there are numerous helper methods to make this task less arduous.
The following sections describe the constituent fields of admin messages and admin reply messages.
Every request to administer an WebSphere MQ Everyplace resource takes the same basic form. Figure 2 shows the basic structure for all administration request messages:
A request is made up of:
Figure 2. Administration request message
The base administration fields, that are common to all administration messages, are:
Table 4. Administration actions
Administration action | Purpose |
---|---|
Action_Create | Create a new instance of a managed resource. |
Action_Delete | Delete an existing managed resource |
Action_Inquire | Inquire on one or more characteristics of a managed resource |
Action_InquireAll | Inquire on all characteristics of a managed resource |
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 method that sets the
Admin_Action field:
Table 5. Setting the administration action field
Administration action | Setting method |
---|---|
Action_Create | create (MQeFields parms) |
Action_Delete | delete (MQeFields parms) |
Action_Inquire | inquire (MQeFields parms) |
Action_InquireAll | inquireAll (MQeFields parms) |
Action_Update | update( MQeFields parms ) |
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.
A set of methods is available for setting some of the request fields:
Table 6. Setting administration request fields
Administration action | Field type | Set and get methods |
---|---|---|
Admin_Parms | MQeFields | MQeFields getInputFields() |
Admin_Action | int | setAction (int action) |
Admin_TargetQMgr | ASCII | setTargetQMgr(String qmgr) |
Admin_MaxAttempts | int | setMaxAttempts(int attempts) |
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 Admin_Name, and it has a type of ASCII.
The full set of characteristics of a resource can be determined by using the characteristics() method against an instance of an administration message. This method returns an MQeFields object that contains one field for each characteristic. MQeFields methods 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, Admin_Name, must be passed. In the case of Action_InquireAll this is the only parameter that is required.
The following code could be used to set the name of the resource to be managed in an administration message:
SetResourceName( MQeAdminMsg msg, String name ) { MQeFields parms; if ( msg.contains( Admin_Parms ) ) parms = msg.getFields( Admin_Parms ); else parms = new MQeFields(); parms.putAscii( Admin_Name, name ); msg.putFields( Admin_Parms, parms ); }
Alternatively, the code can be simplified by using the getInputFields() method to return the Admin_Parms field from the message, or setName() to set the Admin_Name field into the message. This is shown in the following code:
SetResourceName( MQeAdminMsg msg, String name ) { msg.SetName( name ); }
By default, no reply is generated when an administration request is processed. If a reply is required, then the request message must be set up to ask for a reply message. The following fields are defined in the MQe class and are used to request a reply.
If Msg_Style is set to Msg_Style_Request (a reply is required), 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.
As this is a frequently performed process, this code example combines each step in the primeAdminMsg() method, that can be invoked in other chapters throughout this book (assuming that the method has been defined for the class in question).
public class LocalQueueAdmin extends MQe { public String targetQMgr = "ExampleQM"; // target queue manager public MQeFields primeAdminMsg(MQeAdminMsg msg) throws Exception { /* * Set the target queue manager that will process this message */ msg.setTargetQMgr( targetQMgr ); /* * Ask for a reply message to be sent to the queue * manager that processes the admin request */ msg.putInt (MQe.Msg_Style, MQe.Msg_Style_Request); msg.putAscii(MQe.Msg_ReplyToQ, MQe.Admin_Reply_Queue_Name); msg.putAscii(MQe.Msg_ReplyToQMgr, targetQMgr); /* * Setup the correl id so we can match the reply to the request. * - Use a value that is unique to the this queue manager. */ byte[] correlID = Long.toHexString( (MQe.uniqueValue()).getBytes() ); msg.putArrayOfByte( MQe.Msg_CorrelID, correlID ); /* * Ensure matching response message is retrieved * - set up a fields object that can be used as a match parameter * when searching and retrieving messages. */ MQeFields msgTest = new MQeFields(); msgTest.putArrayOfByte( MQe.Msg_CorrelID, new Byte{1, 2, 3, 4} ); /* * Return the unique filter for this message */ return msgTest; }
Depending on how the destination administration queue is defined, delivery of the message can be either synchronous or asynchronous.