Overview

This resource allows you to manage a MQ Channel.

Here is an example on how you should use this with the CHLTYPE in the name:

  mq_channel { 'QM1/RCVR/EM_TEST_CHANNEL':
    ensure   => 'present',
    comphdr  => 'NONE',
    compmsg  => 'NONE',
    hbint    => '320',
    kaint    => 'AUTO',
    maxmsgl  => '4194304',
    monchl   => 'QMGR',
    npmspeed => 'FAST',
    seqwrap  => '999999999',
    sslcauth => 'REQUIRED',
    statchl  => 'QMGR',
    trptype  => 'TCP',
    usedlq   => 'YES',
  }

Here is an deprecated example on how you should use this:

  mq_channel { 'QM1/EM_TEST_CHANNEL':
    ensure   => 'present',
    chltype  => 'RCVR',
    comphdr  => 'NONE',
    compmsg  => 'NONE',
    hbint    => '320',
    kaint    => 'AUTO',
    maxmsgl  => '4194304',
    monchl   => 'QMGR',
    npmspeed => 'FAST',
    seqwrap  => '999999999',
    sslcauth => 'REQUIRED',
    statchl  => 'QMGR',
    trptype  => 'TCP',
    usedlq   => 'YES',
  }

Experience the Power of Puppet for IBM MQ

If you want to play and experiment with Puppet and IBM MQ, please take a look at our playgrounds. At our playgrounds, we provide you with a pre-installed environment, where you experiment fast and easy.

Attributes

Attribute Name Short Description
affinity Use the channel affinity attribute when client applications connect multiple times using the same queue manager name.
amqpka The keep alive time for an AMQP channel in seconds.
backlog  
   
