Channel properties

For cluster-receiver channels on Windows, UNIX and Linux, that use the TCP/IP transport protocol, do not specify a value for this property; IBM MQ generates a name for using, assuming the default port and the current IPv4 address of the system. If the system does not have an IPv4 address, the current IPv6 address of the system is used. For cluster-receiver channels on other platforms, and for cluster-receiver channels that do not use the TCP/IP transport protocol, type the name of the computer that hosts the local queue manager.

Cluster-sender channels: If you type a value in the Local communication address field of a manually defined cluster-sender channel, this value is overwritten with the values in the full repository's cluster-receiver channel when communication is established with the full repository queue manager. As well as specifying the value in the manually defined cluster-sender channel, we must write a channel auto-definition exit to force the value of the Local communication address property into any automatically defined cluster-sender channels.

Cluster-receiver channels: Do not put an IP address in the Local communication address field of a cluster-receiver channel unless all of the queue managers are on the same computer. This is because any queue manager that attempts to connect to a queue manager with an IP address in the Local communication address field of its cluster-receiver channel has these values propagated to their auto-defined cluster-sender channels. We can, however, put a port number or port range in the Local communication address field of a cluster-receiver channel if we want all the queue managers in a cluster to use a specific port or range of ports for all their outbound communications.

• On the following platforms, the value must be greater than or equal to zero, and less than or equal to the maximum message length of the queue manager:
  • AIX
  • IBM i
  • Windows
  • VSE/ESA

• On other platforms, the value must be greater than or equal to zero, and less than or equal to 4,194,304 bytes.
• On IBM MQ for z/OS, the value must be greater than or equal to zero, and less than or equal to 104,857,600 bytes.

This parameter is used on server-connection channels and AMQP channels. Maximum instances specifies the maximum number of simultaneous instances of an individual server-connection channel or AMQP channel.

The value can be a number in the range 0 - 999999999. The default value is 999999999

A value of zero means that all client access is prevented.

If Maximum instances is set to a value which is less than the number of instances of the server-connection channel currently running, then new instances are prevented from starting until sufficient existing instances stop running.

If a client connects on an AMQP channel with an ID that is already connected (that is, it performs a client-takeover) the takeover will succeed regardless of whether the number of connected clients has reached MAXINST.

This parameter is used on server-connection channels. Maximum instances per client specifies the maximum number of simultaneous instances of an individual server-connection channel which can be started from a single client. In this context, connections originating from the same remote network address are regarded as coming from the same client.

The value can be a number 0 - 999999999. The default value is 999999999

A value of zero means that all client access is prevented.

Maximum instances differs from Maximum instances per client in that Maximum instances is the maximum amount of connections, but Maximum instances per client is the maximum amount of connections that each client is allowed to connect to the server.

On z/OS queue managers, the Keep alive interval property specifies the keep alive interval for the individual channel.

On queue managers on multiplatforms, the Keep alive interval property is used only if the channel connects to a z/OS queue manager; to use the functionality provided by the Keep alive interval property, set the Keep alive interval property to Auto to use a value based on the negotiated heartbeat interval value.

For z/OS using CICS, type the highest number in the range 1 - 999999999, that the message sequence number reaches before it restarts at 1.

For all other platforms, type the highest number in the range 100 - 999999999 that the message sequence number reaches before it restarts at 1.

The value must be high enough that the number is not reissued while it is being used by an earlier message. The two ends of the channel must have the same sequence number wrap value when the channel starts; otherwise you get an error.

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) property.

If the receiving end of the channel is not active, the batch can be backed out rather than becoming in-doubt. By backing out the batch, the messages remain available for processing so that they can, for example, be redirected to another channel. Type the number of seconds, 0 - 999999, that the sending end of the channel waits for a response from the receiving end of the channel before assuming that the receiving end of the channel is inactive.

A value of 0 means that batch heartbeating is not used. For more information, see Configure the channel to reduce the opportunity of being put 'in-doubt'.

Private. This is the default value. Start as a private channel on the local queue manager.

Shared. A receiving channel is shared if it was started in response to an inbound transmission directed to the queue sharing group. A sending channel is shared if its transmission queue has a disposition of SHARED.

(Only on Sender channels, Server channels, Cluster Sender channels, and Cluster Receiver channels)

All means that all properties of the message are included with the message when it is sent to the remote queue manager. The properties, except those in the message descriptor (or extension), are placed in one or more MQRFH2 headers in the message data.

Compatibility. This is the default value; it allows applications that expect JMS related properties to be in an MQRFH2 header in the message data to continue to work unmodified.

