Defining Connection Properties

Connection properties specify the following information:

• The host name and port of the broker to which you want to connect

• The transport protocol of the connection service used by the client

• How broker and client acknowledgements are handled to support messaging reliability

• How message flow is to be managed

• How secure messaging should be implemented

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.

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