batchhb Specifies whether batch heartbeats are to be used.
batchint The minimum amount of time, in milliseconds, that a channel keeps a batch open.
batchlim The limit, in kilobytes, of the amount of data that can be sent through a channel before taking a sync point.
batchsz The maximum number of messages that can be sent through a channel before taking a sync point.
certlabl Certificate label for this channel to use.
channel The name of the channel.
chltype The type of channel to manage.
clntwght Set the client channel weighting attribute to select a client channel definition at random based on its weighting when more than one suitable definition is available.
clusnl The name of the namelist that specifies a list of clusters to which the channel belongs.
cluster The name of the cluster to which the channel belongs.
clwlprty Specifies the priority of the channel for the purposes of cluster workload distribution.
clwlrank Specifies the rank of the channel for the purposes of cluster workload distribution.
clwlwght Specifies the weighting to be applied to a channel so that the proportion of messages sent down the channel can be controlled by workload management.
comphdr The list of header data compression techniques supported by the channel.
compmsg The list of message data compression techniques supported by the channel.
conname Connection name.
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.
defcdisp Specifies the default channel disposition of the channel.
defrecon Specifies whether a client connection automatically reconnects a client application if its connection breaks.
descr Plain-text comment.
disable_corrective_change Disable the modification of a resource when Puppet decides it is a corrective change.
disable_corrective_ensure Disable the creation or removal of a resource when Puppet decides is a corrective change.
discint The minimum time in seconds for which the channel waits for a message to arrive on the transmission queue.
ensure The basic property that the resource should be in.
hbint HBINT specifies the approximate time between heartbeat flows sent by a message channel agent (MCA).
kaint The value passed to the communications stack for keepalive timing for this channel.
like The name of a channel.
locladdr LOCLADDR is the local communications address for the channel.
longrty The LONGRTY parameter specifies the maximum number of further attempts that are made by a SDR, SVR, or CLUSSDR channel to connect to a remote queue manager.
longtmr For LONGRTY, LONGTMR is the maximum number of seconds to wait before reattempting connection to the remote queue manager.
maxinst The maximum number of simultaneous instances of an individual SVRCONN channel or AMQP channel that can be started.
maxinstc The maximum number of simultaneous individual SVRCONN channels that can be started from a single client.
maxmsgl Specifies the maximum message length that can be transmitted on the channel.
mcaname Message channel agent name.
mcatype Specifies whether the message-channel-agent program on an outbound message channel runs as a thread or a process.
mcauser Message channel agent user identifier.
modename LU 6.2 mode name (maximum length 8 characters).
monchl Controls the collection of online monitoring data for channels.
mrdata Channel message-retry exit user data.
mrexit Channel message-retry exit name.
mrrty The number of times the channel tries again before it decides it cannot deliver the message.
mrtmr The minimum interval of time that must pass before the channel can try the MQPUT operation again.
msgdata User data for the channel message exit.
msgexit Channel message exit name.
name The full name of the channel.
netprty The priority for the network connection.
npmspeed The class of service for nonpersistent messages on this channel.
password Password used by the message channel agent when attempting to initiate a secure LU 6.2 session with a remote message channel agent.
port The port number used to connect an AMQP channel.
propctl Property control attribute; see PROPCTL channel options.
provider resource.
putaut PUTAUT specifies which user identifiers are used to establish authority for a channel.
qmgr The name of the queue manager containing the specfied queue.
qmname Queue manager name.
rcvdata Channel receive exit user data (maximum length 32 characters).
rcvexit Channel receive exit name.
replace Replace the existing definition with this one, or not.
scydata Channel security exit user data (maximum length 32 characters).
scyexit Channel security exit name.
senddata Channel send exit user data.
sendexit Channel send exit name.
seqwrap When this value is reached, sequence numbers wrap to start again at 1.
sharecnv Specifies the maximum number of conversations that can be sharing each TCP/IP channel instance.
shortrty SHORTRTY specifies the maximum number of attempts that are made by a SDR, SVR, or CLUSSDR channel to connect to the remote queue manager, at intervals specified by SHORTTMR.
shorttmr For SHORTRTY, SHORTTMR is the maximum number of seconds to wait before reattempting connection to the remote queue manager.
sslcauth SSLCAUTH defines whether IBM MQ requires a certificate from the TLS client.
sslciph SSLCIPH specifies the CipherSpec that is used on the channel.
sslpeer Specifies the certificate filter used by the peer queue manager or client at the other end of the channel.
statchl Controls the collection of statistics data for channels.
tpname LU 6.2 transaction program name (maximum length 64 characters).
tproot The topic root for an AMQP channel.
trptype Transport type to be used.
usecltid Distributed[V9.0.0.0 Jun 2016]Specifies that the client ID should be used for authorization checks for an AMQP channel, instead of the MCAUSER attribute value.
usedlq Determines whether the dead-letter queue is used when messages cannot be delivered by channels.
userid Task user identifier.
xmitq Transmission queue name.

affinity

Use the channel affinity attribute when client applications connect multiple times using the same queue manager name. With the attribute, you can choose whether the client uses the same client channel definition for each connection. This attribute is intended to be used when multiple applicable channel definitions are available. Valid values are:

  • 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. For example, suppose that we had the following definitions in the CCDT: 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.

Valid values are PREFERRED, NONE.

Back to overview of mq_channel

amqpka

The keep alive time for an AMQP channel in seconds. 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

Back to overview of mq_channel

backlog

Back to overview of mq_channel

batchhb

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

Back to overview of mq_channel

batchint

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 are sent. BATCHLIM kilobytes are 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 limit is reached). This parameter is valid for channels with a channel type ( CHLTYPE ) of only SDR, SVR, CLUSSDR, and CLUSRCVR.

Back to overview of mq_channel

batchlim

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. The batch is terminated when one of the following conditions is met:

  • BATCHSZ messages are sent.
  • BATCHLIM kilobytes are sent. The transmission queue is empty and BATCHINT is exceeded. 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.

Back to overview of mq_channel

batchsz

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).
  • On distributed platforms, 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).
  • On distributed platforms, 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 - 9999.

Back to overview of mq_channel

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, 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. 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 prior to Version 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.

Back to overview of mq_channel

channel

The name of the channel.

This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.

Back to overview of mq_channel

chltype

