The body of a message listener function is written by the receiving client. Mainly, the function needs to process the incoming message by examining its header, body, and properties. The client is also responsible for freeing the message handle (either from within the handler or from outside the handler) by calling MQFreeMessage.

In addition, you should observe the following guidelines when writing the message listener function:

Callback Type for Asynchronous Message Consumption in Distributed Transactions ^{^^^^^^^^^^^^^^^^^^^^^^^^^^}

MQMessageListenerBAFunc is the type of the callback functions of before/after MQMessageListenerFunc for asynchronous message receiving from a distributed transaction session.

The MQMessageListenerBAFunc type has the following definition:

The body of a connection exception listener function is written by the client. This function will only be called synchronously with respect to a single connection. If you install it as the connection exception listener for multiple connections, then it must be reentrant.

Do not try to close the session (or the connection to which it belongs) in the exception listener.

MQStatus. See the MQStatusIsError function for more information.

Whether you receive messages synchronously or asynchronously, you can call the MQAcknowledgeMessages function to acknowledge receipt of the specified message and of all messages that preceded it.

When you create a session you specify one of several acknowledge modes for that session; these are described in Table 4-3. If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge receipt of messages consumed in that session.

By default, the calling thread to the MQAcknowledgeMessages function will be blocked until the broker acknowledges receipt of the acknowledgment for the broker consumed. If, when you created the session’s connection, you specified the property MQ_ACK_ON_ACKNOWLEDGE_PROPERTY to be MQ_FALSE, the calling thread will not wait for the broker to acknowledge the acknowledgement.

MQ_SESSION_NOT_CLIENT_ACK_MODE
MQ_SESSION_NOT_CLIENT_ACK_MODE
MQ_MESSAGE_NOT_IN_SESSION
MQ_CONCURRENT_ACCESS
MQ_SESSION_CLOSED
MQ_BROKER_CLOSED

MQStatus. See the MQStatusIsError function for more information.

Closing the connection closes all sessions, producers, and consumers created from this connection. This also forces all threads associated with this connection that are blocking in the library to return.

Closing the connection does not actually release all the memory associated with the connection. After all the application threads associated with this connection (and its dependent sessions, producers, and consumers) have returned, you should call the MQFreeConnection function to release these resources. However, MQFreeConnection () does not release resources held by a message or a destination associated with this connection. You must free memory allocated for a message or a destination by explicitly calling the MQFreeMessage or the MQFreeDestination function.

MQ_CONCURRENT_DEADLOCK (If the function is called from an exception listener or a consumer’s message listener.)

MQ_ILLEGAL_CLOSE_XA_CONNECTION (If called to claose an XA connection.)

MQStatus. See the MQStatusIsError function for more information.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the functionMQCloseMessageConsumer.

If the consumer you want to close is a durable consumer and you want to close this consumer permanently, you should call the function MQUnsubscribeDurableMessageConsumer after closing the consumer in order to delete any state information maintained by the broker for this consumer.

MQStatus. See the MQStatusIsError function for more information.

Use the MQCloseMessageProducer function to close a producer without closing its associated session or connection.

MQ_PRODUCER_NOT_IN_SESSION

MQStatus. See the MQStatusIsError function for more information.

Closing a session closes the resources (producers and consumers) associated with that session and frees up the memory allocated for that session.

Calling this function does not release resources held by a message or a destination associated with this session. You must free memory allocated for a message or a destination by explicitly calling the MQFreeMessage or the MQFreeDestination function.

There is no need to close the producers or consumers of a closed session.

MQ_CONCURRENT_DEADLOCK

(If called from a consumer’s message listener in the session.)

MQStatus. See the MQStatusIsError function for more information.

A transacted session supports a series of transactions. Transactions organize a session’s input message stream and output message stream into a series of atomic units. A transaction’s input and output units consist of those messages that have been produced and consumed within the session’s current transaction. (Note that the receipt of a message cannot be part of the same transaction that produces the message.) When you call the MQCommitSession function, its atomic unit of input is acknowledged and its associated atomic unit of output is sent.

The completion of a session’s current transaction automatically begins the next transaction. The result is that a transacted session always has a current transaction within which its work is done. Use the MQRollBackSession () function to roll back a transaction.

