Websphere MQ Everyplace

com.ibm.mqe
Class MQeAdminMsg

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeFields
              |
              +--com.ibm.mqe.MQeMsgObject
                    |
                    +--com.ibm.mqe.MQeAdminMsg
All Implemented Interfaces:
MQeExceptionCodes
Direct Known Subclasses:
MQeBridgeResourceAdminMsg, MQeCommunicationsListenerAdminMsg, MQeConnectionAdminMsg, MQeQueueAdminMsg, MQeQueueManagerAdminMsg

public abstract class MQeAdminMsg
extends MQeMsgObject

This class is used to create a basic MQeAdminMsg. The class extends MQeMsgObject and provides a base for all administration messages. Descendants of this class are created to administer different types of resource.

A typical administration application instantiates a subclass of MQeAdminMsg, configures it with the required administration request, and passes it to the administration queue on the target queue manager. If the application wishes to know the outcome of the action, a reply can be requested. When the request has been processed the result of is returned in a message to the reply-to queue and queue manager specified in the request message. Performing administration using messages provides location transparent administration. A resource can be administered either locally on the owning queue manager or from a remote queue manager using the same administration message.

There are two default queues that can be used for administration requests

MQe.Admin_Queue_Name
The queue that performs administration requests.
MQe.Admin_Reply_Queue_Name
A queue where administration reply messages can be sent.
These two queues can be configured when the queue manager is created.

Every administration messages takes the same basic form.

  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

Breaking each section into more down:
Base admin field items
Admin_Action What administration action to perform
Admin_TargetQMgr The name of the queue manager where the action is to be performed.
Fields specific to the resource being managed
Admin_Parms Input parameters to the action. For example Admin_Name
Optional fields (commonly used)
MQe.Msg_Style Is is a datagram or request message. i.e is a reply required.
MQe.Msg_ReplyToQ Name of the reply to queue
MQe.Msg_ReplyToQMgr Name of the reply to queue manager
MQe.Msg_MsgID A message identifier
MQe.Msg_CorrelID A message correlation identifier. Typically used to match a request message to a treply message.

A reply message is a copy of the request message with a number of new fields together with updates to existing fields. The table below shows the main changes in a reply message: .
Base admin field items
Admin_RC Return code detailing whether the action worked or not.
Admin_Reason If the action failed the main reason is contained in this field
Fields specific to the resource being managed
Admin_Parms Output parameters from the action. For instance if the request was an inquiry then the result is contained in the field.
Admin_Errors Detailed description of any errors.
Optional fields
None.

There are several ways that administration messages can be setup and manipulated:

Each type of resource that can be managed has its own administration message that is derived from MQeAdminMsg. Administration message for the core manageable objects are found in package com.ibm.mqe.administration. Administration messages for bridge related manageable objects are found in package com.ibm.mqe.mqbridge

A number of examples that demonstrates various ways to use administration messages can be found in packages:


Field Summary
static int Action_AddAlias
          Action to use when adding an alias to a resource.
static int Action_Create
          Action to use when creating a resource.
static int Action_Delete
          Action to use when deleting a resource.
static int Action_Inquire
          Action to use when inquiring on one or more characteristics of a resource.
static int Action_InquireAll
          Action to use when inquiring on all characteristics of a resource.
static int Action_RemoveAlias
          Action to use when removing an alias from a resouce.
static int Action_Start
          Action to use when starting a resouce.
static int Action_Stop
          Action to use when stopping a resource.
static int Action_Unknown
          Action is unknown or has not been set.
static int Action_Update
          Action to use when updating a resource.
static java.lang.String Admin_Action
          Name of the field that contains the administration action that is to be performed.
static java.lang.String Admin_Class
          Name of the field that contains the type of the resource being managed.
static java.lang.String Admin_Errors
          The name of a field that contains detailed error information.
static java.lang.String Admin_MaxAttempts
          The name of the field that contains the maximum number of times a request is tried.