The type of channel to manage. This is a required value. Valid values are:

  • SDR
  • SVR
  • RCVR
  • RQSTR
  • CLNTCONN
  • SVRCONN
  • CLUSSDR
  • CLUSRCVR
  • AMQP
  • MQTT

This is an immutable property. So you cannot change it.

This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.

Valid values are SDR, SVR, RCVR, RQSTR, CLNTCONN, SVRCONN, CLUSSDR, CLUSRCVR, AMQP, MQTT.

Back to overview of mq_channel

clntwght

Set the client channel weighting attribute to select a client channel definition at random based on its 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 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. For example, suppose that we had the following two definitions in the CCDT: 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. For example, suppose that we had the following four definitions in the CCDT: 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.

Back to overview of mq_channel

clusnl

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.

Back to overview of mq_channel

cluster

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 and CLUSRCVR channels. Only one of the resultant values of CLUSTER or CLUSNL can be nonblank, the other must be blank.

Back to overview of mq_channel

clwlprty

Specifies the priority of the channel for the purposes of cluster workload distribution. The value must be in the range 0 - 9 where 0 is the lowest priority and 9 is the highest. 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.

Back to overview of mq_channel

clwlrank

Specifies the rank of the channel for the purposes of cluster workload distribution. The value must be in the range 0 - 9 where 0 is the lowest rank and 9 is the highest. 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.

Back to overview of mq_channel

clwlwght

Specifies the weighting to be applied to a channel so that the proportion of messages sent down the channel can be controlled by workload management. The value must be in the range 1 - 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 and CLUSRCVR channels. For more information about this attribute, see CLWLWGHT channel attribute.

Back to overview of mq_channel

comphdr

The list of header data compression techniques supported by the channel. For SDR, SVR, CLUSSDR, CLUSRCVR, and CLNTCONN channels, the values must be specified in order of preference. The first compression technique in the list that is supported by the remote end of the channel is used. The mutually supported compression techniques of the channel are passed to the message exit of the sending channel. The message exit can alter the compression technique on a per message basis. Compression alters the data passed to send and receive exits. Valid values are:

  • NONE No header data compression is performed.
  • SYSTEM Header data compression is performed.

Valid values are NONE, SYSTEM.

Back to overview of mq_channel

compmsg

The list of message data compression techniques supported by the channel. For SDR, SVR, CLUSSDR, CLUSRCVR, and CLNTCONN channels, the values must be specified in order of preference. The first compression technique in the list that is supported by the remote end of the channel is used. The mutually supported compression techniques of the channel are passed to the message exit of the sending channel. The message exit can alter the compression technique on a per message basis. Compression alters the data passed to send and receive exits. Valid values are:

  • 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 RCVR, RQSTR, and SVRCONN channels.

Valid values are NONE, RLE, ZLIBFAST, ZLIBHIGH, ANY.

Back to overview of mq_channel

conname

