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 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

Terms of use | WebSphere software

(c) Copyright IBM Corporation 2004, 2005. All rights reserved.