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

Call the MQCreateProperties function to get a handle to a newly created properties object
Call a function to set one of the connection properties listed in Table 4-2.
Which function you call depends on the type of the property you want to set; for example, to set an MQString property, you call the MQSetStringProperty function; to set a MQBool property, you call the MQSetBoolProperty function; and so on. Each function that sets a property requires that you pass a key name (constant) and value; these are listed and described in Table 4-2.
When you have set all the properties you want to define for the connection, you can then create the connection, by calling the MQCreateConnection function.
The runtime library sets the connection properties that specify the name and version of the Message Queue product; you can retrieve these using the MQGetMetaData function. These properties are described at the end of Table 4-2, starting with MQ_NAME_PROPERTY.

Acknowledge Modes

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

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

Table 4-3 acknowledgeMode Values

Enum	Description
MQ_AUTO_ACKNOWLEDGE	The session automatically acknowledges each message consumed by the client. This happens when one of the receive functions returns successfully, or when the message listener processing the message returns successfully.
MQ_CLIENT_ACKNOWLEDGE	The client explicitly acknowledges all messages for the session that have been consumed up to the point when the `MQAcknowledgeMessages` function has been called. See the discussion of the function MQAcknowledgeMessages for additional information.
MQ_DUPS_OK_ACKNOWLEDGE	The session acknowledges after ten messages have been consumed and does not guarantee that messages are delivered and consumed only once.
MQ_SESSION_TRANSACTED	This value is read only. It is set by the library if you have passed `MQ_TRUE` for the `isTransacted` parameter to the `MQCreateSession` function. It is returned to you by the `MQGetAcknowledgeMode` function if the session is transacted.

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.

Skip Navigation Links
Exit Print View
	Oracle GlassFish Server Message Queue 4.5 Developer's Guide for C Clients