If the message contains a property with a prefix of mcd., jms., usr., or mqext. then all optional message properties (where the Support value is MQPD_SUPPORT_OPTIONAL), except those in the message descriptor (or extension) are placed in one or more MQRFH2 headers in the message data before the message is sent to the remote queue manager. Otherwise all properties of the message, except those in the message descriptor (or extension), are removed from the message before the message is sent to the remote queue manager.

If the message contains a property where the Support field of the property descriptor is not set to MQPD_SUPPORT_OPTIONAL then the message are rejected and treated in accordance with its report options. If the message contains one or more properties where the Support field of the property descriptor is set to MQPD_SUPPORT_OPTIONAL but other fields of the property descriptor are set to non-default values, then these properties are removed from the message before the message is sent to the remote queue manager.

None means that all properties of the message, except those in the message descriptor (or extension), are removed from the message before the message is sent to the remote queue manager. If the message contains a property where the Support field of the property descriptor is not set to MQPD_SUPPORT_OPTIONAL then the message are rejected and treated in accordance with its report options.

(Only on Server-connection channels and Client-connection channels)

• Administrator stop-quiesce
• Heartbeating
• Read ahead

1: Specifies no sharing of conversations over a TCP/IP socket. Client heartbeating and read ahead are available, whether in an MQGET call or not, and channel quiescing is more controllable.

2 - 999999999: The number of shared conversations. The default value is 10.

This is the sequence number from an outstanding request and it indicates a user RESET CHANNEL command request is outstanding. A value of zero indicates that there is no outstanding RESET CHANNEL. The value can be in the range 1 - 999999999.

When the value of RESETSEQ is 0, the DISPLAY CHANNEL command returns RESETSEQ(NO).

(Not on Client-connection channels, Server-connection channels, or Telemetry channels)

• No means that messages that cannot be delivered by a channel are treated as a failure, and the channel either ends in accordance with the setting of Non-persistent message speed, or discards the messages.
• Yes means that if the queue manager Dead-letter queue property provides the name of a Dead Letter Queue, then it is used. Otherwise the behavior is as for No.

(On AMQP channels only)

(On AMQP channels only)

(On AMQP channels only)

(On AMQP channels only)

The default value for TPROOT is SYSTEM.BASE.TOPIC. With this default value, the topic string that an AMQP client uses to publish or subscribe has no prefix, and the client can exchange messages with other MQ pub/sub applications.

Passthrough

Pass through, unchanged, any messages sent or received by the message channel agent for this channel.

This value is valid for channels with a channel type of sender, server, receiver, or requester, and is the default value.

Remove

Remove any AMS protection from messages retrieved from the transmission queue by the message channel agent, and send the messages to the partner.

When the MCA gets a message from the transmission queue, if an AMS policy is defined for the transmission queue, it is applied to remove any AMS protection from the message prior to sending the message across the channel. If an AMS policy is not defined for the transmission queue, the message is sent as is.

This value is valid only for channels with a channel type of sender or server.

As policy

Based on the policy defined for the target queue, apply AMS protection to inbound messages prior to putting them on to the target queue.

When the message channel agent receives an inbound message, if an AMS policy is defined for the target queue, AMS protection is applied to the message prior to the message being put to the target queue. If an AMS policy is not defined for the target queue, the message is put to the target queue as is.

This value is valid only for channels with a channel type of receiver, or requester.

• On z/OS, the user ID assigned to the channel-initiator started task by the z/OS started-procedures table.
• For TCP/IP, for platforms other than z/OS, the user ID from the inetd.conf entry, or the user that started the listener.
• For SNA, for platforms other than z/OS, the user ID from the SNA server entry or, in the absence of this the incoming attach request, or the user that started the listener.
• For NetBIOS or SPX, the user ID that started the listener.

The maximum length of the string is:

• 64 characters on Windows.

  For channels with a CHLTYPE of AMQP, before IBM MQ Version 9.1.1, the MCAUSER user ID setting is only supported for user IDs up to 12 characters in length. From Version 9.1.1 Continuous Delivery, and from Version 9.2.0 Long Term Support, the 12 character limit is removed.

• 12 characters on platforms other than Windows.

On Windows, we can optionally qualify a user identifier with the domain name in the format user@domain.

• On UNIX and Linux, enter the names of one or more exit programs. The maximum total length of all the names together is 999 characters. Use the format libraryname(functionname), where the maximum number of characters in a name is 128.
• On Windows, enter the name of one or more exit programs. The maximum total length of all the names together is 999 characters. Use the format dllname(functionname), where the maximum number of characters in a name is 128.
• On IBM i, enter the names of up to 10 exit programs. Use the format programname libname, where programname occupies the first 10 characters, and libname occupies the second 10 characters. Add spaces at the end of shorter names to bring them up to 10 characters.
• On z/OS, enter the names of up to 8 exit programs. Use the load module name, where the maximum number of characters in a name is 8.
• On other platforms, we can specify the name of only one send exit program for each channel.

