# Visual SourceSafe 6.0a Readme

## Microsoft® Visual SourceSafe™ 6.0a

© 2000 Microsoft Corporation. All rights reserved.

Other product and company names herein may be the trademarks of their respective owners.

Visual SourceSafe Readme includes updated information for the documentation provided with Microsoftâ Visual Studio® -- Development System for Windows® and the Internet. The information in this document is more up-to-date than the information in the Help system.

###

Contents - Click any of the items below

##### Release Description

##### Known Problems

> Installing on a Novell Network Server

> Corrected Documentation Text

> MBCS/DBCS Users

> Bug Fixes

> Unicode Files

##### Getting Started

> Before You Run Setup

##### Installation

> Visual SourceSafe 6.0a Setup

> Installing Visual SourceSafe 6.0a over Visual SourceSafe 6.0 SP4 or Earlier

> Installation Options

> Installing Visual SourceSafe Standalone Version

> Installing Multiple Versions of Visual Studio 6.0 Products "Side-by-Side" on the Same Computer

> (Individual Users) Using Netsetup to Create a Personal Installation

> Upgrading a Database After Installing

> Deleting VSS

##### General Notes and Tips

> New Features in VSS 6.0

> Maintaining Your VSS Database

> Loss of Network Connection Produces Numerical Error Message

> System Date/Time

> Using the Command Line After Running a Client Setup

> Details on Defining a Shadow Folder in Visual SourceSafe

> Running Netsetup from a Windows NT Server Computer Using Windows 95

> VSS Home Page

> Microsoft Knowledge Base

> VSS Newsgroup

##### Best Practices

> Introduction

> General Database Recommendations

> How Visual SourceSafe Tracks Files

> Finding and Repairing Data Corruption

> Backup and Restore

### Visual SourceSafe 6.0a Release Description

Visual SourceSafe version 6.0a is a re-release. It contains a modified installation program and updated VSS files containing all bug fixes made since VSS 6.0 released. This version is intended to upgrade the VSS release included in Microsoft Office Developer version 9.0.

The installation program for VSS 6.0a has been modified to ensure an upgrade of your existing VSS 6.0 installations. Read the Installation section in this document for the latest install directions. For a list of the fixes included in this release, see VSS 6.0a Bug Fixes.

### Known Problems

#### Installing on a Novell Network Server

Novell NetWare servers can be configured to handle either long file names or file names in the 8.3 file name format. If the Novell NetWare server can handle only file names in the 8.3 format, the regular Visual Studio installation process cannot install on the Novell NetWare server. To install VSS on a Novell NetWare server that can handle only file names in the 8.3 format, use the following steps.

To install from the Visual Studio CDs:

1. Insert Disk 2.
2. Switch to the VSS_SS\ folder.
3. Run the following command: setup.exe /F
4. Click Server Applications.
5. When prompted for the installation location, change it to the Novell NetWare Server.

To install from the Visual SourceSafe standalone compact discs:

1. Insert the Visual SourceSafe compact disc.
2. Run the following command: setup.exe /F

#### Corrected Documentation Text

Difference for File Dialog Box topic — In the Dialogs section of the Visual SourceSafe documentation, the first paragraph in the Remarks section is incorrect.

> Current text: This dialog box is used only when you have not selected the visual difference comparison. (For visual differences, make sure you select the Visual option from the Difference Options dialog box.) By default, VSS uses the Visual Difference dialog box.

> Correct text: This dialog box is used only when you have not selected the visual difference comparison. (For visual differences, make sure you select the Visual option from the Difference Options dialog box.) By default, the Visual option is selected, and VSS uses the Differences for <filename> dialog box with options specific to visual differences.

In the File History Options Dialog Box topic of the Visual SourceSafe Documentation, the first sentence of the Labels section is incorrect.

> Current text: Includes only labels in project history if you have selected the Include file checkins option.

