API conventions

Most functions take a handle and an exception block. The handle indicate the object that the function is operating on. The exception block is specific to a thread and provides the ability to communicate errors back to the caller. Some functions do not take a handle. These are Static functions that do not operate on an object. Examples are the Session and terminate and initialization functions (discussed in Session). Functions that create new object handles do not take a handle as an input parameter, instead they return a new handle

All functions return MQERETURN values to indicate success or failure. Data is returned using output parameters, typically indicated by pointers to object handles or by pointers to primitive types.

Function prototypes

Prototypes follow two basic forms:

For the construction of new objects
MQERETURN mqeObjectName_new(MQeExceptBlock *pErrStruct, 
                            MQeObjectHndl   *phNewObjectHndl,
                            .... <parameter>);

All other functions
MQERETURN mqeObjectName_functionName(MQeObjectHndl hObjectHndl, 
                                     MQeExceptBlock *pErrStruct, 
                                     ... <parameters>);

The handle of the object on which the function operates always comes first. With new functions, the exception block comes first as at that point there is no object to operate on.

For each new call there is a matching free call.

MQERETURN mqeObjectName_free
(MQeObjectHndl hObjectHndl, MQeExceptBlock  * pErrStruct);
 


© IBM Corporation 2000, 2003. All Rights Reserved