IBM Support

IT22423: Invalid JVM options on the fteModifyAgent command leaves the agent configuration in an inconsistent state

Subscribe to this APAR

By subscribing, you receive periodic emails alerting you to the status of the APAR, along with a link to the fix after it becomes available. You can track this item individually or track all items by product.

Notify me when this APAR changes.

Notify me when an APAR for this component changes.

 

APAR status

  • Closed as program error.

Error description

  • An IBM MQ Managed File Transfer agent is created and configured
    to run as as Windows Service using the service option (-s
    parameter) on the fteCreateAgent command.
    
    The fteModifyAgent command is then used with the
    -serviceJVMOptions (-sj) parameter to update the agent's Windows
    Service configuration with the specified JVM options.
    
    If the JVM options specified with the -serviceJVMOptions
    parameter were invalid, for example an invalid -X option was
    specified, an error such as that below would be returned from
    the fteModifyAgent command:
    
    BFGWS0032E: Unable to modify Windows service <agent Windows
    Service name>.
    Reason: BFGWS0019E: The specified JVM option(s) -Xfoo are
    invalid.
    Status code: 1, reason: JVMJ9VM007E Command-line option
    unrecognised: -Xfoo
    Error: Could not create the Java Virtual Machine.
    
    If the fteStartAgent command is then run, this fails with the
    error:
    
      BFGWS0035E: Failed to validate the Windows service path,
    because of error 1.
      Reason: ERROR: The system was unable to find the specified
    registry key or value.
    
    The agent does not start in this scenario.
    
    Running the fteModifyAgent command again also fails with the
    error:
    
      BFGWS0032E: Unable to modify Windows service <agent Windows
    Service name>.
      Reason: BFGWS0034E: Unable to delete Windows service <agent
    Windows Service name> because of error 1060.
      Reason: [SC] OpenService FAILED 1060:
    

Local fix

  • Confirm that the Windows Service definition for the IBM MQ
    Managed File Transfer Agent or Logger has been removed using
    Operating System tools and if so, remove the properties:
    
    - wndowsServiceVersion
    - windowsService
    
    the agent's or logger's properties file.  This will ensure the
    agent or logger does not attempt to start using the named, but
    undefined, Windows Service.
    

Problem summary

  • ****************************************************************
    USERS AFFECTED:
    This issue affects users of the IBM MQ Managed File Transfer
    fteModifyAgent or fteModifyLogger commands.
    
    
    Platforms affected:
    MultiPlatform
    
    ****************************************************************
    PROBLEM DESCRIPTION:
    When using the IBM MQ Managed File Transfer fteModifyAgent or
    fteModifyLogger command to modify an existing Windows Service
    definition for an agent or logger, in order to update, add or
    remove Java system properties, the existing Windows Service is
    first deleted before a new one is created in its place with the
    updated configuration.
    
    If the deletion of the existing Windows Service was successful
    but before the new Windows Service was created, a check was made
    to verify that the Java Virtual Machine (JVM) options that were
    specified via the -serviceJVMOptions parameter were valid.  If
    they were not valid, an exception was thrown.
    
    In this case, the previous Windows Service was deleted and the
    new Windows Service was not created, but the properties for the
    agent or logger were not removed from the properties file.  As
    such, when an attempt was made to start the agent or logger, the
    Windows Service properties were read and an attempt was made to
    start the named Windows Service.  As it had been deleted, the
    agent or logger could not be started.
    

Problem conclusion

  • The IBM MQ Managed File Transfer (MFT) fteModifyAgent or
    fteModifyLogger commands have been updated to verify the Java
    Virtual Machine (JVM) options specified via the
    -serviceJVMOptions parameter before deleting an existing Windows
    Service definition.  Therefore, any exception thrown because
    they are invalid, or otherwise could not be validated, will
    result in the fteModifyAgent or fteModifyLogger command failing
    before deleting the existing Windows Service.
    
    In the case where the JVM properties are valid and the deletion
    of the existing Windows Service is successful but a failure
    arises creating the replacement Windows Service, an attempt will
    be made to remove the properties defining the Windows Service
    from the agent or logger properties file.  In this case a
    BFGCL0762E message will be logged and the agent or logger will
    not run as a Windows Service if started.  If the properties
    could not be updated for some reason, a BFGCL0763E message will
    be returned from the command indicating that the Administrator
    will need to manually verify that the state of the Windows
    Service definition is consistent with the Windows Service
    properties defined in the agent or logger properties file.
    
    
    This APAR also addresses an issue when using the fteModifyAgent
    or fteModifyLogger command to change the name of the Windows
    Service under which the MFT process is running.  When running a
    modify command with a different value specified for the -s
    parameter, the Windows Service definition would not be modified
    with the following error reported in the output of the command:
    
     BFGWS0036E: Failed to determine if the Windows service exists,
    because of error 1060.
     Reason: [SC] EnumQueryServicesStatus:OpenService FAILED 1060:
    
    This was because the fteModifyAgent and fteModifyLogger commands
    checked to see whether a Windows Service definition with the new
    target name was already defined.  If so, the modify command
    would fail because the target service name was already taken and
    they must be unique.
    
    The product code expected a 0 reason code to be returned from
    the Windows "sc.exe query" command with no output if the named
    Windows Service did not exist.  However, Windows returns the
    reason code 1060 (x424 - ERROR_SERVICE_DOES_NOT_EXIST) which
    caused the command to throw an exception and abort the modify
    operation.  This APAR updates the logic to check for the Windows
    Service query return code 1060 and if it is returned, the
    fteModifyAgent and fteModifyLogger commands will continue to
    modify the agent or logger Windows Service definition because
    the new target service name for the MFT process does not exist
    on the system and is therefore available for use.
    
    
    Finally, this APAR also adds logging to the fteModifyAgent and
    fteModifyLogger commands such that when either of the commands
    are run, an attempt to log the details regarding the
    modification (and the success or failure of the command) will be
    made to the event log (output0.log file) of the agent/logger
    being being modified.
    
    ---------------------------------------------------------------
    The fix is targeted for delivery in the following PTFs:
    
    Version    Maintenance Level
    v8.0       8.0.0.9
    v9.0 CD    9.0.5
    v9.0 LTS   9.0.0.4
    
    The latest available MQ 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 number

    IT22423

  • Reported component name

    WMQ MFT V8.0

  • Reported component ID

    5724H7252

  • Reported release

    800

  • Status

    CLOSED PER

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2017-09-26

  • Closed date

    2018-01-29

  • Last modified date

    2018-01-29

  • 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

    WMQ MFT V8.0

  • Fixed component ID

    5724H7252

Applicable component levels

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
29 January 2018