MQStatus. See the MQStatusIsError function for more information.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncDurableMessageConsumer function. (You should create a connection, create a session, set up your asynchronous consumer, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped, will result in an MQ_CONCURRENT_ACCESS error.

The MQCreateAsyncDurableMessageConsumer function creates an asynchronous durable message consumer for the specified destination. You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous durable message consumer for a destination, call the function MQCreateDurableMessageConsumer.()

Durable consumers can only be used for topic destinations. If you are creating an asynchronous consumer for a queue destination or if you are not interested in messages that arrive to a topic while you are inactive, you might prefer to use the function MQCreateAsyncMessageConsumer.

The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by this durable subscriber or until they have expired. Sessions with durable subscribers must always provide the same client identifier. (See MQCreateConnection, clientID parameter.) In addition, each durable consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) the durable subscription when it is created.

A session’s consumers are automatically closed when you close the session or connection to which they belong. However, messages will be routed to the durable subscriber while it is inactive and delivered when the durable consumer is recreated. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function. If you want to close a durable consumer permanently, you should call the MQUnsubscribeDurableMessageConsumer after closing it to delete state information maintained by the Broker on behalf of the durable consumer.

MQStatus. See the MQStatusIsError function for more information.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncDurableMessageConsumer function. (You should create a connection, create a session, set up your asynchronous consumers, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped will result in an MQ_CONCURRENT_ACCESS error.

The MQCreateAsyncMessageConsumer function creates an asynchronous message consumer for the specified destination. You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous message consumer for a destination, use the MQCreateMessageConsumer function.

If this consumer is on a topic destination, it will only receive messages produced while the consumer is active. If you are interested in receiving messages published while this consumer is not active, you should create a consumer using the MQCreateAsyncDurableMessageConsumer function instead.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function.

MQStatus. See the MQStatusIsError function for more information.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncSharedDurableMessageConsumer function. (You should create a connection, create a session, set up your asynchronous consumer, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped, will result in an MQ_CONCURRENT_ACCESS error.

You can define parameters to filter messages. The session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous shared durable message consumer for a topic destination, call the function MQCreateSharedDurableMessageConsumer(). To create an unshared asynchronous durable message consumer, use the function MQCreateAsyncDurableMessageConsumer().

Durable consumers can only be used for topic destinations. If you are creating an asynchronous consumer for a queue destination, use MQCreateAsyncMessageConsumer. If you are not interested in messages that arrive to a topic while you are inactive, you might prefer to use the function MQCreateAsyncSharedMessageConsumer.

The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by a consumer on the durable subscription or until they have expired. A durable subscription continues to accumulate messages until it is deleted using the MQUnsubscribeDurableMessageConsumer function.

A shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. This means that multiple active (not closed) consumers on the subscription may exist at the same time. A shared durable subscription is identified by a name specified by the durableName parameter and by the client identifier (which may be unset, see the clientId parameter in MQCreateConnection).

A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set).

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Durable subscriptions and shared non-durable subscriptions have separate name spaces.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use MQCloseMessageConsumer function. To delete the durable subscription, use function MQUnsubscribeDurableMessageConsumer after all its consumers are closed.

MQStatus. See the MQStatusIsError function for more information.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncSharedMessageConsumer . (You should create a connection, create a session, set up your asynchronous consumers, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped will result in an MQ_CONCURRENT_ACCESS error.

You can define parameters to filter messages. The session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous shared message consumer for a topic destination, use the MQCreateSharedMessageConsumer() function.

A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function.

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a bytes message, you can use this handle to define its content with the MQSetBytesMessageBytesMQSetBytesMessageBytes function, to set its headers with the MQSetMessageHeaders function, and to set its properties with the MQSetMessageProperties function.

MQStatus. See the MQStatusIsError function for more information.

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.

This error can be returned if MQ_CONNECTION_TYPE_PROPERTY is SSL and you have not called the MQInitializeSSL function before creating this connection.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateDestination function creates a logical destination and passes a handle to it back to you. Note that the Message Queue administrator has to also create a physical destination on the broker, whose name and type is the same as the destination created here, in order for messaging to happen. For example, if you use this function to create a queue destination called myMailQDest, the administrator has to create a physical destination on the broker named myMailQDest.

If you are doing development, you can simplify this process by turning on the imq.autocreate.topic or imq.autocreate.queue properties for the broker. If you do this, the broker automatically creates a physical destination whenever a message consumer or message producer attempts to access a non-existent destination. The auto-created destination will have the same name as the logical destination name you specified using the MQCreateDestination function. By default, the broker has the properties imq.autocreate.topic and imq.autocreate.queue turned on.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateDurableMessageConsumer function creates a synchronous message consumer for the specified destination. A durable consumer receives all the messages published to a topic, including the ones published while the subscriber is inactive.

You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create an asynchronous durable message consumer for a destination, call the function MQCreateAsyncDurableMessageConsumer.

Durable consumers are for topic destinations. If you are creating a consumer for a queue destination or if you are not interested in messages that arrive to a topic while you are inactive, you should use the function MQCreateMessageConsumer.()

The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by this durable subscriber or until they have expired. Sessions with durable subscribers must always provide the same client identifier (see MQCreateConnection, clientID parameter). In addition, each durable consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) the durable subscription when it is created.

A session’s consumers are automatically closed when you close the session or connection to which they belong. However, messages will be routed to the durable subscriber while it is inactive and delivered when the durable consumer is recreated. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function. If you want to close a durable consumer permanently, you should call the MQUnsubscribeDurableMessageConsumer function after closing it to delete state information maintained by the broker on behalf of the durable consumer.

MQStatus. See the MQStatusIsError function for more information.

Use the MQCreateMessage function to create a message that has a header and, optionally, properties, but which does not have a body. Such messages might be used by applications to signal events, which could be specified using header fields or message properties. This could improve performance because the message does not have a body and therefore there is no body to parse.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateMessageConsumer() function creates a synchronous message consumer for the specified destination. You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create an asynchronous message consumer for a destination, use the MQCreateAsyncMessageConsumer function.

If the consumer is a topic destination, it can only receive messages that are published while it is active. To receive messages published while this consumer is not active, you should create a consumer using either the MQCreateDurableMessageConsumer function or the MQCreateAsyncDurableMessageConsumer function, depending on the receive mode you defined for the session.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer () function.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateMessageProducer function creates a message producer that does not have a specified destination. In this case, you will specify the destination when sending the message itself by using either the MQSendMessageToDestination function or the MQSendMessageToDestinationExt function.

Using the MQCreateMessageProducer function is appropriate when you want to use the same producer to send messages to a variety of destinations. If, on the other hand, you want to use one producer to send many messages to the same destination, you should use the MQCreateMessageProducerForDestination function instead.

A session’s producers are automatically closed when you close the session or connection to which they belong. To close a producer without closing the session or connection to which it belongs, use the MQCloseMessageProducer function.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateMessageProducerForDestination function creates a message producer with a specified destination. All messages sent out by this producer will go to that destination. Use the MQSendMessage function or the MQSendMessageExt function to send messages for a producer with a specified destination.

Use the MQCreateMessageProducer function when you want to use one producer to send messages to a variety of destinations.

A session’s producers are automatically closed when you close the session or connection to which they belong. To close a producer without closing the session or connection to which it belongs, use the MQCloseMessageProducer () function.

MQStatus. See the MQStatusIsError function for more information.

Use the MQCreateProperties function to get a properties handle. You can then use the appropriate MQSet...Property function to set the desired properties.

MQStatus. See the MQStatusIsError function for more information.

The MQCreateSession function creates a new session and passes back a handle to it in the sessionHandle parameter. The number of sessions you can create for a single connection is limited only by system resources. A session is a single-thread context for producing and consuming messages. You can create multiple producers and consumers for a session, but you are restricted to use them serially. In effect, only a single logical thread of control can use them.

A session with a registered message listener is dedicated to the thread of control that delivers messages to the listener. This means that if you want to send messages, for example, you must create another session with which to do this. The only operations you can perform on a session with a registered listener, is to close the session or the connection.

After you create a session, you can create the producers, consumers, and destinations that use the session context to do their work.

MQStatus. See the MQStatusIsError function for more information.

You can define parameters to filter messages. The session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create an asynchronous shared durable message consumer for a topic destination, call the function MQCreateSyncSharedDurableMessageConsumer(). To create an unshared synchronous durable message consumer, use the function MQCreateDurableMessageConsumer().

Durable consumers can only be used for topic destinations. If you are creating a synchronous consumer for a queue destination, use function MQCreateMessageConsumer. If you are not interested in messages that arrive to a topic while you are inactive, you might prefer to use the function MQCreateSharedMessageConsumer.

The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by a consumer on the durable subscription or until they have expired. A durable subscription continues to accumulate messages until it is deleted using the MQUnsubscribeDurableMessageConsumer function.

A shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. This means that multiple active (not closed) consumers on the subscription may exist at the same time. A shared durable subscription is identified by a name specified by the durableName parameter and by the client identifier (which may be unset, see the clientId parameter in MQCreateConnection).

A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set).

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Durable subscriptions and shared non-durable subscriptions have separate name spaces.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use MQCloseMessageConsumer function. To delete the durable subscription, use function MQUnsubscribeDurableMessageConsumer after all its consumers are closed.

