Sun GlassFish Message Queue 4.4 Developer's Guide for C Clients



A handle that specifies the properties that determine the behavior of this connection. You must create this handle using the MQCreateProperties function before you try to create a connection. This handle will be invalid after the function returns successfully.

See Table 4–2 for information about connection properties.


An MQString specifying the user name to use when connecting to the broker.

The library makes a copy of the username string.


An MQString specifying the password to use when connecting to the broker.

The library makes a copy of the password string.


An MQString used to identify the connection. If you use the connection for a durable consumer, you must specify a non-NULL client identifier.

The library makes a copy of the clientID string.


A connection-exception callback function used to notify the user that a connection exception has occurred.


A data pointer that can be passed to the connection exceptionListener callback function whenever it is called. The user can set this pointer to any data that may be useful to pass along to the connection exception listener for this connection. Set this to NULL if you do not need to pass data back to the connection exception listener.


Output parameter for the handle to the connection that is created by this function.

The MQCreateConnection function creates a connection to the broker. The behavior of the connection is specified by key values defined in the properties referenced by the propertiesHandle parameter. You must use the MQCreateProperties function to define these properties.

You cannot change the properties of a connection you have already created. If you need different connection properties, you must close and free the old connection and then create a new connection with the desired properties.

Setting a Client Identifier

To keep track of durable subscriptions, Message Queue uses a unique client identifier that associates a client’s connection with state information maintained by the message service on behalf of the client. By definition, a client identifier is unique, and applies to only one connection at a time.

The messaging service uses a client identifier in combination with a durable subscription name to uniquely identify each durable subscription. If a durable subscriber is inactive at the time that messages are delivered to a topic destination, the broker retains messages for that subscriber and delivers them when the subscriber once again becomes active.

Handling Connection Exceptions

Use the exceptionListener parameter to pass the name of a user-defined callback function that can be called synchronously when a connection exception occurs for this connection. Use the exceptionCallBackData parameter to specify any user data that you want to pass to the callback function.