Microsoft Visual SourceSafe Best Practices

Microsoft Corporation

Created: March 1999

Summary: Outlines recommended practices to help prevent data corruption in Microsoft Visual SourceSafe. Includes a discussion on the data repair tool called Analyze, which ships with the product. (10 printed pages)

Note   These topics are not intended to be the sole reference for Microsoft® Visual SourceSafe™. Product documentation, the Help files, and the Microsoft Knowledge Base are also good resources. The Knowledge Base is the most up-to-date source of breaking news and information on Microsoft products.

Introduction

Under normal operation in a stable environment, Microsoft Visual SourceSafe provides excellent storage and security for your current source data and past revisions. However, as with any database product, data corruption can occur. This article outlines recommended practices to help avoid corruption problems. Although all the practices can help minimize the impact of corruption, one of the most valuable is using a data repair utility called Analyze. The Analyze tool ships with Visual SourceSafe. It checks for and repairs many common data write errors. Run Analyze on your Visual SourceSafe database with your regular tape backup schedule to ensure the stability and security of your source data.

Important   When using Visual SourceSafe, be sure to run the latest version of the application. Microsoft periodically releases service packs for our applications that correct known issues. We recommend that you install the service packs as soon as possible. Customers who want to upgrade their Visual SourceSafe client to the latest Visual Studio Service Pack releases should use the Service Pack installations instead of running netsetup.exe again.

General Database Recommendations

Database Size

Under normal use, your Visual SourceSafe database should not exceed 3 to 5 GB. To determine an appropriate size, consider the amount of free space on the server, the relationship among the projects being stored, the amount of file history you need to access quickly, and user tolerance for reduced performance. Although Visual SourceSafe does not have a size limitation, on very large databases it takes longer to perform normal operations and maintenance tasks, such as running Analyze. Visual SourceSafe does not limit the number of databases you can put on a server.

To reduce potential file size, keep projects that are not interrelated in separate databases. You can use the Archive and Restore utilities included in Visual SourceSafe version 5.0 and later to move projects to another database or to remove outdated history from a project.

Location

Although you can store Visual SourceSafe databases on any Microsoft® Windows®-compatible file server (Windows NT®, Novell, Banyan, and so on), database performance is best on Windows NT. Network operations are generally faster. In addition, in the server-based Windows environment you can run Analyze and other highly intensive file I/O operations directly on the server, often dramatically decreasing execution time.

Analyze Frequency

Use the Analyze tool shipped with Visual SourceSafe to detect and repair problems in the database structure. When you run Analyze regularly, especially in high-use situations, you can discover small problems and fix them before they become worse. Run Analyze weekly or, at a minimum, monthly, as part of regular maintenance.

While running Analyze directly on your production database, you must lock out users. To minimize the impact, restore your regular backup to another location and run Analyze on that copy. Another way that you can create a duplicate on-line copy of your VSS database is to use the ROBOCOPY utility from the Windows NT Resource Kit. This utility copies all the files in a folder and subfolders; however, if a file is in use, it will retry the copy instead of just failing. You can use this method to create a backup of your database on another server as well. If you detect problems in the backup that need to be resolved, you can then lock out users from the production database while making any necessary fixes. If Analyze returns no errors, you do not need to interrupt user connections. This method also checks the validity of the backup strategy.

Each time you run the Analyze utility, create a list of all items in the database. This list is useful in determining which logical file name is related to an error based on the file name (for example, Abcaaaaa.a) for which the error is reported.

To create the physical list, at the command prompt, type:

SS PHYSICAL $/ -R –O@PHYSICAL.TXT 

Free Disk Space

Caution   Do not allow Visual SourceSafe or the Analyze tool to run out of disk space while running. Running out of disk space in the middle of a complex operation can create serious database corruption.

Visual SourceSafe checks for disk space; however, due to performance concerns, it does not check for space on every disk write operation. To avoid possible database corruption, make sure there is enough free space on the server so that a complete copy of the database can be created during normal Analyze operations.

Sharing and Branching

Use the Sharing and Branching features of Visual SourceSafe with discretion. Avoid Sharing or Branching across top-level projects because it complicates the process of archiving a project and restoring it into another database. Moreover, when you branch files and then delete them, the space is not recovered until all copies of the branched file in the database are destroyed.

Number of Users

The acceptable number of users varies depending on the performance of the server and the network. When you control the size of the database, performance improves, and more users can access the database with reasonable performance. The number of full-access users you have determines the number of licenses that you need for Visual SourceSafe.

Server Rights

All users must have create, modify, change/edit, and delete permissions for files in the Data folder and its subfolders in the directory tree. These permissions must also be applied to the share permissions. If a user receives the message "Unable to create user login file," that user does not have the proper permissions to the VSS database location.

Each database has its own User and Rights management systems. You cannot interrelate these files.

Ss.ini and SSAdmin.ini Files