> Correct text: Includes only labels in project history if you have selected the Include file histories option.

In the Advanced Check Out Options Dialog Box topic of the Visual SourceSafe Documentation, the Replace option is incorrect.

> Current text: Replace — Replaces the file with a read-only version.

> Correct text: Replace — Replaces the file with a writable version.

In the Advanced Check Out Options Dialog Box topic of the Visual SourceSafe Documentation, the End of Line option has been removed.

In the Advanced Get Options Dialog Box topic of the Visual SourceSafe Documentation, the End of Line option has been removed.

#### MBCS/DBCS Users

VSS 6.x handles MBCS (multibyte character sets) and DBCS (double-byte character sets) differently from earlier versions of VSS. If you are upgrading an existing installation of VSS that has a file called SSUD.dll, rename it so that VSS 6.x does not recognize it. For example, rename the file to SSUD.bak. If you do not rename it, you may have trouble in the IME with font association (FA) turned off or it may generate GPFs when dialog boxes that are new to VSS 6.x are displayed.

#### Bug Fixes

VSS 6.0a contains the following bug fixes. References to articles in the Microsoft Knowledge Base are included where appropriate.

- Q238242: OLE Automation loads incorrect TypeLibrary in late binding.
- Q238345: OLE Automation: Opening a SourceSafe database fails with "Out of Memory" on WIndows 2000.
- Calling QueryInterface on a IVSSVersion returns E_NOINTERFACE.
- DATA LOSS: Enabling Make Writable on file get dialog causes Replace Writable options to be ignored.
- Running analyze -f overwrites analyze.log file when backup folder is not empty.
- OLE Automation created with VSS 5.0 not working on a 6.0 computer.
- Setting multiple checkouts on a per project basis disables the Checkout option after a file has been checked to one user.
- CDCR: Destroying a project does not show that it is still working.
- Analyze fails to repair or remove orphaned files in a VSS database.
- Names.dat corruption not repaired by Analyze.
- Project Difference shows file changed, then says files are identical.
- Q244960: When running DDUPD.exe on a Visual SourceSafe database, you may receive an error "Out of memory." This typically occurs when you have many files that are labeled
- Q230702: Delete and Destroy or Rename Project gives "File or project not found" and "1E string load failure #%d" errors.
- Restoring archived files generates an error message "Too many file handles open" and the files are not restored.
- Running analyze –f incorrectly truncates long file names resulting in database corruption.
- Q228927: Performance problem with the integration between Visual C++ and VSS.
- Q237184: Branching from a label gives "File or project not found" and "You do not have access rights to $/<deleted project>" and the branch operation does not successfully complete.
- Running analyze.exe –f on a database after archiving and restoring can result in project data file corruption
- Q248760: Sharing a file, then deleting it, and branching the file to the same project causes analyze to report the "Project log '<physical filename>' has a share (from another project) record for item '<filename>', but that item wasn't found in the current project." Running analyze –f does not fix the error/warning message.
- Regular Users cannot open the VSS database on a W2k machine.
- OLE Automation: Memory leak in VSSItem::Get.
- Q196599: VSS 6.0 hangs when issuing a Get on a Label from the History dialog box.
- Q197050: "Get" by Label of subproject of labeled $/ by a VSS 6.0 client on a VSS 5.0 format database results in "Version not found," and nothing is retrieved.
- VSS 6.0 Analyze utility crashes with access violation.
- VSS 6.0 Show Difference window is giving errors. In the VSS 6.0 Show Difference window, several operational bugs were reported that resulted in erroneous information being displayed and valid operations not being performed. Many of these reported display problems with the Show Difference window have been fixed in this release.
- Q196599: Doing a recursive Get from the command line on a root ($/) project label fails with "Unable to finish writing file."

#### Unicode Files

Visual SourceSafe cannot handle Unicode files. When a file is first added to SourceSafe, SourceSafe auto-detects whether the file is in text or binary format. If Unicode files are added as text format files, SourceSafe can corrupt them.

