ALTER CHANNEL (alter channel settings)

Use the MQSC command ALTER CHANNEL to alter the parameters of a channel.

Using MQSC commands

For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.

Parameters not specified in the ALTER CHANNEL command result in the existing values for those parameters being left unchanged.

You can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which you can issue MQSC commands on z/OS®.

Synonym: ALT CHL

Syntax diagrams

The syntax diagrams for ALTER CHANNEL are in the subtopics. There is a separate syntax diagram for each channel type.

Usage notes

  • Changes take effect after the channel is next started.
  • For cluster channels (the CLUSSDR and CLUSRCVR columns in the table), if an attribute can be set on both channels, set it on both and ensure that the settings are identical. If there is any discrepancy between the settings, those that you specify on the CLUSRCVR channel are likely to be used. This is explained in Cluster channels.
  • If you change the XMITQ name or the CONNAME, you must reset the sequence number at both ends of the channel. (See RESET CHANNEL (reset message sequence number for a channel) for information about the SEQNUM parameter.)
  • Successful completion of the command does not mean that the action completed. To check for true completion, see the ALTER CHANNEL step in Checking that async commands for distributed networks have finished.

Parameter descriptions for ALTER CHANNEL

The following table shows the parameters that are relevant for each type of channel. There is a description of each parameter after the table. Parameters are optional unless the description states that they are required.
Table 1. DEFINE and ALTER CHANNEL parameters
Parameter SDR SVR RCVR RQSTR CLNTCONN SVRCONN CLUSSDR CLUSRCVR AMQP
AFFINITY         X        
AMQPKA                 X
BATCHHB X X         X X  
BATCHINT X X         X X  
BATCHLIM X X         X X  
BATCHSZ X X X X     X X  
CERTLABL X X X X X X   X X
channel-name X X X X X X X X X
CHLTYPE X X X X X X X X X
CLNTWGHT         X        
CLUSNL             X X  
CLUSTER             X X  
CLWLPRTY             X X  
CLWLRANK             X X  
CLWLWGHT             X X  
[z/OS]CMDSCOPE [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS] 
COMPHDR X X X X X X X X  
COMPMSG X X X X X X X X  
CONNAME X X   X X   X X  
CONVERT X X         X X  
DEFCDISP X X X X   X      
DEFRECON         X        
DESCR X X X X X X X X X
DISCINT X X       X X X  
HBINT X X X X X X X X  
KAINT X X X X X X X X  
LIKE X X X X X X X X  
LOCLADDR X X   X X   X X X
LONGRTY X X         X X  
LONGTMR X X         X X  
MAXINST           X     X
MAXINSTC           X      
MAXMSGL X X X X X X X X X
MCANAME X X   X     X X  
MCATYPE X X   X     X X  
MCAUSER     X X   X   X X
MODENAME X X   X X   X X  
MONCHL X X X X   X X X  
MRDATA     X X       X  
MREXIT     X X       X  
MRRTY     X X       X  
MRTMR     X X       X  
MSGDATA X X X X     X X  
MSGEXIT X X X X     X X  
NETPRTY               X  
NPMSPEED X X X X     X X  
PASSWORD X X   X X   X X  
PORT                 X
PROPCTL X X         X X  
PUTAUT     X X   X   X  
QMNAME         X        
[z/OS]QSGDISP [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS]X [z/OS] 
RCVDATA X X X X X X X X  
RCVEXIT X X X X X X X X  
REPLACE X X X X X X X X  
SCYDATA X X X X X X X X  
SCYEXIT X X X X X X X X  
SENDDATA X X X X X X X X  
SENDEXIT X X X X X X X X  
SEQWRAP X X X X     X X  
SHARECNV         X X      
SHORTRTY X X         X X  
SHORTTMR X X         X X  
[z/OS][MQ 9.2.0 Jul 2020]SPLPROT X X X X          
SSLCAUTH   X X X   X   X  
SSLCIPH X X X X X X X X X
SSLPEER X X X X X X X X X
STATCHL X X X X     X X  
[MQ 9.2.3 Jul 2021][UNIX, Linux, Windows, IBM i]TMPMODEL                 X
[MQ 9.2.3 Jul 2021][UNIX, Linux, Windows, IBM i]TMPQPRFX                 X
TPNAME X X   X X X X X  
TPROOT                 X
TRPTYPE X X X X X X X X  
USECLTID                 X
USEDLQ X X X X     X X  
USERID X X   X X   X    
XMITQ X X              
AFFINITY
The channel affinity attribute is used so client applications that connect multiple times using the same queue manager name can choose whether to use the same client channel definition for each connection. This attribute is intended to be used when multiple applicable channel definitions are available.
PREFERRED
The first connection in a process reading a client channel definition table (CCDT) creates a list of applicable definitions based on the weighting with any applicable CLNTWGHT(0) definitions 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 non-CLNTWGHT(0) definitions are moved to the end of the list. CLNTWGHT(0) definitions remain at the start of the list and are selected first for each connection. For C, C++ and .NET (including fully managed .NET) clients the list is updated if the CCDT has been modified since the list was created. 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 weighting with any applicable CLNTWGHT(0) definitions selected first in alphabetical order. For C, C++ and .NET (including fully managed .NET) clients the list is updated if the CCDT has been modified since the list was created.
For example, suppose the CCDT includes the following definitions:
CHLNAME(A) QMNAME(QM1) CLNTWGHT(3)
CHLNAME(B) QMNAME(QM1) CLNTWGHT(4)
CHLNAME(C) QMNAME(QM1) CLNTWGHT(4)

The first connection in a process creates its own ordered list based on the weightings. So it might, for example, create the ordered list CHLNAME(B), CHLNAME(A), CHLNAME(C).

For AFFINITY(PREFERRED), each connection in the process attempts to connect using CHLNAME(B). If a connection is unsuccessful the definition is moved to the end of the list which now becomes CHLNAME(A), CHLNAME(C), CHLNAME(B). Each connection in the process then attempts to connect using CHLNAME(A).

For AFFINITY(NONE), each connection in the process attempts to connect using one of the three definitions selected at random based on the weightings.

When sharing conversations is enabled with a non-zero channel weighting and AFFINITY(NONE), multiple connections in a process using the same queue manager name can connect using different applicable definitions rather than sharing an existing channel instance.

[UNIX, Linux, Windows, IBM i]AMQPKA(integer)
The keep alive time for an AMQP channel in milliseconds. If the AMQP client has not sent any frames within the keep alive interval, then the connection is closed with a amqp:resource-limit-exceeded AMQP error condition.

This parameter is valid only for channels with a channel type (CHLTYPE) of AMQP

BATCHHB(integer)
Specifies whether batch heartbeats are to be used. The value is the length of the heartbeat in milliseconds.

Batch heartbeats allow a sending channel to verify that the receiving channel is still active just before committing a batch of messages, so that if the receiving channel is not active, the batch can be backed out rather than becoming in-doubt, as would otherwise be the case. 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. If not, a 'heartbeat' is sent to the receiving channel to check.

The value must be in the range zero through 999999. A value of zero indicates that batch heartbeating is not used.

The BATCHHB parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, and CLUSRCVR.

BATCHINT(integer)
The minimum amount of time, in milliseconds, that a channel keeps a batch open.
The batch is terminated 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.
The value must be in the range 0 - 999999999. Zero means that the batch is terminated as soon as the transmission queue becomes empty, or the BATCHSZ or BATCHLIM limit is reached.
This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.
BATCHLIM(integer)

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. A value of zero in this attribute means that no data limit is applied to batches over this channel.

The batch is terminated 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 parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

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

The BATCHLIM parameter is supported on all platforms.

BATCHSZ(integer)
The maximum number of messages that can be sent through a channel before taking a sync point.
The maximum batch size used is the lowest of the following values:
  • The BATCHSZ of the sending channel.
  • The BATCHSZ of the receiving channel.
  • [z/OS]On z/OS, three less than the maximum number of uncommitted messages allowed at the sending queue manager (or one if this value is zero or less).
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, the maximum number of uncommitted messages allowed at the sending queue manager (or one if this value is zero or less).
  • [z/OS]On z/OS, three less than the maximum number of uncommitted messages allowed at the receiving queue manager (or one if this value is zero or less).
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, the maximum number of uncommitted messages allowed at the receiving queue manager (or one if this value is zero or less).
The maximum number of uncommitted messages is specified by the MAXUMSGS parameter of the ALTER QMGR command.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

The value must be in the range 1 through 9999.

CERTLABL

Certificate label for this channel to use.

The label identifies which personal certificate in the key repository is sent to the remote peer. If this attribute is blank, the certificate is determined by the queue manager CERTLABL parameter.

Note that inbound channels (including receiver, requester, cluster-receiver, unqualified server, and server-connection channels) only send the configured certificate if the IBM MQ version of the remote peer fully supports certificate label configuration, and the channel is using a TLS CipherSpec. See Interoperability of Elliptic Curve and RSA CipherSpecs for further information.

An unqualified server channel is one that does not have the CONNAME field set.

In all other cases, the queue manager CERTLABL parameter determines the certificate sent. In particular, the following only ever receive the certificate configured by the CERTLABL parameter of the queue manager, regardless of the channel-specific label setting:
  • All current Java and JMS clients.
  • Versions of IBM MQ before IBM MQ 8.0.

You do not need to run the REFRESH SECURITY TYPE(SSL) command if you make any changes to CERTLABL on a channel. However, you must run a REFRESH SECURITY TYPE(SSL) command if you make any changes to CERTLABL on the queue manager.