MQStatus. See the MQStatusIsError function for more information.

You can define parameters to filter messages. The session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create an asynchronous shared message consumer for a topic destination, use the MQCreateAsyncSharedMessageConsumer function.

A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function.

MQStatus. See the MQStatusIsError function for more information.

You can use a temporary destination to implement a simple request/reply mechanism. When you pass the handle of a temporary destination to the MQSetMessageReplyTo function, the consumer of the message can use that handle as the destination to which it sends a reply.

Temporary destinations are explicitly created by client applications; they are deleted when the connection is closed. They are maintained (and named) by the broker only for the duration of the connection for which they are created. Temporary destinations are system-generated uniquely for their connection and only their own connection is allowed to create message consumers for them.

For more information, see "The Request-Reply Pattern" in Open Message Queue Technical Overview and "Managing a Broker ", "Configuring and Managing Connection Services" and "Managing Administered Objects" in Open Message Queue Administration Guide.

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a text message, you can use this handle to define its content with the MQSetBytesMessageBytesMQSetStringProperty function, to set its headers with the MQSetMessageHeaders function, and to set its properties with the MQSetMessageProperties function.

MQStatus. See the MQStatusIsError function for more information.

If receiveMode is MQ_SESSION_SYNC_RECEIVE, pass NULL for beforeMessageListener, afterMessageListener, and callbackData.

