Change, Copy, and Create Channel (MQTT)

The Change Channel command changes existing Telemetry channel definitions. The Copy and Create Channel commands create new Telemetry channel definitions - the Copy command uses attribute values of an existing channel definition.

The Change Channel (MQCMD_CHANGE_CHANNEL) command changes the specified attributes in a channel definition. For any optional parameters that are omitted, the value does not change.

The Copy Channel (MQCMD_COPY_CHANNEL) command creates new channel definition using, for attributes not specified in the command, the attribute values of an existing channel definition.

The Create Channel (MQCMD_CREATE_CHANNEL) command creates an IBM MQ channel definition. Any attributes that are not defined explicitly are set to the default values on the destination queue manager. If a system default channel exists for the type of channel being created, the default values are taken from there.


Required parameters (Change, Create Channel)

    ChannelName (MQCFST)
    Channel name (parameter identifier: MQCACH_CHANNEL_NAME).

    Specifies the name of the channel definition to be changed, or created

    The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

    ChannelType (MQCFIN)
    Channel type (parameter identifier: MQIACH_CHANNEL_TYPE). Specifies the type of the channel being changed, copied, or created. The value can be any of the following values:

      MQCHT_MQTT
      Telemetry.

    TrpType (MQCFIN)
    Transmission protocol type of the channel (parameter identifier: MQIACH_XMIT_PROTOCOL_TYPE). This parameter is required for a create command in telemetry. No check is made that the correct transport type has been specified if the channel is initiated from the other end. The value is:

      MQXPT_TCP
      TCP.

    Port (MQCFIN)
    The port number to use if TrpType is set to MQXPT_TCP. This parameter is required for a create command in telemetry, if TrpType is set to MQXPT_TCP.
    The value is in the range 1 - 65335.


Required parameters (Copy Channel)

    ChannelType (MQCFIN)
    Channel type (parameter identifier: MQIACH_CHANNEL_TYPE). Specifies the type of the channel being changed, copied, or created. The value can be any of the following values:

      MQCHT_MQTT
      Telemetry.


