Freeing the administrator handle

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.

Figure 1. 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;

When a handle has been freed, set it to NULL. If this handle is then reused accidentally, the API returns an error.

Figure 2. 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 1. Common reason and return codes
Return codesReason codes Notes
MQERETURN_ADMINISTRATION_ERROR MQEREASON_INVALID_QMGR_NAMEName has invalid character or is NULL
 MQEREASON_INVALID_QUEUE_NAMEName has invalid character or is NULL
MQERETURN_INVALID_ARGUMENTMQEREASON_API_NULL_POINTERPointer is NULL
 MQEREASON_WRONG_TYPEWrong type handle has been passed, for example, QueueManager hndl instead of MQeFields
MQERETURN_QUEUE_ERROR MQEREASON_QMGR_QUEUE_EXISTSQueue already Exists
 MQEREASON_QMGR_QUEUE_NOT_EMPTY Queue is not empty
MQERETURN_QUEUE_MANAGER_ERROR MQEREASON_UNKOWN_QUEUEQueue does not exist
 MQEREASON_UNKOWN_QUEUE_MANAGER Queue manager does not exist
MQERETURN_NOTHING_TO_DOMQEREASON_DUPLICATEName already in use
 MQEREASON_NO_SUCH_QUEUE_ALIASThe queue alias specified does not exist

Parent topic: Configuring with the C administrator API