The MQCreateXASession function creates a new distributed transaction (XA) session. The connectionHandle must be a XA connection handle.

An XA session is the same as a regular session created by MQCreateSession (see MQCreateSession) except:

MQStatus. See the MQStatusIsError function for more information.

You must call this function after you have closed the connection with the MQCloseConnection() function and after all of the application threads associated with this connection and its dependent sessions, producers, and consumers have returned.

You must not call this function while an application thread is active in a library function associated with this connection or one of its dependent sessions, producers, consumers, and destinations.

Calling this function does not release resources held by a message or a destination associated with this connection. You must free memory allocated for a message or a destination by explicitly calling the MQFreeMessage or the MQFreeDestination function.

MQStatus. See the MQStatusIsError function for more information.

Calling the MQCloseConnection, MQCloseSession or MQFreeConnection function does not automatically free destinations created for the connection or for the session.

MQStatus. See the MQStatusIsError function for more information.

Calling the MQCloseCOnnection, MQCloseSession or MQFreeConnection function does not automatically free messages associated with that connection or session.

MQStatus. See the MQStatusIsError function for more information.

You should not free a properties handle if the properties handle passed to a function becomes invalid on its return. If you do, you will get an error.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

If you want to change the acknowledge mode, you need to create another session with the desired mode.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a message, you can use the MQGetMessageType function to determine its type and, if the type is MQ_BYTES_MESSAGE, you can use the MQGetBytesMessageBytes function to retrieve the message bytes (message body).

The bytes message passed to you by this function is not a copy. You should not modify the bytes or attempt to free it.

MQStatus. See the MQStatusIsError function for more information.

The caller is responsible to free the returned connection properties by calling MQFreeProperties.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

Use the MQGetDestinationName function to get the name of a destination. This might be useful for applications that want to do some message processing based on the destination name.

This function is useful when using the Reply-To pattern. You can use the MQGetMessageReplyTo function to obtain a handle to the destination where the message should be sent. You can then use the MQGetDestinationName to get the name of that destination.

MQStatus. See the MQStatusIsError function for more information.