Note: It is an error to inquire, or set, this attribute for cluster-sender channels. If you attempt to do so, you receive the error MQRCCF_WRONG_CHANNEL_TYPE. However, the attribute is present in cluster-sender channel objects (including MQCD structures) and a channel auto-definition (CHAD) exit might set it programmatically if required.
channel-name)
The name of the new channel definition.

This parameter is required on all types of channel.

[UNIX, Linux, Windows, IBM i]On CLUSSDR channels, it can take a different form from the other channel types. If your convention for naming cluster-sender channels includes the name of the queue manager, you can define a cluster-sender channel using the +QMNAME+ construction. After connection to the matching cluster-receiver channel, IBM MQ substitutes the correct repository queue manager name in place of +QMNAME+ in the cluster-sender channel definition. For more information see Components of a cluster.

The name must not be the same as any existing channel defined on this queue manager (unless REPLACE or ALTER is specified).

[z/OS]On z/OS, client-connection channel names can duplicate others.

The maximum length of the string is 20 characters, and the string must contain only valid characters; see Rules for naming IBM MQ objects.

CHLTYPE
Channel type. This parameter is required. It must follow immediately after the channel-name) parameter on all platforms except z/OS.
SDR
Sender channel
SVR
Server channel
RCVR
Receiver channel
RQSTR
Requester channel
CLNTCONN
Client-connection channel
SVRCONN
Server-connection channel
CLUSSDR
Cluster-sender channel
CLUSRCVR
Cluster-receiver channel
Note: If you are using the REPLACE option, you cannot change the channel type.
CLNTWGHT
The client channel weighting attribute is used so client channel definitions can be selected at random based on their weighting when more than one suitable definition is available. Specify a value in the range 0 - 99.

The special value 0 indicates that no random load balancing is performed and applicable definitions are selected in alphabetical order. To enable random load balancing the value can be in the range 1 through 99 where 1 is the lowest weighting and 99 is the highest.

When a client issues an MQCONN with queue manager name "*name" and more than one suitable definition is available in the CCDT the choice of definition to use is randomly selected based on the weighting with any applicable CLNTWGHT(0) definitions selected first in alphabetical order. The distribution is not guaranteed.

For example, suppose the CCDT includes the following two definitions:
CHLNAME(TO.QM1) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address1) CLNTWGHT(2)
CHLNAME(TO.QM2) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address2) CLNTWGHT(4)

A client MQCONN with queue manager name "*GRP1" would choose one of the two definitions based on the weighting of the channel definition. (A random integer 1 - 6 would be generated. If the integer was in the range 1 through 2 address1 would be used otherwise address2 would be used). If this connection was unsuccessful the client would then use the other definition.

The CCDT might contain applicable definitions with both zero and non-zero weighting. In this situation, the definitions with zero weightings are chosen first and in alphabetical order. If these connections are unsuccessful the definitions with non-zero weighting are chosen based on their weighting.

For example, suppose the CCDT includes the following four definitions:
CHLNAME(TO.QM1) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address1) CLNTWGHT(1)
CHLNAME(TO.QM2) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address2) CLNTWGHT(2)
CHLNAME(TO.QM3) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address3) CLNTWGHT(0)
CHLNAME(TO.QM4) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address4) CLNTWGHT(0)

A client MQCONN with queue manager name "*GRP1" would first choose definition "TO.QM3". If this connection was unsuccessful the client would then choose definition "TO.QM4". If this connection was also unsuccessful the client would then randomly choose one of the remaining two definitions based on their weighting.

CLNTWGHT support is added for all supported transport protocols.

CLUSNL(nlname)
The name of the namelist that specifies a list of clusters to which the channel belongs.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR and CLUSRCVR channels. Only one of the resultant values of CLUSTER or CLUSNL can be nonblank, the other must be blank.

CLUSTER(clustername)
The name of the cluster to which the channel belongs. The maximum length is 48 characters conforming to the rules for naming IBM MQ objects.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR. Only one of the resultant values of CLUSTER or CLUSNL can be nonblank, the other must be blank.

CLWLPRTY(integer)
Specifies the priority of the channel for the purposes of cluster workload distribution. The value must be in the range zero through 9 where zero is the lowest priority and 9 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLPRTY queue attribute.

CLWLRANK(integer)
Specifies the rank of the channel for the purposes of cluster workload distribution. The value must be in the range zero through 9 where zero is the lowest rank and 9 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLRANK channel attribute.

CLWLWGHT(integer)
Specifies the weighting to be applied to the channel for the purposes of cluster workload distribution so that the proportion of messages sent down the channel can be controlled. The value must be in the range 1 through 99 where 1 is the lowest rank and 99 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLWGHT channel attribute.

[z/OS]CMDSCOPE
This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue sharing group.
CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.
' '
The command is executed on the queue manager on which it was entered.
qmgr-name
The command is executed on the queue manager you specify, providing the queue manager is active within the queue sharing group. You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.
*
The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group. The effect of * is the same as entering the command on every queue manager in the queue sharing group.
COMPHDR
The list of header data compression techniques supported by the channel. For sender, server, cluster-sender, cluster-receiver, and client-connection channels, the values specified are in order of preference with the first compression technique supported by the remote end of the channel being used.
The mutually supported compression techniques of the channel are passed to the message exit of the sending channel where the compression technique used can be altered on a per message basis. Compression alters the data passed to send and receive exits.
NONE
No header data compression is performed.
SYSTEM
Header data compression is performed.
COMPMSG
The list of message data compression techniques supported by the channel. For sender, server, cluster-sender, cluster-receiver, and client-connection channels, the values specified are in order of preference with the first compression technique supported by the remote end of the channel being used.
The mutually supported compression techniques of the channel are passed to the message exit of the sending channel where the compression technique used can be altered on a per message basis. Compression alters the data passed to send and receive exits.
NONE
No message data compression is performed.
RLE
Message data compression is performed using run-length encoding.
ZLIBFAST
Message data compression is performed using ZLIB encoding with speed prioritized.
ZLIBHIGH
Message data compression is performed using ZLIB encoding with compression prioritized.
ANY
Any compression technique supported by the queue manager can be used. This value is only valid for receiver, requester, and server-connection channels.
CONNAME(string)
Connection name.

For cluster-receiver channels (when specified) CONNAME relates to the local queue manager, and for other channels it relates to the target queue manager.

[z/OS]On z/OS, the maximum length of the string is 48 characters.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, the maximum length of the string is 264 characters

A workaround to the 48 character limit might be one of the following suggestions:
  • Set up your DNS servers so that you use, for example, host name of "myserver" instead of "myserver.location.company.com", ensuring you can use the short host name.
  • Use IP addresses.

Specify CONNAME as a comma-separated list of names of machines for the stated TRPTYPE. Typically only one machine name is required. You can provide multiple machine names to configure multiple connections with the same properties. The connections are usually tried in the order they are specified in the connection list until a connection is successfully established. The order is modified for clients if the CLNTWGHT attribute is provided. If no connection is successful, the channel attempts the connection again, as determined by the attributes of the channel. With client channels, a connection-list provides an alternative to using queue manager groups to configure multiple connections. With message channels, a connection list is used to configure connections to the alternative addresses of a multi-instance queue manager.

This parameter is required for channels with a channel type (CHLTYPE) of SDR, RQSTR, CLNTCONN, and CLUSSDR. It is optional for SVR channels, and for CLUSRCVR channels of TRPTYPE(TCP), and is not valid for RCVR or SVRCONN channels.

Providing multiple connection names in a list was first supported in IBM WebSphere® MQ 7.0.1. It changes the syntax of the CONNAME parameter. Earlier clients and queue managers connect using the first connection name in the list, and do not read the rest of the connection names in the list. In order for the earlier clients and queue managers to parse the new syntax, you must specify a port number on the first connection name in the list. Specifying a port number avoids problems when connecting to the channel from a client or queue manager that is running at a level earlier than IBM WebSphere MQ 7.0.1.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, the TCP/IP connection name parameter of a cluster-receiver channel is optional. If you leave the connection name blank, IBM MQ generates a connection name for you, assuming the default port and using the current IP address of the system. You can override the default port number, but still use the current IP address of the system. For each connection name leave the IP name blank, and provide the port number in parentheses; for example:

(1415)
The generated CONNAME is always in the dotted decimal (IPv4) or hexadecimal (IPv6) form, rather than in the form of an alphanumeric DNS host name.
Note: If you are using any of the special characters in your connection name (for example, parentheses) you must enclose the string in single quotation marks.
The value you specify depends on the transport type (TRPTYPE) to be used:
LU 6.2
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, CONNAME is the name of the CPI-C communications side object. Or, if the TPNAME is not blank, CONNAME is the fully qualified name of the partner logical unit.
  • [z/OS]On z/OS, there are two forms in which to specify the value:
    Logical unit name
    The logical unit information for the queue manager, comprising the logical unit name, TP name, and optional mode name. Logical unit name can be specified in one of three forms:
    Table 2. Logical unit name forms and examples
    Form Example
    luname IGY12355
    luname/TPname IGY12345/APING
    luname/TPname/modename IGY12345/APINGD/#INTER

    For the first form, the TP name and mode name must be specified for the TPNAME and MODENAME parameters; otherwise these parameters must be blank.

    Note: For client-connection channels, only the first form is allowed.
    Symbolic name
    The symbolic destination name for the logical unit information for the queue manager, as defined in the side information data set. The TPNAME and MODENAME parameters must be blank.
    Note: For cluster-receiver channels, the side information is on the other queue managers in the cluster. Alternatively, in this case it can be a name that a channel auto-definition exit can resolve into the appropriate logical unit information for the local queue manager.

    The specified or implied LU name can be that of a VTAM generic resources group.

    For more information, see Configuration parameters for an LU 6.2 connection.
