2 Using the C API

To Set Properties for a Connection

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

2. Call one of the MQSet...Property functions to set one of the connection properties described in Table 4-2 . At a minimum, you must specify the name of the host of the broker to which you want to connect and its port number.

   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 an MQBool property, you call the MQSetBoolProperty function; and so on. Each function that sets a property requires that you pass a key name 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.

   Once the connection is created with the properties you specify, you cannot change its properties. If you need to change connection properties after you have created a connection, you will need to destroy the old connection and its associated objects and create a new one with the desired properties. It is a good idea to think through the desired behavior before you create a connection.

   The code sample below illustrates how you create a properties handle and how you use it for setting connection properties.

   MQStatus status;
   MQPropertiesHandle propertiesHandle = MQ_INVALID_HANDLE;
   
   status = (MQCreateProperties(&propertiesHandle);
   
   status = (MQSetStringProperty(propertiesHandle,
              MQ_BROKER_HOST_PROPERTY, "localhost"));
   
   status = (MQSetInt32Property(propertiesHandle,
              MQ_BROKER_PORT_PROPERTY, 7676));
   
   status = MQSetStringProperty(propertiesHandle,
             MQ_CONNECTION_TYPE_PROPERTY, "TCP"));
                     
   

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

To Iterate Through a Properties Handle

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 of the specified property key and type.

   If you know the property key, you can just use the appropriate MQGet...Property function to get its value. The code sample below illustrates how you implement these steps.

   MQStatus status;
   
   MQPropertiesHandle headersHandle = MQ_INVALID_HANDLE;
   
   MQBool redelivered;
   
   ConstMQString my_msgtype;
   
   status = (MQGetMessageHeaders(messageHandle, &headersHandle));
   
   status = (MQGetBoolProperty(headersHandle,
              MQ_REDELIVERED_HEADER_PROPERTY, &redelivered));
   
   status = MQGetStringProperty(headersHandle,
             MQ_MESSAGE_TYPE_HEADER_TYPE_PROPERTY, &my_msgtype);
   
   
                     
   

Connection Handling

Connections to a message server are specified by a broker host name and port number.

• Set MQ_BROKER_NAME_PROPERTY to specify the broker name.

• Set MQ_BROKER_PORT_PROPERTY to specify the port of the broker's port mapper service. In this case, the port mapper will dynamically assign the port to which the client connects.

• Set MQ_BROKER_SERVICE_PORT_PROPERTY to specify 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.

• Set the connection property MQ_CONNECTION_TYPE_PROPERTY to specify the underlying transport protocol. Possible values are TCP or SSL.

  Remember that you need to configure the JMS service port on the broker side as well. For example, if you want to connect your client via ssljms to port 1756, you would do the following.

  • On the client side: Set the MQ_SERVICE_PORT_PROPERTY to 1756 and set the MQ_CONNECTION_TYPE_PROPERTY to SSL.

  • On the broker side: Set the imq.serviceNameType.protocol.port property to 1756 as follows.

    imq.ssljms.ssl.port=1756
    

The MQ_PING_INTERVAL_PROPERTY also affects connection handling. This property is set to the interval (in seconds) that the connection can be idle before the C client runtime pings the broker to test whether the connection is still alive. This property is useful for either producers who use the connection infrequently or for clients who are exclusive consumers, passively waiting for messages to arrive. The default value is 30 seconds. Setting an interval that is too low may result in some performance loss. The minimum permitted value is 1 second to prevent this from happening.

Currently, the C-API does not support auto-reconnect or failover, which allows the client runtime to automatically reconnect to a broker if a connection fails.

Reliability

Two connection properties enable the acknowledgement of messages sent to the broker and of messages received from the broker. These are described in Message Acknowledgement. In addition to setting these properties, you can also set MQ_ACK_TIMEOUT_PROPERTY, which determines the maximum time that the client runtime will wait for any broker acknowledgement before throwing an exception.

Flow Control

A number of connection properties determine the use of Message Queue control messages by the client runtime. Messages sent and received by Message Queue clients and Message Queue control messages pass over the same client-broker connection. Because of this, delays may occur in the delivery of control messages, such as broker acknowledgements, if these are held up by the delivery of JMS messages. To prevent this type of congestion, Message Queue meters the flow of JMS messages across a connection.

• Set MQ_CONNECTION_FLOW_COUNT_PROPERTY to specify the number of Message Queue messages in a metered batch. When this number of messages is delivered to the client runtime, delivery is temporarily suspended, allowing any control messages that had been held up to be delivered. Message delivery is resumed upon notification by the client runtime, and continues until the count is again reached.

• MQ_CONNECTION_FLOW_LIMIT_PROPERTY specifies the maximum number of unconsumed messages that can be delivered to a client runtime. When the number of messages reaches this limit, delivery stops and resumes only when the number of unconsumed messages drops below the specified limit. This helps 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.