The Ss.ini files of users are limited to 64 KB and a maximum of 10 different computer-specific settings. Each time a user logs on from a different computer, the Ss.ini saves the window positions and other computer-specific information. If you are experiencing unusual user-specific problems, try deleting unnecessary entries in the user's Ss.ini file.

Working Folders

To maintain file integrity, make sure that all users have their own working folders for all projects. When multiple users share a working folder, a file checked out by one user can be modified by anyone with access to that folder. Maintaining separate working folders ensures that users modify only files they have checked out themselves.

System Clocks

Synchronize the dates and system clocks for all Visual SourceSafe client computers with the Visual SourceSafe server. This prevents check-in and check-out operations from appearing to happen out of sequence and affects any labels that are applied. Synchronizing dates and system clocks is particularly important when users from different time zones access the same database.

You can set up a computer running Windows NT Server to act as a Domain Time Source server for users to synchronize their local date and time with the network. For additional information, see How to Set Up and Synchronize with Domain Time Source Servers.

New Databases

Avoid creating a new database by copying an existing one. Doing so can potentially cause problems because the globally unique identifier (GUID) in the Um.dat will be the same for both databases. For further details, see How to Create a New Database in SourceSafe.

Moving Databases or Visual SourceSafe Installations

To move a Visual SourceSafe installation, copy the entire VSS folder and all of its subfolders to the new location. However, do not use XCOPY to do this because it does not copy some zero-byte files. Instead, use Windows Explorer to copy the folder(s). After you have copied the installation, Visual SourceSafe clients must change the #include statement in their local Srcsafe.ini file to reflect the new location. No other modifications are necessary. To move just the database itself, perform the same operation on the Data folder and then modify the DATA_PATH line of the server Srcsafe.ini instead of the client Srcsafe.ini. When specifying the DATA_PATH, use the UNC method (\\SERVER\SHARE). For further details, see HOWTO: Move a VSS Database or Project to New Location.

Tip   After you have moved the VSS location, you can create an Srcsafe.ini file in the old location with a #include statement pointing to the new SrcSafe.ini location. This provides time for users to change their links.

Integrated Environments

When using Visual SourceSafe through the integration in the development environments (Microsoft Visual Basic®, Microsoft Visual C++®, Microsoft Access, Microsoft FrontPage®, and so on) use the integrated component to perform Visual SourceSafe operations that can be done within that environment. For example, do not check out and check in files from both the Visual SourceSafe Explorer and integrated environments. This is very important because Visual SourceSafe does not understand the links between the source files the way the integrated development environment does. For instance, in Visual Basic, a form can be made up of an FRM and an FRX file. Visual Basic knows to check out both files at the same time, but Visual SourceSafe does not. Checking out only one file in Visual SourceSafe Explorer causes the files to get out of sync and hence corrupted in Visual Basic.

How Visual SourceSafe Tracks Files

Visual SourceSafe is a file-based version control system that is designed for use on multiple, industry-standard network servers. No special program needs to be run on the server during normal use. The core of a Visual SourceSafe database is the Data directory; it has a unique structure that is designed for maximum flexibility. A Visual SourceSafe database consists of the following files and folders.

Visual SourceSafe creates two files in the Data directory for every file and project that you add to Visual SourceSafe (with one exception described later in this section). These file pairs are distributed evenly across the A through Z subdirectories in the Data directory. The file without an extension (such as QRBAAAAA) is the log file for the file type being stored. The log file contains internal information for Visual SourceSafe, such as who added the file, where it exists, and all the differences between the versions of the file. The file with an .a or .b extension (such as QRBAAAAA.A) is the most recent version of the actual file stored under a Visual SourceSafe physical name. Each time a file is checked in, the extension it is saved with alternates between .a and .b.

When a user checks in a file, it is copied from their working directory to the Data directory and renamed with the physical name and either an .a or .b extension, whichever is not currently there. Visual SourceSafe then calculates the differences between the .a and .b files and stores it in the log file (the file without an extension). After the log file is updated, the old copy of the data file is deleted. Under normal circumstances you should never have both .a and .b extensions for one physical file name.

Caution   Never rename an .a or .b file in the DATA folder. Although doing so appears to correct the immediate problem that you are experiencing (such as: The file QRBAAAAA.A not found.), it will make the previous versions of the file unrecoverable. If you receive this error, restore the file pair from a recent backup.

When you share a file from another project, no new file pair is created in the Visual SourceSafe database. Instead, Visual SourceSafe creates a reference in the original file's log, noting that the file also exists in another project.

Finding and Repairing Data Corruption

Use the Analyze tool, located in the Microsoft Win32® directory, to check for and correct corruption problems. You should run it as frequently as is practical—once a week is recommended, or at a minimum, once a month. Analyze checks all the files in the Visual SourceSafe Data directory for corruption or disconnected links and often repairs these with proper switch settings. Because Analyze is so thorough, it can be slow to run. The amount of time that Analyze takes to run depends on the content and structure of the database, such as the amount of sharing and branching, and the total number of files.