To work around this issue, add all Unicode files to SourceSafe as binary format files. You can override the file type auto-detect feature by clicking the Advanced button on the File Add dialog when you are adding a file. If the Unicode file has already been added, you can access the properties of the file in SourceSafe and change the file type to Binary.

### Getting Started

#### Before You Run Setup

- Review the Hardware and Software Requirements.

### Installation

#### Visual SourceSafe 6.0a Setup

- Visual SourceSafe 6.0 requires Internet Explorer version 4.01 SP1 or later to enable the Help system. The Setup program for VSS 6.0a does not include a distribution of Internet Explorer, so you must install it before you install VSS 6.0a. You can find the latest version of Internet Explorer at http://www.microsoft.com/windows/ie/. The VSS 6.0a Setup program checks for the minimum required version of Internet Explorer and displays a message if it does not detect it. You can continue the installation, but it is strongly recommended that you quit the VSS 6.0a Setup program and install Internet Explorer version 4.01 SP1 or later before resuming Setup.
- If you already have VSS 6.0 installed on your system, the VSS 6.0a Setup program upgrades your current installation to version 6.0a. Answer Yes when you are asked to upgrade and select the same installation you currently have on your system.
- VSS 6.0a is a minor release to the VSS 6.0 product and cannot run side by side with another installation of VSS 6.0. Either upgrade your existing VSS 6.0 installation to 6.0a or do not install VSS 6.0a on the same system.
- If you upgrade your existing server share installation to VSS 6.0a, your clients can upgrade to VSS 6.0a by re-running the Netsetup program and choosing to upgrade their existing installation.

#### Installing VSS 6.0a Over VSS 6.0 SP4 or Earlier

When you run the VSS 6.0a Setup program on a computer that has VSS 6.0 with SP1, SP2, SP3, or SP4 installed, the Setup program displays the following warning message:

> The Installation Wizard has detected a potentially conflicting version of a Visual Studio 6.0 product on your machine. One or both of these products may not work after installing this product. The Readme topic "Side by Side Product Installations" describes the supported combinations.

> Do you wish to continue?

This warning is valid because installing VSS 6.0a side by side with VSS 6.0 is not supported. Answer Yes to this message and to a subsequent message asking you if you are certain you want to continue.

When Setup continues, it states that you have an older version of the product already installed and asks whether you would like to upgrade it. Click Next to accept the selected folder location. When prompted for the specific installation type, select the type already installed on your system.

#### Installation Options

##### General Notes

The source code control database maintained by VSS must be on a drive that is accessible to all users working on projects controlled by VSS. The most versatile method of working with VSS is to perform a server installation to a network drive, and a netsetup installation on each workstation.

##### Upgrading an Older Version of SourceSafe to Version 6

You will be prompted to replace an existing installation if found. This is recommended, but you can choose an alternate path and then maintain two different databases, one in the old format and one in the new format, on the same computer.

Note Make sure you back up the database before you upgrade.

You will be prompted to convert your database to the new format for faster performance. You should do this only if:

- You are the administrator for your database.
- No people are logged onto the database.
- All users of the database can be upgraded to client software compatible with the version 6 format.

##### VSS Database Administrators Note About Netsetup

Be aware that a full VSS license is required for each user of Visual SourceSafe. For example, if you have 100 people using your VSS database, you must purchase 100 Visual SourceSafe licenses to avoid violating copyright law.

The version 6.0a Netsetup program requires a CD-Key before it can install the Visual SourceSafe client software to a client computer. To make sure your clients can run Netsetup successfully, give a CD-Key from one of your licensed boxes to each user you recommend Netsetup to. It is acceptable to reuse the same CD-Key for everyone running Netsetup, but you are still required to have an individual license on hand for every user.

#### Installing Visual SourceSafe Standalone Version

##### To install Visual SourceSafe standalone version as the Administrator (Admin)

