Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With Connections

All messaging occurs within the context of a connection: the behavior of the connection is defined by the properties set for that connection. You use the functions listed in Table 2–3 to create, start, stop, and close a connection.

Table 2–3 Functions Used to Work with Connections




Initializes the SSL library. You must call this function before you create any connection that uses SSL. 


Creates a connection and passes back a handle to it. 


Starts the specified connection and starts or resumes delivery of messages. 


Stops the specified connection. 


Returns a handle to name and version information for the Message Queue product. 


Closes the specified connection. 

Before you create a connection, you must do the following:

When you have completed these steps, you are ready to call MQCreateConnection to create a connection. After you create the connection, you can create a session as described in Working With Sessions and Destinations .

When you send a message, you do not need to start the connection explicitly by calling MQStartConnection. You do need to call MQStartConnection before the broker can deliver messages to a consumer.

If you need to halt delivery in the course of processing messages, you can call the MQStopConnection() function.

Defining Connection Properties

Connection properties specify the following information:

The following sections examine the effect of properties used to manage connection handling, reliability, message flow, and security.

Table 4–2 lists and describes all properties of a connection. For information on how to set and change connection properties, see Working With Properties.

Connection Handling

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

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.


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.

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.

Working With Secure Connections

Establishing a secure connection between the client and the broker requires both the administrator and the developer to do some additional work. The administrator’s work is described in the Message Encryption in Sun Java System Message Queue 4.3 Administration Guide. In brief, it requires that the administrator do the following:

The developer must also do some work to configure the client for secure messaging. The work required depends on whether the broker is trusted (the default setting) and on whether the developer wants to provide an additional means of verification if the broker is not trusted and the initial attempt to create a secure connection fails.

The MessageQueue C-API library uses NSS to support the SSL transport protocol between the Message Queue C client and the Message Queue broker. The developer 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.

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.

ProcedureTo Establish a Secure Connection


  2. If you want the runtime to check the broker’s certificate, set the MQ_SSL_BROKER_IS_TRUSTED property to false. Otherwise, you can leave it to its default (true) value.

  3. Generate the NSS files CertN .db, keyN.db, and secmod.db using the certificate database tool certutil . You can find this tool at the following locations:

  4. Note the path name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication.

  5. If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, use the certutil tool to import the root certificate of the authority certifying the broker into the database files you generated in Configuring the Client for Secure Communication .

    Make sure that the MQ_BROKER_HOST_PROPERTY value is set to the same value as the (CN) common name in the broker’s certificate.

  6. If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, you have the option of enabling broker fingerprint-based verification in case authorization fails. For details, see Verification Using Fingerprints.

  7. Call the function MQInitializeSSL once (and only once) before creating the connection, and pass the name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication. If the broker is trusted, these files can be empty.

    You must call this function before you create any connection to the broker, including connections that do not use SSL.

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.

ProcedureTo Set Up Fingerprint Certification

  1. Set the broker connection property MQ_SSL_CHECK_BROKER_FINGERPRINT to true.

  2. Retrieve the broker’s certificate fingerprint by using the java keytool -list option on the broker’s keystore file:

    You will use the output of this command as the value for the connection property MQ_SSL_BROKER_CERT_FINGERPRINT in Verification Using Fingerprints. For example, if the output contains a value like the following:

    Certificate fingerprint (MD5): F6:A5:C1:F2:E6:63:40:73:97:64:39:6C:1B:35:0F:8E

    You would specify this value for MQ_SSL_BROKER_CERT_FINGEPRINT.

  3. Set the connection property MQ_SSL_BROKER_CERT_FINGEPRINT to the value obtained in Verification Using Fingerprints.

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:

ProcedureTo Coordinate NSS Initialization

  1. Call the function MQInitializeSSL. (You must specify the path to the directory containing the NSS files as the certdbpath parameter to this function.)

    Your application’s use of NSS must specify the same certdbpath value for the location of its NSS files. (That is, the certificates needed by your application must be located in the same directory as the certificates needed by Message Queue.)

    Internally, the function MQInitializeSSL does the following:

    • Calls the function NSS_Init(certdbpath).

    • Sets DOMESTIC cipher policy using the function NSS_SetDomesticPolicy().

    • Enables all cipher suites, including RSA_NULL_MD5 by calling the function SSL_CipherPrefSetDefault(SSL_RSA_WITH_NULL_MD5, PR_TRUE) .

    • Calls the function SSL_ClearSessionCache().

  2. If your application needs different cipher suite settings, after you call the MQInitializeSSL() function, you can modify the cipher suites by calling the function SSL_CipherPrefSetDefault. However, note that these changes will affect your secure connection to the Message Queue broker as well.

Shutting Down Connections

In order to do an orderly shutdown, you need to close the connection by calling MQCloseConnection() and then to free the memory associated with the connection by calling the MQFreeConnection() function.

To get information about a connection, call the MQGetMetaData() function. This returns name and version information for the Message Queue product.