static java.lang.String Admin_Name
          Name of the field that contains the name of the resource to be managed.
static java.lang.String Admin_Parms
          Name of the field that contains the resource characteristics that are required for or returned by an action.
static java.lang.String Admin_RC
          Name of the field that contains the overall result of the action.
static java.lang.String Admin_Reason
          Name of the field that contains the overall reason for any failure.
static java.lang.String Admin_TargetQMgr
          Name of the field that contains the name of the queue manager on which the requested action is to take place (the target queue manager).
static int RC_Fail
          Return code used when the request fails.
static int RC_Mixed
          Return code used when the request is partially successul.
static int RC_Success
          Return code used when the request completes successfully.
 
Fields inherited from class com.ibm.mqe.MQeFields
ArraySeparator, TypeArrayElements, TypeAscii, TypeBoolean, TypeByte, TypeDouble, TypeFields, TypeFloat, TypeInt, TypeLong, TypeShort, TypeUnicode, TypeUnTyped
 
Fields inherited from class com.ibm.mqe.MQe
Admin_Queue_Name, Admin_Reply_Queue_Name, copyright, DeadLetter_Queue_Name, Event_Activate, Event_Attribute, Event_Authenticate, Event_Close, Event_Logoff, Event_Logon, Event_MiniCert_Validate, Event_Queue, Event_QueueManager, Event_UserBase, JMS_Version, MQ_Headers, MQe_Log_Audit_Failure, MQe_Log_Audit_Success, MQe_Log_Error, MQe_Log_Information, MQe_Log_Success, MQe_Log_Warning, Msg_BackoutCount, Msg_CorrelID, Msg_ExpireTime, Msg_LockID, Msg_MsgID, Msg_OriginQMgr, Msg_Priority, Msg_ReplyToQ, Msg_ReplyToQMgr, Msg_Resend, Msg_Style, Msg_Style_Datagram, Msg_Style_Reply, Msg_Style_Request, Msg_Time, Msg_WrapMsg, sccsid, System_Default_Queue_Name, version
 
Fields inherited from interface com.ibm.mqe.MQeExceptionCodes
Except_Active, Except_AdapterException, Except_AdapterMissingRemoteAddress, Except_Admin_ActionNotSupported, Except_Admin_InvalidField, Except_Admin_NotAdminMsg, Except_AdminAction, Except_Authenticate, Except_BadRequest, Except_BridgeListener, Except_Chnl_Attributes, Except_Chnl_ID, Except_Chnl_Limit, Except_Chnl_Overrun, Except_Closed, Except_Con_AdapterRequired, Except_Con_AliasAlreadyExists, Except_Con_AlreadyExists, Except_Con_InvalidName, Except_Connect_Failure, Except_ConnectonType, Except_Cryptor, Except_Data, Except_Duplicate, Except_JmxProperties, Except_Listener, Except_MessageStore, Except_MiniCertReg_ActivateFailed, Except_MiniCertReg_BadPIN, Except_MiniCertReg_NotOpen, Except_NotActive, Except_NotAllowed, Except_NotFound, Except_NotSupported, Except_PrivateReg_ActivateFailed, Except_PrivateReg_BadPIN, Except_PrivateReg_NotOpen, Except_PublicReg_ActivateFailed, Except_PublicReg_InvalidAddress, Except_PublicReg_InvalidRequest, Except_Q_Full, Except_Q_InvalidName, Except_Q_InvalidPriority, Except_Q_MsgTooLarge, Except_Q_NoMatchingMsg, Except_Q_TargetRegistryRequired, Except_QMgr_Activated, Except_QMgr_AlreadyExists, Except_QMgr_InvalidQMgrName, Except_QMgr_InvalidQName, Except_QMgr_NotActive, Except_QMgr_NotBridgeEnabled, Except_QMgr_NotConfigured, Except_QMgr_QDoesNotExist, Except_QMgr_QExists, Except_QMgr_QNotEmpty, Except_QMgr_RegistryDataVersion, Except_QMgr_UnknownQMgr, Except_QMgr_WrongQType, Except_Reg_AddFailed, Except_Reg_AlreadyExists, Except_Reg_AlreadyOpen, Except_Reg_CRTKeyDecFailed, Except_Reg_CRTKeySignFailed, Except_Reg_DeleteFailed, Except_Reg_DeleteRegistryFailed, Except_Reg_DoesNotExist, Except_Reg_InvalidSession, Except_Reg_ListFailed, Except_Reg_NotDefined, Except_Reg_NotSecure, Except_Reg_NullName, Except_Reg_OpenFailed, Except_Reg_ReadFailed, Except_Reg_RenameFailed, Except_Reg_ResetPINFailed, Except_Reg_SearchFailed, Except_Reg_UpdateFailed, Except_RemoteException, Except_Rule, Except_S_BadIntegrity, Except_S_BadSubject, Except_S_CertificateExpired, Except_S_Cipher, Except_S_InvalidAttribute, Except_S_InvalidSignature, Except_S_MiniCertNotAvailable, Except_S_MissingSection, Except_S_NoPresetKeyAvailable, Except_S_RegistryNotAvailable, Except_Stopped, Except_Syntax, Except_TimeOut, Except_Transporter, Except_TriggerTransmission, Except_Trnsport_QMgr, Except_Trnsport_Request, Except_Type, Except_UdpipAdapterStateException, Except_UdpipAdapterTimeOut, Except_UdpipAdapterUnableToConfirmSuccess, Except_UnCoded, Except_Uncontactable_DontTransmit
 