Use the MQGetDestinationType function to determine the type of a destination: queue or topic. There may be times when you do not know the type of the destination to which you are replying: for example, when you get a handle from the MQGetMessageReplyTo function. Because the semantics of queue and topic destinations differ, you need to determine the type of a destination in order to reply appropriately.

Once you have created a destination with a specified type, you cannot change the type dynamically. If you want to change the type of a destination, you need to free the destination using the MQFreeDestination function and then to create a new destination, with the desired type, using the MQCreateDestination or the MQCreateTemporaryDestination function.

The MQGetFloat32Property function passes back the value of the MQFloat32 property for the specified key.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

The MQGetMessageHeaders function passes back a handle to the message headers. The message header includes the fields described in Table 4-5. Note that most of the fields are set by the send function; the client can optionally set only two of these fields for sending messages.

Table 4-5 Message Header Properties

You are responsible for freeing the headersHandle after you are done with it. Use the MQFreeProperties function to free the handle.

Use the MQSetBytesMessageBytes MQGetMessageProperties function to determine whether any application-defined properties were set for this message and to find out their value.

MQStatus. See the MQStatusIsError function for more information.

The MQGetMessageProperties function allows you to get application-defined properties for a message. Properties allow an application, via message selectors, to select or filter messages on its behalf using application-specific criteria. Having obtained the handle, you can either use one of the MQGet...Property functions to get a value (if you know the key name) or you can iterate through the properties using the MQPropertiesKeyIterationStart function.

You will need to call the function MQFreeProperties() to free the resources associated with this handle after you are done using it.

MQ_NO_MESSAGE_PROPERTIES

MQStatus. See the MQStatusIsError function for more information.

The sender uses the MQSetMessageReplyTo function to specify a destination where replies to the message can be sent. This can be a normal destination or a temporary destination. The receiving client can pass the message handle to the MQGetMessageReplyTo function and determine whether a destination for replies has been set up for the message by the sender and what that destination is. The consumer of the message can then use that handle as the destination to which it sends a reply.

You might need to call the MQGetDestinationType function to determine the type of the destination whose handle is returned to you: queue or topic so that you can set up your reply appropriately.

The advantage of setting up a temporary destination for replies is that Message Queue automatically creates a physical destination for you, rather than your having to have the administrator create one, when the broker’s auto.create.destination property is turned off.

You are responsible for freeing the destination handle by calling the function MQFreeDestination.()

MQ_NO_REPLY_TO_DESTINATION

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a message, you can determine the type of the message using the MQGetMessageType function. Having determined its type, you can use the MQGetTextMessageText function or the MQGetBytesMessageBytes function to obtain the message content.

Note that other message types might be added in the future. You should not design your code so that it only expects two possible message types.

MQStatus. See the MQStatusIsError function for more information.

The Message Queue product you are using is identified by a name and a version number. For example: "Sun Java(tm) System Message Queue 3.5.1." The version number consists of a major, minor, micro, and update release component. For example, the major part of version 3.5.1. is 3; the minor is 5; and the micro is 1. For release 3.7 UR1, the major part is 3; the minor is 7; and the update release is 1.

The name and version information of the Message Queue product are set by the library when you call the MQCreateConnection function to create the connection. You can retrieve this information by calling the MQGetMetaData function and passing a properties handle. Once the function returns and passes the handle back, you can use one of the MQGet...Properties functions to determine the value of a property (key). These properties are described in Table 4-2.

MQStatus. See the MQStatusIsError function for more information.

Use the appropriate MQGet...Property function to find the value of the specified property key.

MQ_NOT_FOUND

Having found that a Message Queue function has not returned successfully, you can determine the reason by passing the return status. This function will return the error code associated with the specified status. These codes are listed and described in Message Queue C API Error Codes.

Some functions might return an MQStatus that contains an NSPR or NSS library error code instead of a Message Queue error code when they fail. For NSPR and NSS library error codes, the MQGetStatusString function will return the symbolic name of the NSPR or NSS library error code. See NSPR and NSS public documentation for NSPR and NSS error code symbols and their interpretation at the following locations:

To obtain an MQString that describes the error, use the MQGetStatusString function. To get an error trace associated with the error, use the MQGetErrorTrace function.

Having found that a Message Queue function has not returned successfully, you can determine the reason why by passing the return status. This function will return an MQString describing the error associated with the specified status.