For best performance, all users should log off Visual SourceSafe before you run Analyze.exe. If you use the -F switch to repair problems, users must log off. However, if you want to run Analyze.exe without requiring users to log off, you can use the -X switch.

Note   Due to the amount of file I/O required, you can dramatically improve performance by running Analyze locally (that is, on the server) rather than across the network.

Analyze has several switches you can use to tell it what to do when running. Do not try to use every switch at once. The more Analyze is required to do, the longer it takes to run.

When you run Analyze, it executes in the following four passes.

1. Checks every file in the Data directory to make sure that it is valid and not corrupt.
2. Checks the relationships between parents (projects) and children (files and projects).
3. Checks the relationships between shared and branched files.
4. Checks the files Um.dat, Rights.dat, and Names.dat and performs cleanup operations.

Analyze supports the following switches.

Running Analyze in the following order provides good coverage.

Each time Analyze runs, it places an Analyze.log file in the Backup folder along with a file called Analyze.bad. The Analyze.bad file contains a list of all files in which Analyze found problems. When Analyze fixes a file, it first creates a copy of the file in the Backup folder so that the repair can be undone if necessary. Each time Analyze runs, it requires that the Backup folder is either empty or does not exist. If there is sufficient disk space, it is a good practice to rename the Backup folders instead of deleting them. This history can prove very useful in troubleshooting corruption issues. The errors and messages reported by Analyze are discussed at length in INFO: Error Messages from Analyze Tool of Visual SourceSafe.

Analyze can also re-create the Status.dat, Names.dat, and Rights.dat files. To do this, rename or delete the files you want rebuilt, and run Analyze -F. Analyze re-creates the Names.dat file with the spaces in long file names appearing as underscores. You then need to rename the file using Visual SourceSafe Explorer. The Rights.dat file is re-created, but as an empty structure; you need to add permissions for each user again.

Microsoft occasionally updates the Analyze tool to include more checking or to improve performance. For the latest version of Analyze, visit the Microsoft Visual SourceSafe Web site located at https://msdn.microsoft.com/ssafe/default.asp.

Backup and Restore

Backups should be performed regularly as part of the daily or weekly file maintenance and security process. When backing up your Visual SourceSafe database, make sure you are getting a full backup of the database. Although you can use incremental backups, you should avoid them because some of the files from the database may not be able to be restored. If users are logged on to Visual SourceSafe and actively using the product, the files they have open will not be backed up by most standard backup utilities. There are several backup and copy utilities that can back up open files. However, if you use these utilities and someone is actively updating a file in Visual SourceSafe when the file is backed up, the backup may be corrupted.

Important   Do not schedule Analyze to run at the same time as a backup of the database! If the backup program has files open that Analyze is trying to open, Analyze will shut down unexpectedly.

Visual SourceSafe automatically closes any files opened by Visual SourceSafe or an integrated application after 15 minutes of inactivity. (This requires Service Pack 3 of Visual SourceSafe 5.0 or later.) The user still appears to be logged on to Visual SourceSafe and the files will be reopened when they start working again. However, the Rights.dat and Status.dat files remain open any time users are logged on and will not be backed up. You can rebuild these if needed using the Analyze utility. Each time the administrator modifies the rights by project information for a Visual SourceSafe database, Visual SourceSafe copies the Rights.dat file to a Rights.bak file. If necessary, you can rename the Rights.bak file during a restore process.

Caution   Never restore a complete backup of a database over an existing database. Visual SourceSafe maintains very complex links between files. Restoring a whole database backup over an existing database may confuse the links between files and cause incorrect versions of the files to be displayed in the database.

Prevent Power Loss

A disaster-recovery study by Contingency Planning Research found that power loss caused 27 percent of data-center disasters in which there was actual data loss in addition to loss of service. This figure includes power outages due to environmental disasters such as snowstorms, tornadoes and hurricanes. To minimize these disasters, invest in an uninterruptible power supply (UPS). Windows NT Server includes built-in support for UPS.

Install Fault-Tolerant Storage

RAID technology minimizes data loss due to problems accessing a hard disk. RAID is a fault-tolerant disk configuration in which part of the physical storage capacity contains redundant information about the data stored on the disks. You can regenerate the data using this redundant information if one of the disks or the access path to it fails, or if a sector on the disk cannot be read.

• Install RAID Level 1 for the operating system and LOGs.
• Install RAID Level 5 or RAID 0+1 for DATA.

For information about how to make your server more reliable, see the following resources:

https://www.microsoft.com/Windows2000/library/howitworks/management/relavail.asp

https://www.microsoft.com/NTServer/nts/deployment/planguide/HighAvail.asp