Optional parameters (Change, Copy, and Create Channel)

    Backlog (MQCFIN)
    The number of concurrent connection requests that the telemetry channel supports at any one time (parameter identifier: MQIACH_BACKLOG).
    The value is in the range 0 - 999999999.

    JAASConfig (MQCFST)
    The file path of the JAAS configuration (parameter identifier: MQCACH_JAAS_CONFIG).
    The maximum length of this value is MQ_JAAS_CONFIG_LENGTH.
    Only one of JAASCONFIG, MCAUSER, and USECLIENTID can be specified for a telemetry channel; if none is specified, no authentication is performed. If JAASConfig is specified, the client flows a user name and password. In all other cases, the flowed user name is ignored.

    LocalAddress (MQCFST)
    Local communications address for the channel (parameter identifier: MQCACH_LOCAL_ADDRESS).

    The maximum length of the string is MQ_LOCAL_ADDRESS_LENGTH.

    The value that you specify depends on the transport type (TransportType) to be used:

      TCP/IP
      The value is the optional IP address and optional port or port range to be used for outbound TCP/IP communications. The format for this information is as follows: 
      [ip-addr][(low-port[,high-port])]
      where ip-addr is specified in IPv4 dotted decimal, IPv6 hexadecimal notation, or alphanumeric form, and low-port and high-port are port numbers enclosed in parentheses. All are optional.

      All Others
      The value is ignored; no error is diagnosed.

    Use this parameter if we want a channel to use a particular IP address, port, or port range for outbound communications. This parameter is useful when a machine is connected to multiple networks with different IP addresses.

    Examples of use

    Value Meaning
    9.20.4.98 Channel binds to this address locally
    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 a port in the range 1000 - 2000 locally
    Note:

    • Do not confuse this parameter with ConnectionName. The LocalAddress parameter specifies the characteristics of the local communications; the ConnectionName parameter specifies how to reach a remote queue manager.

    Protocol (MQCFIL)
    Client protocols supported by the MQTT channel (parameter identifier: MQIACH_PROTOCOL). The value can be one or more of the following values:

      MQPROTO_MQTTV311
      The channel accepts connections from clients using the protocol defined by the MQTT Version 3.1.1 Oasis standard. The functionality provided by this protocol is almost identical to that provided by the pre-existing MQTTV3 protocol.

      MQPROTO_MQTTV3
      The channel accepts connections from clients using the MQTT V3.1 Protocol Specification from mqtt.org.

      MQPROTO_HTTP
      The channel accepts HTTP requests for pages, or WebSockets connections to MQ Telemetry.

    If you specify no client protocols, the channel accepts connections from clients using any of the supported protocols.

    If we are using IBM MQ Version 8.0.0, Fix Pack 3 or later, and your configuration includes an MQTT channel that was last modified in an earlier version of the product, we must explicitly change the protocol setting to prompt the channel to use the MQTTV311 option. This is so even if the channel does not specify any client protocols, because the specific protocols to use with the channel are stored at the time the channel is configured, and previous versions of the product have no awareness of the MQTTV311 option. To prompt a channel in this state to use the MQTTV311 option, explicitly add the option then save your changes. The channel definition is now aware of the option. If you subsequently change the settings again, and specify no client protocols, the MQTTV311 option is still included in the stored list of supported protocols.

    SSLCipherSuite (MQCFST)
    CipherSuite (parameter identifier: MQCACH_SSL_CIPHER_SUITE).

    The length of the string is MQ_SSL_CIPHER_SUITE_LENGTH.

    SSL CIPHER SUITE character channel parameter type.

    SSLClientAuth (MQCFIN)
    Client authentication (parameter identifier: MQIACH_SSL_CLIENT_AUTH). The value can be any of the following values:

      MQSCA_REQUIRED
      Client authentication required

      MQSCA_OPTIONAL
      Client authentication is optional.

      MQSCA_NEVER_REQUIRED
      Client authentication is never required, and must not be provided.

    Defines whether IBM MQ requires a certificate from the TLS client.

    The TLS client is the end of the message channel that initiates the connection. The TLS Server is the end of the message channel that receives the initiation flow.

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

    SSLKeyFile (MQCFST)
    The store for digital certificates and their associated private keys (parameter identifier: MQCA_SSL_KEY_REPOSITORY).
    If we do not specify a key file, TLS is not used.
    The maximum length of this parameter is MQ_SSL_KEY_REPOSITORY_LENGTH.

    SSLPassPhrase (MQCFST)
    The password for the key repository (parameter identifier: MQCACH_SSL_KEY_PASSPHRASE).
    If no pass phrase is entered, then unencrypted connections must be used.
    The maximum length of this parameter is MQ_SSL_KEY_PASSPHRASE_LENGTH.

    TransportType (MQCFIN)
    Transmission protocol type (parameter identifier: MQIACH_XMIT_PROTOCOL_TYPE). No check is made that the correct transport type has been specified if the channel is initiated from the other end. The value can be any of the following values:

      MQXPT_LU62
      LU 6.2.

      MQXPT_TCP
      TCP.

      MQXPT_NETBIOS
      NetBIOS.

      This value is supported in Windows.

      MQXPT_SPX
      SPX.

      This value is supported in Windows.

    This parameter is required for a create command in telemetry; see TransportType for more information.

    UseClientIdentifier (MQCFIN)
    Determines whether to use the client ID of a new connection as the user ID for that connection (parameter identifier: MQIACH_USE_CLIENT_ID).
    The value is either:

      MQUCI_YES
      Yes.

      MQUCI_NO
      No.

    Only one of JAASCONFIG, MCAUSER, and USECLIENTID can be specified for a telemetry channel; if none is specified, no authentication is performed. If USECLIENTID is specified, the flowed user name of the client is ignored.


Error codes (Change, Copy, and Create Channel)

