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

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.

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