SourceSafe Concepts

This page covers how certain concepts in SourceSafe work in the context of AbaPerls.

Contents:
    How AbaPerls Accesses SourceSafe
    The SS-path
    SourceSafe Labels
    Supplementary Labelling of Files
    Pinning

How AbaPerls Accesses SourceSafe

AbaPerls accesses SourceSafe through its OLE interface. This has some quirks, both good and bad for the AbaPerls users, as we shall see on this page.

When AbaPerls connects to a SourceSafe database, it does not use the regular SRCSAFE.INI for the database. Instead AbaPerls creates a directory in your TEMP directory (designated by the environment variable TEMP). This direcory is called SSOPEN.xxx where xxx is a long string of digits to ensure that it is unique. In this directory AbaPerls creates the two files SRCSAFE.INI and USERS.TXT. They contain the minimum information for connecting to the SourceSafe database. The net effect of this arrangement is that with one exception, AbaPerls completely bypasses all customizations for the database, either they are set up in the regular global SRCSAFE.INI for the database, or in the SS.INI for the individual user! Thus AbaPerls does not know about your working directory and what other preferences you may have. And AbaPerls don't want to know. And least of all AbaPerls does not want to be surprised by unexpected settings.

The one exception from this rule is the journal file. AbaPerls reads the SRCSAFE.INI for the database, and if a journal file is defined, this line is copied to AbaPerls own SRCSAFE.INI, so that tools that make changes in the database correctly journals their operations.

When logging into the SourceSafe database, AbaPerls assumes that your Windows user maps to a SourceSafe user; there is no way to specify a SourceSafe user or a password for SourceSafe.

When AbaPerls attempts to create an OLE object for SourceSafe, this may fail with the message Could not create OLE object for SourceSafe under unfortunate circumstances. Here is a short check-list:

Check that you have SourceSafe installed on the machine, and that it is Visual SourceSafe 5 or later. VSS 4 will not do.
Check that you have not installed multiple versions of SourceSafe on the machine. If you install a new version of SourceSafe, explicitly uninstall the older version first. (This does not apply to service packs, but it does apply if you upgrade from VSS 6.0a to VSS 6.0c or to VSS2005)

When an AbaPerls tool completes successfully, AbaPerls deletes the SSOPEN-directory that it created. AbaPerls also attempts to delete the directory in an error causes the tool to abort during execution. Sometimes, though, these directories are left behind. You can safely delete these directories. (However, do not delete the SSOPEN-directory for an AbaPerls tools that is currently running. It appears that SourceSafe occasionally feels a need to re-read the files, and if the directory is gone, the tool might die with a strange error. Been there, done that.)

The SS-path

To access an item – file or project – in SourceSafe you need to specify two things: a path on disk to the SourceSafe database, and a path within that database to the item. AbaPerls collapses this into one string, known as an SS-path. You use SS-paths with the -VSS command-line switch and in config-files.

The form of an SS-path is:

[database/]$/project-path[/file]

You can specify database as a complete file-system path, for instance F:\DEVELOPMENT\OUR-DB\DATA.

If database does not contain any backslashes, AbaPerls tacks on S:\ in the beginning and \DATA in the end, as this agrees with the location of our SourceSafe databases in the AbaSec development.

If you leave out database completely, that is your SS-path starts with $/, AbaPerls will read the database name from the environment variable SSDIR. If this variable is not defined, AbaPerls will use the default S:\DATA.

You specify project-path and file in the normal SourceSafe way. Beware that you must include the $/, as this separates the database part from the project part. If you fail to include project-path, the default will be $/, the top project in the database, and this is rarely want to you want.

Examples of proper SS-paths

ababos32/$/kati/1.0/sql
-- Database S:\ababos32\data, project $/kati/1.0/sql.
data/$/projects/Fond/Config/fond-3.0.cfg
-- Database S:\data\data, proj $/project/Fond/Config, file fond-3.0.cfg.
"C:\Program Files\DevStudio6\Common\VSS/$/MyProject"
-- Database C:\Program Files\DevStudio6\Common\VSS, proj $/MyProject.

Note that when a path includes spaces as in the last example, you need to put the path in quotes, both when you specify it on the command line as an argument to the -VSS comand-line switch and in a config-file.

SourceSafe Labels

Several of the AbaPerls tools permit you to specify a certain version of an object in SourceSafe. This specification can be either a label, a date, a version number or the string LATEST. You cannot however specify whether you are actually using a label, date or a version number. AbaPerls, or more precisely the OLE interface of SourceSafe, will make this decision for you. Thus, you should provide the label or date as-is, and not prepend an L for labels or D for dates as in the SourceSafe GUI when you use AbaPerls.

