Channel attributes for MQSC keywords (A-B)

An alphabetical list of the channel attributes for MQSC keywords, starting with the letter A or B.

AFFINITY (Connection affinity)

This attribute specifies whether client applications that connect multiple times using the same queue manager name, use the same client channel.

Use this attribute (MQIACH_CONNECTION_AFFINITY) when multiple applicable channel definitions are available.

The possible values are:
PREFERRED
The first connection in a process reading a client channel definition table (CCDT) creates a list of applicable definitions based on the client channel weight, with any definitions having a weight of 0 first and in alphabetical order. Each connection in the process attempts to connect using the first definition in the list. If a connection is unsuccessful the next definition is used. Unsuccessful definitions with client channel weight values other than 0 are moved to the end of the list. Definitions with a client channel weight of 0 remain at the start of the list and are selected first for each connection.

Each client process with the same host name always creates the same list.

For client applications written in C, C++, or the .NET programming framework (including fully managed .NET), and for applications that use the IBM® MQ classes for Java and IBM MQ classes for JMS, the list is updated if the CCDT has been modified since the list was created.

This value is the default, and has the value of 1.

NONE
The first connection in a process reading a CCDT creates a list of applicable definitions. All connections in a process select an applicable definition based on the client channel weight, with any definitions having a weight of 0 selected first in alphabetical order.

For client applications written in C, C++, or the .NET programming framework (including fully managed .NET), and for applications that use the IBM MQ classes for Java and IBM MQ classes for JMS, the list is updated if the CCDT has been modified since the list was created.

This attribute is valid for the client-connection channel type only.

ALTDATE (Alter date)

This attribute is the date on which the definition was last altered, in the form yyyy-mm-dd and is valid for all channel types.

ALTTIME (Alter time)

This attribute is the time at which the definition was last altered, in the form hh.mm.ss and is valid for all channel types.

[UNIX, Linux, Windows, IBM i]

AMQPKA (AMQP keep alive)

Use the AMQPKA attribute to specify a keep alive time for the AMQP client connection. If the AMQP client has not sent any frames within the keep alive interval, then the connection is closed.

The AMQPKA attribute determines the value of the idle-timeout attribute sent from IBM MQ to an AMQP client. The attribute is a period of time in milliseconds.

If AMQPKA is set to a value > 0, then IBM MQ flows half that value as the idle-timeout attribute. For example, a value of 10000 causes the queue manager to send an idle-timeout value of 5000. The client should ensure that data is sent to IBM MQ at least every 10000 milliseconds. If data is not received by IBM MQ in that time, IBM MQ assumes that the client has lost its connection and forcibly closes the connection with an amqp:resource-limit-exceeded error condition.

A value of AUTO or 0 means the IBM MQ does not flow an idle-timeout attribute to the AMQP client.

An AMQP client can still flow an idle-timeout value of its own. If it does, IBM MQ flows data (or an empty AMQP frame) at least that frequently to inform the client that it is available.

BATCHHB (Batch heartbeat Interval)

This attribute allows a sending channel to verify that the receiving channel is still active just before committing a batch of messages.

The batch heartbeat interval thus allows the batch to be backed out rather than becoming in-doubt if the receiving channel is not active. By backing out the batch, the messages remain available for processing so they could, for example, be redirected to another channel.

If the sending channel has had a communication from the receiving channel within the batch heartbeat interval, the receiving channel is assumed to be still active, otherwise a 'heartbeat' is sent to the receiving channel to check. The sending channel waits for a response from the receiving end of the channel for an interval, based on the number of seconds specified in the channel Heartbeat Interval (HBINT) attribute.

The value is in milliseconds and must be in the range zero through 999999. A value of zero indicates that batch heart beating is not used.

This attribute is valid for channel types of:
  • Sender
  • Server
  • Cluster sender
  • Cluster receiver

BATCHINT (Batch interval)