This command might return the following error codes in the response format header, in addition to those codes listed in Error codes applicable to all commands.

    Reason (MQLONG)
    The value can be any of the following values:

      MQRCCF_BATCH_INT_ERROR
      Batch interval not valid.

      MQRCCF_BATCH_INT_WRONG_TYPE
      Batch interval parameter not allowed for this channel type.

      MQRCCF_BATCH_SIZE_ERROR
      Batch size not valid.

      MQRCCF_CHANNEL_NAME_ERROR
      Channel name error.

      MQRCCF_CHANNEL_NOT_FOUND
      Channel not found.

      MQRCCF_CHANNEL_TYPE_ERROR
      Channel type not valid.

      MQRCCF_CLUSTER_NAME_CONFLICT
      Cluster name conflict.

      MQRCCF_DISC_INT_ERROR
      Disconnection interval not valid.

      MQRCCF_DISC_INT_WRONG_TYPE
      Disconnection interval not allowed for this channel type.

      MQRCCF_HB_INTERVAL_ERROR
      Heartbeat interval not valid.

      MQRCCF_HB_INTERVAL_WRONG_TYPE
      Heartbeat interval parameter not allowed for this channel type.

      MQRCCF_LONG_RETRY_ERROR
      Long retry count not valid.

      MQRCCF_LONG_RETRY_WRONG_TYPE
      Long retry parameter not allowed for this channel type.

      MQRCCF_LONG_TIMER_ERROR
      Long timer not valid.

      MQRCCF_LONG_TIMER_WRONG_TYPE
      Long timer parameter not allowed for this channel type.

      MQRCCF_MAX_INSTANCES_ERROR
      Maximum instances value not valid.

      MQRCCF_MAX_INSTS_PER_CLNT_ERR
      Maximum instances per client value not valid.

      MQRCCF_MAX_MSG_LENGTH_ERROR
      Maximum message length not valid.

      MQRCCF_MCA_NAME_ERROR
      Message channel agent name error.

      MQRCCF_MCA_NAME_WRONG_TYPE
      Message channel agent name not allowed for this channel type.

      MQRCCF_MCA_TYPE_ERROR
      Message channel agent type not valid.

      MQRCCF_MISSING_CONN_NAME
      Connection name parameter required but missing.

      MQRCCF_MR_COUNT_ERROR
      Message retry count not valid.

      MQRCCF_MR_COUNT_WRONG_TYPE
      Message-retry count parameter not allowed for this channel type.

      MQRCCF_MR_EXIT_NAME_ERROR
      Channel message-retry exit name error.

      MQRCCF_MR_EXIT_NAME_WRONG_TYPE
      Message-retry exit parameter not allowed for this channel type.

      MQRCCF_MR_INTERVAL_ERROR
      Message retry interval not valid.

      MQRCCF_MR_INTERVAL_WRONG_TYPE
      Message-retry interval parameter not allowed for this channel type.

      MQRCCF_MSG_EXIT_NAME_ERROR
      Channel message exit name error.

      MQRCCF_NET_PRIORITY_ERROR
      Network priority value error.

      MQRCCF_NET_PRIORITY_WRONG_TYPE
      Network priority attribute not allowed for this channel type.

      MQRCCF_NPM_SPEED_ERROR
      Nonpersistent message speed not valid.

      MQRCCF_NPM_SPEED_WRONG_TYPE
      Nonpersistent message speed parameter not allowed for this channel type.

      MQRCCF_PARM_SEQUENCE_ERROR
      Parameter sequence not valid.

      MQRCCF_PUT_AUTH_ERROR
      Put authority value not valid.

      MQRCCF_PUT_AUTH_WRONG_TYPE
      Put authority parameter not allowed for this channel type.

      MQRCCF_RCV_EXIT_NAME_ERROR
      Channel receive exit name error.

      MQRCCF_SEC_EXIT_NAME_ERROR
      Channel security exit name error.

      MQRCCF_SEND_EXIT_NAME_ERROR
      Channel send exit name error.

      MQRCCF_SEQ_NUMBER_WRAP_ERROR
      Sequence wrap number not valid.

      MQRCCF_SHARING_CONVS_ERROR
      Value given for Sharing Conversations not valid.

      MQRCCF_SHARING_CONVS_TYPE
      Sharing Conversations parameter not valid for this channel type.

      MQRCCF_SHORT_RETRY_ERROR
      Short retry count not valid.

      MQRCCF_SHORT_RETRY_WRONG_TYPE
      Short retry parameter not allowed for this channel type.

      MQRCCF_SHORT_TIMER_ERROR
      Short timer value not valid.

      MQRCCF_SHORT_TIMER_WRONG_TYPE
      Short timer parameter not allowed for this channel type.

      MQRCCF_SSL_CIPHER_SPEC_ERROR
      TLS CipherSpec not valid.

      MQRCCF_SSL_CLIENT_AUTH_ERROR
      TLS client authentication not valid.

      MQRCCF_SSL_PEER_NAME_ERROR
      TLS peer name not valid.

      MQRCCF_WRONG_CHANNEL_TYPE
      Parameter not allowed for this channel type.

      MQRCCF_XMIT_PROTOCOL_TYPE_ERR
      Transmission protocol type not valid.

      MQRCCF_XMIT_Q_NAME_ERROR
      Transmission queue name error.

      MQRCCF_XMIT_Q_NAME_WRONG_TYPE
      Transmission queue name not allowed for this channel type.

Parent topic: Definitions of the Programmable Command Formats