NetBIOS
A unique NetBIOS name (limited to 16 characters).
SPX
The 4 byte network address, the 6 byte node address, and the 2 byte socket number. These values must be entered in hexadecimal, with a period separating the network and node addresses. The socket number must be enclosed in brackets, for example:
CONNAME('0a0b0c0d.804abcde23a1(5e86)')
TCP
Either the host name, or the network address of the remote machine (or the local machine for cluster-receiver channels). This address can be followed by an optional port number, enclosed in parentheses.

If the CONNAME is a host name, the host name is resolved to an IP address.

The IP stack used for communication depends on both the value specified for CONNAME and the value specified for LOCLADDR. See LOCLADDR for information about how this value is resolved.

[z/OS]On z/OS, the connection name can include the IP_name of an z/OS dynamic DNS group or a Network Dispatcher input port.
Important: Do not include the IP_name or input port for channels with a channel type (CHLTYPE) of CLUSSDR.

On all platforms, when you define a channel with a channel type (CHLTYPE) of CLUSRCVR that is using TCP/IP, you do not need to specify the network address of your queue manager. IBM MQ generates a CONNAME for you, assuming the default port and using the current IP4 address of the system. If the system does not have an IP4 address, the current IP6 address of the system is used.

Note: If you are using clustering between IP6-only and IP4-only queue managers, do not specify an IP6 network address as the CONNAME for CLUSRCVR channels. A queue manager that is capable only of IP4 communication is unable to start a cluster sender channel definition that specifies the CONNAME in IP6 hexadecimal form. Consider, instead, using host names in a heterogeneous IP environment.
CONVERT
Specifies whether the sending message channel agent attempts conversion of the application message data, if the receiving message channel agent cannot perform this conversion.
NO
No conversion by sender
YES
Conversion by sender

[z/OS]On z/OS, N and Y are accepted as synonyms of NO and YES.

The CONVERT parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

DEFCDISP
Specifies the default channel disposition of the channel.
PRIVATE
The intended disposition of the channel is as a PRIVATE channel.
FIXSHARED
The intended disposition of the channel is as a FIXSHARED channel.
SHARED
The intended disposition of the channel is as a SHARED channel.

This parameter does not apply to channels with a channel type (CHLTYPE) of CLNTCONN, CLUSSDR, or CLUSRCVR.

DEFRECON
Specifies whether a client connection automatically reconnects a client application if its connection breaks.
NO
Unless overridden by MQCONNX, the client is not reconnected automatically.
YES
Unless overridden by MQCONNX, the client reconnects automatically.
QMGR
Unless overridden by MQCONNX, the client reconnects automatically, but only to the same queue manager. The QMGR option has the same effect as MQCNO_RECONNECT_Q_MGR.
DISABLED
Reconnection is disabled, even if requested by the client program using the MQCONNX MQI call.
Table 3. Automatic reconnection depends on the values set in the application and in the channel definition
DEFRECON Reconnection options set in the application
  MQCNO_RECONNECT MQCNO_RECONNECT_Q_MGR MQCNO_RECONNECT_AS_DEF MQCNO_RECONNECT_DISABLED
NO YES QMGR NO NO
YES YES QMGR YES NO
QMGR YES QMGR QMGR NO
DISABLED NO NO NO NO
DESCR(string)
Plain-text comment. It provides descriptive information about the channel when an operator issues the DISPLAY CHANNEL command.

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.
DISCINT(integer)
The minimum time in seconds for which the channel waits for a message to arrive on the transmission queue, after a batch ends, before terminating the channel. A value of zero causes the message channel agent to wait indefinitely.

The value must be in the range zero through 999 999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SVRCONN , SDR, SVR, CLUSSDR, CLUSRCVR.

For SVRCONN channels using the TCP protocol, this parameter is the minimum time in seconds for which the SVRCONN instance remains active without any communication from its partner client. A value of zero disables this disconnect processing. The SVRCONN inactivity interval only applies between IBM MQ API calls from a client, so no client is disconnected during an extended MQGET with wait call. This attribute is ignored for SVRCONN channels using protocols other than TCP.

HBINT(integer)

This attribute specifies the approximate time between heartbeat flows that are to be passed from a sending MCA when there are no messages on the transmission queue.

Heartbeat flows unblock the receiving MCA, which is waiting for messages to arrive or for the disconnect interval to expire. When the receiving MCA is unblocked it can disconnect the channel without waiting for the disconnect interval to expire. Heartbeat flows also free any storage buffers that have been allocated for large messages and close any queues that have been left open at the receiving end of the channel.

The value is in seconds and must be in the range 0 through 999999. A value of zero means that no heartbeat flows are to be sent. The default value is 300. To be most useful, the value needs to be less than the disconnect interval value.

For server-connection and client-connection channels, heartbeats can flow from both the server side as well as the client side independently. If no data has been transferred across the channel for the heartbeat interval, the client-connection MQI agent sends a heartbeat flow and the server-connection MQI agent responds to it with another heartbeat flow. This happens irrespective of the state of the channel, for example, irrespective of whether it is inactive while making an API call, or is inactive waiting for client user input. The server-connection MQI agent is also capable of initiating a heartbeat to the client, again irrespective of the state of the channel. To prevent both server-connection and client-connection MQI agents heart beating to each other at the same time, the server heartbeat is flowed after no data has been transferred across the channel for the heartbeat interval plus 5 seconds.

For server-connection and client-connection channels working in the channel mode before IBM WebSphere MQ 7.0, heartbeats flow only when a server MCA is waiting for an MQGET command with the WAIT option specified, which it has issued on behalf of a client application.

For more information, see Heartbeat interval (HBINT).

KAINT(integer)
The value passed to the communications stack for KeepAlive timing for this channel.

For this attribute to be effective, TCP/IP keepalive must be enabled both in the queue manager and in TCP/IP.

[z/OS]On z/OS, you enable TCP/IP keepalive in the queue manager by issuing the ALTER QMGR TCPKEEP(YES) command; if theTCPKEEP queue manager parameter is NO, the value is ignored, and the KeepAlive facility is not used.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, TCP/IP keepalive is enabled when the KEEPALIVE=YES parameter is specified in the TCP stanza in the distributed queuing configuration file, qm.ini, or through the IBM MQ Explorer.

Keepalive must also be enabled within TCP/IP itself. Refer to your TCP/IP documentation for information about configuring keepalive:
  • [AIX]On AIX®, use the no command.
  • [Windows]On Windows, edit the registry.
  • [z/OS]On z/OS, update your TCP/IP PROFILE data set and add or change the INTERVAL parameter in the TCPCONFIG section.

[z/OS]Although this parameter is available on all platforms, its setting is implemented only on z/OS.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, you can access and modify the parameter, but it is only stored and forwarded; there is no functional implementation of the parameter. This functionality is useful in a clustered environment where a value set in a cluster-receiver channel definition on AIX, for example, flows to (and is implemented by) z/OS queue managers that are in, or join, the cluster.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, if you need the functionality provided by the KAINT parameter, use the Heartbeat Interval (HBINT) parameter, as described in HBINT.

(integer)
The KeepAlive interval to be used, in seconds, in the range 1 through 99 999.
0
The value used is that specified by the INTERVAL statement in the TCP profile configuration data set.
AUTO
The KeepAlive interval is calculated based upon the negotiated heartbeat value as follows:
  • If the negotiated HBINT is greater than zero, KeepAlive interval is set to that value plus 60 seconds.
  • If the negotiated HBINT is zero, the value used is that specified by the INTERVAL statement in the TCP profile configuration data set.

This parameter is valid for all channel types. It is ignored for channels with a TRPTYPE other than TCP or SPX.

LIKE(channel-name)
The name of a channel. The parameters of this channel are used to model this definition.
If this field is not completed, and you do not complete the parameter fields related to the command, the values are taken from one of the following default channels, depending upon the channel type:
SYSTEM.DEF.SENDER
Sender channel
SYSTEM.DEF.SERVER
Server channel
SYSTEM.DEF.RECEIVER
Receiver channel
SYSTEM.DEF.REQUESTER
Requester channel
SYSTEM.DEF.SVRCONN
Server-connection channel
SYSTEM.DEF.CLNTCONN
Client-connection channel
SYSTEM.DEF.CLUSSDR
Cluster-sender channel
SYSTEM.DEF.CLUSRCVR
Cluster-receiver channel
This parameter is equivalent to defining the following object for a sender channel, and similarly for other channel types:
LIKE(SYSTEM.DEF.SENDER)
These default channel definitions can be altered by the installation to the default values required.
[z/OS]On z/OS, the queue manager searches page set zero for an object with the name you specify and a disposition of QMGR or COPY. The disposition of the LIKE object is not copied to the object and channel type you are defining.
Note:
  1. QSGDISP(GROUP) objects are not searched.
  2. # LIKE is ignored if QSGDISP(COPY) is specified. However, the group object defined is used as a LIKE object.