• On Windows, UNIX and Linux, type the data for one or more exit programs. Separate the data with commas. The maximum total length of the field is 999 characters.
• On IBM i, type up to 10 strings of data, each with a length of 32 characters. The first string of data is passed to the first send exit, the second string is passed to the second exit, and so on.
• On z/OS, type up to 8 strings of data, each with a length of 32 characters. The first string of data is passed to the first send exit, the second string is passed to the second exit, and so on.
• On other platforms, we can specify only one string of send exit data for each channel.

• On UNIX and Linux, enter the names of one or more exit programs. The maximum total number of characters in all the names together is 999 characters. Use the format libraryname(functionname), where the maximum number of characters in a string is 128.
• On Windows, enter the name of one or more exit programs. Separate the names with commas. The maximum total length of the field is 999 characters. Use the format dllname(functionname), where the maximum number of characters in a string is 128.
• On Windows, type the names of up to 10 exit programs. Separate the names with commas. Use the format programname libname, where programname occupies the first 10 characters, and libname occupies the second 10 characters. Add spaces at the end of shorter names to bring them up to 10 characters.
• On z/OS, type the names of up to 8 exit programs. Separate the names with commas. Use the load module name, where the maximum number of characters is 8.
• On other platforms, we can specify the name of only one send exit program for each channel.

• On Windows, UNIX and Linux, type the data for one or more exit programs. Separate the data with commas. The maximum total length of the field is 999 characters.
• On IBM i, type up to 10 strings of data, each with a length of 32 characters. The first string of data is passed to the first receive exit, the second string is passed to the second exit, and so on.
• On z/OS, type up to 8 strings of data, each with a length of 32 characters. The first string of data is passed to the first receive exit, the second string is passed to the second exit, and so on.
• On other platforms, we can specify only one string of receive exit data for each channel.

• On UNIX and Linux, use the format libraryname(functionname), where the maximum number of characters in a string is 128.
• On IBM i, use the format programname libname, where programname occupies the first 10 characters, and libname occupies the second 10 characters. Add spaces at the end of shorter names to bring them up to 10 characters.
• On z/OS, use the load module name, where the maximum number of characters is 8.

• On UNIX and Linux, enter the names of one or more exit programs. The maximum total length of all the names together is 999 characters. Use the format libraryname(functionname), where the maximum number of characters in a name is 128.
• On Windows, enter the name of one or more exit programs. The maximum total length of all the names together is 999 characters. Use the format dllname(functionname), where the maximum number of characters in a name is 128.
• On IBM i, enter the names of up to 10 exit programs. Use the format programname libname, where programname occupies the first 10 characters, and libname occupies the second 10 characters. Add spaces at the end of shorter names to bring them up to 10 characters.
• On z/OS, enter the names of up to 8 exit programs. Use the load module name, where the maximum number of characters in a name is 8.
• On other platforms, we can specify the name of only one message exit program for each channel.

• On Windows, UNIX and Linux, type the data for one or more exit programs. Separate the data with commas. The maximum total length of the field is 999 characters.
• On IBM i, type up to 10 strings of data, each with a length of 32 characters. The first string of data is passed to the first channel message exit, the second string is passed to the second exit, and so on.
• On z/OS, type up to 8 strings of data, each with a length of 32 characters. The first string of data is passed to the first channel message exit, the second string is passed to the second exit, and so on.
• On other platforms, we can specify only one string of channel message exit data for each channel.

• On UNIX and Linux, use the format libraryname(functionname), where the maximum number of characters in a string is 128.
• On IBM i, use the format programname libname, where programname occupies the first 10 characters, and libname occupies the second 10 characters. Add spaces at the end of shorter names to bring them up to 10 characters.
• On z/OS, use the load module name, where the maximum number of characters is 8.

The value for this parameter is also used to set the value of the Security Protocol property, which is an output field on the Channel status attributes page.

When a client issues an MQCONN requesting connection to a queue manager group, by specifying a queue manager name starting with an asterisk, and more than one suitable channel definition is available in the client channel definition table (CCDT), the definition to use is randomly selected based on the weighting, with any applicable CLNTWGHT(0) definitions selected first in alphabetical order. Specify a value in the range 0 - 99. The default is 0. A value of 0 indicates that no load balancing is performed and applicable definitions are selected in alphabetical order. To enable load balancing choose a value in the range 1 - 99 where 1 is the lowest weighting and 99 is the highest. The distribution of messages between two or more channels with non-zero weightings is approximately proportional to the ratio of those weightings.

PREFERRED. This is the default value. 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 creates the same list.

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.