DEFINE CHANNEL

PREFERRED

The first connection in a process reading a client channel definition table (CCDT) creates a list of applicable definitions. The list is based on the weightings, with any applicable CLNTWGHT(0) definitions first and in alphabetic 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 was 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 alphabetic order. For C, C++ and .NET (including fully managed .NET) clients the list is updated if the CCDT was modified since the list was created.

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(PREFFERED), 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.

If sharing conversations is enabled with a non-zero channel weighting and AFFINITY(NONE), multiple connections do not have to share an existing channel instance. They can connect to the same queue manager name using different applicable definitions rather than sharing an existing channel instance.

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

Batch heartbeats allow a sending channel to verify that the receiving channel is still active just before committing a batch of messages. 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 received 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 0 - 999999. A value of zero indicates that batch heart beats are not used.

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

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 limit is reached.

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

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

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

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

This parameter is supported on all platforms.

While non-persistent messages sent over an NPMSPEED(FAST) channel are delivered to a queue immediately (without waiting for a complete batch), the messages still contribute to the batch size for a channel and, therefore, cause confirm flows to occur when BATCHSZ messages have flowed.

If the batch flows are causing a performance impact when moving only non-persistent messages, and NPMSPEED is set to FAST, you should consider setting the BATCHSZ to the maximum permissible value of 9999, and BATCHLIM to zero.

Additionally, setting BATCHINT to a high value, for example, 999999999 keeps each batch "open" for longer, even if there are no new messages waiting on the transmission queue.

The above settings minimize the frequency of confirm flows, but be aware that if any persistent messages are moved over a channel with these settings, there will be significant delays in the delivery of those persistent messages only.

The maximum number of uncommitted messages is specified by the MAXUMSGS parameter of the ALTER QMGR command.

The value must be in the range 1 - 9999.

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.

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.

This parameter is required on all types of channel.

On CLUSSDR channels, this parameter can take a different form to the other channel types. If your convention for naming CLUSSDR channels includes the name of the queue manager, you can define a CLUSSDR channel using the +QMNAME+ construction. After connection to the matching CLUSRCVR channel, IBM MQ substitutes the correct repository queue manager name in place of +QMNAME+ in the CLUSSDR channel definition. 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.

On z/OS, CLNTCONN 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.

On CLUSRCVR channels when using automatic cluster setup, this parameter can use some additional inserts:

• +AUTOCL+ resolves to the automatic cluster name
• +QMNAME+ resolves to the local queue manager name.

When using these inserts, both the unexpanded string and the string with the replaced values must fit inside the maximum size of the field. If there are configured automatic cluster full repositories in the AutoCluster configuration, the channel name must also fit in the maximum channel name length when +QMNAME+ is replaced with each of the configured full repository names.

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

If a client application issues MQCONN with a queue manager name of *name a client channel definition can be selected at random. The chosen definition is randomly selected based on the weighting. Any applicable CLNTWGHT(0) definitions selected are selected first in alphabetic order. Randomness in the selection of client connection definitions is not guaranteed.

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 weighting are chosen first and in alphabetic order. If these connections are unsuccessful the definitions with non-zero weighting are chosen based on their weighting.

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 is supported for all transport protocols.

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.

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.

On CLUSRCVR channels, when using automatic cluster setup, this parameter can use the value +AUTOCL+, which is automatically expanded to the name of the automatic cluster.

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

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

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

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

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

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

For CLUSRCVR channels, CONNAME relates to the local queue manager, and for other channels it relates to the target queue manager.

On CLUSRCVR channels, when using automatic cluster setup, this parameter can use any variable configured at queue manager create time surrounded by +; for example +CONNAME+.

See the crtmqm -iv option for more information.

Note: When using these inserts, both the unexpanded inserts and the expanded values must fit inside the field maximum size.

On z/OS, CONNAME is mandatory for CLUSRCVR channels. In addition, whether you specify CONNAME, or the name is generated for you, the CONNAME produced must be a valid connection name for the local queue manager, otherwise the full repository is not able to make a connection back to the local queue manager.

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

On Multiplatforms, the maximum length of the string is 264 characters

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.

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

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.

NO

No conversion by sender

YES

Conversion by sender

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

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

PRIVATE

The intended disposition of the channel is as a private channel.

FIXSHARED

The intended disposition of the channel is as a shared channel associated with a specific queue manager.

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.

NO (default)

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.

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

The value must be in the range 0 - 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, DISCINT has a different interpretation. It 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 applies only 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 specifies the approximate time between heartbeat flows sent by a message channel agent (MCA). The flows are sent 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 are allocated for large messages. They also close any queues that are left open at the receiving end of the channel.