LOCLADDR(string)
LOCLADDR is the local communications address for the channel. For channels other than AMQP channels, use this parameter if you want a channel to use a particular IP address, port, or port range for outbound communications. LOCLADDR might be useful in recovery scenarios where a channel is restarted on a different TCP/IP stack. LOCLADDR is also useful to force a channel to use an IP4 or IP6 stack on a dual-stack system. You can also use LOCLADDR to force a channel to use a dual-mode stack on a single-stack system.
Note: AMQP channels do not support the same format of LOCLADDR as other IBM MQ channels. For the format supported by AMQ, see the next parameter AMQP: LOCLADDR.

For channels other than AMQP channels, the LOCLADDR parameter is valid only for channels with a transport type (TRPTYPE) of TCP. If TRPTYPE is not TCP, the data is ignored and no error message is issued.

The value is the optional IP address, and optional port or port range used for outbound TCP/IP communications. The format for this information is as follows:
LOCLADDR([ip-addr][(low-port[,high-port])][,[ip-addr][(low-port[,high-port])]])

The maximum length of LOCLADDR, including multiple addresses, is MQ_LOCAL_ADDRESS_LENGTH.

If you omit LOCLADDR, a local address is automatically allocated.

Note, that you can set LOCLADDR for a C client using the Client Channel Definition Table (CCDT).

All the parameters are optional. Omitting the ip-addr part of the address is useful to enable the configuration of a fixed port number for an IP firewall. Omitting the port number is useful to select a particular network adapter without having the identify a unique local port number. The TCP/IP stack generates a unique port number.

Specify [,[ip-addr][(low-port[,high-port])]] multiple times for each additional local address. Use multiple local addresses if you want to specify a specific subset of local network adapters. You can also use [,[ip-addr][(low-port[,high-port])]] to represent a particular local network address on different servers that are part of a multi-instance queue manager configuration.

ip-addr
ip-addr is specified in one of three forms:
IP4 dotted decimal
For example, 192.0.2.1
IP6 hexadecimal notation
For example, 2001:DB8:0:0:0:0:0:0
Alphanumeric host name form
For example WWW.EXAMPLE.COM
low-port and high-port
low-port and high-port are port numbers enclosed in parentheses.
The following table shows how the LOCLADDR parameter can be used:
Table 4. Examples of how the LOCLADDR parameter can be used
LOCLADDR Meaning
9.20.4.98 Channel binds to this address locally
9.20.4.98, 9.20.4.99 Channel binds to either IP address. The address might be two network adapters on one server, or a different network adapter on two different servers in a multi-instance configuration.
9.20.4.98(1000) Channel binds to this address and port 1000 locally
9.20.4.98(1000,2000) Channel binds to this address and uses a port in the range 1000 - 2000 locally
(1000) Channel binds to port 1000 locally
(1000,2000) Channel binds to port in range 1000 - 2000 locally

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, CLUSSDR, OR CLUSRCVR.

On CLUSSDR channels, the IP address and port to which the outbound channel binds, is a combination of fields. It is a concatenation of the IP address, as defined in the LOCLADDR parameter, and the port range from the cluster cache. If there is no port range in the cache, the port range defined in the LOCLADDR parameter is used.

[z/OS]This port range does not apply to z/OS systems.

Even though this parameter is similar in form to CONNAME, it must not be confused with it. The LOCLADDR parameter specifies the characteristics of the local communications, whereas the CONNAME parameter specifies how to reach a remote queue manager.

When a channel is started, the values specified for CONNAME and LOCLADDR determine the IP stack to be used for communication; see Table 3 and Local Address ( LOCLADDR).

If the TCP/IP stack for the local address is not installed or configured, the channel does not start and an exception message is generated.

[z/OS]For example, on z/OS systems, the message is "CSQO015E: Command issued but no reply received." The message indicates that the connect() request specifies an interface address that is not known on the default IP stack. To direct the connect() request to the alternative stack, specify the LOCLADDR parameter in the channel definition as either an interface on the alternative stack, or a DNS host name. The same specification also works for listeners that might not use the default stack. To find the value to code for LOCLADDR, run the NETSTAT HOME command on the IP stacks that you want to use as alternatives.

Table 5. How the IP stack to be used for communication is determined
Protocols supported CONNAME LOCLADDR Action of channel
IP4 only IP4 address 1   Channel binds to IP4 stack
IP6 address 2   Channel fails to resolve CONNAME
IP4 and 6 host name 3   Channel binds to IP4 stack
IP4 address IP4 address Channel binds to IP4 stack
IP6 address IP4 address Channel fails to resolve CONNAME
IP4 and 6 host name IP4 address Channel binds to IP4 stack
Any address 4 IP6 address Channel fails to resolve LOCLADDR
IP4 address IP4 and 6 host name Channel binds to IP4 stack
IP6 address IP4 and 6 host name Channel fails to resolve CONNAME
IP4 and 6 host name IP4 and 6 host name Channel binds to IP4 stack
IP4 and IP6 IP4 address   Channel binds to IP4 stack
IP6 address   Channel binds to IP6 stack
IP4 and 6 host name   Channel binds to stack determined by IPADDRV
IP4 address IP4 address Channel binds to IP4 stack
IP6 address IP4 address Channel fails to resolve CONNAME
IP4 and 6 host name IP4 address Channel binds to IP4 stack
IP4 address IP6 address Channel maps CONNAME to IP6 5
IP6 address IP6 address Channel binds IP6 stack
IP4 and 6 host name IP6 address Channel binds IP6 stack
IP4 address IP4 and 6 host name Channel binds to IP4 stack
IP6 address IP4 and 6 host name Channel binds to IP6 stack
IP4 and 6 host name IP4 and 6 host name Channel binds to stack determined by IPADDRV
IP6 only IP4 address   Channel maps CONNAME to IP6 5
IP6 address   Channel binds to IP6 stack
IP4 and 6 host name   Channel binds to IP6 stack
Any address IP4 address Channel fails to resolve LOCLADDR
IP4 address IP6 address Channel maps CONNAME to IP6 5
IP6 address IP6 address Channel binds to IP6 stack
IP4 and 6 host name IP6 address Channel binds to IP6 stack
IP4 address IP4 and 6 host name Channel maps CONNAME to IP6 5
IP6 address IP4 and 6 host name Channel binds to IP6 stack
IP4 and 6 host name IP4 and 6 host name Channel binds to IP6 stack
Notes:
  1. IP4 address. An IP4 host name that resolves only to an IP4 network address or a specific dotted notation IP4 address, for example 1.2.3.4. This note applies to all occurrences of ' IP4 address' in this table.
  2. IP6 address. An IP6 host name that resolves only to an IP6 network address or a specific hexadecimal notation IP6 address, for example 4321:54bc. This note applies to all occurrences of ' IP6 address' in this table.
  3. IP4 and 6 host name. A host name that resolves to both IP4 and IP6 network addresses. This note applies to all occurrences of ' IP4 and 6 host name' in this table.
  4. Any address. IP4 address, IP6 address, or IP4 and 6 host name. This note applies to all occurrences of 'Any address' in this table.
  5. Maps IP4 CONNAME to IP4 mapped IP6 address. IP6 stack implementations that do not support IP4 mapped IP6 addressing fail to resolve the CONNAME. Mapped addresses might require protocol translators in order to be used. The use of mapped addresses is not recommended.
AMQP: LOCLADDR(ip-addr)
Note: For the format of LOCLADDR that other IBM MQ channels use, see the previous parameter LOCLADDR.

For AMQP channels, LOCLADDR is the local communications address for the channel. Use this parameter if you want to force the client to use a particular IP address. LOCLADDR is also useful to force a channel to use an IP4 or IP6 address if a choice is available, or to use a particular network adapter on a system with multiple network adapters.

The maximum length of LOCLADDR is MQ_LOCAL_ADDRESS_LENGTH.

If you omit LOCLADDR, a local address is automatically allocated.

ip-addr
ip-addr is a single network address, specified in one of three forms:
IP4 dotted decimal
For example, 192.0.2.1
IP6 hexadecimal notation
For example, 2001:DB8:0:0:0:0:0:0
Alphanumeric host name form
For example, WWW.EXAMPLE.COM

If an IP address is entered, only the address format is validated. The IP address itself is not validated.

LONGRTY(integer)
When a sender, server, or cluster-sender channel is attempting to connect to the remote queue manager, and the count specified by SHORTRTY has been exhausted, this parameter specifies the maximum number of further attempts that are made to connect to the remote queue manager, at intervals specified by LONGTMR.

If this count is also exhausted without success, an error is logged to the operator, and the channel is stopped. The channel must then be restarted with a command (it is not started automatically by the channel initiator).

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

LONGTMR(integer)
For long retry attempts, this parameter is the maximum number of seconds to wait before reattempting connection to the remote queue manager.

The time is approximate; zero means that another connection attempt is made as soon as possible.

The interval between retries might be extended if the channel has to wait to become active.

The value must be in the range zero through 999999999.

Note: For implementation reasons, the maximum retry interval that can be used is 999,999; values exceeding this maximum are treated as 999,999. Similarly, the minimum retry interval that can be used is 2; values less than this minimum are treated as 2.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

MAXINST(integer)

The maximum number of simultaneous instances of an individual server-connection channel or AMQP channel that can be started.

The value must be in the range zero through 999999999.

A value of zero prevents all client access on this channel.

If the value of this parameter is reduced to a number that is less than the number of instances of the server-connection channel that are currently running, then those running instances are not affected. However, new instances cannot start until sufficient existing instances have ceased to run so that the number of currently running instances is less than the value of this parameter.

