Using handles

The WebSphere MQ Everyplace C API is object based, using handles to the objects as parameters. When an API function is called, you should always pass or receive a handle to an object. (There are a few exceptions but these are carefully noted in the WebSphere MQ Everyplace C Programming Reference.) The function called then acts on the object that is represented by the handle. The life cycle of the handles (and consequently the objects they represent) needs to be carefully managed. Functions are provided to create and free handles. Failure to free handles is equivalent to failure to free resources.

Handles are references to objects, and it is possible for handles to reference NULL objects. These handles should still be freed, as the handle itself uses resources (although these are minimal). A macro IS_NULL(pObjectHandle) is provided to determine if a handle points to a null object, as passing a handle to a null object into a API function can put the system into an unstable state.



© IBM Corporation 2000, 2003. All Rights Reserved