The value is in seconds and must be in the range 0 - 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 SVRCONN and CLNTCONN channels, heartbeats can flow from both the server side as well as the client side independently. If no data is transferred across the channel during the heartbeat interval, the CLNTCONN MQI agent sends a heartbeat flow. The SVRCONN MQI agent responds to it with another heartbeat flow. The flows happen 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 SVRCONN MQI agent is also capable of initiating a heartbeat to the client, again irrespective of the state of the channel. The SVRCONN and CLNTCONN MQI agents are prevented from heart beating to each other at the same time. The server heartbeat is flowed if no data is 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).

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

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

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

Although the KAINT parameter is available on all platforms, its setting is implemented only on z/OS.

On Multiplatforms, you can access and modify the parameter, but there is no functional implementation of the parameter, it is only stored and forwarded. 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. 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 99999.

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 keepalive value used is that specified by the INTERVAL statement in the TCP/IP PROFILE configuration data set.

If AUTO is specified for KAINT, and it is a server-connection channel, the TCP INTERVAL value is used instead for the keepalive interval.

In this case, KAINT is zero in DISPLAY CHSTATUS; it would be non-zero if an integer had been coded instead of AUTO.

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

LIKE(SYSTEM.DEF.SENDER)

These default channel definitions can be altered by the installation to the default values required.

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.

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.

LOCLADDR([ip-addr][(low-port[,high-port])][,[ip-addr][(low-port[,high-port])]])

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.

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.

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.

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.

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 IPv4 or IPv6 address if a choice is available, or to use a particular network adapter on a system with multiple network adapters.

If this count is exhausted without success, an error is logged to the operator, and the channel stops. In this circumstance, the channel must be restarted with a command. It is not started automatically by the channel initiator.

The LONGRTY value must be in the range 0 - 9999999.

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

A channel attempts to reconnect if it fails to connect initially, whether it is started automatically by the channel initiator or by an explicit command. It also tries to connect again if the connection fails after the channel successfully connecting. If the cause of the failure is such that more attempts are unlikely to be successful, they are not attempted.

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

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

The LONGTMR value must be in the range 0 - 9999999.

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

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

The value must be in the range 0 - 999999999.

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

New instances of SVRCONN channels cannot start if the number of running instances equals or exceeds the value of this parameter. If MAXINST is changed to less than the number of instances of the SVRCONN channel that are currently running, the number of running instances is not affected.

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.

The value must be in the range 0 - 999999999.

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

If you reduce the value of MAXINSTC to less than the number of instances of the SVRCONN channel that is currently running from an individual client, the running instances are not affected. New SVRCONN instances from that client cannot start until the client is running fewer instances than the value of MAXINSTC.

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

The value zero means the maximum message length for the queue manager; see ALTER QMGR MAXMSGL.

On Multiplatforms, specify a value in the range zero to the maximum message length for the queue manager.

On z/OS, specify a value in the range 0 - 104857600 bytes (100 MB).

Note that by adding the digital signature and key to the message, Advanced Message Security increases the length of the message.

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

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 though the port number specified on the listener.

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

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.

This parameter interacts with PUTAUT, see PUTAUT.

If MCAUSER is nonblank, a user identifier is used by the message channel agent for authorization to access IBM MQ resources. If PUTAUT is DEF, authorization includes authorization to put the message to the destination queue for RCVR or RQSTR channels.

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

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.

This parameter is valid only for channels with a transport type (TRPTYPE) of LU62. If TRPTYPE is not LU62, 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. If CONNAME is a a side-object name 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, see Configuration parameters for an LU 6.2 connection.

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

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 is turned on. Data us collected at a low rate for this channel.

MEDIUM

If the value of the queue manager MONCHL parameter is not NONE, online monitoring data is turned on. Data us collected at a medium rate for this channel.

HIGH

If the value of the queue manager MONCHL parameter is not NONE, online monitoring data is turned on. Data us collected at a high rate for this channel.

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

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

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.

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

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

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. The number of attempts to redeliver the message is controlled by the exit, and not by this parameter.

The value must be in the range 0 - 999999999. A value of zero means that no attempts to redeliver the message are tried.

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

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. The number of attempts to redeliver the message is controlled by the exit, and not by this parameter.

The value must be in the range 0 - 999999999. A value of zero means that if the value of MRRTY is greater than zero, the channel reattempts delivery as soon as possible.

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

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

On UNIX, 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.

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.

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.

MSGEXIT is accepted and ignored by CLNTCONN and SVRCONN channels. CLNTCONN or SVRCONN channels do not call message exits.

If the MSGEXIT, MREXIT, SCYEXIT, SENDEXIT, and RCVEXIT parameters are all left blank, the channel user exit is not invoked. If any of these parameters is nonblank, the channel exit program is called. You can enter text string for these parameters. The maximum length of the string is 128 characters.