1. Install Visual SourceSafe on the shared server.
2. Use the Admin tool to create user accounts in the shared database.
3. Set up security as appropriate for the users of the database.
4. Tell your users where to find Netsetup (if those users are licensed).

##### To install Visual SourceSafe standalone version as a Client

- Run Netsetup from the server location for client-only installation.

> Note A full Visual SourceSafe license is required to use Netsetup by each client.

- or -

- Install the standalone Visual SourceSafe from the compact disc (by choosing Standalone). This creates a local database. To use a shared database, click Open SourceSafe Database on the File menu from the Visual SourceSafe Explorer.

#### Installing Multiple Versions of Visual Studio 6.0 Products "Side-by-Side" on the Same Computer

Visual Studio products with the same version and in the same language—Visual C++ and Visual Basic version 6.0 in English, for example—can be installed separately on the same workstation. Such installations are supported by Microsoft. The Visual Studio 6.0 Installation Wizard detects if other versions of the 6.0 product line have been installed on a workstation.

Mixing different language versions, point releases, or product tiers on the same workstation are generally not supported. This means that the installation can fail, one or more of Visual Studio 6.0 products may not work even if the installation succeeds, or in the worst case you may not be able to remove any of the products completely.

If the wizard generates a warning during installation, the safest course of action is to uninstall the Visual Studio 6.0 product before proceeding. The detection scheme checks for the following scenarios:

- Users installing different language versions of the same product. For example, Japanese Visual Basic and English Visual Basic. Installation of certain combinations is supported.

Product | Supported Installation
Visual Basic | Install in two different locations
Visual C++ | No side-by-side installation is supported.
Visual FoxPro | Install in two different locations
Visual InterDev | Install in the same location. You must reinstall after removing one version.
Visual J++ | Install in the same location. You must reinstall after removing one version.
Visual SourceSafe | Install in the same location. You must reinstall after removing one version. Note The UI language chosen when you run Visual SourceSafe is based on the system's language settings. If that language is not installed for Visual SourceSafe, it uses English instead.
MSDN | Install in default directory.

- Users installing different tiers of Visual Studio 6.0 products. For example, Visual J++ Standard Edition and Visual InterDev Professional Edition. Installing different tiers of the same product on the same workstation is not supported.
- Users installing point releases. Upgrading a later point release of Visual Studio over an earlier point release is supported. However, installing earlier versions over later versions is not supported.
- Users installing stand-alone versions of Visual Studio 6.0 products over the versions installed from Visual Studio 6.0 Professional or Enterprise. For example, Visual FoxPro 6.0 over Visual Studio Professional 6.0. Installing a stand-alone version of the same language versions (English) of Visual Studio 6.0 products is supported. It is safe to install Visual FoxPro 6.0 (English) from the stand-alone version on a workstation that already has Visual Basic 6.0 installed from Visual Studio Professional Edition.

#### (Individual Users) Using NetSetup to Create a Personal Installation

After an administrator has created a VSS installation on the server, users can run NetSetup to copy the VSS executables to their hard disk.

To install using NetSetup:

1. In Windows Explorer, navigate to the main folder containing the VSS Server installation.
2. Double-click netsetup.exe.
3. Follow the instructions in the Installation Wizard, using [Change Folder] to change the default installation path
.

> Warning to Administrators All users, including anyone running Netsetup, must possess an individual VSS license to install and/or use the product. Netsetup is provided as a convenience, but the administrator should make sure to obtain individual licenses for each person that installs and uses the product.

#### Upgrading a Database After Installing

If you were prompted to upgrade your database to the new 6.x format and you indicated Yes, you now have a 6.x database and can take advantage of label promotion and enjoy performance enhancements. If you weren't prompted or you indicated No to the prompt and you now want to upgrade your database, run the DDUPD.exe command-line utility, which exists in the \win32 directory of your VSS 6.x server installation. (You can either go to that directory and run it or add that directory to your path and run it.) We recommend you run DDUPD only when everyone has quit VSS. The syntax is:

