System

The following APIs are used to interact with WebSphere MQ Everyplace:

MQeInitialize
Initiates a session with the WebSphere MQ Everyplace client library.

MQeTerminate
Terminates a session with the WebSphere MQ Everyplace client library.

MQeGetVersion
Gets the version number of current WebSphere MQ Everyplace software.

MQeConfigCreateQMgr
Initializes and creates a queue manager presence on the system.

MQeConfigDeleteQMgr
Terminates and removes the presence of a queue manager in the system.

MQeTraceCmd
Enables trace.

MQeTrace
Writes a trace string to default trace output.

General constraints

A queue manager name must:

A queue name must

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

MQeTerminate

Description
Terminates an application's session with the WebSphere MQ Everyplace subsystem.

Syntax
#include<hmq.h>
MQEVOID MQeTerminate( MQEHSESS hSess, 
				MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle returned by MQeInitialize

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.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEVOID
None

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

See Also
MQeInitialize

MQeGetVersion

Description
Get the version number of the WebSphere MQ Everyplace software running on the device.

Syntax
#include <hmq.h> 
MQEINT32 MQeGetVersion ( MQEINT32 * pCompCode, MQEINT32 * pReason);

Parameters

MQEINT32 * pCompCode- output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEINT32
Four ASCII character value representing the current version, such as '1.00'.

Example
#include <hmq.h>
MQEINT32  compcode;
MQEINT32  reason;
MQEINT32  version;
 
version = MQeGetVersion(&compcode, &reason);
 

MQeConfigCreateQMgr

Description
Initialize and create a queue manager on the device.

Syntax
#include <hmq.h>
MQEVOID MQeConfigCreateQMgr ( MQECHAR * pQMgrName, 
										MQEINT32 * pCompCode, 
                          	MQEINT32 * pReason);
 

Parameters

MQECHAR * pQMgrName - input
The name of the local queue manager to be created.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

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

MQE_EXCEPT_QMGR_ALREADY_EXISTS
An existing queue manager name is defined. Call MQeQMgrGetName to retrieve the current local queue manager name, then call MQeMQeConfigDeleteQMgr to delete the local queue manager, and then call this function again.

Return Value
None.

Example
#include <hmq.h>
MQEHSESS hSess;
MQEINT32  compcode, reason;
MQEINT16  len;
MQECHAR   name[128];
 
hSess     = MQeInitialize( "aSession", &compcode, &reason);
len       = MQeQMgrGetName( hSess, name, 128, 
									&compcode, &reason);
name[len] = '\0';
 
MQeConfigDeleteQMgr( name, &compcode, &reason);
 
MQeConfigCreateQMgr( "MyOwnQMgr", &compcode, &reason);
 
 

See Also

MQeConfigDeleteQMgr

Description
Terminate and remove the presence of WebSphere MQ Everyplace queue manager on the device.

Syntax
#include <hmq.h> 
MQEVOID MQeConfigDeleteQMgr ( MQECHAR * pQMgrName, 
									MQEINT32 * pCompCode, 
                        	MQEINT32 * pReason);

Parameters

MQECHAR * pQMgrName- input
Name of the local queue manager to be created.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

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

MQE_EXCEPT_QMGR_INVALID_QMGR_NAME
The queue manager name provided does not match the current WebSphere MQ Everyplace queue manager name.

Return Value
None.

Example
#include <hmq.h>
MQEHSESS hSess;
MQEINT32  compcode, reason;
MQEINT16  len;
MQECHAR   name[128];
 
hSess     = MQeInitialize( "aSession", &compcode, &reason, );
len       = MQeQMgrGetName( hSess, name, 128, 
										&compcode, &reason);
name[len] = '\0';
 
MQeConfigDeleteQMgr( name, &compcode, &reason, );
 
MQeConfigCreateQMgr( "MyOwnQMgr", &compcode, &reason, );
 
 

See Also

MQeTraceCmd

Description
Starts, stops and sets the option of the WebSphere MQ Everyplace runtime tracing facility. The destination of the trace output is platform dependent. On PalmOS, the trace is written to a standard MemoPad database and can be viewed by calling the MemoPad application.

Syntax
#include <hmq.h>
MQEVOID MQeTraceCmd ( MQEHSESS hSess, MQEINT32 Cmd, MQEINT32 Parm, 
                      MQEINT32 * pCompCode, MQEINT32 * pReason); 

Parameters

MQEHSESS hSess - input
This session handle returned by MQeInitialize.

MQEINT32 Cmd - input

MQE_TRACE_CMD_START
Starts the trace. Parm is ignore.

MQE_TRACE_CMD_STOP
Stops the trace. Parm is ignore

MQE_TRACE_CMD_SET_MASK
Set the trace mask bits specified in Parm

MQEINT32 Parm - input
If Cmd is MQE_TRACE_CMD_SET_MASK then this parameter is

MQE_TRACE_OPTION_APP_MSG
Write out an application trace string that starts with a character

MQE_TRACE_OPTION_APP_INFO
Write out an application trace string that starts with character 'I'

MQE_TRACE_OPTION_APP_WARNING
Write out an application trace string that starts with character 'W'

MQE_TRACE_OPTION_APP_ERROR
Write out an application trace string that starts with character 'E'

MQE_TRACE_OPTION_APP_DEBUG
Write out an application trace string that starts with character 'D'

MQE_TRACE_OPTION_APP_ALL
Write out all application trace strings

MQE_TRACE_OPTION_SYS_MSG
Write out a system trace string that starts with character '_'

MQE_TRACE_OPTION_SYS_INFO
Write out a system trace string that starts with character 'i'.

MQE_TRACE_OPTION_SYS_WARNING
Write out a system trace string that starts with character 'w'

MQE_TRACE_OPTION_SYS_ERROR
Write out a system trace string that starts with character 'e'

MQE_TRACE_OPTION_SYS_DEBUG
Write out a system trace string that starts with character 'd'

MQE_TRACE_OPTION_SYS_ALL
Write out all system trace strings.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

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

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAIL
The WebSphere MQ Everyplace library has too few resources.

Return Value
None.

Example
#include <hmq.h>
MQEHSESS hSess;
MQEINT32  compcode, reason;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason);
 