Table 6. Message exit format and length

Platform	Exit name format	Maximum length	Comment
UNIX and Linux	libraryname (functionname)	128	You can specify the name of more than one exit program. Specify multiple strings separated by commas. However, the total number of characters specified must not exceed 999.
Windows	dllname (functionname)	128	You can specify the name of more than one exit program. Specify multiple strings separated by commas. However, the total number of characters specified must not exceed 999. dllname is specified without the suffix (.DLL).
IBM i	progname libname	20	You can specify the names of up to 10 exit programs by specifying multiple strings separated by commas. program name occupies the first 10 characters and libname the second 10 characters. If necessary, both fields are padded to the right with blanks.
z/OS	loadModuleName	8	You can specify the names of up to eight exit programs by specifying multiple strings separated by commas. 128 characters are allowed for exit names for CLNTCONN channels, subject to a maximum total length including commas of 999.

This parameter is valid only for CLUSRCVR channels.

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.

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

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

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.

PROPCTL specifies what happens to message properties when a message is sent to another queue manager; see

This parameter is applicable to SDR, SVR, CLUSSDR, and CLUSRCVR channels.

This parameter is optional.

DEF

The default user ID is used.

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.

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

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.

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.

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 the channel initiator connection. For more information about which user IDs are checked, see User IDs used by the channel initiator.

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.

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

For CLNTCONN channels, QMNAME is the name of a queue manager to which an IBM MQ MQI client application can request connection. QMNAME is not necessarily the same as the name of the queue manager on which the channel is defined; see Queue manager groups in the CCDT.

For channels of other types, the QMNAME parameter is not valid.

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

DEFINE CHANNEL(channel-name) CHLTYPE(type) 
REPLACE QSGDISP(COPY)

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

On UNIX, 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.

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.

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.

On UNIX, 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.

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

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.

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

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

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

On UNIX, 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.

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.

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.

On UNIX, 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.

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

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.

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

The value must be in the range 100 - 999999999.

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

1

Specifies no sharing of conversations over a TCP/IP channel instance. Client heart beating 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 CLNTCONN SHARECNV value does not match the SVRCONN 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. If many conversations sharing a socket are all busy, there is a possibility of delays. 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.

The value must be in the range 0 - 999999999.

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

A channel attempts to reconnect if it fails to connect initially, whether it is started automatically by the channel initiator or by an explicit command. It also tries to connect again if the connection fails after the channel successfully connecting. If the cause of the failure is such that more attempts are unlikely to be successful, they are not attempted.

The time is approximate. From IBM MQ 8.0, zero means that another connection attempt is made as soon as possible.

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

The value must be in the range 0 - 999999999.

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

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.

Specifies the certificate filter used by the peer queue manager or client at the other end of the channel. The filter is used to compare with the distinguished name of the certificate. 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.

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

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.

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. When the error is output depends on which platform you are running on. An error implies that the SSLPEER string does not match the distinguished name of the flowed certificate.

('OU=Large Unit,OU=Medium Unit')
('OU=*,OU=Medium Unit,OU=Small Unit')
('OU=*,OU=Medium Unit')

('OU=Medium Unit,OU=Small Unit')
('OU=Large Unit,OU=Small Unit')
('OU=Medium Unit')
('OU=Small Unit, Medium Unit, Large Unit')

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

SSLPEER('CN=Test\*')

The maximum length of the parameter is 1024 bytes on Multiplatforms.

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.

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. Data is collected at a low rate for this channel.

MEDIUM

If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on.Data is collected at a medium rate for this channel.

HIGH

If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on.Data is collected at a high rate for this channel.

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

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 therefore is not used in the auto-definition of CLUSSDR channels. For auto-defined CLUSSDR 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.

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

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. See Configuration parameters for an LU 6.2 connection

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.

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

LU62

SNA LU 6.2

NETBIOS

Supported on Windows, and DOS.

Also used on z/OS for defining client-connection channels that connect to servers on the platforms supporting NetBIOS.

SPX

Sequenced packet exchange

Supported on Windows, and DOS.

Also used on 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.

If you do not enter a value for this parameter, the value specified in the SYSTEM.DEF.channel-type definition is used. If the channel is initiated from the other end, no check is made that the correct transport type is specified.

On Multiplatforms, if the SYSTEM.DEF.channel-type definition does not exist, you must specify a value.

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

NO

The MCA user ID should be used for authorization checks.

YES

The client ID should be used for authorization checks.

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.

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.

On Multiplatforms, this parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, or CLUSSDR.

On z/OS, this parameter is supported only for CLNTCONN channels.

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

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.