Constructor Summary
MQeAdminMsg()
          The constructor creates and initializes a default MQeAdminMsg.
 
Method Summary
 MQeFields characteristics()
          Return an MQeFields object containing the characteristics of the resource.
 void create(MQeFields parms)
          Sets up an administration message to run the Action_Create action.
 void delete(MQeFields parms)
          Sets up an administration message to run the Action_Delete action.
 MQeAdminMsg duplicate()
          Creates a duplicate administration message.
 int getAction()
          Returns the administration action that is to be, or has been performed.
 MQeFields getErrorFields()
          Returns a reference to the error fields object.
 java.lang.String[] getFieldInError(java.lang.String fieldName)
          Given the field name of a resource characteristic, return any error that occurred when processing the characteristic.
 MQeFields getInputFields()
          Returns a reference to the input fields object.
 int getMaxAttempts()
          Get the maximum number of times the request should be tried.
 java.lang.String getName()
          Get the name of the managed resource.
 MQeFields getOutputFields()
          Returns a reference to the output fields object.
 int getRC()
          Returns the return code resulting from the action.
 java.lang.String getReason()
          Returns the reason for failure if an error occurred.
 java.lang.String getTargetQMgr()
          Returns the name of the queue manager where the request is to be processed.
 void inquire(MQeFields parms)
          Sets up the administration message to perform the Action_Inquire action.
 void inquireAll(MQeFields parms)
          Sets up the administration message to perform the Action_InquireAll action.
 void setAction(int action)
          Set the administration action to perform.
 void setMaxAttempts(int maxAttempts)
          Set the maximum number of times the request should be attempted.
 void setName(java.lang.String resourceName)
          Set the name of the resource that the action is to be performed on.
 void setTargetQMgr(java.lang.String targetQMgr)
          Set the name of queue manager where the request is to be processed.
 void update(MQeFields parms)
          Sets up an administration message to run the Action_Update action.
 
Methods inherited from class com.ibm.mqe.MQeMsgObject
getMsgUIDFields, getOriginQMgr, getTimeStamp, putOriginQMgr, resetMsgUIDFields, unwrapMsgObject
 