> DDUPD <path to data folder> [-undo] [-redo]

To upgrade a 5.0 database, for example, you would run:

> DDUPD \\server\share\vss\data

To undo an upgrade, return to the version 5.0 format and stop taking advantage of the performance enhancements and label promotions:

> DDUPD \\server\share\vss\data -UNDO

To redo the upgrade process on a database that is already in the new format, run:

> DDUPD \\server\share\vss\data -REDO

#### Deleting VSS

If you delete a VSS installation (including the database) and then attempt to run Setup, Setup may try to install VSS in the Recycle bin (if the old database is found here). This happens only if the Recycle bin hasn't recently been emptied. To remedy the problem:

1. Empty the Recycle bin.
2. Run Setup again, and verify that the default directory for VSS is no longer the Recycle bin.

### General Notes and Tips

#### New Features in VSS 6.0

Microsoft VSS 6.0 adds many new features. Some of the highlights include:

- Create database – Available in the Visual SourceSafe Admin application. With it, you can create a new VSS database in any location. To use this command, on the Tools menu, click Create Database.
- Archive and Restore - Now available in the Visual SourceSafe Admin application in addition to the command line.
- Label promotion - You can promote, or add, a file to an existing label.
- Move files - When you move a file, VSS automatically shares the file to a new project and then deletes it from the original project. In the new project, the file appears as shared.
- Compare differences in multiple projects - You can compare differences in a project against another project, compare in two different local folders, or compare a project against any directory, not just its working directory.
- Deploy individual files from the GUI - In VSS 6.0, using the VSS Explorer, you can now deploy a file as well as an individual folder.
- Filter history information - You can now view history of files and projects without including labels.
- Clean temp directory option - A quick, easy way to delete all files from the temp directory used by VSS, provided the files are not open.
- Check External Hyperlinks - In VSS 6.0, Check Hyperlinks now works on external hyperlinks, or jumps outside the project, as well as internal hyperlinks, or jumps within the project.
- Create desktop shortcuts to VSS databases (from VSS Explorer) - You can create a shortcut on your desktop that opens a specified VSS database in the specified project.
- HTML Help - This version uses HTML Help rather than WinHelp.

#### Maintaining Your VSS Database

It is still advisable to back up the drive where your VSS database resides regularly. It is important to use full backups, not incremental or differential backups, to avoid problems.

In addition, you should run the ANALYZE program periodically to maintain database integrity. If a corruption is found, the ANALYZE program can usually repair the problem. Updates to the ANALYZE tool are posted periodically on the VSS Web site, http://www.msdn.microsoft.com/ssafe. You can check that site to see if there is a version of ANALYZE more recent than the one shipped with this product.

To run ANALYZE:

1. Click the Start menu.
2. Point to Programs.
3. Click Microsoft Visual SourceSafe (if you installed VSS with Microsoft Visual Studio, click Microsoft Visual Studio, then click Visual SourceSafe).
4. Click either Analyze VSS DB or Analyze & Fix VSS DB.

> Note It is always advisable to run ANALYZE and back up older databases before upgrading them to the 6.x format.

#### Loss of Network Connection Produces Numerical Error Message

If you are using VSS on a remote database and you lose your connection to the server, the following error will occur:

> "unknown error - 20038," (or similar)

If you see this error, you have lost your network connection.

To correct the situation

1. Restore your network connection.
2. Restart VSS to continue your work.

#### System Date/Time

VSS uses the date and time that your local computer stores. If your computer is not synchronized with other computers, unpredictable results can occur. For instance, you check in a file after someone else, but VSS thinks your checkin happened first because your system clock was off!

The best solution for this problem is to synchronize your local date and time with the network on a regular basis. With Windows NT this can be done with a Domain Time Source Server. Check the http://www.novell.com/ site for information on time synchronization with Novell NetWare servers.

#### Using the Command Line after Running a Client Setup

If you are working from the command line and receive a message stating "No VSS database (SRCSAFE.INI) found. Use the SSDIR environment variable or run netsetup.", set the SSDIR variable. This tells VSS where to find the Srcsafe.ini file for the VSS server installation to which you want to connect. You can do this by typing the following at the Command prompt:

> set ssdir=\\server\share\vss

Where \\server\share\vss is the folder where the Srcsafe.ini file is located.

Note There should not be a space between the equal sign and the location of the VSS server installation. For example, the following will not work:

> set ssdir= \\server\share\vss.

#### Details on Defining a Shadow Folder in Visual SourceSafe

A shadow folder is a live mirror (on the file system) of the projects in the Visual SourceSafe (VSS) database.

For a shared database, you must set up the shadow folder with a Universal Naming Convention (UNC) path, such as \\Server\Share\Shadow, to avoid failure when changes are made from a computer other than the one used to set up the shadow. Make sure the UNC contains no long names, just eight-character short names for the \\Server\Share\Root portion.

For example, instead of defining the shadow folder as D:\VSSShadow, you can define the shadow folder as: \\server\D\Shadow.

Confirm that all the Visual SourceSafe users have read/write access to the UNC directory.

#### Running Netsetup from a Windows NT Server Computer Using Windows 95

Due to a problem Windows 95 has accessing some programs on Windows NT Server computers through a UNC that contains long names, you should create a network share on the Windows NT Server computer that points directly to the VSS location on the server's disk drive, and avoid long names for the server and share names as well.

For instance, if VSS is installed to:

> D:\Program Files\Microsoft Visual Studio\Common\VSS

You can provide users access to it by setting:

> D:\
> shared as
> \\Long Server Name\Long Share Name

And they would then access it with:

> \\Long Server Name\Long Share Name\Program Files\Microsoft Visual Studio\Common\Vss\Netsetup.exe

The long names cause computers running Windows 95 to fail when the server is a computer running Windows NT.

Instead, set it up with:

> D:\Program Files\Microsoft Visual Studio\Common\VSS
> shared as
> \\Server\VSSShare

In this way, users can access Netsetup.exe with the following short UNC:

> \\Server\VSSShare\Netsetup.exe

#### VSS Home Page

Microsoft VSS has a home page on the Internet. This home page features a variety of information including articles on VSS, a self-running demo that you can download, a collection of helpful VSS utilities, and much more. The URL for the home page is: http://www.msdn.microsoft.com/ssafe.

#### Microsoft Knowledge Base

If you encounter problems or have questions not addressed here or in the online documentation, you can search the Microsoft Knowledge Base at http://support.microsoft.com/support. The Knowledge Base is also available on the MSDN Library Visual Studio 6.0, included on the CD-ROM with Visual SourceSafe.

#### VSS Newsgroup

You can exchange information with other VSS users by visiting the microsoft.public.visual.sourcesafe newsgroup on the Internet. This newsgroup is on the msnews.microsoft.com server.

Note Microsoft does not provide support for messages posted to the newsgroup.

### Best Practices

The most up-to-date SourceSafe Best Practices Guide can be found at: http://msdn.microsoft.com/library/default.asp?URL=/library/techart/vssbest.htm. This guide is in English only.

#### Introduction

Under normal operation in a stable environment, 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 section 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, make sure that you are running the latest version of the applications. 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 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

For more detailed information on Analyze, see Finding and Repairing Data Corruption later in this document.

##### 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 does check 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

Users' Ss.ini files 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 the Knowledge Base article "How to Set Up and Synchronize with Domain Time Source Servers (search on article ID Q131715).

##### 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 details on how to create a new database, see Knowledge Base article Q123467, "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 details, see Knowledge Base article Q176909, "HOWTO: Move a VSS Database or Project to New Location."

