IT42017: Managed File Transfer (MFT) agent shuts down due to reason code 2017 when using the multiple channel functionality

APAR status

• Closed as program error.

Error description

• An IBM MQ Managed File Transfer agent has been configured with
  the following entry in its agent.properties file:
  
  agentMultipleChannelsEnabled=true
  
  to enable the multiple channel functionality.
  
  After the agent has started, it receives a managed transfer
  request asking it to act as the source agent for a managed
  transfer, where the source and destination agent queue managers
  are the same. An example of this is shown below:
  
  fteCreateTransfer -rt -1
                    -sa AGENT1
  				  -sm QM1
  				  -da AGENT2
  				  -dm QM1
  				  -df "C:\MFTFiles\Output\File1.txt"
  				  "/MFTFiles/Input/File1.txt"
  
  
  Shortly after the agent starts to process the request, it writes
  the following messages to its event log (output0.log) and shuts
  itself down:
  
  BFGTR0022E: The agent has received a reason code of '2017' from
  the message queue interface (MQI). The agent cannot continue
  processing and will now end.
  BFGAG0171E: The agent has ended abnormally with return code 70.
  

Local fix

• Disable multi-channel functionality (comment out the entries
  for the properties in the agent's agent.properties file).
  

Problem summary

• ****************************************************************
  USERS AFFECTED:
  This issue affects users of IBM MQ 9.3 Managed File Transfer who
  have agents that:
  
  - Have the property:
  
  agentMultipleChannelsEnabled=true
  
  set in their agent.properties file, to enable multiple channel
  support.
  - And act as the source agent for managed transfers, where the
  source and destination agent queue managers are the same.
  
  
  Platforms affected:
  MultiPlatform
  
  ****************************************************************
  PROBLEM DESCRIPTION:
  IBM MQ Managed File Transfer (MFT) provides some functionality
  called multiple channel support. When this functionality is
  enabled, a source agent will send internal messages containing
  item data to the destination agent's data queue
  (SYSTEM.FTE.DATA.<destination agent name>) over multiple MQ
  channels.
  
  In order to use this, configuration changes are required on the
  source agent, as well as the source and destination agent queue
  managers.
  
  On the MFT side, the only change that is needed is to add the
  agent property:
  
  agentMultipleChannelsEnabled=true
  
  to the source agent's agent.properties file.
  
  Some more extensive changes are required on the source and
  destination queue managers, to set up the channels that the
  agent will use. Information on the steps needed to do this can
  be found in the following topics in the MQ 9.3 sections of IBM
  Documentation:
  
  Topic: Configuring an MFT agent for multiple channels in a
  cluster
  URI:
  https://www.ibm.com/docs/en/ibm-mq/9.2?topic=managers-configurin
  g-mft-agent-multiple-channels-in-cluster
  
  Topic: Configuring an MFT agent for multiple channels:
  non-clustered
  URI:
  https://www.ibm.com/docs/en/ibm-mq/9.2?topic=managers-configurin
  g-mft-agent-multiple-channels-non-clustered
  
  
  When the functionality is enabled and the source agent receives
  a managed transfer request, its internal TransferSender thread
  connects to the source agent's queue manager and then issues a
  number of MQOPEN API calls to build a list of handles to the
  destination agent's data queue. These API calls are made with
  the following options:
  
  - Queue Name: SYSTEM.FTE.DATA.<destination_agent_name>
  - Queue Manager Name:
  SYSTEM.FTE.<destination_agent_queue_manager_name>_<counter>
  
  If the queue managers have been configured correctly, one or
  more of the MQOPEN API calls will complete successfully - each
  successful MQOPEN call provides a handle to the queue over a
  different channel.
  
  When an MQOPEN call fails with reason code 2087
  (MQRC_UNKNOWN_REMOTE_Q_MGR), the TransferSender thread
  determines that it has got a complete list of handles and will
  then use those during the managed transfer.
  
  
  Now, if a source agent:
  
  - Was configured to use the multiple channel support
  functionality.
  - And then received a managed transfer request, where the
  destination agent queue manager was the same as its queue
  manager.
  - And the queue manager had been configured with the DEFXMITQ
  (Default transmission queue) attribute set.
  
  then it would issue the MQOPEN calls mentioned above to see how
  many channels were available for it to use.
  
  Because the source and destination agents were using the same
  queue manager, no channels had been defined for the source agent
  to use. However, because the queue manager had been configured
  with the DEFXMITQ attribute set, MQ's name resolution rules
  meant that the MQOPEN call always worked and would never fail
  with reason code 2087. As a result, the TransferSender thread
  got stuck in a loop, issuing MQOPEN API calls over and over
  again, until one eventually failed with reason code 2017
  (MQRC_HANDLE_NOT_AVAILABLE). When this happened, the agent wrote
  the messages:
  
  BFGTR0022E: The agent has received a reason code of '2017' from
  the message queue interface (MQI). The agent cannot continue
  processing and will now end.
  BFGAG0171E: The agent has ended abnormally with return code 70.
  
  to its event log (output0.log) and shut itself down.
  

Problem conclusion

• To resolve this issue, MQ Managed File Transfer has been updated
  so that if a source agent:
  
  - Has been configured to use the multiple channel support
  functionality.
  - And receives a managed transfer request, where the destination
  agent queue manager is the same as its queue manager.
  
  then it will not enable the multiple channel functionality. This
  ensures that its TransferSender thread only creates one handle
  to the destination agent's data queue, which prevents the issue
  reported in this APAR from occurring.
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v9.3 LTS   9.3.0.2
  v9.x CD    9.3.2
  
  The latest available maintenance can be obtained from
  'WebSphere MQ Recommended Fixes'
  http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006037
  
  If the maintenance level is not yet available information on
  its planned availability can be found in 'WebSphere MQ
  Planned Maintenance Release Dates'
  http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006309
  ---------------------------------------------------------------
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

• Fixed component name

  MQ BASE V9.3

• Fixed component ID

  5724H7291

Applicable component levels