Methods inherited from class com.ibm.mqe.MQeFields
contains, copy, copy, dataType, deepCopy, delete, dump, dumpedType, dumpToString, equals, fields, getArrayLength, getArrayOfByte, getArrayOfDoubleAsLong, getArrayOfFloatAsInt, getArrayOfInt, getArrayOfLong, getArrayOfShort, getAscii, getAsciiArray, getAttribute, getBoolean, getByte, getDoubleAsLong, getFields, getFieldsArray, getFloatAsInt, getInt, getIntArray, getLong, getLongArray, getObject, getShort, getShortArray, getUnicode, getUnicodeArray, includes, isEqualTo, putArrayLength, putArrayOfByte, putArrayOfDoubleAsLong, putArrayOfFloatAsInt, putArrayOfInt, putArrayOfLong, putArrayOfShort, putAscii, putAsciiArray, putBoolean, putByte, putByteArray, putDoubleAsLong, putFields, putFieldsArray, putFloatAsInt, putInt, putIntArray, putLong, putLongArray, putObject, putShort, putShortArray, putUnicode, putUnicodeArray, rename, restore, restoreFromString, restoreFromString, restoreFromString, setAttribute, updateValue
 
Methods inherited from class com.ibm.mqe.MQe
abbreviate, alias, asciiToByte, byteToAscii, byteToHex, byteToHex, byteToInt, byteToLong, byteToShort, byteToUnicode, fileSeparator, getEventLogHandler, hexToAscii, hexToByte, intToByte, isCLDC, loadClass, loadObject, log, setEventLogHandler, setLoader, sliceByteArray, type, unicodeToByte, uniqueValue
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

Admin_TargetQMgr

