IT44414: An improperly terminated MFT environment variable in an agent property value will cause the agent to restart.

APAR status

• Closed as program error.

Error description

• IBM MQ Managed File Transfer (MFT properties are allowed to
  include Windows environment variable references. This is
  documented on the following page.
  
  Title: The use of environment variables in MFT properties
  URL:
  https://www.IBM.com/docs/en/ibm-mq/9.3?topic=reference-use-envir
  onment-variables-in-mft-properties
  
  If the environment variable reference is improperly terminated
  (for example: %MQ_DATA_PATH/mqft instead  of
  %MQ_DATA_PATH%/mqft), an FFDC file will be generated and the
  agent will be unable to start.
  
  For example:
  
  #-----------------------------------------------------------
  # Note: The following contains a syntax error.
  #       The environment variable name should start, and end
  #       with "%".  Like this: %MQ_DATA_PATH%
  #-----------------------------------------------------------
  transferRoot=%MQ_DATA_PATH\mqft
  
  The agent's event log (output0.log) file will contain messages
  like this:
  
  BFGUT0002E: An internal error has occurred. Product failure
  data was captured in file
  "FFDC.FTE.20230808122002407.3895653834752555010.log".
  BFGAG0007E: An internal error occurred that prevented process
  startup.  The exception was begin 1, end -1, length 17.
  BFGAG0171E: The agent has ended abnormally with return code 70.
  
  The FFDC file that is generated will include a stack trace that
  looks similar to this:
  
  Class:      com.ibm.wmqfte.agent.AgentRuntime
  Method:     mainLoop
  Probe:      FFDC_003
  Cause:      java.lang.StringIndexOutOfBoundsException: begin 1,
  end -1, length 17
  java.lang.StringIndexOutOfBoundsException: begin 1, end -1,
  length 17
          at java.lang.String.substring(String.java:2744)
          at
  com.ibm.wmqfte.utils.VariableSubstitution.substituteWindowsVaria
  bles(VariableSubstitution.java:77)
          at
  com.ibm.wmqfte.utils.VariableSubstitution.substituteVariables(Va
  riableSubstitution.java:46)
  ...
  

Local fix

• Properly terminate the environment variable reference.
  

Problem summary

• ****************************************************************
  USERS AFFECTED:
  This issue affects users of MQ Managed File Transfer (MFT).
  
  
  Platforms affected:
  MultiPlatform
  
  ****************************************************************
  PROBLEM DESCRIPTION:
  When configuring an IBM MQ Managed File Transfer agent, it is
  possible to use environment variables as the values for
  properties. A complete list of properties that can take
  environment variables as their values can be found in the "The
  use of environment variables in MFT properties" topic in the MQ
  9.3 section of the IBM Documenation site. The URI for the topic
  is
  https://www.ibm.com/docs/en/ibm-mq/9.3?topic=reference-use-envir
  onment-variables-in-mft-properties
  
  
  If a property in an agent.properties file for an agent contained
  an improperly terminated environment variable, such as the
  following example on Windows:
  
  transferRoot=%MQ_DATA_PATH\mqft
  
  (there is a missing % character after MQ_DATA_PATH), then the
  agent would:
  
  - Generate an FFDC
  - Write a BFGAG0007E message to its event log (output0.log)
  - And shut itself down, exiting with return code 70.
  
  The agent's process controller would then detect that the agent
  had stopped unexpectedly, and restart it. However, when the
  agent restarted, it failed to process the environment variable
  in the property again, so generated another FFDC, wrote another
  BFGAG0007E message to its event log and stopped with error code
  70, which caused the process controller to restart it, and so
  on.
  
  
  An example of the messages that would be written to the event
  log are shown below:
  
  BFGUT0002E: An internal error has occurred. Product failure data
  was captured in file
  "FFDC.FTE.20230808122002407.3895653834752555010.log".
  BFGAG0007E: An internal error occurred that prevented process
  startup.  The exception was begin 1, end -1, length 17.
  BFGAG0171E: The agent has ended abnormally with return code 70.
  
  and here is an example of the FFDC that would be created:
  
  ----------------------------
  ......
  Thread:     1 (main)
  Class:      com.ibm.wmqfte.agent.AgentRuntime
  Method:     mainLoop
  Probe:      FFDC_003
  Cause:      java.lang.StringIndexOutOfBoundsException: begin 1,
  end -1, length 17
  java.lang.StringIndexOutOfBoundsException: begin 1, end -1,
  length 17
  	at java.lang.String.substring(String.java:2744)
  	at
  com.ibm.wmqfte.utils.VariableSubstitution.substituteWindowsVaria
  bles(VariableSubstitution.java:77)
  	at
  com.ibm.wmqfte.utils.VariableSubstitution.substituteVariables(Va
  riableSubstitution.java:46)
  	at
  com.ibm.wmqfte.configuration.FTEPropertyItem.getAsStringValue(FT
  EPropertyItem.java:681)
  	at
  com.ibm.wmqfte.configuration.FTEPropertyAbs.getPropertyAsString(
  FTEPropertyAbs.java:458)
  	at
  com.ibm.wmqfte.agent.Agent.doInitialisation(Agent.java:798)
  	at
  com.ibm.wmqfte.agent.AgentRuntime.mainLoop(AgentRuntime.java:586
  )
  	at com.ibm.wmqfte.agent.Agent.main(Agent.java:427)
  	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native
  Method)
  	at
  sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessor
  Impl.java:90)
  	at
  sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethod
  AccessorImpl.java:55)
  	at java.lang.reflect.Method.invoke(Method.java:508)
  	at
  com.ibm.wmqfte.agent.bootstrap.impl.BootstrapMain.run(BootstrapM
  ain.java:284)
  	at
  com.ibm.wmqfte.agent.bootstrap.impl.BootstrapMain.main(Bootstrap
  Main.java:118)
  ......
  ----------------------------
  

Problem conclusion

• To resolve this issue, MQ Managed File Transfer (MFT) agents
  have been updated to:
  
  - Catch any StringIndexOutOfBoundsExceptions that can occur
  while processing environment variables in its agent properties
  file.
  - Write a BFGUB0089W message to its event log (output0.log)
  reporting the issue.
  - And then carry on with its initialisation, using the default
  value of the property.
  
  An example of the new BFGUB0089W message is shown below:
  
  BFGUB0089W: The value "%MQ_DATA_PATHmqft" for the property
  "transferRoot" contains an incorrectly formatted environment
  variable. The default value "C:\Users\Administrator" has been
  used instead.
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v9.x CD    9.3.5
  
  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