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 which 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.
Figure 11. Creating an Administrator Handle for a new Queue Manager
rc = mqeAdministrator_new(&exceptBlock, &hAdministrator, NULL); if(MQERETURN_OK == rc) { /* mqeAdministrator_QueueManager_create */ /* further mqeAdministrator calls */ /* ... */ rc = mqeAdministrator_free(hAdministrator, &exceptBlock); } hAdministrator = NULL;
We recommend that once a handle has been freed it is accidentally set to NULL. If this handle is then accidentally reused, the API returns an error.
Figure 12. Creating an Administrator Handle for an existing Queue Manager
/* mqeQueueManager_new(...,&hQueueManager,...) */ /* ... */ rc = mqeAdministrator_new(&exceptBlock, &hAdministrator, hQueueManager); if(MQERETURN_OK == rc) { /* further mqeAdministrator calls */ /* ... */ rc = mqeAdministrator_free(hAdministrator, &exceptBlock); }
Table 10. Common reason and return codes
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 |