Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_AdminMsg.h File Reference

MQeAdminMsg object. More...


Functions

MQERETURN mqeAdminMsg_free (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct)
 Frees the MQeAdminMsgHndl pointed by phMsgObj.

MQERETURN mqeAdminMsg_create (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeFieldsHndl hParms)
 Setup an administration message to run the Create action.

MQERETURN mqeAdminMsg_characteristics (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeFieldsHndl *phField)
 Returns a fields object containing the characteristics of the resource.

MQERETURN mqeAdminMsg_delete (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeFieldsHndl hParms)
 Setup an administration message to run the MQE_ADMIN_ACTION_DELETE action.

MQERETURN mqeAdminMsg_duplicate (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeAdminMsgHndl *phDup)
 Create a duplicate of this message.

MQERETURN mqeAdminMsg_getAction (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQEINT32 *pAction)
 Return the administration action.

MQERETURN mqeAdminMsg_getErrorFields (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeFieldsHndl *phErrors)
 Return a reference to the error fields object.

MQERETURN mqeAdminMsg_getFieldInError (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeStringHndl *phErrors, MQEINT32 *pNumOfErrors, MQECONST MQeStringHndl hFieldName)
 Return error(s) for a named field.

MQERETURN mqeAdminMsg_getInputFields (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeFieldsHndl *phFields)
 Return a reference to the input fields parameters.

MQERETURN mqeAdminMsg_getMaxAttempts (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQEINT32 *pMaxAttempts)
 Gets the maximum number of retries.

MQERETURN mqeAdminMsg_getName (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeStringHndl *phName)
 Return the name of the managed resource.

MQERETURN mqeAdminMsg_getOutputFields (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeFieldsHndl *phFields)
 Return a reference to the output fields object.

MQERETURN mqeAdminMsg_getRC (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQEINT32 *pRC)
 Return the return code.

MQERETURN mqeAdminMsg_getReason (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeStringHndl *phReason)
 Return the reason for failure.

MQERETURN mqeAdminMsg_getTargetQMgr (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQeStringHndl *phName)
 Returns the queue manager where the result is to be processed.

MQERETURN mqeAdminMsg_inquire (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeFieldsHndl hParms)
 Setup an administration message to run the Inquire action.

MQERETURN mqeAdminMsg_inquireAll (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeFieldsHndl hParms)
 Setup an administration message to run the InquireAll action.

MQERETURN mqeAdminMsg_setAction (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQEINT32 action)
 Set the action to perform.

MQERETURN mqeAdminMsg_setName (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeStringHndl hName)
 Set the name of the resource to be managed.

MQERETURN mqeAdminMsg_setTargetQMgr (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeStringHndl hName)
 Set the target queue manager on which the request is to be processed.

MQERETURN mqeAdminMsg_setMaxAttempts (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQEINT32 maxAttempts)
 Set the maximum attempts.

MQERETURN mqeAdminMsg_update (MQeAdminMsgHndl hMsgObj, MQeExceptBlock *pErrStruct, MQECONST MQeFieldsHndl hParms)
 Setup an administration message to run the Update action.


Detailed Description

An MQeAdminMsg is a specialization of MQeMessage. It provides helper functions to create messages that are used for administration. Further specializations of MQeAdminMsg are available for specific uses.

Note that there are no new methods here, but there is a free. This free can be called on any administration message to release the storage.

Administration messages come in 2 styles, requests and replies:

Requests contain:

Replies contain:

Function Documentation

MQERETURN mqeAdminMsg_free MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct
 

Parameters:
phMsgObj  [in] The MQeAdminMsgHndl to be freed
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_create MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeFieldsHndl    hParms
 

Sets up an administration message to run the MQE_ADMIN_ACTION_CREATE action Attempts to create a new managed resource with the characteristics specified in the hParams parameters.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for the object to be acted on
hParms  [in] MQeFields with the resource characteristics
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Any characteristics that are different to the their default value should be included. The resource name can also be specified in the hParms or it can be set with the putName method.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_characteristics MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeFieldsHndl *    phField
 