Normally you should use a label to specify a version, and anything which is not a version number, a date or the string LATEST is a label. But as we shall see, there are some pitfalls with strings that may look like labels, but which in fact are dates according to SourceSafe.

Version-numbers first: a string with only numbers is a hard reference to a certain version of a file or a project. This is only meaningful for single files, not on projects due to the way AbaPerls uses the labels. If you specify version 9 for a certain project, AbaPerls would then attempt to retrieve version 9 of a file in version 9 of that project. (Why, see further below under Supplementary Labelling of Files.)

The string can also be interpreted as a date. This is handled somewhat differently depending on the SourceSafe version. With SourceSafe 6.0, the SourceSafe OLE interface performs the interpretation. SourceSafe 2005 never interprets strings as dates, so in this case AbaPerls attempts to convert the string by a direct call to Automation, but to gain some performance, AbaPerls only does this if the string starts with a digit and also includs a non-digit. The date format depends on your regional settings. With Swedish settings, both these formats work with 6.0, but only the first with SourceSafe 2005:

"97-03-03 12.00"
"Maj 19 2002 12:00"

Notice that when you use a date with spaces in it, you must enclose it quotes when you pass it as an argument to a command-line switch. You cannot use dates with spaces in a config-file.

There are some unexpected variations. The string 4.00.0012 does not look like a date, does it? Well, Automation thinks it is a date.(4.00.0060 is not date, nor is 4.60.0012 nor 24.00.0012, but 4.00.0059 is. Get the picture.)

You should only use dates with AbaPerls as an emergency exit when you discover that you forgot to label, and there is no way to add a label after-the-fact. (Sometimes you can save the show by labelling a historic version of the SQL project.) Never use dates as a matter of routine.

A special case, is the string LATEST. This is a private AbaPerls convention to specify that you want the latest version of everything. (See below about pinning though.) For a single project, this is the same as specifying no label at all, but for a config-file this makes quite a difference, as explained on the config-file page.

If a string is not LATEST and cannot be interpreted as a version number or a date, it is a label. Specifically a string on the form LetterMajor.Middle.Minor, such as L4.30.0120, is always a label. This is AbaPerls standard format for labels as described on the page about the AbaPerls subsystem structure.

Supplementary Labelling of Files

Normally you label a project, but occassionally you need to label a single file. The typical scenario is that you label a project, say that the label is L1.10.0010. When testing, you realize that there is an error in the file MY_SP.SP, so you check in a new version of that file. Now, you don't want to label the project anew, because there might be changes to other files that you do not want to include in a new build. Rather you label the new version of MY_SP.SP with L1.10.0010.

An alternative scenario is that you find that MY_SP.SP was one step too far ahead, and that an earlier version of MY_SP.SP should be included in the build you plan to do from L1.10.0010. You can address this by bringing up the history dialogue for MY_SP.SP and select Details for the proper version, and then insert L1.10.0010 in the Label box.

As this may look like the "label promotion" feature introduced in VSS 6, it is worth pointing out that the above works with VSS 5 too when you use AbaPerls. This is because AbaPerls first reads the project to find out which files are inlucded in the project at the given label, date or version number of the project, but as AbaPerls walk through the file list, it gets the version for the label for each file, due to how the OLE interface works. (Which is why given version 9 for a project, it will retrieve version 9 of all files in the project.)

There are two more possible scenarios: 1) A file was missing, so you add it and label it L1.10.0010. 2) There was a file that shouldn't be there, so you delete it from the project. However, these cases are not handled by AbaPerls (and neither by the SourceSafe GUI, even with a SourceSafe 6 database.) The reason for this is that adding or removing a file from a project, creates a new version of that project. (A creative reader may think that this could be addressed by labelling that particular subproject as well, but please don't do this unless you know exactly what you are doing.)

Pinning

SourceSafe has this concept of pinning. When you pin a version of a file which is not the lastest version of that file, many SourceSafe commands behave as if the pinned version is the latest version of this file. A command that does not, is Check out: you cannot check out a pinned file at all.

If you have a pinned a file or a version, and then specify LATEST as the label to an AbaPerls tool, then you will get the pinned version, not the most recently checked-in version.

Overall, pinning is not an area that AbaPerls has explored, and there is no special support in AbaPerls for pinned files. If you have pinned a file, you may find that AbaPerls performs exactly what you want, or you may find that the tool breaks completely.