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