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 a WebSphere® 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.

This parameter is required on all types of channel; on a CLUSSDR it can be different from on the other channel types. If your convention for naming channels includes the name of the queue manager, you can make a CLUSSDR definition using the +QMNAME+ construction, and WebSphere MQ substitutes the correct repository queue manager name in place of +QMNAME+. This facility applies to AIX® , HP-UX, Linux®, IBM® i, Solaris, and Windows only. See Configuring a queue manager cluster for more details.

ChannelType(MQCFIN)

Channel type (parameter identifier: MQIACH_CHANNEL_TYPE).

Specifies the type of the channel being changed, copied, or created. The value can be:

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:

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

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:

MQSCA_REQUIRED: Client authentication required.
MQSCA_OPTIONAL: Client authentication optional.

Defines whether IBM WebSphere MQ requires a certificate from the SSL client.

The SSL client is the end of the message channel that initiates the connection. The SSL 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 you do not specify a key file, SSL 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:

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:

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: SSL CipherSpec not valid.
MQRCCF_SSL_CLIENT_AUTH_ERROR: SSL client authentication not valid.
MQRCCF_SSL_PEER_NAME_ERROR: SSL 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.