If an AMQP client attempts to connect to an AMQP channel, and the number of connected clients has reached MAXINST, the channel closes the connection with a close frame. The close frame contains the following message: amqp:resource-limit-exceeded. If a client connects with an ID that is already connected (that is, it performs a client-takeover), and the client is permitted to take over the connection, the takeover will succeed regardless of whether the number of connected clients has reached MAXINST.

This parameter is valid only for channels with a channel type ( CHLTYPE) of SVRCONN or AMQP.

MAXINSTC(integer)
The maximum number of simultaneous individual server-connection channels that can be started from a single client. In this context, connections that originate from the same remote network address are regarded as coming from the same client.

The value must be in the range zero through 999999999.

A value of zero prevents all client access on this channel.

If the value of this parameter is reduced to a number that is less than the number of instances of the server-connection channel that is currently running from individual clients, then those running instances are not affected. However, new instances from those clients cannot start until sufficient instances have ceased to run that the number of running instances is less than the value of this parameter.

This parameter is valid only for channels with a channel type (CHLTYPE) of SVRCONN.

MAXMSGL(integer)
Specifies the maximum message length that can be transmitted on the channel. This parameter is compared with the value for the partner and the actual maximum used is the lower of the two values. The value is ineffective if the MQCB function is being executed and the channel type (CHLTYPE) is SVRCONN.

The value zero means the maximum message length for the queue manager.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, specify a value in the range zero through to the maximum message length for the queue manager.

[z/OS]On z/OS, specify a value in the range zero through 104857600 bytes (100 MB).

See the MAXMSGL parameter of the ALTER QMGR command for more information.

MCANAME(string)
Message channel agent name.

This parameter is reserved, and if specified must only be set to blanks (maximum length 20 characters).

MCATYPE
Specifies whether the message-channel-agent program on an outbound message channel runs as a thread or a process.
PROCESS
The message channel agent runs as a separate process.
THREAD
The message channel agent runs as a separate thread

In situations where a threaded listener is required to service many incoming requests, resources can become strained. In this case, use multiple listener processes and target incoming requests at specific listeners through the port number specified on the listener.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, this parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLUSSDR, or CLUSRCVR.

[z/OS]On z/OS, this parameter is supported only for channels with a channel type of CLUSRCVR. When specified in a CLUSRCVR definition, MCATYPE is used by a remote machine to determine the corresponding CLUSSDR definition.

MCAUSER(string)
Message channel agent user identifier.
Note: An alternative way of providing a user ID for a channel to run under is to use channel authentication records. With channel authentication records, different connections can use the same channel while using different credentials. If both MCAUSER on the channel is set and channel authentication records are used to apply to the same channel, the channel authentication records take precedence. The MCAUSER on the channel definition is only used if the channel authentication record uses USERSRC(CHANNEL). For more details, see Channel authentication records.

This parameter interacts with PUTAUT, see the definition of that parameter for more information.

If it is nonblank, it is the user identifier that is to be used by the message channel agent for authorization to access IBM MQ resources, including (if PUTAUT is DEF) authorization to put the message to the destination queue for receiver or requester channels.

If it is blank, the message channel agent uses its default user identifier.

The default user identifier is derived from the user ID that started the receiving channel. The possible values are:
  • [z/OS]On z/OS, the user ID assigned to the channel-initiator started task by the z/OS started-procedures table.
  • [UNIX, Linux, Windows, IBM i]For TCP/IP, on Multiplatforms, the user ID from the inetd.conf entry, or the user that started the listener.
  • [UNIX, Linux, Windows, IBM i]For SNA, on Multiplatforms, the user ID from the SNA server entry or, in the absence of this user ID 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:
  • [Windows]64 characters on Windows.

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

  • 12 characters on platforms other than Windows.

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

This parameter is not valid for channels with a channel type (CHLTYPE) of SDR, SVR, CLNTCONN, CLUSSDR.

MODENAME(string)
LU 6.2 mode name (maximum length 8 characters).

This parameter is valid only for channels with a transport type (TRPTYPE) of LU 6.2. If TRPTYPE is not LU 6.2, the data is ignored and no error message is issued.

If specified, this parameter must be set to the SNA mode name unless the CONNAME contains a side-object name, in which case it must be set to blanks. The actual name is then taken from the CPI-C Communications Side Object, or APPC side information data set.

[z/OS]See Configuration parameters for an LU 6.2 connection for more information about configuration parameters for an LU 6.2 connection for your platform.

This parameter is not valid for channels with a channel type (CHLTYPE) of RCVR or SVRCONN.

MONCHL
Controls the collection of online monitoring data for channels:
QMGR
Collect monitoring data according to the setting of the queue manager parameter MONCHL.
OFF
Monitoring data collection is turned off for this channel.
LOW
If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a low rate of data collection, for this channel.
MEDIUM
If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a moderate rate of data collection, for this channel.
HIGH
If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a high rate of data collection, for this channel.

For cluster channels, the value of this parameter is not replicated in the repository and, therefore, not used in the auto-definition of cluster-sender channels.

For auto-defined cluster-sender channels, the value of this parameter is taken from the queue manager attribute MONACLS. If you want to modify the value, use the command ALTER QMGR MONACLS(HIGH), then restart the auto-defined sender channel.

Changes to this parameter take effect only on channels started after the change occurs.

MRDATA(string)
Channel message-retry exit user data. The maximum length is 32 characters.

This parameter is passed to the channel message-retry exit when it is called.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MREXIT(string)
Channel message-retry exit name.

The format and maximum length of the name is the same as for MSGEXIT, however you can only specify one message-retry exit.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MRRTY(integer)
The number of times the channel tries again before it decides it cannot deliver the message.

This parameter controls the action of the MCA only if the message-retry exit name is blank. If the exit name is not blank, the value of MRRTY is passed to the exit to use, but the number of retries performed (if any) is controlled by the exit, and not by this parameter.

The value must be in the range zero through 999999999. A value of zero means that no retries are performed.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MRTMR(integer)
The minimum interval of time that must pass before the channel can try the MQPUT operation again. This time interval is in milliseconds.

This parameter controls the action of the MCA only if the message-retry exit name is blank. If the exit name is not blank, the value of MRTMR is passed to the exit to use, but the retry interval is controlled by the exit, and not by this parameter.

The value must be in the range zero through 999 999 999. A value of zero means that the retry is performed as soon as possible (if the value of MRRTY is greater than zero).

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MSGDATA(string)
User data for the channel message exit. The maximum length is 32 characters.

This data is passed to the channel message exit when it is called.

[AIX, Linux, Windows]On AIX, Linux®, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

[IBM i]On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first message exit specified, the second string to the second exit, and so on.

[z/OS]On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first message exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of message exit data for each channel.

Note: This parameter is accepted but ignored for server-connection and client-connection channels.
MSGEXIT(string)
Channel message exit name.
If this name is nonblank, the exit is called at the following times:
  • Immediately after a message has been retrieved from the transmission queue (sender or server), or immediately before a message is put to a destination queue (receiver or requester).

    The exit is given the entire application message and transmission queue header for modification.

  • At initialization and termination of the channel.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

[IBM i]On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

[z/OS]On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one message exit name for each channel.

For channels with a channel type (CHLTYPE) of CLNTCONN or SVRCONN, this parameter is accepted but ignored, because message exits are not invoked for such channels.

The format and maximum length of the name depends on the environment:
  • [AIX][Linux]On AIX and Linux, it is of the form:
    libraryname(functionname)
    The maximum length of the string is 128 characters.
  • [Windows]On Windows, it is of the form:
    dllname(functionname)
    where dllname is specified without the suffix .DLL. The maximum length of the string is 128 characters.
  • [IBM i]On IBM i, it is of the form:
    progname libname
    where progname occupies the first 10 characters and libname the second 10 characters (both padded to the right with blanks if necessary). The maximum length of the string is 20 characters.
  • [z/OS]On z/OS, it is a load module name, maximum length 8 characters (128 characters are allowed for exit names for client-connection channels, subject to a maximum total length including commas of 999).
NETPRTY(integer)
The priority for the network connection. Distributed queuing chooses the path with the highest priority if there are multiple paths available. The value must be in the range zero through 9; zero is the lowest priority.

This parameter is valid only for CLUSRCVR channels.

NPMSPEED
The class of service for nonpersistent messages on this channel:
FAST
Fast delivery for nonpersistent messages; messages might be lost if the channel is lost. Messages are retrieved using MQGMO_SYNCPOINT_IF_PERSISTENT and so are not included in the batch unit of work.
NORMAL
Normal delivery for nonpersistent messages.
If the sending side and the receiving side do not agree about this parameter, or one does not support it, NORMAL is used.
Notes:
  1. If the active recovery logs for IBM MQ for z/OS are switching and archiving more frequently than expected, given that the messages being sent across a channel are non-persistent, setting NPMSPEED(FAST) on both the sending and receiving ends of the channel can minimize the SYSTEM.CHANNEL.SYNCQ updates.
  2. If you are seeing high CPU usage relating to updates to the SYSTEM.CHANNEL.SYNCQ, setting NPMSPEED(FAST) can significantly reduce the CPU usage.

This parameter is valid only for channels with a CHLTYPE of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

PASSWORD(string)
Password used by the message channel agent when attempting to initiate a secure LU 6.2 session with a remote message channel agent. The maximum length is 12 characters.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, this parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, or CLUSSDR.

[z/OS]On z/OS, it is supported only for channels with a channel type (CHLTYPE) of CLNTCONN.

Although the maximum length of the parameter is 12 characters, only the first 10 characters are used.

