MQeInitialize

Description
Initializes WebSphere MQ Everyplace for the application. If the initialization is successful, this API creates a handle to the session object for use in subsequent calls to the WebSphere MQ Everyplace subsystem. This handle must be specified on all subsequent message queuing calls issued by the application. The handle ceases to be valid when the MQeTerminate call is issued.

Syntax
#include <hmq.h> 
MQEHSESS MQeInitialize( MQECHAR * SessionName, MQEINT32 * pCompCode, 
                        MQEINT32 * pReason)

Parameters

MQECHAR * SessionName - input
This is the null terminated string name that identifies this application or a component of this application. Because this name is used to identify the session, any open session with the same name is closed and all resources associated with it are released. This allows the library to recover from applications that crash without calling the MQeTerminate API.

The SessionName must be:

  • At least one character long (a null or a zero length string is invalid)
  • Conform to the ASCII character set except ' { } [ ] # ( ) : ; , ' = '
There is no limit to the length of the name but you are recommended to keep it short, preferably less than 20 characters.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_WARNING, *pReason may have any of the following values:

MQE_WARN_SESSION_DELETED
A session with the same name was deleted. This could happen if a session was left open because the application that opened it crashed or exited without calling the MQeTerminate API.

If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_ARGUMENT
Invalid session name, too short or too long.

MQE_EXCEPT_ALLOCATION_FAILED
WebSphere MQ Everyplace library has too few session handles or system storage resources.

MQE_EXCEPT_QMGR_INVALID_QMGR_NAME
Local queue manager name is not set.

MQE_EXCEPT_QMGR_NOT_ACTIVE
PalmOS At least one of the three WebSphere MQ Everyplace resources, hmqLib.prc, hmqFields.prc or hmqIni.prc, is not installed on this device.

Return Value

MQEHSESS hSess
A session handle. If any error occurs during the initialization, then an MQEHANDLE_NULL is returned.

Example
#include <hmq.h>
MQEHSESS hSess;
MQEINT32  compcode;
MQEINT32  reason;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason);
if (hSess!=MQEHANDLE_NULL) {
   MQeTerminate(hSess, &compcode, &reason, );
}

See Also
MQeTerminate


© IBM Corporation 2002. All Rights Reserved