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.

 
Value for miniDumpType Description of Information Dumped
0 Stack traces for all existing threads in a process.
1 Data sections from all loaded modules, including global variables, which can significantly increase the size of the dump.
2 All accessible memory in the process.
4 High-level information about the operating system handles that are active when the dump is generated.
8 Filters the stack and backing store memory written to the dump file to remove all but the pointer values necessary to reconstruct a stack trace. This typically removes private information.
10 Scans the stack and backing store memory for pointer references to modules in the module list.
20 Information from the list of modules that were recently unloaded, if the operating system provides this information. (Not supported with DBGHELP v5.1 and earlier.)
40 Includes pages that have data referenced by locals or other stack memory. (Not supported with DBGHELP v5.1 and earlier.)
80 Filters the module paths for information such as user names or important directories. This option may prevent the system from locating the image file and should be used only in particular situations. (Not supported with DBGHELP v5.1 and earlier.)
100 Includes complete per-process and per-thread information from the operating system. (Not supported with DBGHELP v5.1 and earlier.)
200 Scans the virtual address space for other types of memory to be included. (Not supported with DBGHELP v5.1 and earlier.)
400 Eliminates memory regions that are not essential to meet criteria specified for the dump, which reduces the data that is dumped and can help avoid dumping memory that may contain sensitive data. (Not supported with DBGHELP v6.1 and earlier.)
800 Includes memory region information. (Not supported with DBGHELP v6.1 and earlier.)
1000 Includes thread state information. (Not supported with DBGHELP v6.1 and earlier.)
2000 Includes all code and code-related sections from loaded modules to capture executable content. (Not supported with DBGHELP v6.1 and earlier.)

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.


DISCLAIMER

The information in technical documents comes without any warranty or applicability for a specific purpose. The author(s) or distributor(s) will not accept responsibility for any damage incurred directly or indirectly through use of the information contained in these documents. The instructions may need to be modified to be appropriate for the hardware and software that has been installed and configured within a particular organization.  The information in technical documents should be considered only as an example and may include information from various sources, including IBM, Microsoft, and other organizations.