PORT(integer)
The port number used to connect an AMQP channel. The default port for AMQP 1.0 connections is 5672. If you are already using port 5672, you can specify a different port.
PROPCTL
Property control attribute.

Specifies what happens to properties of messages when the message is about to be sent to a V6 or prior queue manager (a queue manager that does not understand the concept of a property descriptor).

This parameter is applicable to Sender, Server, Cluster Sender, and Cluster Receiver channels.

This parameter is optional.

Permitted values are:
COMPAT
COMPAT allows applications which expect JMS-related properties to be in an MQRFH2 header in the message data to continue to work unmodified.
Table 6. Range of results, depending on which mesage properties are set, when PROPCTL value is COMPAT
Message properties Result
The message contains a property with a prefix of mcd., jms., usr. or mqext. All optional message properties (where the Support value is MQPD_SUPPORT_OPTIONAL), except properties in the message descriptor or extension, are placed in one or more MQRFH2 headers in the message data before the message it sent to the remote queue manager.
The message does not contain a property with a prefix of mcd., jms., usr. or mqext. All message properties, except properties in the message descriptor or extension, are removed from the message before the message is sent to the remote queue manager.
The message contains a property where the Support field of the property descriptor is not set to MQPD_SUPPORT_OPTIONAL The message is rejected with reason MQRC_UNSUPPORTED_PROPERTY and treated in accordance with its report options.
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. The properties with non-default values are removed from the message before the message is sent to the remote queue manager.
The MQRFH2 folder that would contain the message property needs to be assigned with the content='properties' attribute The properties are removed to prevent MQRFH2 headers with unsupported syntax flowing to a V6 or prior queue manager.
NONE
All properties of the message, except properties 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 is rejected with reason MQRC_UNSUPPORTED_PROPERTY and treated in accordance with its report options.
ALL
All properties of the message are included with the message when it is sent to the remote queue manager. The properties, except properties in the message descriptor (or extension), are placed in one or more MQRFH2 headers in the message data.
PUTAUT
Specifies which user identifiers are used to establish authority to put messages to the destination queue (for messages channels) or to execute an MQI call (for MQI channels).
DEF
The default user ID is used.

[z/OS]On z/OS, DEF might involve using both the user ID received from the network and that derived from MCAUSER.

CTX
The user ID from the UserIdentifier field of the message descriptor is used.

[z/OS]On z/OS, CTX might involve also using the user ID received from the network or that derived from MCAUSER, or both.

[z/OS]ONLYMCA
The user ID derived from MCAUSER is used. Any user ID received from the network is not used. This value is supported only on z/OS.
[z/OS]ALTMCA
The user ID from the UserIdentifier field of the message descriptor is used. Any user ID received from the network is not used. This value is supported only on z/OS.

[z/OS]On z/OS, the user IDs that are checked, and how many user IDs are checked, depends on the setting of the MQADMIN RACF® class hlq.RESLEVEL profile. Depending on the level of access the user ID of the channel initiator has to hlq.RESLEVEL, zero, one or two user IDs are checked. To see how many user IDs are checked, see RESLEVEL and channel initiator connections. For more information about which user IDs are checked, see User IDs used by the channel initiator.

[z/OS]On z/OS, this parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, CLUSRCVR, or SVRCONN. CTX and ALTMCA are not valid for SVRCONN channels.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, this parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

QMNAME(string)
Queue manager name.

For channels with a channel type (CHLTYPE) of CLNTCONN, this parameter is the name of a queue manager to which an application that is running in a client environment and using the client channel definition table can request connection. This parameter need not be the name of the queue manager on which the channel is defined, to allow a client to connect to different queue managers.

For channels of other types, this parameter is not valid.

[z/OS]QSGDISP
This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

Table 7. Behavior for each of the QSGDISP values
QSGDISP ALTER
COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue sharing group to attempt to refresh local copies on page set zero:
DEFINE CHANNEL(channel-name) CHLTYPE(type)
REPLACE QSGDISP(COPY)
The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.
RCVDATA(string)
Channel receive exit user data (maximum length 32 characters).

This parameter is passed to the channel receive exit when it is called.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

[IBM i]On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first receive exit specified, the second string to the second exit, and so on.

[z/OS]On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first receive exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of receive exit data for each channel.

RCVEXIT(string)
Channel receive exit name.
If this name is nonblank, the exit is called at the following times:
  • Immediately before the received network data is processed.

    The exit is given the complete transmission buffer as received. The contents of the buffer can be modified as required.

  • At initialization and termination of the channel.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

[IBM i]On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

[z/OS]On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one receive exit name for each channel.

The format and maximum length of the name is the same as for MSGEXIT.

REPLACE and NOREPLACE
Whether the existing definition [z/OS](and on z/OS, with the same disposition) is to be replaced with this one. This parameter is optional. Any object with a different disposition is not changed.
REPLACE
The definition replaces any existing definition of the same name. If a definition does not exist, one is created. REPLACE does not alter the channel status.
NOREPLACE
The definition does not replace any existing definition of the same name.
SCYDATA(string)
Channel security exit user data (maximum length 32 characters).

This parameter is passed to the channel security exit when it is called.

SCYEXIT(string)
Channel security exit name.
If this name is nonblank, the exit is called at the following times:
  • Immediately after establishing a channel.

    Before any messages are transferred, the exit is able to instigate security flows to validate connection authorization.

  • Upon receipt of a response to a security message flow.

    Any security message flows received from the remote processor on the remote queue manager are given to the exit.

  • At initialization and termination of the channel.

The format and maximum length of the name is the same as for MSGEXIT but only one name is allowed.

SENDDATA(string)
Channel send exit user data. The maximum length is 32 characters.

This parameter is passed to the channel send exit when it is called.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

[IBM i]On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first send exit specified, the second string to the second exit, and so on.

[z/OS]On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first send exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of send exit data for each channel.

SENDEXIT(string)
Channel send exit name.
If this name is nonblank, the exit is called at the following times:
  • Immediately before data is sent out on the network.

    The exit is given the complete transmission buffer before it is transmitted. The contents of the buffer can be modified as required.

  • At initialization and termination of the channel.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

[IBM i]On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

[z/OS]On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one send exit name for each channel.

The format and maximum length of the name is the same as for MSGEXIT.

SEQWRAP(integer)
When this value is reached, sequence numbers wrap to start again at 1.

This value is nonnegotiable and must match in both the local and remote channel definitions.

The value must be in the range 100 through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

SHARECNV(integer)
Specifies the maximum number of conversations that can be sharing each TCP/IP channel instance. A SHARECNV value of:
1
Specifies no sharing of conversations over a TCP/IP channel instance. Client heartbeating is available whether in an MQGET call or not. Read ahead and client asynchronous consumption are also available, and channel quiescing is more controllable.
0
Specifies no sharing of conversations over a TCP/IP channel instance.

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLNTCONN or SVRCONN. If the client-connection SHARECNV value does not match the server-connection SHARECNV value, the lower of the two values is used. This parameter is ignored for channels with a transport type (TRPTYPE) other than TCP.

All the conversations on a socket are received by the same thread.

High SHARECNV limits have the advantage of reducing queue manager thread usage. However, if many conversations sharing a socket are all busy, there is a possibility of delays as the conversations contend with one another to use the receiving thread. In this situation, a lower SHARECNV value is better.

The number of shared conversations does not contribute to the MAXINST or MAXINSTC totals.

Note: You should restart the client for this change to take effect.
SHORTRTY(integer)
The maximum number of attempts that are made by a sender, server, or cluster-sender channel to connect to the remote queue manager, at intervals specified by SHORTTMR, before the (normally longer) LONGRTY and LONGTMR are used.

Retry attempts are made if the channel fails to connect initially (whether it is started automatically by the channel initiator or by an explicit command), and also if the connection fails after the channel has successfully connected. However, if the cause of the failure is such that more attempts are unlikely to be successful, they are not attempted.

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

SHORTTMR(integer)
For short retry attempts, this parameter is the maximum number of seconds to wait before reattempting connection to the remote queue manager.

The time is approximate; zero means that another connection attempt is made as soon as possible.

The interval between retries might be extended if the channel has to wait to become active.

The value must be in the range zero through 999999999.

Note: For implementation reasons, the maximum retry interval that can be used is 999999; values exceeding this maximum are treated as 999999. Similarly, the minimum retry interval that can be used is 2; values less than this minimum are treated as 2.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

[z/OS][MQ 9.2.0 Jul 2020]SPLPROT
SPLPROT (Security Policy Protection) specifies how a server-to-server Message Channel Agent should deal with message protection when AMS is active and an applicable policy exists.
This parameter applies to z/OS only, from IBM MQ 9.1.3 onwards.
The permitted values are:
PASSTHRU
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 (CHLTYPE) of SDR, SVR, RCVR, or RQSTR, 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 message channel agent 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 SDR or SVR.
ASPOLICY
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 RCVR or RQSTR.
SSLCAUTH
Defines whether IBM MQ requires a certificate from the TLS client. The initiating end of the channel acts as the TLS client, so this parameter applies to the end of the channel that receives the initiation flow, which acts as the TLS server.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, SVRCONN, CLUSRCVR, SVR, or RQSTR.

The parameter is used only for channels with SSLCIPH specified. If SSLCIPH is blank, the data is ignored and no error message is issued.

