Handles and items

An application needs a mechanism for accessing MQe items such as the queue manager, fields, strings, and so on. Handles use MQe items. The handle points to an area of memory used to store the specific information for that instance of the item. Type information is held for each item. Therefore, you must take care to initialize the handle correctly.

To use a handle, you must initialize it. You can do this by calling the new function of the associated item to be used. For example, to create an MQeString, you must first call the mqeString_new() function and pass a pointer to MQeStringHndl to that function. The mqeString_new() function allocates memory for the internal structure and sets the required default values by MQeString. Once completed successfully, the function returns the handle, which can now be used in subsequent calls to MQeString functions.

Once an item has been finished with, it is important to call the free() function of the item with which the handle is associated. The free() functions release all the systems resources used by that item. Setting the handle to NULL introduces a memory leak to the application and the system may run out of resources. To avoid this, set the handle to NULL after it has been freed.
Note: We recommend that you do not attempt to free a handle more than once, as this can cause unpredictable results.

You must use handles only with their associated items. You must also initialize and free them in the correct manner. The only instances where the application is not responsible for initializing the handle is when a pointer to a handle is passed as an input parameter to an MQe API. In such instances, a fully initialized handle is returned to the application without the user having to invoke the relevant new() function. An example of this is mqeQueueManager_BrowseMessages(), which has a pointer to an MQeVectorHndl as an input parameter. However, in instances like this, the application is still responsible for freeing the handle.


Terms of use | WebSphere software

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