This attribute is a period, in milliseconds, during which the channel keeps a batch open even if there are no messages on the transmission queue.

You can specify any number of milliseconds, from zero through 999 999 999. The default value is zero.

If you do not specify a batch interval, the batch closes when one of the following conditions is met:
  • The number of messages specified in BATCHSZ have been sent.
  • The number of bytes specified in BATCHLIM have been sent.
  • The transmission queue is empty.

On channels with a light load, where the transmission queue frequently becomes empty, the effective batch size might be much smaller than BATCHSZ.

You can use the BATCHINT attribute to make your channels more efficient by reducing the number of short batches. Be aware, however, that you can slow down the response time, because batches last longer and messages remain uncommitted for longer.

If you specify a BATCHINT, batches close only when one of the following conditions is met:
  • The number of messages specified in BATCHSZ have been sent.
  • The number of bytes specified in BATCHLIM have been sent.
  • There are no more messages on the transmission queue and a time interval of BATCHINT has elapsed while waiting for messages (since the first message of the batch was retrieved).
Note: BATCHINT specifies the total amount of time that is spent waiting for messages. It does not include the time spent retrieving messages that are already available on the transmission queue, or the time spent transferring messages.
This attribute is valid for channel types of:
  • Sender
  • Server
  • Cluster sender
  • Cluster receiver

BATCHLIM (Batch limit)

This attribute is the limit, in kilobytes, of the amount of data that can be sent through a channel before taking a sync point.

A sync point is taken after the message that caused the limit to be reached has flowed across the channel.

The value must be in the range 0 - 999999. The default value is 5000.

A value of zero in this attribute means that no data limit is applied to batches over this channel.

The batch is ended when one of the following conditions is met:
  • BATCHSZ messages have been sent.
  • BATCHLIM bytes have been sent.
  • The transmission queue is empty and BATCHINT is exceeded.
This attribute is valid for channel types of:
  • Sender
  • Server
  • Cluster sender
  • Cluster receiver

BATCHSZ (Batch size)

This attribute is the maximum number of messages to be sent before a sync point is taken.

The batch size does not affect the way the channel transfers messages; messages are always transferred individually, but are committed or backed out as a batch.

To improve performance, you can set a batch size to define the maximum number of messages to be transferred between two sync points. The batch size to be used is negotiated when a channel starts, and the lower of the two channel definitions is taken. On some implementations, the batch size is calculated from the lowest of the two channel definitions and the two queue manager MAXUMSGS values. The actual size of a batch can be less; for example, a batch completes when there are no messages left on the transmission queue or the batch interval expires.

A large value for the batch size increases throughput, but recovery times are increased because there are more messages to back out and send again. The default BATCHSZ is 50, and you are advised to try that value first. You might choose a lower value for BATCHSZ if your communications are unreliable, making the need to recover more likely.

Sync point procedure needs a unique logical unit of work identifier to be exchanged across the link every time a sync point is taken, to coordinate batch commit procedures.

If the synchronized batch commit procedure is interrupted, an in-doubt situation might arise. In-doubt situations are resolved automatically when a message channel starts. If this resolution is not successful, manual intervention might be necessary, using the RESOLVE command.

Some considerations when choosing the number for batch size:
  • If the number is too large, the amount of queue space taken up on both ends of the link becomes excessive. Messages take up queue space when they are not committed, and cannot be removed from queues until they are committed.
  • If there is likely to be a steady flow of messages, you can improve the performance of a channel by increasing the batch size because fewer confirm flows are needed to transfer the same quantity of bytes.
  • If message flow characteristics indicate that messages arrive intermittently, a batch size of 1 with a relatively large disconnect time interval might provide a better performance.
  • The number can be in the range 1 through 9999.
  • Even though nonpersistent messages on a fast channel do not wait for a sync point, they do contribute to the batch-size count.
This attribute is valid for channel types of:
  • Sender
  • Server
  • Receiver
  • Requester
  • Cluster sender
  • Cluster receiver