REQUIRED
IBM MQ requires and validates a certificate from the TLS client.
OPTIONAL
The peer TLS client system might still send a certificate. If it does, the contents of this certificate are validated as normal.
SSLCIPH(string)
Specifies the CipherSpec that is used on the channel. The maximum length is 32 characters.
[z/OS][IBM i]Attention: On IBM MQ for z/OS, you can also specify the four digit hexadecimal code of a CipherSpec, whether or not it appears in the following table. On IBM i, you can also specify the two digit hexadecimal code of a CipherSpec, whether or not it appears in the following table. Also, on IBM i, installation of AC3 is a prerequisite for the use of TLS. You should not specify hexadecimal cipher values in SSLCIPH, because it is unclear from the value which cipher will be used, and the choice of which protocol to be used is indeterminate. Using hexadecimal cipher values can lead to CipherSpec mismatch errors.
The SSLCIPH values must specify the same CipherSpec on both ends of the channel.
This parameter is valid on all channel types that use transport type TRPTYPE(TCP). If the parameter is blank, no attempt is made to use TLS on the channel.
The value for this parameter is also used to set the value of SECPROT, which is an output field on the DISPLAY CHSTATUS command.
Note: When SSLCIPH is used with a telemetry channel, it means TLS Cipher Suite. See the SSLCIPH description for DEFINE CHANNEL (MQTT).

[AIX, Linux, Windows][z/OS][MQ 9.2.0 Jul 2020]From IBM MQ 9.1.1, you can specify a value of ANY_TLS12, which represents a subset of acceptable CipherSpecs that use the TLS 1.2 protocol; these CipherSpecs are listed in the following table. See Migrating existing security configurations to use the ANY_TLS12 CipherSpec for information on changing your existing security configurations to use the ANY_TLS12 value.

[AIX, Linux, Windows][MQ 9.2.0 Jul 2020]From IBM MQ 9.1.4, on AIX, Linux, and Windows, IBM MQ provides an expanded set of alias CipherSpecs that includes ANY_TLS12_OR_HIGHER, and ANY_TLS13_OR_HIGHER. These alias CipherSpecs are listed in the following table.
Attention: If your enterprise needs to guarantee that a certain CipherSpec is negotiated and used, you must not use an alias CipherSpec value such as ANY_TLS12.

[MQ 9.2.0 Jul 2020]For information on changing your existing security configurations to use the ANY_TLS12_OR_HIGHER CipherSpec, see Migrating existing security configurations to use the ANY_TLS12_OR_HIGHER CipherSpec.

Table 8. CipherSpecs you can use with IBM MQ TLS support
Platform support 1 CipherSpec name Protocol used Data integrity Encryption algorithm Encryption bits FIPS 2 Suite B
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]Alias CipherSpecs

All

ANY_TLS13_OR_HIGHER 3 4 5 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated

All

ANY_TLS13 4 5 6 TLS 1.3 Negotiated Negotiated Negotiated Negotiated Negotiated

All

ANY_TLS12_OR_HIGHER 4 5 7 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated

All

ANY_TLS12 8 TLS 1.2 Negotiated Negotiated Negotiated Negotiated Negotiated

All

ANY 9 Negotiated Negotiated Negotiated Negotiated Negotiated Negotiated
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]CipherSpecs for TLS 1.3

All

TLS_AES_128_GCM_SHA2564 5 TLS 1.3 GCM AES-128 with GCM 128 No No

All

TLS_AES_256_GCM_SHA3844 5 TLS 1.3 GCM AES-256 with GCM 256 No No

All

TLS_CHACHA20_POLY1305_SHA2564 5 TLS 1.3 POLY1305 CHACHA20 256 No No

[AIX, Linux, Windows]

TLS_AES_128_CCM_SHA256 TLS 1.3 CBC-MAC AES-128 with CTR 128 No No

[AIX, Linux, Windows]

TLS_AES_128_CCM_8_SHA256 11 TLS 1.3 CBC-MAC AES-128 with CTR 128 No No
CipherSpecs for TLS 1.2
All TLS_RSA_WITH_AES_128_CBC_SHA25610 TLS 1.2 SHA-256 AES 128 Yes No
All TLS_RSA_WITH_AES_256_CBC_SHA256 10 12 TLS 1.2 SHA-256 AES 256 Yes No
All TLS_RSA_WITH_AES_128_GCM_SHA256 10 13 TLS 1.2 SHA-256 and AEAD GCM AES 128 Yes No
All TLS_RSA_WITH_AES_256_GCM_SHA38410 12 13 TLS 1.2 SHA-384 and AEAD GCM AES 256 Yes No
All ECDHE_ECDSA_AES_128_CBC_SHA256 10 TLS 1.2 SHA-256 AES 128 Yes No
All ECDHE_ECDSA_AES_256_CBC_SHA384 10 12 TLS 1.2 SHA-384 AES 256 Yes No
All ECDHE_RSA_AES_128_CBC_SHA256 10 TLS 1.2 SHA-256 AES 128 Yes No
All ECDHE_RSA_AES_256_CBC_SHA384 10 12 TLS 1.2 SHA-384 AES 256 Yes No

[UNIX, Linux, Windows, IBM i]

ECDHE_ECDSA_AES_128_GCM_SHA256 12 13 TLS 1.2 SHA-256 and AEAD GCM AES SHA384 Yes 128 bit

[UNIX, Linux, Windows, IBM i]

ECDHE_ECDSA_AES_256_GCM_SHA384 12 13 TLS 1.2 SHA-384 and AEAD GCM AES SHA384 Yes 192 bit
All ECDHE_RSA_AES_128_GCM_SHA256 13 TLS 1.2 SHA-256 and AEAD GCM AES 128 Yes No
All ECDHE_RSA_AES_256_GCM_SHA384 12 13 TLS 1.2 AEAD AES-128 GCM AES SHA384 Yes No
Notes:
  1. For a list of platforms covered by each platform icon, see Release and platform icons in the product documentation.
  2. Specifies whether the CipherSpec is FIPS-certified on a FIPS-certified platform. See Federal Information Processing Standards (FIPS) for an explanation of FIPS.
  3. [AIX, Linux, Windows][MQ 9.2.0 Jul 2020]The ANY_TLS13_OR_HIGHER alias CipherSpec negotiates the highest level of security that the remote end will allow but will only connect using a TLS 1.3 or higher protocol.
  4. [MQ 9.2.0 Jul 2020][z/OS][MQ 9.2.0 Jul 2020]To use TLS 1.3, or the ANY CipherSpec, on IBM MQ for z/OS, the operating system must be z/OS 2.4 or later.
  5. [IBM i][MQ 9.2.0 Jul 2020]To use TLS 1.3, or the ANY CipherSpec, on IBM i the underlying operating system version must support TLS 1.3. See System TLS support for TLSv1.3 for more information.
  6. [AIX, Linux, Windows][MQ 9.2.0 Jul 2020]The ANY_TLS13 alias CipherSpec represents a subset of acceptable CipherSpecs that use the TLS 1.3 protocol, as listed in this table for each platform.
  7. [AIX, Linux, Windows][MQ 9.2.0 Jul 2020]The ANY_TLS12_OR_HIGHER alias CipherSpec negotiates the highest level of security that the remote end will allow but will only connect using a TLS 1.2 or higher protocol.
  8. [MQ 9.2.0 Jul 2020] The ANY_TLS12 CipherSpec represents a subset of acceptable CipherSpecs that use the TLS 1.2 protocol, as listed in this table for each platform.
  9. [AIX, Linux, Windows][MQ 9.2.0 Jul 2020]The ANY alias CipherSpec negotiates the highest level of security that the remote end will allow.
  10. [IBM i][MQ 9.2.0 Jul 2020]These CipherSpecs are not enabled on IBM i 7.4 systems that have System Value QSSLCSLCTL set to *OPSSYS.
  11. [AIX, Linux, Windows][MQ 9.2.0 Jul 2020]These CipherSpecs use an 8-octet Integrity Check Value (ICV) instead of a 16-octet ICV.
  12. This CipherSpec cannot be used to secure a connection from the IBM MQ Explorer to a queue manager unless the appropriate unrestricted policy files are applied to the JRE used by the Explorer.
  13. [Windows][MQ 9.2.0 Jul 2020][Linux][MQ 9.2.0 Jul 2020]Following a recommendation by GSKit, TLS 1.2 GCM CipherSpecs have a restriction which means that after 2ˆ24.5 TLS records are sent, using the same session key, the connection is terminated with message AMQ9288.

    To prevent this error from happening: avoid using TLS 1.2 GCM Ciphers, enable secret key reset, or start your IBM MQ queue manager or client with the environment variable GSK_ENFORCE_GCM_RESTRICTION=GSK_FALSE set.

    This restriction does not apply to IBM MQ for z/OS.
    Important: The GCM restriction is active, regardless of the FIPS mode being used.

For more information about CipherSpecs, see Enabling CipherSpecs.

When you request a personal certificate, you specify a key size for the public and private key pair. The key size that is used during the SSL handshake can depend on the size stored in the certificate and on the CipherSpec:
  • [AIX, Linux, Windows][z/OS]On z/OS, AIX, Linux, and Windows, when a CipherSpec name includes _EXPORT, the maximum handshake key size is 512 bits. If either of the certificates exchanged during the SSL handshake has a key size greater than 512 bits, a temporary 512-bit key is generated for use during the handshake.
  • [z/OS]For z/OS, System SSL state that if a TLS V1.3 connection is being negotiated:
    • The minimum key size for an RSA peer certificate is the larger of the following two values: 2048, or the value specified in the GSK_PEER_RSA_MIN_KEY_SIZE attribute.
    • The minimum key size for an ECC peer certificate is the larger of the following two values: 256, or the value specified in the GSK_PEER_ECC_MIN_KEY_SIZE attribute.
  • [AIX, Linux, Windows]On UNIX, Linux, and Windows, when a CipherSpec name includes _EXPORT1024, the handshake key size is 1024 bits.
  • Otherwise the handshake key size is the size stored in the certificate.
