Notes on SourceSafe

This page covers the fine-print how AbaPerls accesses SourceSafe

Contents:
   How AbaPerls Accesses SourceSafe
   Version-specifications with SourceSafe
   Characteristics of Labels in SourceSafe
   Repository IDs
   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 directory 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 customisations for the database, regardless whether 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 some unexpected settings.

The exception that I mentioned 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:

When an AbaPerls tool completes successfully, AbaPerls deletes the ssopen-directory that it created. AbaPerls also attempts to delete the directory in case 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 tool 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.)

Version-specifications with SourceSafe

There are several places in AbaPerls where you can specify a version for a directory or a file, either with the ‑label option (ABASQL, DBBUILD or DBUPDGEN) or as an argument (LISTCONFIG or a config-file). When you use the SourceSafe GUI you specify whether you mean a label, a date or a version number by prefixing an L for a label, a D for a date, and nothing at all for version numbers.

This does not apply when you use AbaPerls, for the simple reason that the OLE interface for SourceSafe does not support this convention. A combination of what AbaPerls enforces and the conventions in OLE and the SourceSafe API, leads to the following rules:

  1. If you specify LATEST, this means the most recently checked-in version. (This is an convention enforced by AbaPerls).
  2. If you have a string which consists of digits only, this is taken as a version number. (I have not tested strings > 10 chars to see what happens.) This is only meaningful when you specify a version for an individual file with ABASQL.
  3. If you have a string that starts with a non-digit, this is always a label. That includes labels on the standard AbaPerls format LetterMajor.Middle.Minor.
  4. If string starts with a digit, and OLE can interpret it as a date, it is a date. Normally you should specify a date on the form YYYY-MM-DD hh:mm:ss. Beware however, that OLE's definition of what is a date is somewhat overly generous. The string 4.00.0059 is interpreted as a date. But 4.00.00060 is not. Nor is 24.00.0059 for that matter. Thus, there is all reason to avoid labels with a leading digit with SourceSafe. (And this is also the story behind the leading letter in AbaPerls label format.)

Characteristics of Labels in SourceSafe

Labels in SourceSafe are fairly static, as they are intended to reflect a snapshot in time. Normally you label a directory, whereupon the label is applied on the current version of all files in that directory recursively. The one modification you can make later to the label, is that you can set that label explicitly on a different version of the file. SourceSafe will then include that version of the file in the label. The purpose of re-labelling an explicit file is that there may some urgent problem, maybe a quick oops! that needs to be fixed.

However, you cannot add a file to the directory after the label and apply the label to the file. Well, nothing will stop you from adding the label, but tools like DBBUILD or DBUPDGEN will not find the file, because SourceSafe will not consider the file to be part of the label.

If you later delete a file from the directory, AbaPerls will still find the file if you load from that label. If you rename a file, you need to use the old name when you work with the old label. This is perfectly normal and what you would expect, but a corollary of this is that you can not make any such modifications within the label.

Repository IDs

AbaPerls tracks for each SourceSafe database a repository id which is stored in the table abarepositorymappings. This permits different developers to access a SourceSafe with different paths, for instance different drive letters, without breaking the Version Checks for Production and Test databases.

AbaPerls reads the repository ID for a SourceSafe database from the file um.dat in the data directory of the SourceSafe database. The only time you have to care about this is if you decide to split up a big SourceSafe database in two by means of Archive and Restore. In this case, the restored database may get a new id, whereupon you will get clashes when you try to run ABASQL from the newly restored database. The simplest way to address this is probably to run DBBUILD ‑rebuild on all affected databases. You could also set the repositoryid column in abarepositorymappings to NULL. (Editing um.dat with a hex editor to restore the old ID will not work, since um.dat has a checksum.)

Pinning

SourceSafe has this concept of pinning. When you pin a version of a file which is not the latest 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.