Tip After you have moved the VSS location, you can create a 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 a FRM and a FRX file. Visual Basic knows to check out both files at the same time, but SourceSafe does not. Checking only one file out in the Visual SourceSafe Explorer causes the files to get out of sync in Visual Basic and hence corrupted.

#### 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.

File/folder | Description
SrcSafe.ini | Visual SourceSafe database global settings and configuration information for all users.
Users.txt | List of all users of the Visual SourceSafe database.
Data\Aaaaaaaa.cnt | Physical name of last file added to the database.
Data\Crcs.dat | CRC information used to speed up the get and check-out processes (Visual SourceSafe 6.0 format databases only).
Data\Names.dat | Long file name information.
Data\Rights.dat | User and project security information.
Data\Status.dat | Visual SourceSafe Explorer cache file (used to speed up the display of the Visual SourceSafe Explorer).
Data\Um.dat | User management information (names and passwords) and the database identifier (GUID).
Data\Version.dat | Visual SourceSafe database version.
Data\A…Z (folders) | Folders containing log files and data files.
Data\Backup (folder) | Contains analyze log file (analyze.log), list of bad files (analyze.bad), and backups of files changed by Analyze.
Data\Labels (folder) | Label cache information used for label promotion (Visual SourceSafe 6.0 format databases only).
Data\Locks (folder) | Used if Visual SourceSafe locking is enabled.
Data\Loggedin (folder) | Contains user logon files and an Admin.lck file if the database is locked.
Users (folder) | Contains Template.ini, which stores default values for the Ss.ini file for new users. The Users folder also contains a subfolder for each user. This subfolder contains an Ss.ini file defining user-specific settings. The Admin folder also contains Ssadmin.ini, which defines administrator settings.

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 contents 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. Analyze checks every file in the Data directory to make sure that it is valid and is not corrupt.
2. Analyze checks the relationships between parents (projects) and children (files and projects).
3. Analyze checks the relationships between shared and branched files.
4. Analyze checks the files Um.dat, Rights.dat, and Names.dat and performs cleanup operations.

Analyze supports the following switches.

Switch | Description
-B<folder> | Specifies the folder to use for backup.
-C | Compresses unused space. (This simply removes blank space and does not compress the log files.) This pass can generate a large number of files in the backup folder and should be used only when there is plenty of disk space available.
-D | Deletes unused files.
-DB | Deletes the Backup folder. Caution If you find corruption, create backup copies of logs before running Analyze with the -DB switch.
-F | Automatically fixes corrupted files. (Requires users to log off database.)
-I- | When the analysis is complete, the program quits. (Useful if running in a batch script.)
-V1 | Displays only critical errors. (This is the default setting, if no -V switch is used.)
-V2 | Displays only significant errors.
-V3 | Displays all errors and inconsistencies.
-V4 | Displays errors, inconsistencies, and informational notes.
-X | Does not attempt to lock the database when analyzing. (Recommended only when users must remain logged on while Analyze.exe runs; -X cannot be used with -F. If Analyze tries to access a file that is in use while in this mode, it will quit and you will need to re-run it at a later time.)

Running Analyze in the following order provides good coverage.

Command line | Description
Analyze –V4 <database path> | The first pass should always locate problems before trying to fix them.
Analyze -F –V4 <database path> | If errors are reported in the first pass, run Analyze again in fix mode to correct them.
Analyze -F -C –V4 <database path> | Run this pass when you have “Found a DIFF” and “Found a COMMENT” errors that you want removed. Caution Since the DIFF and COMMENT messages can occur in a large number of files, it is extremely important that you have enough disk space available when running a Compress pass on your database.

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 Knowledge Base article Q152807, "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 http://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.

Note 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:

http://www.microsoft.com/backofficeserver/prodinfo/BOS_Checklst.doc

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

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

http://www.microsoft.com/NTServer/fileprint/exec/overview/reliability.asp