SSLPEER(string)

Specifies the filter to use to compare with the Distinguished Name of the certificate from the peer queue manager or client at the other end of the channel. (A Distinguished Name is the identifier of the TLS certificate.) If the Distinguished Name in the certificate received from the peer does not match the SSLPEER filter, the channel does not start.

Note: An alternative way of restricting connections into channels by matching against the TLS Subject Distinguished Name, is to use channel authentication records. With channel authentication records, different TLS Subject Distinguished Name patterns can be applied to the same channel. If both SSLPEER on the channel and a channel authentication record are used to apply to the same channel, the inbound certificate must match both patterns in order to connect. For more information, see Channel authentication records.

This parameter is optional; if it is not specified, the Distinguished Name of the peer is not checked at channel startup. (The Distinguished Name from the certificate is still written into the SSLPEER definition held in memory, and passed to the security exit). If SSLCIPH is blank, the data is ignored and no error message is issued.

This parameter is valid for all channel types.

The SSLPEER value is specified in the standard form used to specify a Distinguished Name. For example:
SSLPEER('SERIALNUMBER=4C:D0:49:D5:02:5F:38,CN="H1_C_FR1",O=IBM,C=GB')

You can use a semi-colon as a separator instead of a comma.

The possible attribute types supported are:
Table 9. Attribute types supported by SSLPEER
Summary attribute Description
SERIALNUMBER Certificate serial number
MAIL Email address
E Email address (Deprecated in preference to MAIL)
UID or USERID User identifier
CN Common Name
T Title
OU Organizational Unit name
DC Domain component
O Organization name
STREET Street / First line of address
L Locality name
ST (or SP or S) State or Province name
PC Postal code / zip code
C Country
UNSTRUCTUREDNAME Host name
UNSTRUCTUREDADDRESS IP address
DNQ Distinguished name qualifier
IBM MQ accepts only uppercase letters for the attribute types.

If any of the unsupported attribute types are specified in the SSLPEER string, an error is output either when the attribute is defined or at run time (depending on which platform you are running on), and the string is deemed not to have matched the Distinguished Name of the flowed certificate.

If the Distinguished Name of the flowed certificate contains multiple OU (organizational unit) attributes, and SSLPEER specifies these attributes to be compared, they must be defined in descending hierarchical order. For example, if the Distinguished Name of the flowed certificate contains the OUs OU=Large Unit, OU=Medium Unit, OU=Small Unit, specifying the following SSLPEER values works:
('OU=Large Unit,OU=Medium Unit')
('OU=*,OU=Medium Unit,OU=Small Unit')
('OU=*,OU=Medium Unit')
but specifying the following SSLPEER values fails:
('OU=Medium Unit,OU=Small Unit')
('OU=Large Unit,OU=Small Unit')
('OU=Medium Unit')
('OU=Small Unit, Medium Unit, Large Unit')
As indicated in these examples, attributes at the low end of the hierarchy can be omitted. For example, ('OU=Large Unit,OU=Medium Unit') is equivalent to ('OU=Large Unit,OU=Medium Unit,OU=*')

If two DNs are equal in all respects except for their DC values, the same matching rules apply as for OUs except that in DC values the left-most DC is the lowest-level (most specific) and the comparison ordering differs accordingly.

Any or all the attribute values can be generic, either an asterisk (*) on its own, or a stem with initiating or trailing asterisks. Asterisks allow the SSLPEER to match any Distinguished Name value, or any value starting with the stem for that attribute.

If an asterisk is specified at the beginning or end of any attribute value in the Distinguished Name on the certificate, you can specify '\*' to check for an exact match in SSLPEER. For example, if you have an attribute of CN='Test*' in the Distinguished Name of the certificate, you can use the following command:
SSLPEER('CN=Test\*')

[AIX, Linux, Windows]The maximum length of the parameter is 1024 bytes on AIX, Linux, and Windows.

[IBM i]The maximum length of the parameter is 1024 bytes on IBM i.

[z/OS]The maximum length of the parameter is 256 bytes on z/OS.

Channel authentication records provide greater flexibility when using SSLPEER and support 1024 bytes on all platforms.

STATCHL
Controls the collection of statistics data for channels:
QMGR
The value of the STATCHL parameter of the queue manager is inherited by the channel.
OFF
Statistics data collection is turned off for this channel.
LOW
If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a low rate of data collection, for this channel.
MEDIUM
If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a moderate rate of data collection, for this channel.
HIGH
If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a high rate of data collection, for this channel.

Changes to this parameter take effect only on channels started after the change occurs.

[z/OS]On z/OS systems, enabling this parameter simply turns on statistics data collection, regardless of the value you select. Specifying LOW, MEDIUM, or HIGH makes no difference to your results. This parameter must be enabled in order to collect channel accounting records.

For cluster channels, the value of this parameter is not replicated in the repository and used in the auto-definition of cluster-sender channels. For auto-defined cluster-sender channels, the value of this parameter is taken from the attribute STATACLS of the queue manager. This value might then be overridden in the channel auto-definition exit.

[MQ 9.2.3 Jul 2021][UNIX, Linux, Windows, IBM i]TMPMODEL(string)
The name of the model queue to be used while creating a temporary queue (maximum length 48 characters).
The default queue is SYSTEM.DEFAULT.MODEL.QUEUE.
[MQ 9.2.3 Jul 2021][UNIX, Linux, Windows, IBM i]TMPQPRFX(string)
The temporary queue name prefix to add to the beginning of the model queue when deriving a temporary queue name (maximum length 48 characters).
The default is AMQP.*.
TPNAME(string)
LU 6.2 transaction program name (maximum length 64 characters).

This parameter is valid only for channels with a transport type (TRPTYPE) of LU 6.2.

Set this parameter to the SNA transaction program name, unless the CONNAME contains a side-object name in which case set it to blanks. The actual name is taken instead from the CPI-C Communications Side Object, or the APPC side information data set.

[z/OS]See Configuration parameters for an LU 6.2 connection for more information about configuration parameters for an LU 6.2 connection for your platform.

[Windows][z/OS]On Windows SNA Server, and in the side object on z/OS, the TPNAME is wrapped to uppercase.

This parameter is not valid for channels with a channel type (CHLTYPE) of RCVR.

TPROOT
The topic root for an AMQP channel. The default value for TPROOT is SYSTEM.BASE.TOPIC. With this value, the topic string an AMQP client uses to publish or subscribe has no prefix, and the client can exchange messages with other IBM MQ publish/subscribe applications. To have AMQP clients publish and subscribe under a topic prefix, first create an IBM MQ topic object with a topic string set to the prefix you want, then set TPROOT to the name of the IBM MQ topic object you created.

This parameter is valid only for channels with a channel type (CHLTYPE) of AMQP

TRPTYPE
Transport type to be used.

On all platforms, this parameter is optional because, if you do not enter a value, the value specified in the SYSTEM.DEF.channel-type definition is used. However, no check is made that the correct transport type has been specified if the channel is initiated from the other end.

[z/OS]On z/OS, if the SYSTEM.DEF.channel-type definition does not exist, the default is LU62.

This parameter is required on all other platforms.
LU62
SNA LU 6.2
NETBIOS
[Windows]NetBIOS (supported only on Windows, and DOS).
[z/OS]This attribute also applies to z/OS for defining client-connection channels that connect to servers on the platforms supporting NetBIOS.
SPX
[Windows]Sequenced packet exchange (supported only on Windows, and DOS).
[z/OS]This attribute also applies to z/OS for defining client-connection channels that connect to servers on the platforms supporting SPX.
TCP
Transmission Control Protocol - part of the TCP/IP protocol suite
[UNIX, Linux, Windows, IBM i]USECLTID
Specifies that the client ID should be used for authorization checks for an AMQP channel, instead of the MCAUSER attribute value.
NO
The MCA user ID should be used for authorization checks.
YES
The client ID should be used for authorization checks.
USEDLQ
Determines whether the dead-letter queue is used when messages cannot be delivered by channels.
NO
Messages that cannot be delivered by a channel are treated as a failure. The channel either discards the message, or the channel ends, in accordance with the NPMSPEED setting.
YES
When the DEADQ queue manager attribute provides the name of a dead-letter queue, then it is used, else the behavior is as for NO. YES is the default value.
USERID(string)
Task user identifier. The maximum length is 12 characters.

This parameter is used by the message channel agent when attempting to initiate a secure LU 6.2 session with a remote message channel agent.

[UNIX, Linux, Windows, IBM i]On Multiplatforms, this parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, or CLUSSDR.

[z/OS]On z/OS, it is supported only for CLNTCONN channels.

Although the maximum length of the parameter is 12 characters, only the first 10 characters are used.

On the receiving end, if passwords are kept in encrypted format and the LU 6.2 software is using a different encryption method, an attempt to start the channel fails with invalid security details. You can avoid invalid security details by modifying the receiving SNA configuration to either:
  • Turn off password substitution, or
  • Define a security user ID and password.
XMITQ(string)
Transmission queue name.

The name of the queue from which messages are retrieved. See Rules for naming IBM MQ objects.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR or SVR. For these channel types, this parameter is required.

There is a separate syntax diagram for each type of channel: