Data Types

Note that Message Queue data types designated as handles map
to opaque structures (objects). Please do not attempt to dereference these
handles to get to the underlying objects. Instead, use the functions provided
to access the referenced objects.

Table 4–1 Message Queue C-API
Data Type Summary

Message Queue Type

Description

ConstMQString

A constant MQString.

MQAckMode

An enum used to specify the acknowledgement mode
of a session. Possible values include the following:

A handle used to reference a Message Queue connection. You get this
handle when you call the MQCreateConnection() function.

MQConsumerHandle

A handle used to reference a Message Queue consumer. A consumer can
be durable, nondurable and synchronous, or asynchronous. You get this handle
when you call one of the functions used to create consumers. See Receiving Messages for more information.

A handle used to reference Message Queue properties. You use this handle
to define or read connection properties and message headers or message properties.
See Working With Properties for more information.

MQReceiveMode

An enum used to specify whether consumers are synchronous
or asynchronous. It can be one of the following:

A handle used to reference a Message Queue session. You get this handle
when you call the MQCreateSession() function.

MQStatus

A data type returned by nearly all functions defined in mqcrt.h.
See Error Handling for more information on
how you handle errors returned by Message Queue functions.

MQString

A null terminated UTF-8 encoded character string

MQType

An enum used to return the type of a single property;
possible values include the following:

MQ_INT8_TYPE

MQ_INT16_TYPE

MQ_INT32_TYPE

MQ_INT64_TYPE

MQ_FLOAT32_TYPE

MQ_FLOAT64_TYPE

MQ_STRING_TYPE

MQ_INVALID_TYPE

Connection Properties

When you create a connection using the MQCreateConnection function, you must pass a handle to an object of type MQPropertiesHandle. The following table lists and describes the key values that define
each property. The procedure that follows the table explains how you set the
properties referenced by this handle.

Table 4–2 Connection Properties

Key Name

Description

MQ_CONNECTION_TYPE_PROPERTY

An MQString specifying the transport protocol of
the connection service used by the client. Supported types are TCP or TLS (SSL). The TCP protocol underlies the jms service; the TLS protocol supports the ssljms service.

Default: TCP

MQ_ACK_TIMEOUT_PROPERTY

A 32-bit integer specifying the maximum time in milliseconds that the
client runtime will wait for any broker acknowledgement before returning an MQ_TIMEOUT_EXPIRED error. A value of 0 means there is no time-out.

Default: 0

MQ_BROKER_HOST_PROPERTY

An MQString specifying the broker host name to which
to connect.

If you set the property MQ_SSL_BROKER_IS_TRUSTED to false, the value
you specify for the property MQ_BROKER_HOST_PROPERTY must match the CN (common name) of the
broker’s certificate.

No default.

MQ_PING_INTERVAL_PROPERTY

A 32-bit integer specifying the interval (in seconds) that the connection
can remain idle before the client runtime tests the connection by pinging
the broker. (The exact amount of time it takes for the ping to detect connection
failure varies with the system’s TCP configuration.)

A ping interval that is <= 0 turns off the ping for the connection.
The minimum allowable interval is 1 second. This prevents an application from
setting the interval to a value that would affect performance.

The ping interval is logged at the INFO level by the C client runtime
when a connection is created.

Default: 30 seconds

MQ_BROKER_PORT_PROPERTY

A 32-bit integer specifying the number of the port for the broker's
port mapper service.

No default.

MQ_BROKER_SERVICE_PORT_PROPERTY

A 32–bit integer that specifies the number of a port to which
the client connects. This is a static, fixed port assignment; it bypasses
the broker's port mapper service. If you do need to connect to a fixed port
on the broker, make sure that the service needed is enabled and available
at the specified port by setting the imq.serviceName.protocolType.port broker
property.

MQ_ACK_ON_PRODUCE_PROPERTY

An MQBool specifying whether the producing client
waits for broker acknowledgement of receipt of message from the producing
client.

If set to MQ_TRUE, the broker acknowledges receipt
of all messages (persistent and non-persistent) from the producing client,
and the producing client thread will block waiting for those acknowledgements.

If set to MQ_FALSE, broker does not acknowledge receipt
of any message (persistent or non-persistent) from the producing client, and
the producing client thread will not block waiting for broker acknowledgements.

Default: the broker acknowledges
receipt of persistent messages only from the producing
client, and the producing client thread will block waiting for those acknowledgements.

MQ_ACK_ON_ACKNOWLEDGE_PROPERTY

An MQBool specifying whether the broker confirms
(acknowledges) consumer acknowledgements. A consumer acknowledgement can be
initiated either by the client’s session or by the consuming client,
depending on the session acknowledgement mode (see Acknowledge Modes). If the session’s acknowledgement mode is MQ_DUPS_OK_ACKNOWLEDGE, this flag has no effect.

If set to MQ_TRUE, the broker acknowledges all consuming
acknowledgements, and the consuming client thread blocks waiting for these
broker acknowledgements.

If set to MQ_FALSE, the broker does not acknowledge
any consuming client acknowledgements, and the consuming client thread will
not block waiting for such broker acknowledgements.

A 32-bit integer, greater than 0, specifying the number of Message Queue messages
in a metered batch. When this number of messages is delivered from the broker
to the client runtime, delivery is temporarily suspended, allowing any control
messages that had been held up to be delivered. Payload message delivery is
resumed upon notification by the client runtime, and continues until the count
is again reached.

Default: 100

MQ_CONNECTION_FLOW_LIMIT_ENBABLED_PROPERTY

An MQBool specifying whether the value MQ_CONNECTION_FLOW_LIMIT_PROPERTY is used to control message flow. Specify MQ_TRUE to
use the value and MQ_FALSE otherwise.

Default: MQ_FALSE

MQ_CONNECTION_FLOW_LIMIT_PROPERTY

A 32-bit integer, greater than 0, specifying the maximum number of unconsumed
messages the client runtime can hold for each connection. Note however, that
unless MQ_CONNECTION_FLOW_LIMIT_ENBABLED_PROPERTY is MQ_TRUE, this limit is not checked.

When the number of unconsumed messages held by the client runtime for
the connection exceeds the limit, message delivery stops. It is resumed (in
accordance with the flow metering governed by MQ_CONNECTION_FLOW_COUNT_PROPERTY) only when the number of unconsumed messages drops below the value
set with this property.

This limit prevents a consuming client that is taking a long time to
process messages from being overwhelmed with pending messages that might cause
it to run out of memory.

Default: 1000

MQ_SSL_BROKER_IS_TRUSTED

An MQ_Bool specifying whether the broker is trusted.

Default: MQ_TRUE

MQ_SSL_CHECK_BROKER_FINGERPRINT

An MQ_Bool. If it is set to MQ_TRUE and
if MQ_SSL_BROKER_IS_TRUSTED is MQ_FALSE,
the broker’s certificate fingerprint is compared with the MQ_SSL_BROKER_CERT_FINGERPRINT property value in case of certificate authorization failure. If
they match, the broker’s certificate is authorized for use in the SSL
connection.

Default: MQ_FALSE

MQ_SSL_BROKER_CERT_FINGERPRIN

An MQString specifying the MD5 hash, in hex format,
of the broker’s certificate.

Default: NULL

MQ_NAME_PROPERTY

An MQString that specifies the name of the Message Queue product.
This property is set by the runtime library. See MQGetMetaData for more information.

MQ_VERSION_PROPERTY

An MQInt32 that specifies the version of the Message Queue product.
This property is set by the runtime library. See MQGetMetaData for more information.

MQ_MAJOR_VERSION_PROPERTY

An MQInt32 that specifies the major version of the Message Queue product.
For example, if the version is 3.5.0.1, the major version would be 3.

This property is set by the runtime library. See MQGetMetaData for more information.

MQ_MINOR_VERSION_PROPERTY

An MQInt32 that specifies the minor version of the Message Queue product.
For example, if the version is 3.5.0.1, the minor version would be 5.

This property is set by the runtime library. See MQGetMetaData for more information.

MQ_MICRO_VERSION_PROPERTY

An MQInt32 that specifies the micro version of the Message Queue product.
For example, if the version is 3.5.0.1, the micro version would be 0.

This property is set by the runtime library. See MQGetMetaData for more information.

MQ_SERVICE_PACK_PROPERTY

An MQInt32 that specifies the service pack version
of the Message Queue product. For example, if the version is 3.5.0.1, the
service pack version would be 1.

This property is set by the runtime library. See MQGetMetaData for more information.

MQ_UPDATE_RELEASE_PROPERTY

An MQInt32 that specifies the update release version
of the Message Queue product. For example, if the version is 3.7 UR1, the
update release value would be 1.

This property is set by the runtime library. See MQGetMetaData for more information.

To Set Connection Properties

Call the MQCreateProperties function to get
a handle to a newly created properties object

Call a function to set one of the connection properties listed
in Table 4–2.

Which
function you call depends on the type of the property you want to set; for
example, to set an MQString property, you call the MQSetStringProperty function; to set a MQBool property, you call
the MQSetBoolProperty function; and so on. Each function
that sets a property requires that you pass a key name (constant) and value;
these are listed and described in Table 4–2.

When you have set all the properties you want to define for the
connection, you can then create the connection, by calling the MQCreateConnection function.

The runtime library sets the connection properties
that specify the name and version of the Message Queue product; you can retrieve
these using the MQGetMetaData function. These
properties are described at the end of Table 4–2, starting with MQ_NAME_PROPERTY.

Acknowledge Modes

The Message Queue runtime supports reliable delivery by using transacted
sessions or through acknowledgement options set at the session level. When
you use the MQCreateSession function to create
a session, you must specify an acknowledgement option for that session using
the acknowledgeMode parameter. The value of this parameter
is ignored for transacted sessions.

Table 4–3describes the effect
of the options you can set using the acknowledgeMode parameter.

Table 4–3 acknowledgeMode Values

Enum

Description

MQ_AUTO_ACKNOWLEDGE

The session automatically acknowledges each message consumed by the
client. This happens when one of the receive functions returns successfully,
or when the message listener processing the message returns successfully.

MQ_CLIENT_ACKNOWLEDGE

The client explicitly acknowledges all messages for the session that
have been consumed up to the point when the MQAcknowledgeMessages function
has been called. See the discussion of the function MQAcknowledgeMessages for additional information.

MQ_DUPS_OK_ACKNOWLEDGE

The session acknowledges after ten messages have been consumed and does
not guarantee that messages are delivered and consumed only once.

MQ_SESSION_TRANSACTED

This value is read only. It is set by the library if you have passed MQ_TRUE for the isTransacted parameter to the MQCreateSession function. It is returned to you by the MQGetAcknowledgeMode function if the session is transacted.

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:

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.

Do not try to close the session (or the connection to which
it belongs) and consumer handle in the message listener.

It is possible for a message listener to return an error;
however, this is considered a client programming error. If the listener discovers
that the message is badly formatted or if it cannot process it for some other
reason, it should handle the problem itself by re-directing it to an application-specific
bad-message destination and process it later.

If the message listener
does return an error, the client runtime will try to redeliver the message
once if the session’s acknowledge mode is either MQ_AUTO_ACKNOWLEDGE or MQ_DUPS_OK_ACKNOWLEDGE .

Parameters

The handle to the connection on which the connection exception
occurred. The client runtime sets this handle when it calls the connection
exception handler.

exception

An MQStatus for the connection exception
that occurred. The client runtime specifies this value when it calls the exception
handler.

You can pass this status result to any functions used to handle errors
to get an error code or error string. For more information, see Error Handling.

callbackData

Whatever void pointer was passed as the listenerCallbackData parameter to the functionMQCreateConnection for
more information.

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.

MQAcknowledgeMessages

The MQAcknowledgeMessages function acknowledges the
specified message and all messages received before it on the same session.
This function is valid only if the session is created with acknowledge mode
set to MQ_CLIENT_ACKNOWLEDGE .

Return Value

Parameters

sessionHandle

The handle to the session for the consumer that received the
specified message.

messageHandle

A handle to the message that you want to acknowledge. This
handle is passed back to you when you receive the message (either by calling
one of the receive functions or when a message is delivered to your message
listener function.)

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.

MQCloseConnection

Return Value

Parameters

connectionHandle

The handle to the connection that you want to close. This
handle is created and passed back to you by the function MQCreateConnection.

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.

Common Errors

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.)

Return Value

Parameters

The handle to the consumer you want to close. This handle
is created and passed back to you by one of the functions used to create consumers.

This handle is invalid after the function returns.

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.

Return Value

Parameters

sessionHandle

The handle to the transacted session that you want to commit.

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.

Return Value

Parameters

sessionHandle

The handle to the session to which this consumer belongs.
This handle is passed back by the MQCreateSession() function. For this asynchronous durable
consumer, the session must have been created with the MQ_SESSION_ASYNC_RECEIVE receive mode.

destinationHandle

A handle to a topic destination on which the consumer receives
messages. This handle remains valid after the call.

durableName

An MQString specifying a name for the durable
subscriber. The library makes a copy of the durableName string.

messageSelector

An expression (based on SQL92 conditional syntax) that specifies
the criteria upon which incoming messages should be selected for this consumer.

Specify a NULL or empty string to indicate that there
is no message selector for this consumer. In this case, all messages are delivered.

Specify MQ_TRUE to inhibit delivery of
messages published by this consumer’s own connection.

messageListener

The name of an MQMessageListenerFunc type
callback function that is to be called when this consumer receives a message
on the specified destination.

listenerCallbackData

A pointer to data that you want passed to your message listener
function when it is called by the library.

consumerHandle

Output parameter for the handle that references the consumer
for the specified destination.

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.

Return Value

Parameters

sessionHandle

The handle to the session to which this consumer belongs.
This handle is created and passed back to you by the MQCreateSession function. For this asynchronous consumer, the session must have been
created with the MQ_SESSION_ASYNC_RECEIVE receive mode.

destinationHandle

A handle to the destination on which the consumer receives
messages. This handle remains valid after the call returns.

messageSelector

An expression (based on SQL92 conditional syntax) that specifies
the criteria upon which incoming messages should be selected for this consumer.

Specify a NULL or empty string to indicate that there
is no message selector for this consumer. In this case, all messages will
be delivered.

Specify MQ_TRUE to inhibit delivery of
messages published by this consumer’s own connection.

The setting of this parameter applies only to topic destinations. It
is ignored for queues.

messageListener

The name of an MQMessageListenerFunc type
callback function that is to be called when this consumer receives a message
for the specified destination.

listenerCallbackData

A pointer to data that you want passed to your message listener
function when it is called by the library.

consumerHandle

Output parameter for the handle that references the consumer
for the specified destination.

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.

Return Value

Parameters

propertiesHandle

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.

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

The library makes a copy of the username string.

password

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

The library makes a copy of the password string.

clientID

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.

exceptionListener

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

listenerCallBackData

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.

connectionHandle

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.

Return Value

Parameters

The handle to the session with which you want to associate
this destination.

destinationName

An MQString specifying the logical name
of this destination. The library makes a copy of the destinationName string.
See discussion below.

Destination names starting with “mq” are reserved and should
not be used by clients.

destinationType

An enum specifying the destination type, either MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION.

destinationHandle

Output parameter for the handle to the newly created destination.
You can pass this handle to functions sending messages or to message producers
or consumers.

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.

Return Value

Parameters

sessionHandle

The handle to the session to which this consumer belongs.
This handle is passed back to you by the MQCreateSession() function. For
this (synchronous) durable consumer, the session must have been created with
the MQ_SESSION_SYNC_RECEIVE receive mode.

destinationHandle

A handle to a topic destination on which the consumer receives
messages. This handle remains valid after the call returns.

durableName

An MQString specifying the name of the
durable subscriber to the topic destination. The library makes a copy of the durableName string.

messageSelector

An expression (based on SQL92 conditional syntax) that specifies
the criteria upon which incoming messages should be selected for this consumer.

Specify a NULL or empty string to indicate that there
is no message selector for this consumer. In this case, the consumer receives
all messages. The library makes a copy of the messageSelector string.

Specify MQ_TRUE to inhibit delivery of
messages published by this consumer’s own connection.

consumerHandle

Output parameter for the handle that references the consumer
for the specified destination.

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.

MQCreateMessage

Return Value

Parameters

messageHandle

Output parameter for the handle that references the newly
created message.

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.

MQCreateMessageConsumer

The MQCreateMessageConsumer function creates a synchronous
message consumer for the specified destination.

Return Value

Parameters

sessionHandle

The handle to the session to which this consumer belongs.
This handle is passed back to you by the MQCreateSession() function. For
this (synchronous) consumer, the session must have been created with the MQ_SESSION_SYNC_RECEIVE receive mode.

destinationHandle

A handle to the destination on which the consumer receives
messages. This handle remains valid after the call returns.

messageSelector

An expression (based on SQL92 conditional syntax) that specifies
the criteria upon which incoming messages should be selected for this consumer.
Specify a NULL or empty string to indicate that there is
no message selector for this consumer and that all messages should be returned.

Specify MQ_TRUE to inhibit delivery of
messages published by this consumer’s own connection. This applies only
to topic destinations; it is ignored for queues.

consumerHandle

Output parameter for the handle that references the consumer
for the specified destination.

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.

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.

Common Errors

MQ_SESSION_CLOSED

MQCreateMessageProducerForDestination

The MQCreateMessageProducerForDestination function
creates a message producer with a specified destination.

Return Value

Parameters

A handle to the destination where you want this producer to
send all messages. This handle remains valid after the call returns.

producerHandle

Output parameter for the handle that references the producer.

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.

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.

Common Errors

MQ_SESSION_CLOSED
MQ_BROKER_CONNECTION_CLOSED

MQCreateProperties

The MQCreateProperties function creates a properties
handle and passes it back to the caller.

Return Value

Parameters

The handle to the connection to which this session belongs.
This handle is passed back to you by the MQCreateConnection() function.
You can create multiple sessions on a single connection.

isTransacted

An MQBool specifying whether this session
is transacted. Specify MQ_TRUE if the session is transacted.
In this case, the acknowledgeMode parameter is ignored.

acknowledgeMode

An enumeration of the possible kinds of acknowledgement modes
for the session. See Acknowledge Modes for
information on these values.

After you have created a session, you can determine its acknowledgement
mode by calling the MQGetAcknowledgeMode() function.

receiveMode

An enumeration specifying whether this session will do synchronous
or asynchronous message receives. Specify MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE.

If the session is only for producing messages, the receiveMode has
no significance. In that case, specify MQ_SESSION_SYNC_RECEIVE to
optimize the session’s resource use.

sessionHandle

A handle to this session. You will need to pass this handle
to the functions you use to manage the session and to create destinations,
consumers, and producers associated with this session.

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.

For a session that is not transacted, use the MQRecoverSession() function
to restart message delivery with the last unacknowledged message.

For a session that is transacted, use the MQRollBackSession() function
to roll back any messages that were delivered within this transaction. Use
the MQCommitSession() function
to commit all messages associated with this transaction.

For a session that has acknowledgeMode set
to MQ_CLIENT_ACKNOWLEDGE, use the function MQAcknowledgeMessages to acknowledge consumed messages.

Use the MQCloseSession() function to close a session and all its associated producers
and consumers. This function also frees memory allocated for the session.

MQCreateTemporaryDestination

The MQCreateTemporaryDestination function creates
a temporary destination and passes its handle back to you.

Return Value

Parameters

The handle to the session with which you want to associate
this destination.

destinationType

An enum specifying the destination type, either MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION.

destinationHandle

Output parameter for the handle to the newly created temporary
destination.

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.

Return Value

Parameters

The handle to the connection to which this session belongs.
This handle is passed back to you by the MQGetXAConnection function. You can create multiple sessions on a single connection.

receiveMode

An enumeration specifying whether this session will do synchronous
or asynchronous message receives. Specify MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE.

If the session is only for producing messages, the receiveMode has
no significance. In that case, specify MQ_SESSION_SYNC_RECEIVE to
optimize the session’s resource use.

beforeMessageListener

A callback function before asynchronous message delivery.

afterMessageListener

A callback function after asynchronous message delivery.

callbackData

A data pointer to be passed to the beforeDelivery and afterDelivery
functions.

sessionHandle

A handle to this session. You will need to pass this handle
to the functions you use to manage the session and to create destinations,
consumers, and producers associated with this session.

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:

An XA session is always XA transacted and the distributed
transaction is managed by a X/Open distributed transaction manager. MQCommitSession and MQRollbackSession should not be called on
a XA session.

Sending/receiving messages with an XA session must be done
in an XA transaction.

If receiveMode is MQ_SESSION_ASYNC_RECEIVE,
callback functions beforeMessageListener and afterMessageListener must be specified. beforeMessageListener will
be called by the C-API runtime before it calls the messageListener callback; afterMessageListener will be called by the C-API runtime after it
calls the messageListener callback.

The beforeMesageListener and afterMessageListener functions are provided
to the application to associate and disassociate the C-API runtime calling
thread with an XA transaction, to demarcate XA transactions, and to set appropriate
application association context to the calling thread if the application's
distributed transaction processing environment requires that.

The beforeMessageListener callback can return an error to the C-API
runtime, however like the MQMessageListenerFunc callback,
a well programmed application, should not return runtime error from afterMessageListener callback. On calling afterMessageListener callback,
the C-API runtime passes an errorCode to the callback to indicate whether
the processing of the message acknowledgement successful (see MQMessageListenerBAFunc type). The callbackData parameter will be passed
to the beforeMessageListener and afterMessageListener callback functions unchanged.

Return Value

Parameters

connectionHandle

A handle to the connection you want to free.

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.

Common Errors

MQ_STATUS_CONNECTION_NOT_CLOSED

MQFreeDestination

The MQFreeDestination function frees memory allocated
for the destination referenced by the specified handle.

Return Value

Parameters

A handle to a message that is passed to you when you receive
a message.

messageBytes

Output parameter that contains the start address of the bytes
that constitute the body of this bytes message.

messageBytesSize

Output parameter that contains the size of the message body
in bytes.

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.

MQGetConnectionProperties

The MQGetConnectionProperties function gets the connection
properties used to create the connection specified by s connectionHandle.

Return Value

Parameters

Output parameter for the destination name. The returned destinationName is a copy which the caller is responsible for freeing
by calling the MQFreeString() function

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.

MQGetDestinationType

The MQGetDestinationType passes back the type of
the specified destination.

Return Value

Parameters

destinationHandle

A handle to the destination whose type you want to know.

destinationType

Output parameter for the destination type; either MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION.

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.

MQGetErrorTrace

The MQGetErrorTrace function returns an MQString describing the error trace at the time when a function call failed
for the calling thread.

MQString MQGetErrorTrace ()

Having found that a Message Queue function has not returned successfully,
you can get an error trace when the error occurred by calling the MQGetErrorTrace function in the same thread that called the unsuccessful Message Queue function.

The MQGetErrorTrace function returns an MQString describing the error trace if it can determine this information.
The function will return a NULL string if there is no error
trace available.

Return Value

Parameters

messageHandle

The message handle.

headersHandle

Output parameter for the handle to the message header properties.

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

Key

Type

Set By

MQ_CORRELATION_ID_HEADER_PROPERTY

MQString

Client (optional)

MQ_MESSAGE_TYPE_HEADER_PROPERTY

MQString

Client (optional)

MQ_PERSISTENT_HEADER_PROPERTY

MQBool

Send function

MQ_EXPIRATION_HEADER_PROPERTY

MQInt64

Send function

MQ_PRIORITY_HEADER_PROPERTY

MQInt8

Send function

MQ_TIMESTAMP_HEADER_PROPERTY

MQInt64

Send function

MQ_MESSAGE_ID_HEADER_PROPERTY

MQString

Send function

MQ_REDELIVERED_HEADER_PROPERTY

MQBool

Message Broker

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

Return Value

Parameters

messageHandle

A handle to a message whose properties you want to get.

propertiesHandle

Output parameter for the handle to the message properties.

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.

Common Errors

MQ_NO_MESSAGE_PROPERTIES

MQGetMessageReplyTo

The MQGetMessageReplyTo function passes back the
destination where replies to this message should be sent.

Return Value

Parameters

A handle to a message expecting a reply. This is the handle
that is passed back to you when you receive the message.

destinationHandle

Output parameter for the handle to the reply destination.

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.()

Common Errors

MQ_NO_REPLY_TO_DESTINATION

MQGetMessageType

The MQGetMessageType function passes back information
about the type of a message: MQ_TEXT_MESSAGE, MQ_BYTES_MESSAGE , or MQ_MESSAGE.

Return Value

Parameters

messageHandle

A handle to a message whose type you want to determine.

messageType

Output parameter that contains the message type: MQ_TEXT_MESSAGE or MQ_BYTES_MESSAGE.

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.

MQGetMetaData

The MQGetMetaData function returns name and version
information for the current Message Queue service to which a client is connected.

Return Value

Parameters

connectionHandle

The handle to the connection that you want the information
about.

propertiesHandle

Output parameter that contains the properties handle.

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.

MQGetPropertyType

The MQGetPropertyType function returns the type of
the property value for a property key in the specified properties handle.

Common Errors

MQGetStatusCode

Parameters

status

The status returned by any Message Queue function that returns
an MQStatus.

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 Appendix A, 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:

MQGetStatusString

The MQGetStatusString function returns an MQString describing the specified status.

MQString MQGetStatusString(const MQStatus status);

Parameters

status

The status returned by any Message Queue function that returns
an MQStatus.

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.

MQGetStringProperty

The MQGetStringProperty function passes back the
value of the specified key for the specified MQString property.

Return Value

Parameters

messageHandle

A handle to an MQ_TEXT_MESSAGE message
that is passed to you when you receive a message.

messageText

The output parameter that points to the message text.

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.

MQGetXAConnection

The MQGetXAConnection function passes back a handle
to an XA connection. This should only be called when the Message Queue C-API
is used in a X/Open distributed transaction processing environment with Message Queue as
an XA-compliant resource manager.

Return Value

Parameters

An MQString specifying the path to the
directory that contains the certificate data base files.

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.

Common Errors

MQ_INCOMPATIBLE_LIBRARY
MQ_SSL_ALREADY_INITIALIZED
MQ_SSL_INIT_ERROR

MQPropertiesKeyIterationGetNext

The MQPropertiesKeyIterationGetNext function passes
back the address of the next property key in the referenced properties handle.

Return Value

Parameters

The handle to the message consumer. This handle is passed
back to you when you create a synchronous message consumer.

messageHandle

Output parameter for the handle to the message to be received.
You are responsible for freeing the message handle when you are done by calling
the MQFreeMessage() function.

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 MQAcknowledgeMessage()s.

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.

Return Value

Parameters

The handle to the message consumer. This handle is passed
back to you when you create a synchronous message consumer.

messageHandle

Output parameter for the handle to the message to be received.
You are responsible for freeing the message handle when you are done by calling
the MQFreeMessage() function.

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().

Return Value

Parameters

The handle to the message consumer. This handle is passed
back to you when you create a synchronous message consumer.

timeoutMilliseconds

The number of milliseconds to wait for a message to arrive.

messageHandle

Output parameter for the handle to the message to be received.
You are responsible for freeing the message handle when you are done by calling
the MQFreeMessage() function.

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.

Return Value

Parameters

sessionHandle

The handle to the session that you want to recover.

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:

Stop message delivery in this session.

Mark all messages that might have been delivered but not acknowledged
as redelivered.

Restart the delivery sequence including all unacknowledged
messages that had been previously delivered. (Redelivered messages might not
be delivered in their original delivery order.)

Return Value

Parameters

sessionHandle

The handle to the transacted session that you want to roll
back.

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.

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.

MQ_PERSISTENT_HEADER_PROPERTY will be set
to MQ_PERSISTENT_DELIVERY.

This means that
the calling thread will be blocked, waiting for the broker to acknowledge
receipt of your messages, unless you set the connection property MQ_ACK_ON_PRODUCE_PROPERTY to MQ_FALSE.

MQ_PRIORITY_HEADER_PROPERTY will be set
to 4.

MQ_EXPIRATION_HEADER_PROPERTY will be set
to 0, which means that the message will never expire.

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.

A integer value of 0 through 9; 0 being the lowest priority
and 9 the highest.

msgTimeToLive

An integer value specifying in milliseconds how long the message
will live before it expires. When a message is sent, its expiration time is
calculated as the sum of its time-to-live value and current GMT. A value of
0 indicates that he message will never expire.

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.

Property

Default value

msgDeliveryMode

MQ_PERSISTENT_DELIVERY

msgPriority

4

msgTimeToLive

0, meaning no expiration limit

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:

If you set the property to MQ_TRUE, the
broker acknowledges receipt of all messages (persistent and non-persistent)
from the producing client.

If you set the property to MQ_FALSE, the
broker does not acknowledge receipt of any message (persistent or non-persistent)
from the producing client.

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.

Return Value

Parameters

The handle to the producer sending this message. This handle
is passed back to you by the MQCreateMessageProducer() function.

messageHandle

A handle to the message you want to send.

destinationHandle

A handle to the destination where you want to send the message.

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.

MQ_PERSISTENT_HEADER_PROPERTY will be set
to MQ_PERSISTENT_DELIVERY.

This means that
the caller will be blocked, waiting for broker acknowledgement for the receipt
of your messages unless you set the connection property MQ_ACK_ON_PRODUCE_PROPERTY to MQ_FALSE.

MQ_PRIORITY_HEADER_PROPERTY will be set
to 4.

MQ_EXPIRATION_HEADER_PROPERTY will be set
to 0, which means that the message will never expire.

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.

Return Value

Parameters

The handle to the producer sending this message. This handle
is passed back to you when you call the MQCreateMessageProducer() function.

messageHandle

A handle to the message you want to send.

destinationHandle

A handle to the destination where you want to send the message.

msgDeliveryMode

An enum of either MQ_PERSISTENT_DELIVERY or MQ_NONPERSISTENT_DELIVERY.

msgPriority

A integer value of 0 through 9; 0 being the lowest priority
and 9 the highest.

msgTimeToLive

An integer value specifying in milliseconds how long the message
will live before it expires. When a message is sent, its expiration time is
calculated as the sum of its time-to-live value and current GMT. A value of
0 indicates that the message will never expire.

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:

Return Value

Parameters

messageHandle

A handle to a message.

headersHandle

A handle to the header properties object. This handle will
be invalid after the function returns.

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

Key

Type

Set By

MQ_CORRELATION_ID_HEADER_PROPERTY

MQString

Client (optional)

MQ_MESSAGE_TYPE_HEADER_PROPERTY

MQString

Client (optional)

MQ_PERSISTENT_HEADER_PROPERTY

MQBool

Send function

MQ_EXPIRATION_HEADER_PROPERTY

MQInt64

Send function

MQ_PRIORITY_HEADER_PROPERTY

MQInt8

Send function

MQ_TIMESTAMP_HEADER_PROPERTY

MQInt64

Send function

MQ_MESSAGE_ID_HEADER_PROPERTY

MQString

Send function

MQ_REDELIVERED_HEADER_PROPERTY

MQBool

Message Broker

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.

Common Errors

MQ_PROPERTY_WRONG_VALUE_TYPE

MQSetMessageProperties

The MQSetMessageProperties function sets the specified
properties for a message. You can also use this function to change a message's
properties.

Return Value

Parameters

A handle to a message whose application-defined properties
you want to set.

propertiesHandle

A handle to a properties object that you have created and
set using one of the set property functions. This handle is invalid after
the function returns.

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.

MQSetMessageReplyTo

The MQSetMessageReplyTo function specifies the destination
where replies to this message should be sent.

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.

MQSetStringProperty

The MQSetStringProperty function sets an MQString property with the specified key to the specified value.

Return Value

Parameters

messageHandle

A handle to a message whose text body you want to set.

messageText

An MQString specifying the message text.
The library makes a copy of the message text.

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.

MQStartConnection

The MQStartConnection function starts the specified
connection to the broker and starts or resumes message delivery.

Return Value

Parameters

connectionHandle

The handle to the connection that you want to start. This
handle is the handle that is created and passed back to you by the MQCreateConnection() function.

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.

Common Errors

MQStatusIsError

The MQStatusIsError function returns MQ_TRUE if
the status parameter passed to it represents an error.

MQBool MQStatusIsError(const MQStatus status);

Parameters

status

The status returned by any Message Queue function that returns
an MQStatus.

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.

Return Value

Parameters

connectionHandle

The handle to the connection that you want to stop. This handle
is passed back to you by the MQCreateConnection() function.

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.

Return Value

Parameters

The handle to the session to which this consumer belongs.
This handle is created and passed back to you by the MQCreateSession() function.

durableName

An MQString specifying the name of the
durable subscriber.

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.

Common Errors

MQ_CANNOT_UNSUBSCRIBE_ACTIVE_CONSUMER

MQ_CONSUMER_NOT_FOUND

Header Files

The Message Queue C-API is defined in the header files listed in Table 4–7. The files are listed in alphabetical
order. The file mqcrt.h includes all the Message Queue C-API
header files.

Enumeration of types that can be stored in a properties object, of types
of message that can be received, of acknowledgement modes, of delivery modes,
of destination types, of session receiving modes, and of handle types.