Connection name. For CLUSRCVR channels, CONNAME relates to the local queue manager, and for other channels it relates to the target queue manager. [z/OS]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. [z/OS]On z/OS, the maximum length of the string is 48 characters. On distributed platforms, 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. 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 Version 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 Version 7.0.1. On AIX, HP-UX, IBM i, Linux, Solaris, and Windows platforms, 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. Tip 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: LU62 [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: 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 CLNTCONN 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 CLUSRCVR channels, the side information is on the other queue managers in the cluster. Alternatively, 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. On AIX, HP-UX, IBM i, Linux, Solaris, and Windows , CONNAME is the name of the CPI-C communications side object. Alternatively, if the TPNAME is not blank, CONNAME is the fully qualified name of the partner logical unit [z/OS]; 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 CLUSRCVR 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 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. Do not include the IP_name or input port for channels with a channel type ( CHLTYPE ) of CLUSSDR. On AIX, HP-UX, Linux, IBM i, Solaris, Windows[z/OS], and z/OS, you do not always need to specify the network address of your queue manager. If you define a channel with a channel type ( CHLTYPE ) of CLUSRCVR that is using TCP/IP, IBM MQ generates a CONNAME for you. It assumes the default port and uses the current IPv4 address of the system. If the system does not have an IPv4 address, the current IPv6 address of the system is used. Note If you are using clustering between IPv6 -only and IPv4 -only queue managers, do not specify an IPv6 network address as the CONNAME for CLUSRCVR channels. A queue manager that is capable only of IPv4 communication is unable to start a CLUSSDR channel definition that specifies the CONNAME in IPv6 hexadecimal form. Consider, instead, using host names in a heterogeneous IP environment.

Back to overview of mq_channel

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. Valid values are:

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

Valid values are NO, YES.

Back to overview of mq_channel

defcdisp

Specifies the default channel disposition of the channel. Valid values are:

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

Valid values are PRIVATE, FIXSHARED, SHARED.

Back to overview of mq_channel

defrecon

Specifies whether a client connection automatically reconnects a client application if its connection breaks. Valid values are:

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

Valid values are NO, YES, QMGR, DISABLED.

Back to overview of mq_channel

descr

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 the information is sent to another queue manager they might be translated incorrectly. The characters must be in the coded character set identifier (CCSID) of the local queue manager.

Back to overview of mq_channel

disable_corrective_change

Disable the modification of a resource when Puppet decides it is a corrective change.

(requires easy_type V2.11.0 or higher)

When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.

Using the disable_corrective_change parameter, you can disable corrective changes on the current resource.

Here is an example of this:

crucial_resource {'be_carefull':
  ...
  disable_corrective_change => true,
  ...
}

When a corrective ensure does happen on the resource Puppet will not modify the resource and signal an error:

    Error: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change
    Error: /Stage[main]/Main/Crucial_resource[be_carefull]/parameter: change from '10' to '20' failed: Corrective change present requested by catalog, but disabled by parameter disable_corrective_change. (corrective)

Back to overview of mq_channel

disable_corrective_ensure

Disable the creation or removal of a resource when Puppet decides is a corrective change.

(requires easy_type V2.11.0 or higher)

When using a Puppet Server, Puppet knows about adaptive and corrective changes. A corrective change is when Puppet notices that the resource has changed, but the catalog has not changed. This can occur for example, when a user, by accident or willingly, changed something on the system that Puppet is managing. The normal Puppet process then repairs this and puts the resource back in the state as defined in the catalog. This process is precisely what you want most of the time, but not always. This can sometimes also occur when a hardware or network error occurs. Then Puppet cannot correctly determine the current state of the system and thinks the resource is changed, while in fact, it is not. Letting Puppet recreate remove or change the resource in these cases, is NOT wat you want.

Using the disable_corrective_ensure parameter, you can disable corrective ensure present or ensure absent actions on the current resource.

Here is an example of this:

crucial_resource {'be_carefull':
  ensure                    => 'present',
  ...
  disable_corrective_ensure => true,
  ...
}

When a corrective ensure does happen on the resource Puppet will not create or remove the resource and signal an error:

    Error: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure.
    Error: /Stage[main]/Main/Crucial_resource[be_carefull]/ensure: change from 'absent' to 'present' failed: Corrective ensure present requested by catalog, but disabled by parameter disable_corrective_ensure. (corrective)

Back to overview of mq_channel

discint

The minimum time in seconds for which the channel waits for a message to arrive on the transmission queue. The waiting period starts after a batch ends. After the end of the waiting period, if there are no more messages, the channel is ended. A value of zero causes the message channel agent to wait indefinitely. 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.

Back to overview of mq_channel

ensure

The basic property that the resource should be in.

Valid values are present, absent.

Back to overview of mq_channel

hbint

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. On SVRCONN and CLNTCONN channels, heartbeats flow only when a server MCA is waiting for an MQGET command with the WAIT option specified. The server MCA issues an MQGET on behalf of a client application that issues an MQGET.

Back to overview of mq_channel

kaint

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, 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 distributed platforms, 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. Keepalive must also be switched on within TCP/IP itself. Refer to your TCP/IP documentation for information about configuring keepalive. On AIX, use the no command. On HP-UX, use the ndd command. 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. On distributed platforms, 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 Solaris, for example, flows to (and is implemented by) z/OS queue managers that are in, or join, the cluster. On distributed platforms, 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.

Back to overview of mq_channel

like

The name of a channel. The parameters of this channel are used to model this definition. If you do not set LIKE, and do not set a parameter field related to the command, its value is taken from one of the default channels. The default values depend 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 CLUSSDR channel SYSTEM.DEF.CLUSRCVR Cluster-receiver channel SYSTEM.DEF.AMQP AMQP channel This parameter is equivalent to defining the following object: LIKE(SYSTEM.DEF.SENDER) for a SDR channel, and similarly for other channel types. 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 QSGDISP(GROUP) objects are not searched. LIKE is ignored if QSGDISP(COPY) is specified. However, the group object defined is used as a LIKE object.

Back to overview of mq_channel

locladdr

LOCLADDR is the local communications address for the channel. 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 IPv4 or IPv6 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. This 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: IPv4 dotted decimal For example 192.0.2.1 IPv6 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 3. 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.

Back to overview of mq_channel

longrty

The LONGRTY parameter specifies the maximum number of further attempts that are made by a SDR, SVR, or CLUSSDR channel to connect to a remote queue manager. The interval between attempts is specified by LONGTMR. The LONGRTY parameter takes effect if the count specified by SHORTRTY is exhausted. 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.

Back to overview of mq_channel

longtmr

For LONGRTY, LONGTMR 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 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. Note For implementation reasons, the maximum LONGTMR value is 999,999; values exceeding this maximum are treated as 999,999. Similarly, the minimum interval between attempting to reconnect is 2 seconds. Values less than this minimum are treated as 2 seconds. This parameter is valid only for channels with a channel type ( CHLTYPE ) of SDR, SVR, CLUSSDR, or CLUSRCVR.

Back to overview of mq_channel

maxinst

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. [V9.0.0.0 Jun 2016]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.

Back to overview of mq_channel

maxinstc

The maximum number of simultaneous individual SVRCONN 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 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.

Back to overview of mq_channel

maxmsgl

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; see ALTER QMGR MAXMSGL. On AIX, HP-UX, IBM i, Linux, Solaris, and Windows, specify a value in the range zero to the maximum message length for the queue manager. [z/OS]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.

Back to overview of mq_channel

mcaname

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

Back to overview of mq_channel

mcatype

Specifies whether the message-channel-agent program on an outbound message channel runs as a thread or a process.

Valid values are:

  • 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. This parameter is valid only for channels with a channel type ( CHLTYPE ) of SDR, SVR, RQSTR, CLUSSDR, or CLUSRCVR. It is supported only on AIX, HP-UX, IBM i, Linux, Solaris, and Windows. [z/OS]On z/OS, it 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.

Valid values are PROCESS, THREAD.

Back to overview of mq_channel

mcauser

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 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. The default user identifier is derived from the user ID that started the receiving channel. The possible values are: [z/OS]z/OS, [z/OS]The user ID assigned to the channel-initiator started task by the z/OS started-procedures table. TCP/IP, distributed platforms The user ID from the inetd.conf entry, or the user that started the listener. SNA, distributed platforms The user ID from the SNA server entry. In the absence of the user ID from the SNA server entry, the user from the incoming attach request, or the user that started the listener. NetBIOS or SPX The user ID that started the listener. The maximum length of the string is 64 characters on Windows and 12 characters on other platforms. 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.

Back to overview of mq_channel

modename

LU 6.2 mode name (maximum length 8 characters). 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 [z/OS]; 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.

Back to overview of mq_channel

monchl

Controls the collection of online monitoring data for channels. Valid values are:

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

Valid values are QMGR, OFF, LOW, MEDIUM, HIGH.

Back to overview of mq_channel

mrdata

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.

Back to overview of mq_channel

mrexit

Channel message-retry exit name. 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.

Back to overview of mq_channel

mrrty

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

Back to overview of mq_channel

mrtmr

The minimum interval of time that must pass before the channel can try the MQPUT operation again. The 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. 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.

Back to overview of mq_channel

msgdata

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. On AIX, HP-UX, Linux, Solaris, 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. [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 SVRCONN and CLNTCONN channels.

Back to overview of mq_channel

msgexit

Channel message exit name. If MSGEXIT is nonblank the exit is called at the following times: Immediately after a SDR or SVR channel retrieves a message from the transmission queue. Immediately before a RQSTR channel puts a message on destination queue. When the channel is initialized or ended. The exit is passed the entire application message and transmission queue header for modification. MSGEXIT is accepted and ignored by CLNTCONN and SVRCONN channels. CLNTCONN or SVRCONN channels do not call message exits. The format and maximum length of the exit name depends on the platform; see Table 5. 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.

Back to overview of mq_channel

name

The full name of the channel. A channel’s full name constists of the name of the Queue manager a slash and then the name of the channel. Here is an example:

QMGR1/RCVR/MY.FIRST.CHANNEL

Back to overview of mq_channel

netprty

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 0 - 9; 0 is the lowest priority. This parameter is valid only for CLUSRCVR channels.

Back to overview of mq_channel

npmspeed

The class of service for nonpersistent messages on this channel. Valid values are:

  • 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 value of NPMSPEED differs between the sender and receiver, or either one does not support it, NORMAL is used. This parameter is valid only for channels with a CHLTYPE of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

Valid values are FAST, NORMAL.

Back to overview of mq_channel

password

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

Back to overview of mq_channel

port

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.

Back to overview of mq_channel

propctl

Property control attribute; see PROPCTL channel options. 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. 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. Message properties Result The message contains a property with a prefix of mcd., jms., usr. or mqext. If the Support value is MQPD_SUPPORT_OPTIONAL, all optional message properties are placed in one or more MQRFH2 headers. This rule does not apply to properties in the message descriptor or extension, which remain in the same place. Optional message properties are moved into 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. 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 Version 6 or prior queue manager. NONE All properties of the message, except properties in the message descriptor or extension, are removed from the message. The properties are removed 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. The error is reported in accordance with the report options set in the message header. 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.

Valid values are COMPAT, NONE, ALL.

Back to overview of mq_channel

provider

The specific backend to use for this mq_channel resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.Available providers are:

simple
Manage MQ Channels

Back to overview of mq_channel

putaut

PUTAUT specifies which user identifiers are used to establish authority for a channel. It specifies the user identifier to put messages to the destination queue using a message channel, or to run an MQI call using an MQI channel. 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 [z/OS]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 [z/OS]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. [z/OS]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 distributed platforms, this parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR. [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.

Valid values are DEF, CTX.

Back to overview of mq_channel

qmgr

The name of the queue manager containing the specfied queue.

This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.

Back to overview of mq_channel

qmname

Queue manager name. 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.

Back to overview of mq_channel

rcvdata

Channel receive exit user data (maximum length 32 characters). This parameter is passed to the channel receive exit when it is called. On AIX, HP-UX, Linux, Solaris, 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. [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.

Back to overview of mq_channel

rcvexit

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][HP-UX][Linux][Solaris][Windows]On AIX, HP-UX, Linux, Solaris, 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. [IBMi]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.

Back to overview of mq_channel

replace

Replace the existing definition with this one, or not. This parameter is optional. [z/OS]On z/OS it must have the same disposition. Any object with a different disposition is not changed. Valid values are:

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

Back to overview of mq_channel

scydata

Channel security exit user data (maximum length 32 characters). This parameter is passed to the channel security exit when it is called.

Back to overview of mq_channel

scyexit

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.

Back to overview of mq_channel

senddata

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][HP-UX][Linux][Solaris][Windows]On AIX, HP-UX, Linux, Solaris, 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. [IBMi]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.

Back to overview of mq_channel

sendexit

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][HP-UX][Linux][Solaris][Windows]On AIX, HP-UX, Linux, Solaris, 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. [IBMi]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.

Back to overview of mq_channel

seqwrap

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

Back to overview of mq_channel

sharecnv

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 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. Note You should restart the client for this change to take effect.

Back to overview of mq_channel

shortrty

SHORTRTY specifies the maximum number of attempts that are made by a SDR, SVR, or CLUSSDR channel to connect to the remote queue manager, at intervals specified by SHORTTMR. After the number of attempts is exhausted, the channel tries to reconnect using to the schedule defined by LONGRTY. 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.

Back to overview of mq_channel

shorttmr

For SHORTRTY, SHORTTMR is the maximum number of seconds to wait before reattempting connection to the remote queue manager. The time is approximate. From IBM MQ Version 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. Note For implementation reasons, the maximum SHORTTMR value is 999,999; values exceeding this maximum are treated as 999,999. From IBM MQ Version 8.0, if SHORTTMR is set to 1 then the minimum interval between attempting to connect is 2 seconds. This parameter is valid only for channels with a channel type ( CHLTYPE ) of SDR, SVR, CLUSSDR, or CLUSRCVR.

Back to overview of mq_channel

sslcauth

SSLCAUTH defines whether IBM MQ requires a certificate from the TLS client. The TLS client is the initiating end of the channel. SSLCAUTH is applied to the TLS server, to determine the behavior required of the client. The TLS server is the end of the channel that receives the initiation flow. 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.

Valid values are REQUIRED, OPTIONAL.

Back to overview of mq_channel

sslciph

SSLCIPH specifies the CipherSpec that is used on the channel. The maximum length is 32 characters. This parameter is valid on all channel types which use transport type TRPTYPE(TCP). If the SSLCIPH parameter is blank, no attempt is made to use SSL on the channel. Specify the name of the CipherSpec you are using. The CipherSpecs that can be used with IBM MQ SSL support are shown in the following table. The SSLCIPH values must specify the same CipherSpec on both ends of the channel.

Back to overview of mq_channel

sslpeer

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. 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. Both SSLPEER and a channel authentication record can be applied to the same channel. If so, the inbound certificate must match both patterns in order to connect. For more information, see Channel authentication records. 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. 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.

Back to overview of mq_channel

statchl

Controls the collection of statistics data for channels. Valid values are:

  • 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. [z/OS]On z/OS, 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. 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.

Valid values are QMGR, OFF, LOW, MEDIUM, HIGH.

Back to overview of mq_channel

tpname

LU 6.2 transaction program name (maximum length 64 characters). 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. [z/OS]See Configuration parameters for an LU 6.2 connection On Windows SNA Server,[z/OS] 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.

Back to overview of mq_channel

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 MQ pub/sub applications. Alternatively, AMQP clients can publish and subscribe under a different topic prefix, specified in the TPROOT attribute. This parameter is valid only for channels with a channel type ( CHLTYPE ) of AMQP

Back to overview of mq_channel

trptype

Transport type to be used. On AIX, HP-UX, Linux, IBM i, Solaris, Windows[z/OS], and z/OS, this parameter is optional because, if you do not enter a value, 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. [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 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 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

This is a puppet parameter and not a managed property. Therefor it is only used during creation of the resource. Changes to this parameter in your manifest, do NOT result in modifications on the system.

Valid values are LU62, NETBIOS, SPX, TCP.

Back to overview of mq_channel

usecltid

Distributed[V9.0.0.0 Jun 2016]Specifies that the client ID should be used for authorization checks for an AMQP channel, instead of the MCAUSER attribute value. Valid values are:

  • NO The MCA user ID should be used for authorization checks.
  • YES The client ID should be used for authorization checks.

Valid values are YES, NO.

Back to overview of mq_channel

usedlq

Determines whether the dead-letter queue is used when messages cannot be delivered by channels. Valid values are:

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

Valid values are NO, YES.

Back to overview of mq_channel

userid

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. On distributed platforms 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 encrypted and the LU 6.2 software is using a different encryption method, the channel fails to start. The error is diagnosed as 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.

Back to overview of mq_channel

xmitq

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.

Back to overview of mq_channel