A C application uses an object handle to access an object. There are two kinds of object handle. One kind of object handle has a data type that is related to the type of the object, and the other kind is a generic object handle whose data type is not related to the type of the object.
When a C application calls a function to create an object, XMS stores the object internally and returns a handle for the object to the application. The application can then use the handle subsequently to access the object.
Every object handle has a data type, which is related to the type of the object. Table 1 shows the object handle data type for each type of object. Note that BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage, and Message objects all have handles with the same data type, xmsHMsg. For more information about how to use handles for messages, see The body of an XMS message.
Type of object | Object handle data type |
---|---|
Connection | xmsHConn |
ConnectionFactory | xmsHConnFact |
ConnectionMetaData | xmsHConnMetaData |
Destination | xmsHDest |
ErrorBlock | xmsHErrorBlock |
InitialContext | xmsHInitialContext |
Iterator | xmsHIterator |
Message, BytesMessage, MapMessage, ObjectMessage, StreamMessage, and TextMessage | xmsHMsg |
MessageConsumer | xmsHMsgConsumer |
MessageProducer | xmsHMsgProducer |
Property | xmsHProperty |
QueueBrowser | xmsHQueueBrowser |
Requestor | xmsHRequestor |
Session | xmsHSess |
Certain functions return a generic object handle, which is not related to the type of the object that they create. A generic object handle has data type xmsHObj.
If an application receives a generic object handle from one of these functions, the application can call the xmsGetHandleTypeId() function in the PropertyContext class to determine the object handle data type that is related to the type of the object. The application can then call any function to perform an operation on the object by casting, if necessary, the generic object handle to the data type required by the function.