To obtain the error code for the specified status, use the MQGetStatusCode function. To get an error trace associated with the error, use the MQGetErrorTrace function.

You must call the MQFreeString function to free the MQString returned by the MQGetStatusString function when you are done.

MQStatus. See the MQStatusIsError function for more information.

You should not modify or attempt to free the value returned.

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a message, you can use the MQGetMessageType () function to determine its type and, if the type is text, you can use the MQGetTextMessageText() function to retrieve the message text.

The MQString passed to you by this function is not a copy. You should not modify the bytes or attempt to free it.

MQStatus. See the MQStatusIsError function for more information.

MQCloseConnection should not be called on an XA connection handle.

MQStatus. See the MQStatusIsError function for more information.

The Message Queue C-API library uses NSS to support the SSL transport protocol between the Message Queue C client and the Message Queue broker.

Before you connect to a broker over SSL, you must initialize the SSL library by calling the MQInitializeSSL function. If your client uses secure connections, you must call this function once and only once before you create any connection, even if that connection is not an SSL connection.

The certificateDatabasePath parameter specifies the path to the NSS certificate database where cert7.db or cert8.db , key3.db, and secmod.db files are located.

The work required to configure secure communication includes initializing the SSL library using the MQInitializeSSL function. There may be additional work, depending on whether the broker is trusted (the default setting) and on whether you want to provide an additional means of verification if the broker is not trusted and the initial attempt to create a secure connection fails. For complete information see Working With Secure Connections.

You must take care if the client application using secure Message Queue connections uses NSS (for other purposes) directly as well and does NSS initialization. For additional information, see Coordinating NSS Initialization.

MQStatus. See the MQStatusIsError function for more information.

To Get Message Properties

Follow this procedure:

MQBool

To Get Message Properties

Follow this procedure:

MQStatus. See the MQStatusIsError function for more information.

To Get Message Properties

Follow this procedure:

MQStatus. See the MQStatusIsError function for more information.

This function can only be called if the session is created with receive mode MQ_SESSION_SYNC_RECEIVE. The MQReceiveMessageNoWait function passes a handle back to you in the messageHandle parameter if there is a message arrived for the consumer specified by the consumerHandle parameter. If there is no message for the consumer, the function returns immediately with an error.

When you create a session, you specify one of several acknowledge modes for that session; these are described in Acknowledge Modes. If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge messages that you have received. For more information, see the description of the function MQAcknowledgeMessages.

Because distributed applications involve greater processing time, such an application might not behave as expected if it were run locally. For example, calling the MQReceiveMessageNoWait function might return MQ_NO_MESSAGE even when there is a message available to be retrieved.

If a client connects to the broker and immediately calls the MQReceiveMessageNoWait , it is possible that the message queued for the consuming client is in the process of being transmitted from the broker to the client. The client runtime has no knowledge of what is on the broker, so when it sees that there is no message available on the client’s internal queue, it returns with MQ_NO_MESSAGE .

You can avoid this problem by having your client use one of the synchronous receive methods that specifies a timeout interval.

You can use the MQReceiveMessageWait function if you want the receive function to block while waiting for a message to arrive. You can use the MQReceiveMessageWithTimeout function to wait for a specified time for a message to arrive.

MQStatus. See the MQStatusIsError function for more information.

This function can only be called if the session is created with receive mode MQ_SESSION_SYNC_RECEIVE. The MQReceiveMessageWait function passes a handle back to you in the messageHandle parameter if there is a message arrived for the consumer specified by the consumerHandle parameter. If there is no message for the consumer, the function blocks until a message is delivered.

When you create a session, you specify one of several acknowledge modes for that session; these are described in Acknowledge Modes. If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge messages that you have received. For more information, see the description of the function MQAcknowledgeMessages.

You can use the MQReceiveMessageNoWait function instead if you do not want to block while waiting for a message to arrive. You can use the function MQReceiveMessageWithTimeout to wait for a specified time for a message to arrive.

MQStatus. See the MQStatusIsError function for more information.

This function can only be called if the session is created with receive mode MQ_SESSION_SYNC_RECEIVE. The MQReceiveMessageWithTimeout function passes a handle back to you in the messageHandle parameter if a message arrives for the consumer specified by the consumerHandle parameter in the amount of time specified by the timoutMilliseconds parameter. If no message arrives within the specified amount of time, the function returns an error.