/* Start the trace */
MQeTraceCmd ( hSess, MQE_TRACE_CMD_START, 0, 
              &compcode, &reason );
MQeTraceCmd ( hSess, MQE_TRACE_CMD_SET_MASK, 
              MQE_TRACE_OPTION_SYS_ERROR | MQE_TRACE_OPTION_APP_MSG,
              &compcode, &reason);
 
MQeTrace( hSess, MQTS(" Starting MQe..."));
MQeTrace( hSess, MQTS("IThis is a information trace msg."));
 
/* Stop the trace */
MQeTraceCmd ( hSess, MQE_TRACE_CMD_STOP, 0, &compcode, &reason );
 
/* Terminate the MQe session */
MQeTerminate( hSess, &compcode, &reason);

See Also
MQeTrace

MQeTrace

Description
Writes a string to the WebSphere MQ Everyplace trace facility. The size of the string character MQETCHAR and the destination of the trace output is platform dependent. On PalmOS, the string character is a single byte and the trace is written to a standard MemoPad database and can be viewed by calling the MemoPad application. For code portability, it is recommended that the trace string be wrapped in an MQTS() macro.

Syntax
#include <hmq.h> 
MQEVOID MQeTrace ( MQEHSESS hSess, MQETCHAR * pTStr);

Parameters

MQEHSESS hSess - input
The session handle returned by MQeInitialize.

MQETCHAR pTStr - input
A null terminated trace string.

Return Value
None.

Example
#include <hmq.h>
MQHSESS hSess;
MQEINT32  compcode;
MQEINT32  reason;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason );
 
/* Start the trace */
MQeTraceCmd ( hSess, MQE_TRACE_CMD_START, 0, &compcode, &reason);
MQeTraceCmd ( hSess, MQE_TRACE_CMD_SET_MASK, 
              MQE_TRACE_OPTION_SYS_ERROR | MQE_TRACE_OPTION_APP_MSG, 
             &compcode, &reason );
 
MQeTrace( hSess, MQTS(" Starting MQe..."));
MQeTrace( hSess, MQTS("IThis is a information trace msg."));
 
/* Stop the trace */
MQeTraceCmd ( hSess, MQE_TRACE_CMD_STOP, 0, &compcode, &reason  );
 
/* Terminate the MQe session */
MQeTerminate( hSess, &compcode, &reason);
 

See Also
MQeTraceCmd



© IBM Corporation 2002. All Rights Reserved