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