Allocating and freeing a message object

Because a WebSphere MQ Everyplace message object is an MQeFields object, its construction is fundamentally the same. Both MQeFields and message objects are constructed by calling the MQeFieldsAlloc API. The Type parameter specifies whether an MQeFields or a message object is created. The MQeFieldsAlloc API returns a handle that is passed back in all fields API calls. Specifying a type of MQE_OBJECT_TYPE_MQE_FIELDS creates a fields object and specifying MQE_OBJECT_TYPE_MQE_MSGOBJECT creates a message object. Other types such as MQE_OBJECT_TYPE_MQE_ADMIN_MSG are also available (see the hmq.h file).

A message or MQeFields object that is no longer required should be destroyed to free resources back to the operating system. The MQeFieldsFree API is provided to destroy MQeFields based objects that were created with the MQeFieldsAlloc API. MQeFieldsFree takes the handle to the object (to be destroyed) as a parameter.

The following code fragment shows MQeFields objects being created and destroyed.

#include <hmq.h>
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds, hMsg;
 
hSess = MQeInitialize("MyAppsName", 
								&compcode	
								&reason);
hFlds = MQeFieldsAlloc( hSess, 
													MQE_OBJECT_TYPE_MQE_FIELDS, 
													&compcode	, 
													&reason);
hMsg  = MQeFieldsAlloc( hSess, 
										MQE_OBJECT_TYPE_MQE_MSGOBJECT, 
										&compcode, 
										&reason);
MQeFieldsFree(hSess, 
					hFlds, 
					&compcode, 
					&reason);
MQeFieldsFree(hSess, 
					hMsg , 
					&compcode, 
					&reason);
MQeTerminate (hSess, 
					&compcode, 
					&reason);

Note that it is the responsibility of the application to delete message objects that are returned from WebSphere MQ Everyplace even if the application did not create the message. For example, WebSphere MQ Everyplace returns a message object from an MQeQMgrGetMsg API call and this must be deleted by the application.

Note:
The 'C' API returns a reason code of MQE_EXCEPT_INVALID_HANDLE when a NULL or previously allocated handle is passed to an API. However, if an arbitrary handle is passed then the API behavior is not defined.
Note:
A previously allocated handle is one that the WebSphere MQ Everyplace API returned to the application but it has been deleted and is no longer valid. Examples are a Session Handle that has subsequently been deleted by MQeTerminate(), or an MQeFieldsHandle that has been deleted by MQeFieldsFree().


© IBM Corporation 2002. All Rights Reserved