When the application has finished with the administrator handle it should be destroyed using the mqeAdministrator_free call. This allows the system to free up any resources that are in use by the administrator. Once an administrator handle has been freed, it must not be used in any of the mqeAdministrator_* API calls - if the handle is used, the behavior is indeterminate, but is likely cause an access violation. If further administration actions are to be performed, the handle can be recreated with the mqeAdministrator_new call.
rc = mqeAdministrator_new(&exceptBlock, &hAdministrator, NULL); if(MQERETURN_OK == rc) { /* mqeAdministrator_QueueManager_create */ /* further mqeAdministrator calls */ /* ... */ rc = mqeAdministrator_free(hAdministrator, &exceptBlock); } hAdministrator = NULL;
When a handle has been freed, set it to NULL. If this handle is then reused accidentally, the API returns an error.
/* mqeQueueManager_new(...,&hQueueManager,...) */ /* ... */ rc = mqeAdministrator_new(&exceptBlock, &hAdministrator, hQueueManager); if(MQERETURN_OK == rc) { /* further mqeAdministrator calls */ /* ... */ rc = mqeAdministrator_free(hAdministrator, &exceptBlock); }
Return codes | Reason codes | Notes® |
---|---|---|
MQERETURN_ADMINISTRATION_ERROR | MQEREASON_INVALID_QMGR_NAME | Name has invalid character or is NULL |
MQEREASON_INVALID_QUEUE_NAME | Name has invalid character or is NULL | |
MQERETURN_INVALID_ARGUMENT | MQEREASON_API_NULL_POINTER | Pointer is NULL |
MQEREASON_WRONG_TYPE | Wrong type handle has been passed, for example, QueueManager hndl instead of MQeFields | |
MQERETURN_QUEUE_ERROR | MQEREASON_QMGR_QUEUE_EXISTS | Queue already Exists |
MQEREASON_QMGR_QUEUE_NOT_EMPTY | Queue is not empty | |
MQERETURN_QUEUE_MANAGER_ERROR | MQEREASON_UNKOWN_QUEUE | Queue does not exist |
MQEREASON_UNKOWN_QUEUE_MANAGER | Queue manager does not exist | |
MQERETURN_NOTHING_TO_DO | MQEREASON_DUPLICATE | Name already in use |
MQEREASON_NO_SUCH_QUEUE_ALIAS | The queue alias specified does not exist |