StarQuest Technical Documents

Troubleshooting Replicator Service Exceptions

Last Update: 23 February 2018
Product: StarQuest Data Replicator
Version: 3.4 or later
Article ID: SQV00DR012

Abstract

The StarQuest Data Replicator software includes a component, the Replicator Service, which runs as a Windows service. If you encounter a problem with the Replicator Service shutting down due to an unhandled exception, StarQuest Technical Support may ask that you provide a dump of the environment at the time the exception occurs to help troubleshoot the problem. This technical document describes how to enable the Replicator Service to take advantage of the Windows dump facility to capture detailed information about the conditions that may be causing the failure.

Solution

If you are encountering exceptions from the Data Replicator Service you may need to capture detailed system information to help StarQuest Technical Support and Engineering determine what is causing the problem. This may require generating a dump file that contains technical details of the system environment and processes at the time the problem occurs. The dump is generated using the Windows DBGHELP dynamic link library (DBGHELP.DLL). This technical document describes how to prepare a Windows computer to generate a dump file when the Replicator Service encounters an exception that cannot be handled.

Generating a dump when the Replicator Service encounters an exception requires the following preparation:

• ensuring that the Replicator Service program account has privilege to the Debug Programs security policy and
• optionally, setting an Advanced Setting to control the level of information that is captured

The following sections detail how to prepare for and generate the dump file.

Changing the Debug Programs Security Policy

Generating a dump requires that the account under which the Replicator Service runs has privilege to debug programs. Use the Windows Local Security Policy tool to add a user to the Debug Programs policy. The Local Security Policy tool is available from the Administrative Tools shortcut. Select the Debug Programs policy and execute the Properties command to display the properties, from which you can add a user or group to which you want to grant the privilege. The default configuration for the Replicator Service is to run as a SYSTEM account, although another user account can be specified when the Data Replicator Service is configured.

After you change the Security Settings you must restart the Replicator Service for the changes to take affect. You can stop and start the Replicator Service from the Replicator Manager or from the Windows Services control panel.

The CrashDumps Directory

When you install the StarQuest Replicator Manager a directory named CrashDumps is created in the common user directory.\Users\Public\Documents under StarQuest\SQDR. When a dump file is generated to the CrashDumps directory it is named with a format of:

sqdrsvc-<PID>-<TID>-YYYYMMDD-HHMMSS.dmp

<PID> is the process ID, <TID> is the thread ID, YYYYMMDD is the date, and HHMMSS is the time. If the SQDR service has permission to use the Debug facility, a dump file is written to the CrashDumps directory.

Specifying the Level of Dump Information

The default SQDR service dump file contains the normal level of information, which is just the information necessary to capture stack traces for all existing threads in a process.

Use the SQDR Service Properties application to modify the advanced value miniDumpType to increase the level of detail that is saved to the dump file.

The levels and decimal values are shown in the following table. The values can be combined to include different levels of information, such as setting the value to 3 to generate data sections for all loaded modules (value 1) and all accessible memory in the process (value 2). StarQuest Technical Support can advise whether you need to increase the dump level value, and, if so, what value to specify.

Additional information about miniDumpType may be found in the Advanced Settings topic of the SQDR help file.

Generating the Dump File

After you prepare the system as described in the previous steps, proceed to use the StarQuest Data Replicator software in your normal manner. If an exception occurs and the SQDR service has permission, a dump file is generated. Send the dump file (.dmp) to the StarQuest technician whom you are working with to solve the problem.