When you create a session, you specify one of several acknowledge modes for that session; these are described in Acknowledge Modes. If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge messages that you have received. For more information, see the description of the function MQAcknowledgeMessages.

You can use the MQReceiveMessageWait function to block while waiting for a message to arrive. You can use the MQReceiveMessageNoWait() function if you do not want to wait for the message to arrive.

MQStatus. See the MQStatusIsError function for more information.

You can only call this function for sessions that are not transacted. To rollback message delivery for a transacted session, use the MQRollBackSession () function. This function may be most useful if you use the MQ_CLIENT_ACKNOWELDGE mode.

All consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges all messages that have been delivered to the client.

Restarting a session causes it to take the following actions:

MQStatus. See the MQStatusIsError function for more information.

A transacted session groups messages into an atomic unit known as a transaction. As messages are produced or consumed within a transaction, the broker tracks the various sends and receives, completing these operations only when you call the MQCommitSession() function.

If a send or receive operation fails, you must use the MQRollBackSession function to roll back the entire transaction. This means that those messages that have been sent are destroyed and those messages that have been consumed are automatically recovered.

MQStatus. See the MQStatusIsError function for more information.

The MQSendMessage function sends the specified message on behalf of the specified producer to the destination associated with the message producer. If you use this function to send a message, the following message header fields are set to default values when the send completes.

If you set those message properties, they will be ignored when a message is sent. To send a message with these properties set to different values, you can use the MQSendMessageExt function to specify different values for these properties.

You cannot use this function with a producer that is created without a specified destination.

MQStatus. See the MQStatusIsError function for more information.

The MQSendMessageExt function sends the specified message on behalf of the specified producer to the destination associated with the message producer. Use this function if you want to change the default values for the message header properties as shown in the next table.

If you set these message headers using the MQSetMessageHeaders function before the send, they will be ignored when the message is sent. When the send completes, these message headers hold the values that are set by the send.

You cannot use this function with a producer that is created without a specified destination.

You can set the broker property MQ_ACK_ON_PRODUCE_PROPERTY to make sure that the message has reached its destination on the broker:

Note that "acknowledgement" in this case is not programmatic but internally implemented. That is, the client thread is blocked and does not return until the broker acknowledges messages it receives from the producing client.

MQStatus. See the MQStatusIsError function for more information.

The MQSendMessageToDestination function sends the specified message on behalf of the specified producer to the specified destination. If you use this function to send a message, the following message header fields are set as follows when the send completes.

To send a message with these properties set to different values, you must use the MQSendMessageToDestinationExt function, which allows you to set these three header properties.

If you set these message headers using the MQSetMessageHeaders function before the send, they will be ignored when the message is sent. When the send completes, these message headers hold the values that are set by the send.

You cannot use this function with a producer that is created with a specified destination.

MQStatus. See the MQStatusIsError function for more information.

The MQSendMessageToDestinationExt function sends the specified message on behalf of the specified producer to the specified destination. Use this function if you want to change the default values for the message header properties as shown below:

If these default values suit you, you can use the MQSendMessageToDestination function to send the message.

You cannot use this function with a producer that is created with a specified destination.

You can set the broker property MQ_ACK_ON_PRODUCE_PROPERTY to make sure that the message has reached its destination on the broker:

Note that "acknowledgement" in this case is not programmatic but internally implemented. That is, the client thread is blocked and does not return until the broker acknowledges messages it receives.

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a bytes message from MQCreateBytesMessage , you can use this handle to define its body with the MQSetBytesMessageBytes function, to set its application-defined properties with the MQSetMessageProperties function, and to set certain message headers with the MQSetMessageHeaders function.

MQStatus. See the MQStatusIsError function for more information.

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

MQ_HASH_VALUE_ALREADY_EXISTS

MQStatus. See the MQStatusIsError function for more information.

After you have created a properties handle and defined values for message header properties using one of the MQSet...Property functions, you can pass the handle to the MQSetMessageHeaders function to define the message header properties.

The message header properties are described in the table below. For sending messages, the client can only set two of these: the correlation ID property and the message type property. The client is not required to set these; they are provided for the client’s convenience. For example, the client can use the key MQ_MESSAGE_TYPE_HEADER_PROPERTY to sort incoming messages according to application-defined message types.

Table 4-6 Message Header Properties

Header properties that are not specified in the headersHandle are not affected. You cannot use this function to override header properties that are set by the broker or the send function. The header properties for persistence, expiration, and priority (MQSetMessageHeaders)() are set to default values if the user called the MQSendMessage() or MQSendMessageToDestination() function, or they are set to values the user specifies (in parameters) if the user called the MQSendMessageExt () or the MQSendMessageToDestinationExt() function.

Use the MQSetBytesMessageBytes() function or the MQSetTextMessageText() function to set the body of a message. Use the MQSetMessageProperties function to set the application-defined properties of a message that are not part of the header.

MQ_PROPERTY_WRONG_VALUE_TYPE

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a message, you can use this handle to define its body with the MQSetBytesMessageBytes() or MQSetTextMessageText() function, and to set its header properties with the MQSetMessageHeaders() function.

Property values are set prior to sending a message. The MQSetMessageProperties function allows you to set application-defined properties for a message. For example, application-defined properties allow an application, via message selectors, to select or filter, messages on its behalf using application-specific criteria.

You define the message properties and their values using the MQCreateProperties function to create a properties object, then you use one of the set property functions to define each key and value in it. See Working With Properties for more information.

MQStatus. See the MQStatusIsError function for more information.

The sender uses the MQSetMessageReply function to specify a destination where replies to the message can be sent. This can be a normal destination or a temporary destination. The receiver of a message can use the MQGetMessageReplyTo function to determine whether a sender has set up a destination where replies are to be sent. The advantage of setting up a temporary destination for replies is that Message Queue automatically creates a physical destination for you, rather than your having to have the administrator create one if the broker’s auto_create_destination property is turned off.

MQStatus. See the MQStatusIsError function for more information.

The library makes a copy of the property key and also makes a copy of the value.

MQStatus. See the MQStatusIsError function for more information.

After you obtain the handle to a text message, you can use this handle to define its body with the MQSetTextMessageText() function. You can set its application-defined properties with the MQSetMessageProperties function, and you can set certain message headers with the MQSetMessageHeaders function.

MQStatus. See the MQStatusIsError function for more information.

When a connection is created it is in stopped mode. Until you call this function, messages are not delivered to any consumers. Call this function to start a connection or to restart a connection that has been stopped with the MQStopConnection() function. To create an asynchronous consumer, you could have the connection in stopped mode, and start or restart the connection after you have set up the asynchronous message consumer.

Use the MQCloseConnection function to close a connection, and then use the MQFreeConnection function to free the memory allocated to the connection.

MQ_BROKER_CONNECTION_CLOSED

Nearly all Message Queue C library functions return an MQStatus. You can pass this status result to the MQStatusIsError function to determine whether your call succeeded. If the MQStatusIsError function returns MQ_TRUE(=1), the function failed; if it returns MQ_FALSE(=0), the function returned successfully.

If the MQStatusIsError returns MQ_TRUE, you can get more information about the error that occurred by passing the status returned to the MQGetStatusCode function. This function will return the error code associated with the specified status.

To obtain an MQString that describes the error, use the MQGetStatusString function. To get an error trace associated with the error, use the MQGetErrorTrace function.

MQStatus. See the MQStatusIsError function for more information.

You can restart message delivery by calling the MQStartConnection function. When the connection has stopped, delivery to all the connection’s message consumers is inhibited: synchronous receives block, and messages are not delivered to message listeners. This call blocks until receives and/or message listeners in progress have completed.

You should not call MQStopConnection in a message listener callback function.

Use the MQCloseConnection function to close a connection, and then use the MQFreeConnection function to free the memory allocated to the connection.

MQ_BROKER_CONNECTION_CLOSED
MQ_CONCURRENT_DEADLOCK

MQStatus. See the MQStatusIsError function for more information.

When you call the MQUnsubscribeDurableMessageConsumer function, the client runtime instructs the broker to delete the state information that the broker maintains for this consumer. If you try to delete a durable consumer while it has an active topic subscriber or while a received message has not been acknowledged in the session, you will get an error. You should only unsubscribe a durable message consumer after closing it.

MQ_CANNOT_UNSUBSCRIBE_ACTIVE_CONSUMER
MQ_CONSUMER_NOT_FOUND