Start Channel Listener

The Start Channel Listener (MQCMD_START_CHANNEL_LISTENER) command starts an IBM MQ listener. On z/OS, this command is valid for any transmission protocol; on other platforms, it is valid only for TCP transmission protocols.


Optional parameters

    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. We 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, we must be using a queue sharing group environment, and the command server must be enabled.

    The maximum length is MQ_Q_MGR_NAME_LENGTH.

    InboundDisposition (MQCFIN)
    Inbound transmission disposition (parameter identifier: MQIACH_INBOUND_DISP). This parameter applies to z/OS only. Specifies the disposition of the inbound transmissions that are to be handled. The value can be any of the following values:

      MQINBD_Q_MGR
      Listen for transmissions directed to the queue manager. MQINBD_Q_MGR is the default.

      MQINBD_GROUP
      Listen for transmissions directed to the queue sharing group. MQINBD_GROUP is permitted only if there is a shared queue manager environment.

    IPAddress (MQCFST)
    IP address (parameter identifier: MQCACH_IP_ADDRESS). This parameter applies to z/OS only.

    The IP address for TCP/IP specified in IPv4 dotted decimal, IPv6 hexadecimal, or alphanumeric form. This parameter is valid only for channels that have a TransportType of MQXPT_TCP.

    The maximum length of the string is MQ_IP_ADDRESS_LENGTH.

    ListenerName (MQCFST)
    Listener name (parameter identifier: MQCACH_LISTENER_NAME). This parameter does not apply to z/OS.

    The name of the listener definition to be started. On those platforms on which this parameter is valid, if this parameter is not specified, the default listener SYSTEM.DEFAULT.LISTENER is assumed. If this parameter is specified, no other parameters can be specified.

    The maximum length of the string is MQ_LISTENER_NAME_LENGTH.

    LUName (MQCFST)
    LU name (parameter identifier: MQCACH_LU_NAME). This parameter applies to z/OS only.

    The symbolic destination name for the logical unit (LU) as specified in the APPC side information data set. The LU must be the same LU that is specified in the channel initiator parameters to be used for outbound transmissions. This parameter is valid only for channels with a TransportType of MQXPT_LU62.

    The maximum length of the string is MQ_LU_NAME_LENGTH.

    Port (MQCFIN)
    Port number for TCP (parameter identifier: MQIACH_PORT_NUMBER). This parameter applies to z/OS only.

    The port number for TCP. This parameter is valid only for channels with a TransportType of MQXPT_TCP.

    TransportType (MQCFIN)
    Transmission protocol type (parameter identifier: MQIACH_XMIT_PROTOCOL_TYPE). The value can be:

      MQXPT_LU62
      LU 6.2.

      MQXPT_TCP
      TCP.

      MQXPT_NETBIOS
      NetBIOS.

      MQXPT_SPX
      SPX.

    MQIACF_IGNORE_STATE
    This parameter allows you to specify whether we want the command to return an error return code, if the object is already in the state the command would move it to. Possible values are:

      MQIS_NO
      If the channel listener being started is already in that state, the command returns RC=10. This is the existing behavior, and NO is the default value.

      MQIS_YES
      If the channel listener being started is already in that state, the command returns RC=0. The return code is the case as if the channel listener is not running.


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_COMMS_LIBRARY_ERROR
      Communications protocol library error.

      MQRCCF_LISTENER_NOT_STARTED
      Listener not started.

      MQRCCF_LISTENER_RUNNING
      Listener already running.

      MQRCCF_NETBIOS_NAME_ERROR
      NetBIOS listener name error.

Parent topic: Definitions of the Programmable Command Formats