The VSS writer has been added as an integral component of the c-treeACE Server for Windows. This component is supplied as a Windows dynamic link library (c-treeACEVSSWriter.dll) and can be optionally loaded by c-treeACE at startup. (An executable, c-treeACEVSSWriter.exe, is also supplied for testing purposes, however, not intended for production use.)
VSS Configuration
VSS_WRITER YES
With this option enabled, c-treeACE loads the Volume Shadow Copy Service (VSS) writer DLL (c-treeACEVSSWriter.dll) and initializes the VSS writer when the server starts. A FULL CONSISTENCY VSS backup of FairCom database files will be created, which is comparable to cleanly shutting down the FairCom server and then backing up all files.
For application files that are under full transaction control, a FULL CONSISTENCY VSS backup is more time-consuming and invasive than strictly required. Application files with the ctTRNLOG property are under full transaction control. If full transaction controlled files and the database transaction logs (L*.FCS and S0*.FCS) are included in backups, a normal database automatic recovery takes place at startup and will properly restore CRASH CONSISTENT backed up data. Do NOT enable VSS_WRITER YES in ctsrvr.cfg, on application files that are under full transaction control.
Note: VSS backups require the Volume Shadow Copy service to be running. If this Windows service is set to start manually or is off by default, it needs to be started before VSS backup will work.
The following message is logged in CTSTATUS.FCS indicating the VSS writer has been started:
Mon Sep 13 14:11:27 2010
- User# 00001 VSS Init: Successfully started the VSS writer.
If you run the command “vssadmin list writers” on a machine with c-treeACE Server running and a properly configured VSS, the list should include c‑treeACEVSSWriter.
Compatibility Notes
User Permissions
FairCom VSS Writer is intended to be run by users with Administrator permissions. To avoid permission issues when running the VSS Writer with a user that is not an Administrator, you must perform the following operations on the Windows registry:
Files to Be Backed Up
The VSS writer needs a list of files that are considered as under the server's control. This information must be located in the file ctsrvr.dds residing in the server's working directory (where the faircom.exe is located). For the VSS backup, only entries between !FILES and !END are relevant. There is no directory recursion, so wildcards will not be matched in subdirectories.
!FILES
C:\FairCom\ctreeSDK\ctreeAPI\bin.sql\ctreeSQL.dbs\test1.dat
C:\FairCom\ctreeSDK\ctreeAPI\bin.sql\ctreeSQL.dbs\test1.idx
ctreeSQL.dbs\*.dat
ctreeSQL.dbs\*.idx
ctreeSQL.dbs\SQL_SYS\*
!END
This information tells the backup utility which files are under c-treeACE control. If the set of files being backed up does not intersect with the set of files listed in ctsrvr.dds, the VSS service does not interact with c-treeACE VSS writer, resulting in an invalid backup of any files open by the server.
While testing, it is recommended to run the c-treeACE SQL Server with DIAGNOSTICS VSS_WRITER in ctsrvr.cfg. When the VSS writer is correctly configured, you should see entries logged to CTSTATUS.FCS like those listed in VSS Diagnostic Logging.
VSS Diagnostic Logging
The following c-treeACE configuration option enables VSS writer diagnostic logging (this can be enabled dynamically on the fly with server administrator utilities):
DIAGNOSTICS VSS_WRITER
When enabled, the VSS writer logs diagnostic messages to CTSTATUS.FCS. These messages indicate the sequence of operations to which the VSS writer is responding. Some examples are shown below:
Tue Sep 14 15:44:05 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called
Tue Sep 14 15:44:07 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPrepareBackup called
Tue Sep 14 15:44:07 2010
- User# 00016 VSS Diag: [0x1098] (+) Component: CtreeACE
Tue Sep 14 15:44:07 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPrepareSnapshot called
Tue Sep 14 15:44:07 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnFreeze called
Tue Sep 14 15:44:07 2010
- User# 00016 VSS Diag: [0x1098] QuietCtree(ctQTblockALL | ctQTflushAllFiles)...
Tue Sep 14 15:44:08 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnThaw called
Tue Sep 14 15:44:08 2010
- User# 00016 VSS Diag: [0x1098] QuietCtree(ctQTunblockALL)...
Tue Sep 14 15:44:08 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPostSnapshot called
Tue Sep 14 15:44:10 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called
Tue Sep 14 15:44:25 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called
Tue Sep 14 15:44:26 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnBackupComplete called
Tue Sep 14 15:44:26 2010
- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnBackupShutdown called
Note: The VSS writer always logs error messages to the Windows event log, even if the DIAGNOSTICS VSS_WRITER option is not specified in the configuration file.
Dynamic API Interaction
The following SQL built-in procedures can enable VSS Writer support:
call fc_set_sysconfig('vss_writer', 'YES');
call fc_set_sysconfig('diagnostics', 'VSS_WRITER');
The SetConfiguration(), ctSETCFG() API function can be used to change VSS configuration dynamically.
Examples
If the c-treeACE VSS writer is not running, the following call starts it:
ctSETCFG(setcfgVSS_WRITER, "YES");
If the c-treeACE VSS writer is running, the following call stops it:
ctSETCFG(setcfgVSS_WRITER, "NO");
The following call enables VSS writer diagnostic logging:
ctSETCFG(setcfgDIAGNOSTICS, "VSS_WRITER");
The following call disables VSS writer diagnostic logging:
ctSETCFG(setcfgDIAGNOSTICS, "~VSS_WRITER");