• MQ_CONNECTION_FLOW_LIMIT_ENABLED_PROPERTY specifies whether the value MQ_CONNECTION_FLOW_LIMIT_PROPERTY is used to control message flow.

You should keep the value of MQ_CONNECTION_FLOW_COUNT_PROPERTY low if the client is doing operations that require many responses from the broker; for example, the client is using the CLIENT_ACKNOWLEDGE or AUTO_ACKNOWLEDGE modes, persistent messages, transactions, or if the client is adding or removing consumers. You can increase the value of MQ_CONNECTION_FLOW_COUNT_PROPERTY without compromising performance if the client has only simple consumers on a connection using DUPS_OK mode.

The C API does not currently support consumer-based flow control.

Configuring the Client for Secure Communication

By default the MQ_SSL_BROKER_IS_TRUSTED property is set to true, and this means that the Message Queue client runtime will accept any certificate that is presented to it. The following procedure explains what you must do to establish a secure connection.

Verification Using Fingerprints

If certificate authorization fails when the broker is using a certificate authority, it is possible to give the client runtime another means of establishing a secure connection by comparing broker certificate fingerprints. If the fingerprints match, the connection is granted; if they do not match, the attempt to create the connection will fail.

Coordinating NSS Initialization

If your application uses NSS directly, other than to support Message Queue secure communication, you need to coordinate NSS initialization with the Message Queue C-API library. There are two cases to consider:

• Your application does not use secure Message Queue connections.

  In this case, you should do your application's NSS initialization before calling MQCreateConnection to create any connection to the Message Queue broker.

• Your application does use secure Message Queue connections.

  In this case, you should follow the procedure outlined below before calling MQCreateConnection to create any Message Queue connection.

Transacted Sessions

If you specify that a session be transacted, the acknowledge mode is ignored. Within a transacted session, the broker tracks sends and receives, completing these operations only when the client issues a call to commit the transaction. If a send or receive operation fails, the operation will return an error. Your application can handle the error by ignoring it, retrying it, or rolling back the entire transaction. When a transaction is committed, all the successful operations are completed. When a transaction is rolled back, all the successful operations are cancelled. A transaction cannot encompass both the production and consumption of the same message.

The scope of a local transaction is a single session. One or more producer or consumer operations can be grouped into a single local transaction only if performed in the context of a single session.

To extend the scope of a transaction beyond a single session, you can use a distributed transaction. A distributed transaction is managed by an external distributed transaction manager, as described in Working With Distributed Transactions.

Message Acknowledgement

Both messages that are sent and messages that are received can be acknowledged.

In the case of message producers, if you want the broker to acknowledge its having received a non-persistent message (to its physical destination), you must set the connection's MQ_ACK_ON_PRODUCE_PROPERTY to MQ_TRUE. If you do so, the sending function will return only after the broker has acknowledged receipt of the message. By default, the broker acknowledges receipt of persistent messages.

Acknowledgements on the consuming side means that the client runtime acknowledges delivery and consumption of all messages from a physical destination before the message service deletes the message from that destination. You can specify one of the following acknowledge modes for the consuming session when you create that session.

• MQ_AUTO_ACKNOWLEDGE specifies that the session automatically acknowledge each message consumed by the client.

• MQ_CLIENT_ACKNOWLEDGE specifies that the client must explicitly acknowledge messages by calling MQAcknowledgeMessages. In this case, all messages are acknowledged that have been consumed up to the point where the acknowledge function is called. (This could include messages consumed asynchronously by many different message listeners in that session, independent of the order in which they were consumed.)

• MQ_DUPS_OK_ACKNOWLEDGE specifies that the session acknowledges receipt of messages after each ten messages are consumed. It does not guarantee that messages are delivered and consumed only once.

(The setting of the connection property MQ_ACK_ON_ACKNOWLEDGE_PROPERTY also determines the effect of some of these acknowledge modes. For more information, see Table 4-2.)

Receive Mode

You can specify a session's receive mode as either MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE. If the session you create will be used for sending messages only, you should specify MQ_SESSION_SYNC_RECEIVE for its receive mode for optimization because the asynchronous receive mode automatically allocates an additional thread for the delivery of messages it expects to receive.

Programming Domains

When you create a destination, you must also specify its type: MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION. See "Messaging Domains" in Oracle GlassFish Server Message Queue Technical Overview for a discussion of these two types of destinations and how to choose the type that suits your needs.

Auto-Created Destinations

By default, the imq.autocreate.topic and imq.autocreate.queue broker properties are turned on. In this case, which is more convenient in a development environment, the broker automatically creates a physical destination whenever a message consumer or message producer attempts to access a non-existent destination. The auto-created physical destination will have the same name as that of the destination you created using the MQCreateDestination function.

Temporary Destinations

You use the MQCreateTemporaryDestination function to create a temporary destination. You can use such a 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 and are automatically 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.

Getting Information About Destinations

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.

Message Header

A header is required of every message. Header fields contain values used for routing and identifying messages.

Some header field values are set automatically by Message Queue during the process of producing and delivering a message, some depend on settings specified when message producers send a message, and others are set on a message-by-message basis by the client using the MQSetMessageHeader function. Table 2-7 lists the header fields defined (and required) by JMS and their corresponding names, as defined by the C-API.

For additional information about each property type and who sets it, see MQSetMessageHeaders.

Message Body Types

JMS specifies six classes (or types) of messages. The C-API supports only three of these types, as described in Table 2-8. If a Message Queue C client expects to receive messages from a Message Queue Java client, it will be unable to process messages whose body types are other than those described in the table. It will also be unable to process messages that are compressed by the Message Queue Java client runtime.

Composing the Message

Create a message using either the MQCreateBytesMessage function or the MQCreateTextMessage function. Either of these functions returns a message handle that you can then pass to the functions you use to set the message body, header, and properties (listed in Composing Messages). You can also use the MQCreateMessage function to create a message that has a header and properties but no message body.

• Use the MQSetTextMessageText function to define the body of a text message; use the MQSetBytesMessageBytes function to define the body of a bytes message.

• Use the MQSetMessageHeaders to set any message header properties.

  The message header can specify up to eight properties; most of these are set by the client runtime when sending the message or are set by the broker. The client can set MQ_CORRELATION_ID_HEADER_PROPERTY and MQ_MESSAGE_TYPE_HEADER_PROPERTY for sending a message.

• Use the MQSetMessageProperties function to set any user-defined properties for this message.

When you set message header properties or when you set additional user-defined properties, you must pass a handle to a properties object that you have created using the MQCreateProperties function. For more information, see Working With Properties.

You can use the MQSetMessageReplyTo function to associate a message with a destination that recipients can use for replies. To do this, you must first create a destination that will serve as your reply-to destination. Then, pass a handle to that destination when you call the MQSetMessageReplyTo function. 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.

Working With Consumers

When you create a consumer, you need to make several decisions:

• Do you want to receive messages synchronously or asynchronously?

  If you create a synchronous consumer, you can call one of three kinds of receive functions to receive your messages. If you create an asynchronous consumer, you must specify the name of a callback function that the client runtime can call when a message is delivered to the destination for that consumer. For information about the callback function signature, see Callback Type for Asynchronous Message Consumption .

• If you are consuming messages from a topic, do you want to use a durable or a nondurable consumer?

  A durable consumer receives all the messages published to a topic, including the ones published while the subscriber is inactive. A nondurable consumer only receives messages while the subscriber is active.

  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. In addition, each consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) each durable subscription it creates.

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 a new 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 function MQUnsubscribeDurableMessageConsumer after closing it, to delete state information maintained by the broker on behalf of the durable consumer.

Receiving a Message Synchronously

If you have created a synchronous consumer, you can use one of three receive functions: MQReceiveMessageNoWait, MQReceiveMessageWait , or MQReceiveMessagewithTimeOut. In order to use any of these functions, you must have specified MQ_SESSION_SYNC_RECEIVE for the receive mode when you created the session.

When you create a session you must specify one of several acknowledge modes for that session. 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. If the session is transacted, the acknowledge mode parameter is ignored.

When the receiving function returns, it gives you a handle to the delivered message. You can pass that handle to the functions described in Processing a Message, in order to read message properties and information stored in the header and body of the message.

It is possible that a message can be lost for synchronous consumers in a session using AUTO_ACKNOWLEDGE mode if the provider fails. To prevent this possibility, you should either use a transacted session or a session in CLIENT_ACKNOWLEDGE mode.

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 on the broker. See the usage notes provided in the section MQReceiveMessageNoWait for more information.

Receiving a Message Asynchronously

To receive a message asynchronously, you must create an asynchronous message consumer and pass the name of an MQMessageListenerFunc type callback function. (Therefore, you must set up the callback function before you create the asynchronous consumer that will use it.) You should start the connection only after creating an asynchronous consumer. If the connection is already started, you should stop the connection before creating an asynchronous consumer.

You are also responsible for writing the message listener function. Mainly, the function needs to process the incoming message by examining its header, body, and properties, or it needs to pass control to a function that can do this processing. The client is also responsible for freeing the message handle (either from within the listener or from outside of the listener) by calling the MQFreeMessage function.

When you create a session you must specify one of several acknowledge modes for that session. 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 about the signature and content of a call back function, see Callback Type for Asynchronous Message Consumption.

When the callback function is called by the session delivery of a message, it gives you a handle to the delivered message. You can pass that handle to the functions described in Processing a Message, in order to read message properties and information stored in the header and body of the message.