public static final java.lang.String Admin_TargetQMgr
Name of the field that contains the name of the queue manager on which the requested action is to take place (the 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, must be the same.
Field type ascii
Set in request message mandatory

See Also:
Constant Field Values

Admin_Action

public static final java.lang.String Admin_Action
Name of the field that 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:

These actions may be added to in order to provide additional actions that are specific to a resource. Also some of the common actions are not applicable to all resources.
Field type int
Set in request message mandatory

See Also:
Constant Field Values

Action_Create

public static final int Action_Create
Action to use when creating a resource.

See Also:
Admin_Action, Constant Field Values

Action_Delete

public static final int Action_Delete
Action to use when deleting a resource.

See Also:
Admin_Action, Constant Field Values

Action_Inquire

public static final int Action_Inquire
Action to use when inquiring on one or more characteristics of a resource.

See Also:
Admin_Action, Constant Field Values

Action_InquireAll

public static final int Action_InquireAll
Action to use when inquiring on all characteristics of a resource.

See Also:
Admin_Action, Constant Field Values

Action_Update

public static final int Action_Update
Action to use when updating a resource.

See Also:
Admin_Action, Constant Field Values

Action_Stop

public static final int Action_Stop
Action to use when stopping a resource.

See Also:
Admin_Action, Constant Field Values

Action_Start

public static final int Action_Start
Action to use when starting a resouce.

See Also:
Admin_Action, Constant Field Values

Action_AddAlias

public static final int Action_AddAlias
Action to use when adding an alias to a resource.

See Also:
Admin_Action, Constant Field Values

Action_RemoveAlias

public static final int Action_RemoveAlias
Action to use when removing an alias from a resouce.

See Also:
Admin_Action, Constant Field Values

Action_Unknown

public static final int Action_Unknown
Action is unknown or has not been set.

See Also:
Admin_Action, Constant Field Values

Admin_Parms

public static final java.lang.String Admin_Parms
Name of the field that contains the resource characteristics that are required for or returned by an 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 Admin_Name field. The full set of characteristics of a resource can be determined by using the characteristics() method against an instance of an administration message.

The action requested determines the set of characteristics that can be set in this field. In all cases, the name of the resource, must be set. For certain actions like Action_InquireAll this is the only parameter that is required.

For a reply message this field contains the results of the request. For instance if the request was an inquiry then the results will be contained in this field.
Field type MQeFields
Set in request message mandatory

See Also:
Constant Field Values

Admin_Name

public static final java.lang.String Admin_Name
Name of the field that contains the name of the resource to be managed.

The name of the resouce must be placed into the Admin_Parms field for every request.
Field type ascii
Set in request message mandatory

See Also:
Admin_Parms, Constant Field Values

Admin_RC

public static final java.lang.String Admin_RC
Name of the field that contains the overall result of the action.

A reply message will contain this field which can take the following values:

More detailed information on any failure can be found in fields:

Field type byte
Set in request message no

See Also:
Admin_Reason, Admin_Errors, Constant Field Values

RC_Success

public static final int RC_Success
Return code used when the request completes successfully.

See Also:
Admin_RC, Constant Field Values

RC_Fail

public static final int RC_Fail
Return code used when the request fails.

See Also:
Admin_RC, Admin_Errors, Constant Field Values

RC_Mixed

public static final int RC_Mixed
Return code used when the request is partially successul. A mixed return code could result if for example a request is made to update four attributes of a queue and three succeed and one fails.

See Also:
Admin_RC, Admin_Errors, Constant Field Values

Admin_Reason

public static final java.lang.String Admin_Reason
Name of the field that contains the overall reason for any failure.

If an action failed with either RC_Mixed or RC_Fail then a reply message will provide a reason for the failure. If several failures occured, for instance a 2 attributes of a resource were in error then more detailed information can be found in field Admin_Errors. The field typically contains a toString() of the exception that caused the failure. If the exception is of type MQeException the string includes the MQeException code at the start of the string as "Code=nnn;"
Field type unicode
Set in request message no

See Also:
Admin_RC, Admin_Errors, Constant Field Values

Admin_Errors

public static final java.lang.String Admin_Errors
The name of a field that contains detailed error information.

The MQeFields object contains any errors related to subproblems that occur when a request fails with a return code of RC_Fail or RC_Mixed. For each attribuute in error there will be a corresponding field in this MQeFields object.If the field that was processed was an array then the corresponding error field will be of type ascii array. If the field that was processed was not an array then the corresponding error field will be of type ascii. For example if an update request was made to change 4 attributes of a resource and 2 of the updates were successful and 2 failed, this field would contain information detailing the reason for the 2 failures.

Each error is typically a toString() representation of the exception that caused the failure. If the exception is of type MQeException the string includes the MQeException code at the start of the string as "Code=nnn;"
Field type MQeFields
Set in request message no

See Also:
Admin_RC, Admin_Reason, Constant Field Values

Admin_MaxAttempts

public static final java.lang.String Admin_MaxAttempts
The name of the field that contains the maximum number of times a request is tried.

If a request fails then it can be retried. As an example if a request to delete a queue fails because there are messages on the queue then a retry may succeed.
Field type int
Set in request message optional

See Also:
Constant Field Values

Admin_Class

public static final java.lang.String Admin_Class
Name of the field that contains the type of the resource being managed.
Field type ascii
Set in request message no

See Also:
Constant Field Values
Constructor Detail

MQeAdminMsg

public MQeAdminMsg()
            throws java.lang.Exception
The constructor creates and initializes a default MQeAdminMsg.

Example:
 MQeAdminMsg  exMQeAdminMsg = (MQeAdminMsg) new MQeQueueManagerAdminMsg();
 
 
Method Detail

characteristics

public MQeFields characteristics()
                          throws java.lang.Exception
Return an MQeFields object containing the characteristics of the resource.

The complete set of field names and types for the resource can be determined from the resulting MQeFields object. (It does not contain the value of each characteristic)

Returns:
An MQeFields object containing the valid characteristics of the resource
Throws:
java.lang.Exception
Example:
 public void UseCharacteristics(MQeAdminMsg msg) throws Exception {
 
     MQeFields chars = msg.characteristics();
     Enumeration fields = chars.fields();
 
     while (fields.hasMoreElements()) {
         System.out.println("Contains field:" +
             (String) fields.nextElement());
     }
     }
 

create

public void create(MQeFields parms)
            throws java.lang.Exception

Sets up an administration message to run the Action_Create action.

Attempts to create a new resource with characteristics as specified in the parms parameter.

The Admin_Action and Admin_Parms fields are set by this method

Parameters:
parms - an MQeFields object containing name value pairs for any characteristics that require a setting different to that of the resources default setting. The name of the resource can be included in parms but can also be set with the setName(java.lang.String) method.
Throws:
java.lang.Exception
See Also:
Action_Create
Example:
 
 //Create ExampleQ
 MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
 msg.setName("ExampleQM");
 parms.putUnicode(MQeQueueAdminMsg.Queue_Description,
     "a new description ...");
 
 //Set the action required and its parameters into the message
 msg.create(parms);
 
 

delete

public void delete(MQeFields parms)
            throws java.lang.Exception

Sets up an administration message to run the Action_Delete action.

Attempts to delete a resource.

The Admin_Action and Admin_Parms fields are set by this method

Parameters:
parms - an MQeFields that must contain the name of the managed resource to delete if it has not been set with the setName(java.lang.String) method.
Throws:
java.lang.Exception
See Also:
Action_Create
Example:
 //Delete ExampleQ
 MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
 msg.setName("ExampleQM");
 msg.delete(parms);
 
 

duplicate

public MQeAdminMsg duplicate()
                      throws java.lang.Exception

Creates a duplicate administration message.

All fields are duplicated with the exception of fields that constitute the messages unique identifier.

Note:The MQeFields.copy(com.ibm.mqe.MQeFields, boolean) method is employed so only a shallow copy of the message is made.

Returns:
MQeAdminMsg a duplicate of this message.
Throws:
java.lang.ClassNotFoundException
java.lang.Exception
Example:
 //Create a message as the same type as this one
 MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 MQeQueueAdminMsg reply = (MQeQueueAdminMsg) requestMsg.duplicate();
 
 
 

getAction

public int getAction()

Returns the administration action that is to be, or has been performed.

Returns:
an int that is the value of field Admin_Action from the administration message or Action_Unknown if not set.
See Also:
Admin_Action
Example:
 int action = 0;
 
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     action = requestMsg.getAction();
     switch (action) {
     case 1: // Create
         // performCreate();
         break;
 
     case 2: // Delete
         // performDelete();
         break;
 
     default:;
         break;
     }
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getErrorFields

public MQeFields getErrorFields()

Returns a reference to the error fields object.

Returns:
the Admin_Errors MQeFields object from the administration message or an empty MQeFields object if the field does not exist.
See Also:
Admin_Errors
Example:
 MQeFields errs = null;
 
 try {
     MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     if (replyMsg.getRC() != 0) {
         errs = replyMsg.getErrorFields();
         Enumeration fields = errs.fields();
 
         while (fields.hasMoreElements()) {
             String errF = (String) fields.nextElement();
 
             System.out.println("Field:" +
                 errF +
                 "failed with error ");
         }
     }
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getFieldInError

public java.lang.String[] getFieldInError(java.lang.String fieldName)

Given the field name of a resource characteristic, return any error that occurred when processing the characteristic.

Checks the Admin_Errors field for any error information related to a named characteristic.

Parameters:
fieldName - the field name of the characteristic to check
Returns:
A string array containing any error that occurred when processing the named field or an empty array if the field was not in error.
See Also:
Admin_Errors
Example:
 String[] errs = null;
 
 try {
     MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     if (replyMsg.getRC() != 0) {
         fieldName = MQeQueueAdminMsg.Queue_Priority;
         errs = replyMsg.getFieldInError(fieldName);
         if (errs != null)
             System.out.println("Error setting priority" + errs[0]);
     }
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getInputFields

public MQeFields getInputFields()

Returns a reference to the input fields object.

The input fields object contains the input parameters required by an action. The input parameters for an action are stored in the Admin_Parms field of the administration message.

Returns:
the Admin_Parms MQeFields object from the administration message or an empty MQeFields object if the field does not exist.
See Also:
Admin_Parms, getOutputFields()
Example:
 MQeFields parms = null;
 
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     parms = requestMsg.getInputFields();
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getMaxAttempts

public int getMaxAttempts()

Get the maximum number of times the request should be tried.

Returns:
an int that is the value of field Admin_MaxAttempts from the administration message or a default of 1 if not set.
See Also:
Admin_MaxAttempts
Example:
 int tries = 0;
 
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     tries = requestMsg.getMaxAttempts();
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getName

public java.lang.String getName()

Get the name of the managed resource.

Returns:
a string that is the value of field Admin_Name from the administration message or null if not set.
See Also:
Admin_Name
Example:
 String name = " ";
 
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     name = requestMsg.getName();
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getOutputFields

public MQeFields getOutputFields()

Returns a reference to the output fields object.

The output fields object contains both the input parameters of a request together with the results of the request (not error details). The output parameters for an action are stored in the Admin_Parms field of the administration message.

Returns:
the Admin_Parms MQeFields object from the administration message or an empty MQeFields object if it does not exist.
See Also:
Admin_Parms
Example:
 MQeFields parms = null;
 
 try {
     MQeQueueAdminMsg replyMsg = new MQeQueueAdminMsg();
 
     parms = replyMsg.getOutputFields();
     if (parms.contains(MQeQueueAdminMsg.Queue_Description)) {
         System.out.println("Queue description:" +
             parms.getUnicode(MQeQueueAdminMsg.Queue_Description));
     }
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getRC

public int getRC()
          throws java.lang.Exception

Returns the return code resulting from the action.

Returns:
an int that is the value of field Admin_RC from the administration message.
Throws:
java.lang.Exception
See Also:
Admin_RC
Example:
 String error = " ";
 int rc = 0;
 
 try {
     MQeAdminMsg ReplyMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     rc = ReplyMsg.getRC();
     if (rc != ReplyMsg.RC_Success)
         error = ReplyMsg.getReason();
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getReason

public java.lang.String getReason()

Returns the reason for failure if an error occurred.

Returns:
a String that is the value of field Admin_Reason from the administration message.
See Also:
Admin_Reason
Example:
 String error = " ";
 int rc = 0;
 
 try {
     MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     rc = replyMsg.getRC();
     if (rc != replyMsg.RC_Success)
         error = replyMsg.getReason();
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

getTargetQMgr

public java.lang.String getTargetQMgr()
                               throws java.lang.Exception

Returns the name of the queue manager where the request is to be processed.

Returns:
the name of the queue manager where the request is to be processed.
Throws:
MQeException -
  • Except_Type : "wrong field type"
  • Except_NotFound : Item +"not found"
java.lang.Exception
Example:
 String targetQMgr = " ";
 
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     targetQMgr = requestMsg.getTargetQMgr();
 } catch (Exception e) {
     System.out.println("Target queue manager not set");
 }
 
 

inquire

public void inquire(MQeFields parms)
             throws java.lang.Exception

Sets up the administration message to perform the Action_Inquire action.

When performed, the action will return the specified characteristics of an existing resource.

The Admin_Action and Admin_Parms fields are set by this method

Parameters:
parms - an MQeFields object containing one or more names of the characteristic(s) of the resource that is to be inquired on. The name of the resource can be included in parms but can also be set with the setName(java.lang.String) method.
Throws:
java.lang.Exception
See Also:
Action_Inquire
Example:
 //Request the value of description and max queue depth
 try {
     MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     parms = new MQeFields();
     parms.putUnicode(MQeQueueAdminMsg.Queue_Description, null);
     parms.putInt(MQeQueueAdminMsg.Queue_MaxQSize, 0);
 
     //set the name of the queue to inquire on
     msg.setName("ExampleQM");
 
     //Set the action required and its parameters into the message
     msg.inquire(parms);
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

inquireAll

public void inquireAll(MQeFields parms)
                throws java.lang.Exception

Sets up the administration message to perform the Action_InquireAll action.

When performed the action will return all the characteristics of an existing resource.

The Admin_Action and Admin_Parms fields are set by this method

Parameters:
parms - an MQeFields object containing the name of the resource to be inquired on. The name of the resource can be included in parms but can also be set with the setName(java.lang.String) method in which case parms can be set to null.
Throws:
java.lang.Exception
See Also:
Action_InquireAll
Example:
 try {
     MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     //set the name of the queue to inquire on
     msg.setName("ExampleQM");
 
     //Set the action required and its parameters into the message
     msg.inquireAll(new MQeFields());
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

setAction

public void setAction(int action)

Set the administration action to perform.

Sets the Admin_Action field in the administration message.

Parameters:
action - the action to perform
See Also:
Admin_Action
Example:
 try {
     MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     requestMsg.setAction(MQeAdminMsg.Action_Inquire);
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

setMaxAttempts

public void setMaxAttempts(int maxAttempts)
Set the maximum number of times the request should be attempted.

Sets the Admin_MaxAttempts field in the administration message

Parameters:
maxAttempts - the maximum number of times the request can be attempted.
See Also:
Admin_MaxAttempts

setName

public void setName(java.lang.String resourceName)
             throws java.lang.Exception

Set the name of the resource that the action is to be performed on.

Sets the Admin_Name field in the administration message

Parameters:
resourceName - Name of the resource
Throws:
java.lang.Exception
See Also:
Admin_Name
Example:
 
 MQeFields parms = new MQeFields();
 
 //Set the action required and its parameters into the message
 try {
     MQeAdminMsg msg = (MQeAdminMsg) new MQeConnectionAdminMsg();
 
     msg.inquireAll(parms);
     msg.setName("ExampleQM");
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

setTargetQMgr

public void setTargetQMgr(java.lang.String targetQMgr)
                   throws java.lang.Exception

Set the name of queue manager where the request is to be processed.

Sets the Admin_TargetQMgr field in the administration message

Parameters:
targetQMgr - the name of the queue manager that will process the request.
Throws:
java.lang.Exception
See Also:
Admin_TargetQMgr
Example:
 try {
     MQeQueueAdminMsg requestMsg = new MQeQueueAdminMsg();
 
     requestMsg.setTargetQMgr("ExampleQM");
     requestMsg.setName("ExampleQM");
     requestMsg.create(new MQeFields());
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

update

public void update(MQeFields parms)
            throws java.lang.Exception

Sets up an administration message to run the Action_Update action.

When the action is performed, an attempt is made to update the specified characteristics of a resource

The Admin_Action and Admin_Parms fields are set by this method

Parameters:
parms - an MQeFields object containing the set of fields that are to be updated. The name of the resource can be included in parms but can also be set with the setName(java.lang.String) method.
Throws:
java.lang.Exception
See Also:
Action_Update
Example:
 //Set name of resource to be managed
 try {
     MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg();
 
     msg.setName("ExampleQM");
 
     //Change the value of description
     parms = new MQeFields();
     parms.putUnicode(MQeQueueAdminMsg.Queue_Description, "Change description ...");
 
     //Set the action required and its parameters into the message
     msg.update(parms);
 } catch (Exception e) {
     System.err.println("Failure ! " + e.toString());
 }
 
 

Websphere MQ Everyplace