MQCMD_START_CHANNEL (Start Channel)

The Start Channel (MQCMD_START_CHANNEL) PCF command starts an IBM® MQ channel. This command can be issued to a channel of any type (except MQCHT_CLNTCONN). If, however, it is issued to a channel with a ChannelType value of MQCHT_RECEIVER, MQCHT_SVRCONN, or MQCHT_CLUSRCVR, the only action is to enable the channel, not start it.

Where there is both a locally defined channel and an auto-defined cluster-sender channel of the same name, the command applies to the locally defined channel.

If there is no locally defined channel but more than one auto-defined cluster-sender channel, the command applies to the last channel added to the repository on the local queue manager.

None of the following attributes are applicable to MQTT channels unless specifically mentioned in the parameter description.

Required parameters

ChannelName (MQCFST)

Channel name (parameter identifier: MQCACH_CHANNEL_NAME).

The name of the channel to be started. The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

This parameter is required for all channel types including MQTT channels.

Optional parameters for z/OS

CommandScope (MQCFST)

Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS® only.

Specifies how the command is executed when the queue manager is a member of a queue sharing group. You can specify one of the following:

blank (or omit the parameter altogether). The command is executed on the queue manager on which it was entered.
a queue manager name. The command is executed on the queue manager you specify, providing it is active within the queue sharing group. If you specify a queue manager name other than the queue manager on which it was entered, you must be using a queue sharing group environment, and the command server must be enabled.
an asterisk (*). The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group.

The maximum length is MQ_QSG_NAME_LENGTH.

ChannelDisposition (MQCFIN)

Channel disposition (parameter identifier: MQIACH_CHANNEL_DISP). This parameter applies to z/OS only.

Specifies the disposition of the channels to be started.

If this parameter is omitted, then the value for the channel disposition is taken from the default channel disposition attribute of the channel object.

The value can be:

MQCHLD_PRIVATE: A receiving channel is private if it was started in response to an inbound transmission directed to the queue manager.
A sending channel is private if its transmission queue has a disposition other than MQQSGD_SHARED.
MQCHLD_SHARED: A receiving channel is shared if it was started in response to an inbound transmission directed to the queue sharing group.
A sending channel is shared if its transmission queue has a disposition of MQQSGD_SHARED.
MQCHLD_FIXSHARED: Shared channels tied to a specific queue manager.

The combination of the ChannelDisposition and CommandScope parameters also controls from which queue manager the channel is operated. The possible options are:

On the local queue manager where the command is issued.
On another specific named queue manager in the group.
On every active queue manager in the group.
On the most suitable queue manager in the group, determined automatically by the queue manager itself.

The various combinations of


ChannelDisposition

and


CommandScope

are summarized in Table 1

Table 1. ChannelDisposition and CommandScope for START CHANNEL
`ChannelDisposition`	`CommandScope` blank or local-qmgr	`CommandScope` qmgr-name	`CommandScope(*)`
MQCHLD_PRIVATE	Start as a private channel on the local queue manager	Start as a private channel on the named queue manager	Start as a private channel on all active queue managers
MQCHLD_SHARED	For channels of `ChannelType` MQCHT_SENDER, MQCHT_REQUESTER, and MQCHT_SERVER, start as a shared channel on the most suitable queue manager in the group. For a shared channel of `ChannelType` MQCHT_RECEIVER and MQCHT_SVRCONN, start the channel on all active queue managers. For a shared channel of `ChannelType` MQCHT_CLUSSDR and MQCHT_CLUSRCVR, this option is not permitted. MQCHLD_SHARED might automatically generate a command using `CommandScope` and send it to the appropriate queue manager. If there is no definition for the channel on the queue manager to which the command is sent, or if the definition is unsuitable for the command, the command fails. The definition of a channel on the queue manager where the command is entered might be used to determine the target queue manager where the command is run. Therefore, it is important that channel definitions are consistent. Inconsistent channel definitions might result in unexpected command behavior.	Not permitted	Not permitted
MQCHLD_FIXSHARED	For a shared channel of `ChannelType` MQCHT_SENDER, MQCHT_REQUESTER, and MQCHT_SERVER, with a nonblank `ConnectionName`, start as a shared channel on the local queue manager.	For a shared channel of `ChannelType` MQCHT_SENDER, MQCHT_REQUESTER, and MQCHT_SERVER, with a nonblank `ConnectionName`, start as a shared channel on the named queue manager.	Not permitted

Optional parameters for Multiplatforms

MQIACF_IGNORE_STATE

Specifies whether the command fails if the channel is already running. The possible values are:

MQIS_NO: The command fails if the channel is already running. This is the default value.
MQIS_YES: The command succeeds regardless of the current state of the channel.

Error codes

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

Reason (MQLONG)

The value can be any of the following values:

MQRCCF_CHANNEL_INDOUBT: Channel in-doubt.
MQRCCF_CHANNEL_IN_USE: Channel in use.
MQRCCF_CHANNEL_NOT_FOUND: Channel not found.
MQRCCF_CHANNEL_TYPE_ERROR: Channel type not valid.
MQRCCF_MQCONN_FAILED: MQCONN call failed.
MQRCCF_MQINQ_FAILED: MQINQ call failed.
MQRCCF_MQOPEN_FAILED: MQOPEN call failed.
MQRCCF_NOT_XMIT_Q: Queue is not a transmission queue.