Returns a fields object containing the characteristics of the resource. The complete set of field names and types for the resource can be determined from the resulting fields object.

Parameters:
hMsgObj  [in] Handle for object to be acted on
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
phField  [out] MQeFields handle
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null)
phCharacteristics must point to an existing MQeFields handle. This handle does not need to have been created by calling mqeFields_new.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_delete MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeFieldsHndl    hParms
 

Attempts to delete a managed resource

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hParms  [in] MQeFields that must contain the name of the managed resource if the name has not been set with setName
Precondition:
hMsgObj must not be NULL
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_duplicate MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeAdminMsgHndl *    phDup
 

All MQSeries Everyplace fields are duplicated with the exception of fields that constitute the unique message ID. mqeFields_copy is employed which means that only a shallow copy of the message is made.

Parameters:
hMsgObj  [in] Handle for object to be acted on
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
phDup  [out] Handle for the duplication
Precondition:
hMsgObj must not be NULL
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null)
(*phDup) must point to an existing MQeAdminMsgHndl handle
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeMsg_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getAction MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQEINT32 *    pAction
 

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

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
pAction  [out] Pointer to the result variable
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*pAction) must point to an existing MQEINT32 variable.
Returns :
The action in (*pAction)
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_getErrorFields MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeFieldsHndl *    phErrors
 

Error fields contain any errors related to problems that occurred when processing the action. For instance suppose a request is made to update two characteristics and one succeeds and one fails. Error fields contain the details of the one that fails. The name of the field in error matches that in MQE_ADMIN_PARAMS.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phErrors  [out] Pointer to the result handle
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null)
(*phErrors) must point to an existing MQeFields pointer
Returns :
MQeFields object created and handle placed at (*phErrors)
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeFields_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getFieldInError MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeStringHndl *    phErrors,
MQEINT32 *    pNumOfErrors,
MQECONST MQeStringHndl    hFieldName
 

This method is used to obtain information on individual errors after a mqeAdminMsg_getRC return of MQE_ADMIN_RC_FAIL or MQE_ADMIN_RC_MIXED. Given a fields name return any error that occurred when processing the field.

If the field that was processed was an array then a corresponding string array, containing the same number of elements, is returned . If the field that was processed was not an array, the returned array only contain one element. If the field was not in error then null is returned.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure *
hMsgObj  [in] Handle for object to be acted on.
phErrors  [out] Pointer to an array of MQeString for error strings
pNumOfErrors  [out] Pointer to an MQEINT32 variable for the number of errors returned in phErrors
hFieldName  [in] Field name of interest
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*phErrors) must point to an existing MQeFields pointer.
Returns :
A String array containing any error that occurred when processing the named field.
 * ------------------------ ----------------- ------------------------------- -------------------------
 * initial (*pNumOfErrors)  initial phErrors  returned (*pNumOfErrors)        returned phErrors
 * ------------------------ ----------------- ------------------------------- -------------------------
 * 0                        any               size of (*phErrors) required    not defined
 * any                      NULL              ditto                           ditto
 * != 0                     != NULL           number of (*phErrors) elements  points to the results
 *                                            used                            
 * 
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeString_free() to free the object(s) returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getInputFields MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeFieldsHndl *    phFields
 

The input fields object contains the input parameters required for a specific action.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phFields  [out] Pointer to the result fields
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*phFields) must point to an existing MQeFields pointer.
Returns :
MQeFields object that contains the input parameters required for an action
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeFields_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getMaxAttempts MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQEINT32 *    pMaxAttempts
 

Get the maximum number of times the request should be retried if the request is not successfully transmitted at the time of the initial request.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for the object to be acted on
pMaxAttempts  [out] Pointer to the result variable
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*pMaxAttempts) must point to an existing MQEINT32 variable.
Returns :
Field MQE_ADMIN_MAXATTEMPTS from the MQeAdminMsg is returned. A default of one is returned if the filed is not set.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_getName MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeStringHndl *    phName
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phName  [out] Pointer to the MQeString result
Precondition:
hMsgObj must not be NULL.
pErrStruct ponts to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*phName) must point to an existing MQeString pointer.
Returns :
Field MQE_ADMIN_NAME from the MQeAdminMsg or a null MQeString if this field is not set
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeString_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getOutputFields MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeFieldsHndl *    phFields
 

OutputFields contains both the input parameters of a request and the results of the request.

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phFields  [out] Pointer to the result fields
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*phFields) must point to an existing MQeFields pointer.
Returns :
Fields object with results of the action
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeFields_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getRC MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQEINT32 *    pRC
 

Gets the code resulting from the action

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
pRC  [out] Pointer to the result variable
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information are returned if pErrStruct is null).
(*pRC) must point to an existing MQEINT32 variable.
Returns :
The return code, which is one of the following:
  • MQE_ADMIN_RC_SUCCESS
  • MQE_ADMIN_RC_FAIL
  • MQE_ADMIN_RC_MIXED
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_getReason MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeStringHndl *    phReason
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phReason  [out] Pointer to the result handle
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
(*phReason) must point to an existing MQeString pointer.
Returns :
A string describing the cause of the failure
Return values:
MQERETURN_OK  Completed Successfully
Warning:
Users are expected to use mqeString_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_getTargetQMgr MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQeStringHndl *    phName
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
phQueueMAnager  [out] Pointer to the MQeString in which to put the result
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
If pQMgr is NULL and/or the dereferenced pQMgrLen is <= 0, pQMgrLen is set to the buffer length required to return the target queue manager name.
Returns :
The queue manager where the request is to be processed
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_FOUND  Queue manager not set
MQERETURN_J_TYPE  Queue manager not set
Warning:
Users are expected to use mqeString_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeAdminMsg_inquire MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeFieldsHndl    hParms
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hParms  [in] MQeFields with names of characteristics to be inquired
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
phParms needs to contain the name of the resource to be inquired on if not already set and the names of the characteristics of the resource that are to be inquired on.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_inquireAll MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeFieldsHndl    hParms
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hParms  [in] MQeFields with names of characteristics of the managed object
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
phParms contains the name of the resource or null.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_setAction MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQEINT32    action
 

Applicable actions are:

  • MQE_ADMIN_ACTION_DELETE
  • MQE_ADMIN_ACTION_INQUIRE
  • MQE_ADMIN_ACTION_INQUIREALL
  • MQE_ADMIN_ACTION_UPDATE
  • MQE_ADMIN_ACTION_ADDALIAS
  • MQE_ADMIN_ACTION_REMOVEALIAS
  • MQE_ADMIN_ACTION_ADD_QMGR
  • MQE_ADMIN_ACTION_REMOVE_QMGR
Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
action  [in] Action to perform
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Action must indicate a known action.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_setName MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeStringHndl    hName
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hName  [in] Name of the resource
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
hName must indicate a name.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_setTargetQMgr MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeStringHndl    hName
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hName  [in] Name of the queue manager
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
hName must indicate a valid queue manager name.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_setMaxAttempts MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQEINT32    maxAttempts
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
maxAttempts  [in] Value o fmaxAttempts
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeAdminMsg_update MQeAdminMsgHndl    hMsgObj,
MQeExceptBlock   pErrStruct,
MQECONST MQeFieldsHndl    hParms
 

Sets up the administration message to perform the MQE_ADMIN_ACTION_UPDATE action. This action attempts to update the characteristics of a managed resources based on those in hParams

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure
hMsgObj  [in] Handle for object to be acted on
hParms  [in] MQeFields handle
Precondition:
hMsgObj must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
phParms needs to contain the name of the resource to update (if the name is not already set) together with any resource characteristics that are to be changed.
Return values:
MQERETURN_OK  Completed Successfully


Generated Thu Aug 11 23:41:18 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference