8/9

# 4 Reference

This chapter provides reference documentation for the Message Queue C-API. It includes information about the following:

- Data Types describes the C declarations for data types used by Message Queue messaging

- Function Reference describes the C functions that implement Message Queue messaging

- Header Files describes the contents of the C-API header files

For information on building C-Message Queue programs, see Client Design Issues.

For information on how you use the C API to complete specific programming tasks, see Using the C API.

## Data Types

Data Types summarizes the data types defined by the Message Queue C API. The table lists data types in alphabetical order and provides cross references for types that require broader discussion.

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: `MQ_AUTO_ACKNOWLEDGE` `MQ_CLIENT_ACKNOWLEDGE` `MQ_DUPS_OK_ACKNOWLEDGE` `MQ_SESSION_TRANSACTED` See Acknowledge Modes for more information.
`MQBool` | A boolean that can assume one of two values:
    MQ_TRUE(=1)
    MQ_FALSE(=0).
`MQChar` | `char` type.
`MQConnectionHandle` | 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.
`MQDeliveryMode` | An `enum` used to specify whether a message is sent persistently: `MQ_NON_PERSISTENT_DELIVERY` `MQ_PERSISTENT_DELIVERY` You specify this value with the MQSendMessageExt function or the MQSendMessageToDestinationExt function.
`MQDestinationHandle` | A handle used to reference a Message Queue destination. You get this handle when you call the MQCreateDestination function or the MQCreateTemporaryDestination function.
`MQDestinationType` | An enum used to specify the type of a destination: `MQ_QUEUE_DESTINATION` `MQ_TOPIC_DESTINATION` You set the destination type using the MQCreateDestination function or the MQCreateTemporaryDestination function.
`MQError` | A 32-bit unsigned integer.
`MQConnectionExceptionListenerFunc` | The type of a callback function used for connection exception handling. For more information, see Callback Type for Connection Exception Handling.
`MQFloat32` | A 32-bit floating-point number.
    MQFloat64
| A 64-bit floating-point number.
`MQInt16` | A 16-bit signed integer.
`MQInt32` | A 32-bit signed integer.
`MQInt64` | A 64-bit signed integer.
`MQInt8` | An 8-bit signed integer.
`MQMessageHandle` | A handle used to reference a Message Queue message. You get this handle when you call the MQCreateBytesMessage function, or the MQCreateTextMessage function, or on receipt of a message.
`MQMessageListenerFunc` | The type of a callback function used for asynchronous message receipt. For more information, see Callback Type for Asynchronous Message Consumption.
`MQMessageType` | An `enum` passed back by the MQGetMessageType and used to specify the type of a message; possible values include the following: `MQ_TEXT_MESSAGE` `MQ_BYTES_MESSAGE` `MQ_MESSAGE` `MQ_UNSUPPORTED_MESSAGE`
`MQProducerHandle` | A handle used to reference a Message Queue producer. You get this handle when you call MQCreateMessageProducer or MQCreateMessageProducerForDestination.
`MQPropertiesHandle` | 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: `MQ_SESSION_SYNC_RECEIVE` `MQ_SESSION_ASYNC_RECEIVE` See MQCreateSession for more information.
`MQSessionHandle` | 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. Default: `MQ_TRUE` For more information, see the discussion for the MQAcknowledgeMessages function and Message Acknowledgement.
    MQ_CONNECTION_FLOW_COUNT_PROPERTY
| 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

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

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

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

### Callback Type for Asynchronous Message Consumption

When you call the MQCreateAsyncMessageConsumer function or the MQCreateAsyncDurableMessageConsumer function, you must pass the name of an `MQMessageListenerFunc` type callback function that is to be called when the consumer receives a message to the specified destination.

The `MQMessageListenerFunc` type has the following definition:

    MQError (* MQMessageListenerFunc)(
                    const MQSessionHandle  sessionHandle,
                    const MQConsumerHandle  consumerHandle,
                    MQMessageHandle  messageHandle
                    void * callbackData);

#### Parameters

`sessionHandle`

  The handle to the session to which this consumer belongs. The client runtime specifies this handle when it calls your message listener.

`consumerHandle`

  A handle to the consumer receiving the message. The client runtime specifies this handle when it calls your message listener.

`messageHandle`

  A handle to the incoming message. The client runtime specifies this handle when it calls your message listener.

`callbackData`

  The void pointer that you passed to the function MQCreateAsyncMessageConsumer or the function MQCreateAsyncDurableMessageConsumer.

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

### 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:

    MQError (* MQMessageListenerBAFunc)(
                    const MQSessionHandle  sessionHandle,
                    const MQConsumerHandle  consumerHandle,
                    MQMessageHandle  messageHandle
                    MQError  errorCode
                    void * callbackData);

#### Parameters

`sessionHandle`

  The handle to the session to which this consumer belongs. The client runtime specifies this handle when it calls your message listener.

`consumerHandle`

  A handle to the consumer receiving the message. The client runtime specifies this handle when it calls your message listener.

`messageHandle`

  A handle to the incoming message. The client runtime specifies this handle when it calls your message listener.

`errorCode`

  Client runtime processing status that is passed to the before/after callback functions.

`callbackData`

  The void pointer that is passed to the function MQCreateAsyncMessageConsumer.

Note:

What additional information is needed for his function type?

### Callback Type for Connection Exception Handling

The client runtime will call this function when a connection exception occurs.

The `MQConnectionExceptionListenerFunc` type has the following definition:

    Void (* MQConnectionExceptionListenerFunc)(
                    const MQConnectionHandle connectionHandle,
                    MQStatus exception,
                    void * callbackData);

#### Parameters

`connectionHandle`

  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.

## Function Reference

This section describes the C-API functions in alphabetical order. Function Reference lists the C-API functions.

Table 4-4 Message Queue C-API Function Summary

Function | Description
--- | ---
MQAcknowledgeMessages | Acknowledges the specified message and all messages received before it on the same session.
MQCloseConnection | Closes the specified connection.
MQCloseMessageConsumer | Closes the specified consumer.
MQCloseMessageProducer | Closes the specified message producer without closing its connection.
MQCloseSession | Closes the specified session.
MQCommitSession | Commits a transaction associated with the specified session.
MQCreateAsyncDurableMessageConsumer | Creates a durable asynchronous message consumer for the specified destination.
MQCreateAsyncMessageConsumer | Creates an asynchronous message consumer for the specified destination.
MQCreateBytesMessage | Creates an `MQ_BYTES_MESSAGE` message.
MQCreateConnection | Creates a connection to the broker.
MQCreateDestination | Creates a logical destination and passes a handle to it back to you.
MQCreateDurableMessageConsumer | Creates a durable synchronous message consumer for the specified destination.
MQCreateMessage | Creates an `MQ_MESSAGE` message.
MQCreateMessageConsumer | Creates a synchronous message consumer for the specified destination.
MQCreateMessageProducer | Creates a message producer with no default destination.
MQCreateMessageProducerForDestination | Creates a message producer with a default destination.
MQCreateProperties | Creates a properties handle.
MQCreateSession | Creates a session and passes back a handle to the session.
MQCreateTemporaryDestination | Creates a temporary destination and passes its handle back to you.
MQCreateTextMessage | Creates a text message.
MQCreateXASession | Creates a distributed transaction (XA) session.
MQFreeConnection | Releases memory assigned to the specified connection and to all resources associated with that connection.
MQFreeDestination | Releases memory assigned to the specified destination and to all resources associated with that destination.
MQFreeMessage | Releases memory assigned to the specified message.
MQFreeProperties | Releases the memory allocated to the referenced properties handle.
MQFreeString | Releases the memory allocated to the specified `MQString`.
MQGetAcknowledgeMode | Passes back the acknowledgement mode of the specified session.
MQGetBoolProperty | Passes back a property of type `MQBool`.
MQGetBytesMessageBytes | Passes back the address and size of a `MQ_BYTES_MESSAGE` message body.
MQGetConnectionProperties | Passes back a handle to the properties used in creating the connection associated with the specified connection handle.
MQGetDestinationName | Passes back the name of the physical destination to which the specified message has been sent.
MQGetDestinationType | Passes back the type of the specified destination.
MQGetErrorTrace | Returns a string describing the stack at the time the specified error occurred.
MQGetFloat32Property | Passes back the value of the `MQFloat32` property for the specified key.
MQGetFloat64Property | Passes back the value of the `MQFloat64` property for the specified key.
MQGetInt16Property | Passes back the value of the `MQInt16` property for the specified key.
MQGetInt32Property | Passes back the value of the `MQInt32` property for the specified key.
MQGetInt64Property | Passes back the value of the `MQInt64` property for the specified key.
MQGetInt8Property | Passes back the value of the `MQInt8` property for the specified key.
MQGetMessageHeaders | Passes back a handle to the header of the specified message.
MQGetMessageProperties | Passes back a handle to the properties for the specified message.
MQGetMessageReplyTo | Passes back the destination where replies to this message should be sent.
MQGetMessageType | Passes back the type of the specified message.
MQGetMetaData | Passes back Message Queue version information.
MQGetPropertyType | Passes back the type of the specified property key.
MQGetStatusCode | Returns the code for the specified `MQStatus` result.
MQGetStatusString | Returns a string description for the specified `MQStatus` result.
MQGetStringProperty | Passes back the value for the specified property. Type (in the function name) can be `String`, `Bool`, `Int8`, `Int16`, `Int32`, `Int64` , `Float32`, `Float64`.
MQGetTextMessageText | Passes back the contents of an `MQ_TEXT_MESSAGE` message.
MQGetXAConnection | Passes back the distributed transaction (XA) connection.
MQInitializeSSL | Initializes the SSL library. You must call this function before you create a connection that uses SSL.
MQPropertiesKeyIterationGetNext | Passes back the next property key in the properties handle.
MQPropertiesKeyIterationHasNext | Returns true if there is another property key in a properties object.
MQPropertiesKeyIterationStart | Starts iterating through a properties object.
MQReceiveMessageNoWait | Passes back a handle to a message delivered to the specified consumer.
MQReceiveMessageWait | Passes back a handle to a message delivered to the specified consumer when the message becomes available.
MQReceiveMessageWithTimeout | Passes back a handle to a message delivered to the specified consumer if a message is available within the specified amount of time.
MQRecoverSession | Stops message delivery and restarts message delivery with the oldest unacknowledged message.
MQRollBackSession | Rolls back a transaction associated with the specified session.
MQSendMessage | Sends a message for the specified producer.
MQSendMessageExt | Sends a message for the specified producer and allows you to set priority, time-to-live, and delivery mode.
MQSendMessageToDestination | Sends a message to the specified destination.
MQSendMessageToDestinationExt | Sends a message to the specified destination and allows you to set message header properties.
MQSetBoolProperty | Sets an `MQBool` property with the specified key to the specified value.
MQSetBytesMessageBytes | Sets the message body for the specified `MQ_BYTES_MESSAGE` message.
MQSetFloat32Property | Sets an `MQFloat` 32 property with the specified key to the specified value.
MQSetFloat64Property | Sets an `MQFloat` 64 property with the specified key to the specified value.
MQSetInt16Property | Sets an `MQInt16` property with the specified key to the specified value.
MQSetInt32Property | Sets an `MQInt` 32 property with the specified key to the specified value.
MQSetInt64Property | Sets an `MQInt64` property with the specified key to the specified value.
MQSetInt8Property | Sets an `MQInt8` property with the specified key to the specified value.
MQSetMessageHeaders | Sets the header part of the message.
MQSetMessageProperties | Sets the user-defined properties for the specified message.
MQSetMessageReplyTo | Specifies the destination where replies to this message should be sent.
MQSetStringProperty | Sets an `MQString` property with the specified key to the specified value.
MQSetStringProperty | Sets the message body for the specified `MQ_TEXT_MESSAGE` message.
MQSetTextMessageText | Defines the body for a text message.
MQStartConnection | Starts the specified connection to the broker and starts or resumes message delivery.
MQStatusIsError | Returns `MQ_TRUE` if the specified `MQStatus` result is an error.
MQStopConnection | Stops the specified connection to the broker. This stops the broker from delivering messages.
MQUnsubscribeDurableMessageConsumer | Unsubscribes the specified durable message consumer.

### 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` .

    MQAcknowledgeMessages  (const MQSessionHandle  sessionHandle,
                                  const MQMessageHandle messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

#### Common Errors

`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`

### MQCloseConnection

The `MQCloseConnection` function closes the connection to the broker.

    MQCloseConnection(MQConnectionHandle connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

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

### MQCloseMessageConsumer

The `MQCloseMessageConsumer` function closes the specified message consumer.

    MQCloseMessageConsumer(MQConsumerHandle consumerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`consumerHandle`

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

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.

#### Common Errors

    MQ_CONSUMER_NOT_IN_SESSION
    MQ_BROKER_CONNECTION_CLOSED

### MQCloseMessageProducer

The `MQCloseMessageProducer` function closes a message producer.

    MQCloseMessageProducer(MQProducerHandle producerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`producerHandle`

  A handle for this producer that was passed to you by the functionMQCreateMessageProducer or by the function MQCreateMessageProducerForDestination.

  This handle is invalid after the function returns successfully.

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

#### Common Errors

`MQ_PRODUCER_NOT_IN_SESSION`

### MQCloseSession

The `MQCloseSession` function closes the specified session.

    MQCloseSession(MQSessionHandle sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

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

  This handle is invalid after the function returns successfully.

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.

#### Common Errors

`MQ_CONCURRENT_DEADLOCK`

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

### MQCommitSession

The `MQCommitSession` function commits a transaction associated with the specified session.

    MQCommitSession(const MQSessionHandle sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

#### Common Errors

    MQ_NOT_TRANSACTED_SESSION
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_NOT_TRANSACTED_SESSION
    MQ_XA_SESSION_IN_PROGRESS

### MQCreateAsyncDurableMessageConsumer

The `MQCreateAsyncDurableMessageConsumer` function creates an asynchronous durable message consumer for the specified destination.

    MQCreateAsyncDurableMessageConsumer (
                   const MQSessionHandle sessionHandle,
                   const MQDestinationHandle destinationHandle,
                   ConstMQString durableName,
                   ConstMQString messageSelector,
                   MQBool noLocal,
                   MQMessageListenerFunc messageListener,
                   void * listenerCallbackData,
                   MQConsumerHandle * consumerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

  The library makes a copy of the `messageSelector` string.

  For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.

`noLocal`

  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.

#### Common Errors

    MQ_NOT_ASYNC_RECEIVE_MODE
    MQ_INVALID_MESSAGE_SELECTOR
    MQ_DESTINATION_CONSUMER_LIMIT_EXCEEDEED
    MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
    MQ_CONSUMER_NO_DURABLE_NAME
    MQ_QUEUE_CONSUMER_CANNOT_BE_DURABLE
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQCreateAsyncMessageConsumer

The `MQCreateAsyncMessageConsumer` function creates an asynchronous message consumer for the specified destination.

    MQCreateAsyncMessageConsumer
                  (const MQSessionHandle sessionHandle,
                   const MQDestinationHandle destinationHandle,
                   ConstMQString messageSelector,
                   MQBool noLocal,
                   MQMessageListenerFunc messageListener,
                   void * listenerCallBackData,
                   MQConsumerHandle * consumerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

  The library makes a copy of the `messageSelector` string.

  For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.

`noLocal`

  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.

#### Common Errors

    MQ_NOT_ASYNC_RECEIVE_MODE
    MQ_INVALID_MESSAGE_SELECTOR
    MQ_DESTINATION_CONSUMER_LIMIT_EXCEEDEED
    MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQCreateBytesMessage

The `MQCreatesBytesMessage` function creates a bytes message and passes a handle to it back to you.

    MQCreateBytesMessage(MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  Output parameter for the handle to the new, empty message.

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

### MQCreateConnection

The `MQCreateConnection` function creates a connection to the broker.

If you want to connect to the broker over SSL, you must call the MQInitializeSSL function to initialize the SSL library before you create the connection.

    MQCreateConnection
                 (MQPropertiesHandle propertiesHandle
                 ConstMQString username,
                 ConstMQString password,
                 ConstMQString clientID,
                 MQConnectionExceptionListenerFunc exceptionListener,
                 void * listenerCallBackData,
                 MQConnectionHandle * connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### 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 successfully.

  See Table 4-2 for information about connection properties.

`username`

  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.

- Use the MQStartConnection function to start or restart the connection. Use the MQStopConnection function to stop a connection.

- Use the MQGetMetaData function to get information about the name of the Message Queue product and its version.

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

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

#### Common Errors

    MQ_INCOMPATIBLE_LIBRARY
    MQ_CONNECTION_UNSUPPORTED_TRANSPORT
    MQ_COULD_NOT_CREATE_THREAD
    MQ_INVALID_CLIENT_ID
    MQ_CLIENT_ID_IN_USE
    MQ_COULD_NOT_CONNECT_TO_BROKER
    MQ_SSL_NOT_INITIALIZED

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

### MQCreateDestination

The `MQCreateDestination` function creates a a logical destination and passes a handle to it back to you.

    MQCreateDestination(const MQSessionHandle sessionHandle
                     ConstMQString destinationName,
                     MQDestinationType destinationType,
                     MQDestinationHandle * destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

  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.

#### Common Errors

    MQ_INVALID_DESTINATION_TYPE
    MQ_SESSION_CLOSED

### MQCreateDurableMessageConsumer

The `MQCreateDurableMessageConsumer` function creates a synchronous durable message consumer for the specified topic destination.

    MQCreateDurableMessageConsumer
              (const MQSessionHandle sessionHandle,
               const MQDestinationHandle destinationHandle,
               ConstMQString durableName,
               ConstMQString messageSelector,
               MQBool noLocal
               MQConsumerHandle * consumerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

  For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.

`noLocal`

  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.

#### Common Errors

    MQ_NOT_SYNC_RECEIVE_MODE
    MQ_INVALID_MESSAGE_SELECTOR
    MQ_DESTINATION_CONSUMER_LIMITE_EXCEEDEED
    MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
    MQ_CONSUMER_NO_DURABLE_NAME
    MQ_QUEUE_CONSUMER_CANNOT_BE_DURABLE
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQCreateMessage

The `MQCreateMessage` function creates a new message of type `MQ_MESSAGE`.

    MQCreateMessage
                      (MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQCreateMessageConsumer
                      (const MQSessionHandle sessionHandle,
                       const MQDestinationHandle destinationHandle,
                       ConstMQString messageSelector,
                       MQBool noLocal
                       MQConsumerHandle * consumerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

  The library makes a copy of the `messageSelector` string.

  For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.

`noLocal`

  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.

#### Common Errors

    MQ_NOT_SYNC_RECEIVE_MODE
    MQ_INVALID_MESSAGE_SELECTOR
    MQ_DESTINATION_CONSUMER_LIMIT_EXCEEDEED
    MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQCreateMessageProducer

The `MQCreateMessageProducer` function creates a message producer that does not have a specified destination.

    MQCreateMessageProducer(const MQSessionHandle sessionHandle,
     MQProducerHandle * producerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

  The handle to the session to which this producer should belong.

`producerHandle`

  Output parameter for the handle that references the producer.

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.

#### Common Errors

    MQ_SESSION_CLOSED

### MQCreateMessageProducerForDestination

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

    MQCreateMessageProducerForDestination
                        (const MQSessionHandle sessionHandle,
                         const MQDestinationHandle destinationHandle,
                         MQProducerHandle * producerHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

  The handle to the session to which this producer belongs.

`destinationHandle`

  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.

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.

#### Common Errors

    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQCreateProperties

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

    MQCreateProperties (MQPropertiesHandle * propertiesHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  Output parameter for the handle that references the newly created properties object.

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

### MQCreateSession

The `MQCreateSession` function creates a session, defines its behavior, and passes back a handle to the session.

    MQCreateSession(const MQConnectionHandle connectionHandle,
                     MQBool isTransacted,
                     MQAckMode acknowledgeMode,
                     MQReceiveMode receiveMode
                     MQSessionHandle * sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`connectionHandle`

  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.

    MQCreateTemporaryDestination(const MQSessionHandle sessionHandle
     MQDestinationType destinationType,
     MQDestinationHandle * destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

  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.

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

#### Common Errors

    MQ_INVALID_DESTINATION_TYPE
    MQ_SESSION_CLOSED

### MQCreateTextMessage

The `MQCreatesTextMessage` function creates a text message and passes a handle to it back to you.

    MQCreateTextMessage( MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  Output parameter for the handle to the new, empty message.

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

### MQCreateXASession

The `MQCreateXASession` function creates a distributed transaction (XA) session on an XA connection, defines its behavior, and passes back a handle to the session.

    MQCreateXASession(const MQConnectionHandle connectionHandle,
                     MQReceiveMode receiveMode
                     MQMessageListenerBAFunc     beforeMessageListener,
                     MQMessageListenerBAFunc     afterMessageListener,
                     void *                      callbackData,
                     MQSessionHandle * sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`connectionHandle`

  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 `beforeMessageListener` 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.

  During normal processing, the C-API runtime:

  1. Calls the `beforeMessageListener` function.

  2. Processes the message, calling the `messageListener` function.

  3. Calls the `afterMessageListener` function.

  However, errors can alter this processing sequence:

  - If the `beforeMessageListener` function returns an error (a value other than `MQ_OK`), the C-API runtime logs a warning message containing the error code and then stops processing the message. It does not call `messageListener` or `afterMessageListener`.

  - If the attempt to call `messageListener` fails, or if message acknowledgement fails, the C-API runtime passes the appropriate error code to `afterMessageListener`.

  - If the `messageListener` function returns an error, the C-API runtime logs a warning containing the error code and then passes the `MQ_CALLBACK_RUNTIME_ERROR` error to `afterMessageListener`, regardless of the actual error code returned.

  - If the `afterMessageListener` function returns an error, the C-API runtime logs a warning containing the error code.

  Even if an error occurs, the `callbackData` parameter is passed to the `beforeMessageListener` and `afterMessageListener` functions unchanged.

#### Common Errors

    MQ_NOT_XA_CONNECTION
    MQ_INVALID_RECEIVE_MODE
    MQ_BROKER_CONNECTION_CLOSED
    MQ_COULD_NOT_CREATE_THREAD

### MQFreeConnection

The `MQFreeConnection` function deallocates memory assigned to the specified connection and to all resources associated with that connection.

    MQFreeConnection(MQConnectionHandle connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQFreeDestination(MQDestinationHandle destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`destinationHandle`

  A handle to the destination you want to free.

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

### MQFreeMessage

The `MQFreeMessage` function frees memory allocated for the message referenced by the specified handle.

    MQFreeMessage(MQMessageHandle messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  A handle to the message you want to free.

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

### MQFreeProperties

The `MQFreeProperties` function frees the memory allocated to the referenced properties object.

    MQFreeProperties(MQPropertiesHandle propertiesHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object you want to free.

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.

### MQFreeString

The `MQFreeString` function frees the memory allocated for the specified `MQString`.

    MQFreeString(MQString statusString);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`statusString`

  An `MQString` returned by the `MQGetStatusString` function or by the `MQGetErrorTrace` function.

### MQGetAcknowledgeMode

The `MQGetAcknowledgeMode` function passes back the acknowledgement mode of the specified session.

    MQGetAcknowledgemode(const MQSessionHandle sessionHandle
                               MQAckMode * ackMode);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`sessionHandle`

  The handle to the session whose acknowledgement mode you want to determine.

`ackMode`

  Output parameter for the `ackMode`. The `ackMode` returned can be one of four enumeration values. See Acknowledge Modes for information about these values.

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

### MQGetBoolProperty

The `MQGetBoolProperty` function passes back the value of the `MQBool` property for the specified key.

    MQGetBoolProperty(const MQPropertiesHandle propertiesHandle,
                            ConstMQString key,
                            MQBool * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the specified key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetBytesMessageBytes

The `MQGetBytesMessageBytes` function passes back the address and size of a bytes message body.

    MQGetBytesMessageBytes(const MQMessageHandle messageHandle,
     const MQInt8 * messageBytes
     MQInt32 * messageBytesSize);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

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

    MQGetConnectionProperties (const MQConnectionHandle connectionHandle,
    MQPropertiesHandle * propertiesHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`connectionHandle`

  A handle to a connection.

`propertiesHandle`

  A handle to the properties of the connection.

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

### MQGetDestinationName

The `MQGetDestinatioName` function passes back the name of the specified destination.

    MQGetDestinationName (const MQDestinationHandle destinationHandle,
                                 MQString * destinationName);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`destinationHandle`

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

`destinationName`

  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.

    MQGetDestinationType (const MQDestinationHandle destinationHandle,
     MQDestinationType * destinationType);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

The following is an example of an error trace output.

    connect:../../../../src/share/cclient/io/TCPSocket.cpp:195:mq:-5981
    readBrokerPorts:../../../../src/share/cclient/client/PortMapper
                                                    Client.cpp:48:mq:-5981
    connect:../../../../../src/share/cclient/client/protocol/
                                        TCPProtocolHandler.cpp:111:mq:-5981
    connectToBroker:../../../../src/share/cclient/client/Connection.
                                                         cpp:412:mq:-5981
    openConnection:../../../../src/share/cclient/client/Connection.
                                                         cpp:227:mq:1900
    MQCreateConnectionExt:../../../../src/share/cclient/cshim/
                                            iMQConnectionShim.cpp:102:mq:1900

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

#### MQGetFloat32Property

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

    MQGetFloat32Property(const MQPropertiesHandle propertiesHandle,
                               ConstMQString key,
                               MQFloat32 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetFloat64Property

The `MQGetFloat64Property` function passes back the value of the `MQFloat64` property for the specified key.

    MQGetFloat64Property(const MQPropertiesHandle propertiesHandle,
     ConstMQString key,
     MQFloat64 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetInt16Property

The `MQGetInt16Property` function passes back the value of the `MQInt16` property for the specified key.

    MQGetInt16Property(const MQPropertiesHandle propertiesHandle,
                             ConstMQString key,
                             MQInt16 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the specified key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetInt32Property

The `MQGetInt32Property` function passes back the value of the `MQInt32` property for the specified key.

    MQGetInt32Property(const MQPropertiesHandle propertiesHandle,
                             ConstMQString key,
                             MQInt32 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetInt64Property

The `MQGetInt64Property` function passes back the value of the MQInt64 property for the specified key.

    MQGetint64Property (const MQPropertiesHandle propertiesHandle,
                              ConstMQString key,
                              MQInt64 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetInt8Property

The `MQGetInt8Property` function passes back the value of the `MQInt8` property for the specified key.

    MQGetInt8Property (const MQPropertiesHandle propertiesHandle,
                             ConstMQString key,
                             MQInt8 * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter for the property value.

#### Common Errors

    MQ_NOT_FOUND
    MQ_INVALID_TYPE_CONVERSION

### MQGetMessageHeaders

The `MQGetMessageHeaders` function passes back a handle to the message headers.

`MQGetMessageHeaders`

      (const MQMessageHandle messageHandle
       MQPropertiesHandle * headersHandle) ;

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

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

### MQGetMessageProperties

The `MQGetMessageProperties` function passes back the user-defined properties for a message.

    MQGetMessageProperties (const MQMessageHandle messageHandle,
                                  MQPropertiesHandle * propsHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQGetMessageReplyTo (const MQMessageHandle messageHandle,
                               MQDestinationHandle * destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

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

    MQGetMessageType(const MQMessageHandle messageHandle,
                           MQMessageType * messageType);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQGetMetaData (const MQConnectionHandle connectionHandle,
                         MQPropertiesHandle * propertiesHandle)

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQGetPropertyType (const MQPropertiesHandle  propertiesHandle,
                             ConstMQString key,
                             MQType * propertyType);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle that you want to access.

`key`

  The property key for which you want to get the type of the property value.

`propertyType`

  Output parameter for the type of the property value.

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

#### Common Errors

`MQ_NOT_FOUND`

### MQGetStatusCode

The `MQGetStatusCode` function returns the error code associated with specified status.

    MQError MQGetStatusCode(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 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:

- For NSPR error codes, see the "NSPR Error Handling" chapter at the following location: `http://www.mozilla.org/projects/nspr/reference/html/index.html`.

- For SSL and SEC error codes, see the "NSS and SSL Error Codes" chapter at the following location: `http://www.mozilla.org/projects/security/pki/nss/ref/ssl/`.

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.

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

    MQGetStringProperty(const MQPropertiesHandle propertiesHandle,
                              ConstMQString key,
                              ConstMQString * value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle for the key you want to get.

`key`

  The name of a property key.

`value`

  Output parameter that points to the value of the specified key

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

### MQGetTextMessageText

The `MQGetTextMessageText` function passes back the contents of a text message.

    MQGetTextMessageText(const MQMessageHandle messageHandle,
                               ConstMQString * messageText);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQGetXAConnection(MQConnectionHandle * connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`connectionHandle`

  A handle to an XA connection.

`MQCloseConnection` should not be called on an XA connection handle.

#### Common Errors

    MQ_STATUS_INVALID_HANDLE

### MQInitializeSSL

The `MQInitializeSSL` function initializes the SSL library.

    MQInitializeSSL (ConstMQString certificateDatabasePath);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`certificateDatabasePath`

  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.

    MQPropertiesKeyIterationGetNext
                                                (const MQPropertiesHandle propertiesHandle,
                            ConstMQString * key);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle whose contents you want to access.

`key`

  The output parameter for the next properties key in the iteration. You should not attempt to modify or free it.

##### To Get Message Properties

Follow this procedure:

1. Start the process by calling the `MQPropertiesKeyIterationStart ()` function.

2. Loop using the `MQPropertiesKeyIterationHasNext()` function.

3. Extract the name of each property key by calling the `MQPropertiesKeyIterationGetNext ()` function.

4. Determine the type of the property value for a given key by calling the `MQGetPropertyType()` function.

5. Use the appropriate `MQGet...Property` function to find the property value for the specified property key.

   If you know the property key, you can just use the appropriate `MQGet...Property` function to access its value.

   You should not modify or free the property key that is passed back to you by this function. Note that this function is not multi-thread-safe.

### MQPropertiesKeyIterationHasNext

The `MQPropertiesKeyIterationHasNext` function returns `MQ_TRUE` if there are additional property keys left in the iteration.

    MQPropertiesKeyIterationHasNext
                  (const MQPropertiesHandle  propertiesHandle);

#### Return Value

MQBool

#### Parameters

`propertiesHandle`

  A properties handle that you want to access.

##### To Get Message Properties

Follow this procedure:

1. Start the process by calling the `MQPropertiesKeyIterationStart ()` function.

2. Loop using the `MQPropertiesKeyIterationHasNext()` function.

3. Extract the name of each property key by calling the `MQPropertiesKeyIterationGetNext ()` function.

4. Determine the type of the property value for a given key by calling the `MQGetPropertyType()` function.

5. Use the appropriate `MQGet...Property` function to find the value for the specified property key.

   If you know the property key, you can just use the appropriate `MQGet...Property` function to get its value. Note that this function is not multi-thread-safe.

### MQPropertiesKeyIterationStart

The `MQPropertiesKeyIterationStart` function starts or resets the iteration process or the specified properties handle.

    MQPropertiesKeyIterationStart
                  (const PropertiesHandle propertiesHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A properties handle that you want to access.

##### To Get Message Properties

Follow this procedure:

1. Start the process by calling the `MQPropertiesKeyIterationStart ()` function.

2. Loop using the `MQPropertiesKeyIterationHasNext()` function.

3. Extract the name of each property key by calling the `MQPropertiesKeyIterationGetNext ()` function.

4. Determine the type of the property value for a given key by calling the `MQGetPropertyType()` function.

5. Use the appropriate `MQGet...Property` function to find the property value for the specified property key.

   If you know the property key, you can just use the appropriate `MQGet...Property` function to get its value. Note that this function is not multi-thread-safe.

### MQReceiveMessageNoWait

The `MQReceiveMessageNoWait` function passes a handle back to a message delivered to the specified consumer if a message is available.

    MQReceiveMessageNoWait(const MQConsumerHandle consumerHandle,
                                                          MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`consumerHandle`

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

#### Common Errors

    MQ_NOT_SYNC_RECEIVE_MODE
    MQ_CONCURRENT_ACCESS
    MQ_NO_MESSAGE
    MQ_CONSUMER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQReceiveMessageWait

The `MQReceiveMessageWait` function passes a handle back to a message delivered to the specified consumer when the message becomes available.

    MQReceiveMessageWait (const MQConsumerHandle consumerHandle,
                                    MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`consumerHandle`

  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.

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.

#### Common Errors

    MQ_NOT_SYNC_RECEIVE_MODE
    MQ_CONCURRENT_ACCESS
    MQ_CONSUMER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQReceiveMessageWithTimeout

The `MQReceiveMessageWithTimeout` function passes a handle back to a message delivered to the specified consumer if a message is available within the specified amount of time.

    MQReceiveMessageWithTimeout
                                                (const MQConsumerHandle consumerHandle,
                                                 MQInt32 timeoutMilliseconds,
                                                 MQMessageHandle * messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`consumerHandle`

  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.

#### Common Errors

    MQ_NOT_SYNC_RECEIVE_MODE
    MQ_CONCURRENT_ACCESS
    MQ_TIMEOUT_EXPIRED
    MQ_CONSUMER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQRecoverSession

The `MQCRecoverSession` function stops message delivery and restarts message delivery with the oldest unacknowledged message.

    MQRecoverSession(const MQSessionHandle sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

#### Common Errors

    MQ_TRANSACTED_SESSION
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED

### MQRollBackSession

The `MQRollBackSession` function rolls back a transaction associated with the specified session.

    MQRollBackSession(const MQSessionHandle sessionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

#### Common Errors

    MQ_NOT_TRANSACTED_SESSION
    MQ_CONCURRENT_ACCESS
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_XA_SESSION_IN_PROGRESS

### MQSendMessage

The `MQSendMessage` function sends a message using the specified producer.

    MQSendMessage(const MQProducerHandle producerHandle,
                        const MQMessageHandle messageHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`producerHandle`

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

`messageHandle`

  A handle to the message you want to send.

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.

#### Common Errors

    MQ_PRODUCER_NO_DESTINATION
    MQ_PRODUCER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQSendMessageExt

The `MQSendMessageExt` function sends a message using the specified producer and allows you to specify selected message header properties.

    MQSendMessageExt
                    (const MQProducerHandle producerHandle,
                     const MQMessageHandle messageHandle
                     MQDeliveryMode msgDeliveryMode,
                     MQInt8 msgPriority,
                     MQInt64 msgTimeToLive);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`producerHandle`

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

`messageHandle`

  A handle to the message you want to send.

`msgDeliveryMode`

  An enum

  `MQ_PERSISTENT_DELIVERY`
  `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 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:

- By default, the broker acknowledges receiving persistent messages only.

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

#### Common Errors

    MQ_PRODUCER_NO_DESTINATION
    MQ_INVALID_PRIORITY
    MQ_INVALID_DELIVERY_MODE
    MQ_PRODUCER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQSendMessageToDestination

The `MQSendMessageToDestination` function sends a message using the specified producer to the specified destination.

    MQSendMessageToDestination
                (const MQProducerHandle  producerHandle,
                 const MQMessageHandle messageHandle,
                 const MQDestinationHandle destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`producerHandle`

  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.

#### Common Errors

    MQ_PRODUCER_HAS_DEFAULT_DESTINATION
    MQ_PRODUCER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQSendMessageToDestinationExt

The `MQSendMessageToDestinationExt` function sends a message to the specified destination for the specified producer and allows you to set selected message header properties.

    MQSendMessageToDestinationExt
              (const MQProducerHandle  producerHandle,
               const MQMessageHandle  messageHandle,
               const MQDestinationHandle  destinationHandle,
               MQDeliveryMode msgDeliveryMode,
               MQInt8 msgPriority,
               MQInt64 msgTimeToLive);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`producerHandle`

  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:

Property

  Default value

`msgDeliveryMode`

  `MQ_PERSISTENT_DELIVERY`

`msgPriority`

  4

`msgTimeToLive`

  0, meaning no expiration limit

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:

- By default, the broker acknowledges receiving persistent messages only from the producing client.

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

#### Common Errors

    MQ_PRODUCER_HAS_DEFAULT_DESTINATION
    MQ_INVALID_PRIORITY
    MQ_INVALID_DELIVERY_MODE
    MQ_PRODUCER_CLOSED
    MQ_SESSION_CLOSED
    MQ_BROKER_CONNECTION_CLOSED
    MQ_THREAD_OUTSIDE_XA_TRANSACTION
    MQ_XA_SESSION_NO_TRANSATION

### MQSetBoolProperty

The `MQSetBoolProperty` function sets an `MQBool` property with the specified key to the specified value.

    MQSetBoolProperty
                   (const MQPropertiesHandle propertiesHandle,
                    ConstMQString key,
                    MQBool value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of the property key. The library makes a copy of the property key.

`value`

  The `MQBool` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetBytesMessageBytes

The `MQSetBytesMessageBytes` function defines the body for a bytes message.

    MQSetBytesMessageBytes
                      (const MQMessageHandle messageHandle,
                       const MQInt8 * messageBytes,
                       MQInt32 messageSize);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  A handle to an `MQ_BYTES_MESSAGE` message whose body you want to set.

`messageBytes`

  A pointer to the bytes you want to set. The library makes a copy of the message bytes.

`messageSize`

  An integer specifying the number of bytes in `messageBytes` .

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.

### MQSetFloat32Property

The `MQSetFloat32Property` function sets an `MQFloat32` property with the specified key to the specified value.

    MQSetFloat32Property
                 (const MQPropertiesHandle propertiesHandle,
                  ConstMQString key,
                  MQFloat32 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQFloat32` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetFloat64Property

The `MQSetFloat64Property` function sets an `MQFloat64` property with the specified key to the specified value.

    MQSetFloat64Property
             (const MQPropertiesHandle propertiesHandle,
              ConstMQString key,
              MQFloat64 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQFloat64` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetInt16Property

The `MQSetInt16Property` function sets an `MQInt16` property with the specified key to the specified value.

    MQSetInt16Property
            (const MQPropertiesHandle propertiesHandle,
             ConstMQString key,
             MQInt16 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQInt16` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetInt32Property

The `MQSetInt32Property` function sets an `MQInt32` property with the specified key to the specified value.

    MQSetInt32Property
              (const MQPropertiesHandle propertiesHandle,
               ConstMQString key,
               MQInt32 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQInt32` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetInt64Property

The `MQSetInt64Property` function sets an `MQInt64` property with the specified key to the specified value.

    MQSetInt64Property
            (const MQPropertiesHandle propertiesHandle,
             ConstMQString key,
             MQInt64 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set.

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQInt64` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetInt8Property

The `MQSetInt8Property` function sets an `MQInt8` property with the specified key to the specified value.

    MQSetInt8Property
               (const MQPropertiesHandle propertiesHandle,
                ConstMQString key,
                MQInt8 value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set

`key`

  The name of a property key. The library makes a copy of the property key.

`value`

  The `MQInt8` property value.

#### Common Errors

`MQ_HASH_VALUE_ALREADY_EXISTS`

### MQSetMessageHeaders

The `MQSetMessageHeaders` function creates the header part of the message.

    MQSetMessageHeaders
                   (const MQMessageHandle messageHandle
                    MQPropertiesHandle headersHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  A handle to a message.

`headersHandle`

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

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.

    MQSetMessageProperties
                 (const MQMessageHandle messageHandle,
                  MQPropertiesHandle propsHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

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

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.

    MQSetMessageReplyTo
             (const MQMessageHandle messageHandle,
              const MQDestinationHandle   destinationHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`messageHandle`

  A handle to a message expecting a reply.

`destinationHandle`

  The destination to which the reply is sent. Usually this is a handle to a destination that you created using the MQCreateDestination function or the function MQCreateTemporaryDestination. The handle is still valid when this function returns.

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.

    MQSetStringProperty
                     (const MQPropertiesHandle propertiesHandle,
                      ConstMQString key,
                      ConstMQString value);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

#### Parameters

`propertiesHandle`

  A handle to the properties object whose property value for the specified key you want to set. You get this handle from the `MQCreateProperties ()` function.

`key`

  The name of a property key. The library makes a copy of the property key

`value`

  The property value to set. The library makes a copy of the value.

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

### MQSetTextMessageText

The `MQSetTextMessageText` function defines the body for a text message.

    MQSetTextMessageText
                   (const MQMessageHandle messageHandle,
                    ConstMQString messageText);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

    MQStartConnection
                 (const MQConnectionHandle connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

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

#### Common Errors

`MQ_BROKER_CONNECTION_CLOSED`

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

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.

### MQStopConnection

The `MQStopConnection` function stops the specified connection to the broker. This stops the broker from delivering messages.

    MQStopConnection
                   (const MQConnectionHandle connectionHandle);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

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

#### Common Errors

`MQ_BROKER_CONNECTION_CLOSED`
`MQ_CONCURRENT_DEADLOCK`

### MQUnsubscribeDurableMessageConsumer

The `MQUnsubscribeDurableMessageConsumer` function unsubscribes the specified durable message consumer.

    MQUnsubscribeDurableMessageConsumer
                        (const MQSessionHandle   sessionHandle,
                         ConstMQString durableName);

#### Return Value

`MQStatus`. See the MQStatusIsError function for more information.

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

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

Table 4-7 Message Queue C-API Header Files

File Name | Contents
--- | ---
    mqbasictypes.h
| Defines the types `MQBool`, `MQInt8`, `MQInt16`, `MQInt32`, `MQInt64`, `MQFloat32`, `MQFloat64`.
    mqbytes-message.h
| Function prototypes for creating, getting, setting bytes message.
    mqcallback-types.h
| Asynchronous receive and connection exception handling callback types.
    mqconnection.h
| Function prototypes for creating, managing, and closing connections. Function prototype for creating session.
    mqconnection-props.h
| Connection property constants
    mqconsumer.h
| Function prototypes for synchronous receives and closing the consumer.
    mqcrt.h
| All Message Queue C-API public header files.
    mqdestination.h
| Function prototypes to free destinations and get information about destinations.
    mqerrors.h
| Error codes
    mqheader-props.h
| Message header property constants
    mqmessage.h
| Function prototypes for getting and setting parts of message, freeing message, and acknowledging message.
    mqproducer.h
| Function prototypes for sending messages and closing the message producer.
    mqproperties.h
| Function prototypes for creating, setting, and getting properties
    mqsession.h
| Function prototypes for managing and closing sessions; for creating destinations, message producers and message consumers.
    mqssl.h
| Function declaration for initializing the SSL library.
    mqstatus.h
| Function prototypes for getting error information.
    mqtext-message.h
| Function prototypes for creating, getting, setting text message.
    mqtypes.h
| 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.
    mqversion.h
| Version information constant definitions.