Visual FoxPro and Visual SourceSafe
Ted Roche, MCSD
CAUTION for VFP 5.0 users (and those who saw Ted's second benchmarking session at the 1997 DevCon session): Visual Studio 97 Service Pack 2 causes "Invalid Page Faults" in VFP if using integrated SourceSafe projects! Avoid Service Pack 2. You can find Service Pack 3 for Visual Studio 97 on the Microsoft Web site.
After installation, the developer who creates a project selects "Add Project to Source Control" if the Tools/Options are not set to do this automatically. All other developers can now access the project by selecting "Join Source Control Project…" from their File menu.
Each developer maintains their own copy of the shared project, and each has a complete copy of all of the source code. By default, all of the source code is flagged read-only to prevent inadvertent code changes. After checking out an individual file, additions and modifications to the source code are made by each developer on their local machine. When the changes have been tested and are ready to be shared with the rest of the development team, the developer chooses "Update Project List" from the Project/Source Control menu. This option updates a text version of the project, a .PJM file, with the changes this developer has made to their local project file. When other developers choose to update the shared project list, they will see the changes made by this developer.
Source Code Control works best on text files, as differing versions of text files can be visually compared. Since FoxPro keeps a lot of its designs in table format (SCX, VCX, MNX), these files cannot be compared directly. Instead, the integrated source control creates an ASCII version of each of these files (with corresponding SCA, VCA and MNA extensions) so that changes can be "diffed." The SCCTEXT.PRG program is used to create and interpret these ASCII files; this file can be modified to suit your needs.
Figure 1: Source Code Control using VFP's Project Manager enforces coordination between developers
Figure 2: Administrator option for multiple checkouts must be turned on.
Figure 3: Fox VSS 5.0, you'll need to add the *.prg to VFP's File Types. VSS 6.0 fixes this.
Figure 4: Tools/Options/Project dialog provides SourceSafe options
Project Manager displays icons to show the status of each file:
Project file and all database and table files are not checked in. The project file is generated for each developer by the FoxPro-SourceSafe interface by reading the .PJM file, checked out by each developer who joins the project. The PJM file contains the "header" information for the project - name, address, icon, generator options, and a line for each file within the project.
Figure 5: Contents of a typical .PJM file
Once you have succeeded in using Visual SourceSafe with the Visual FoxPro Project Manager, there are a number of ways in which the collaboration between the two products can be enhanced:
Consider Automation as an Alternative
Rather than using the internal source code control mechanism, it is possible to control Visual Studio using Automation directly from FoxPro. You can scan the contents of a project (PJX files are just data tables) and process directly against the SourceSafe backend.
Documentation for SourceSafe 6.0 was expected to be available by the time the product ships. Documentation for version 5.0 is available on the Microsoft Web site at http://www.microsoft.com/ssafe An extract of the object model is included below:
A SourceSafe database.
A project or file. Note that there is also a VSSItems that is a collection for all the children in one project.
One way of representing a specific version of a file or project. A VSSVersions is a collection of all the versions of a particular file or project.
A checkout record on a file. Note that once again there is a collection, since one file may have many simultaneous checkouts.
Here's a sample routine that lists the files available along the path specified:
* Program....: LISTTREE.PRG
* Version....: 1.0
* Author.....: Ted Roche
* Date.......: October 15, 1997
* Compiler...: Visual FoxPro 05.00.00.0412 for Windows
IF TYPE("lcPath") <> "C"
lcPath = "$/"
local loSSAfe, loVSSItems, loRoot, loNode
loSSafe = CREATEOBJECT("SourceSafe")
loRoot = loSSafe.VSSItem(lcPath)
loVSSItems = loRoot.Items()
FOR EACH loNode in loVSSItems
* loNode = loVSSItems.Item(lnCount)
release loNode, loVSSItems, loRoot, loSSafe
This second sample opens a database, displays a few properties and then checks out a specific file. Properties of the file are then displayed.
* Program....: TESTVSS1.PRG
* Version....: 1.0
* Author.....: Ted Roche
* Date.......: October 12, 1997
* Compiler...: Visual FoxPro 05.00.00.0412 for Windows
* Abstract...: Open and work with VSS via Automation
oSSafe = CREATEOBJECT("SourceSafe")
* Syntax is object.open(path to srcsafe.ini, username, password)
* The following lines show some of the object's properties
* The next line assumes FoxApps is the Visual SourceSafe project and
* Tastrade is a subproject
oFile = oSSafe.VSSItem("$/folkview/prg/ffmain.prg")
? oFile.IsCheckedOut = 2
Whenever a SourceSafe operation is attempted, an "In Desktop" window appears, blocking your access to the FoxPro application and occasionally intercepting keystrokes. Thanks to Christof Lange for pointing out that you can get rid of this annoying window with HIDE WINDOW "SOURCE" or HIDE WINDOW "Ergebnisse der Quellcode-Kontrolle."
Attempting to add a program that is not within the subdirectory tree of the main project results in a SourceSafe Error. SourceSafe will not allow you to include files outside of project directory tree. There are several work-arounds, depending on the situation. If the file is used in this application only, the simplest thing to do is just to move it into the directory structure. If the file is used in multiple projects, one alternative is to add it to its own project, within the SourceSafe native interface, and then use sharing within VSS, add the file to the current project, within FoxPro add it to the project, and select "overwrite" to update the file to the most recent version within FoxPro.
Look at sharing between projects to maintain control of common files (FoxTools, framework source code); considering "pinning" to lock in versions for shared branches.
Look at labeling options within Visual SourceSafe to control and document versions sent to testing or released to clients.
Modifications to SCCTEXT.PRG
The October '97 issue of FoxPro Advisor has an excellent article by Mark Wilden with several suggestions on changes to SCCTEXT.PRG. One issue he identified was a problem with SCX and VCX files jumbling the order of methods each time they were saved. When SCCTEXT generated the method code for the corresponding SCA or VCA file, the methods were not sorted, so viewing differences in the files was difficult. Mark proposed a simple change to the SCCTEXT program to sort these methods before writing out the file.
The Project/Source Control/Share… option allows you to add any controlled files from any other project directly into your project. Unfortunately, there is no option to specify where these files are stored - all are placed in the project root directory. Move the file within the SourceSafe interface by dragging and dropping in to the correct folder and deleting the file from the root (Yes, this is how you have to do a "move" - copy and delete - there is no native move functionality). Finally, modify the PJM file directly to point to the new location of the file.
By default, the VFP-VSS interface does not include data files under source code control, nor does it include the database container. Consider adding data files that are more control files than end-user data. Take a look at the GENDBC program, included with Visual FoxPro in the TOOLS\GenDBC directory, to generate a program containing all of your database container properties and methods. Consider a tool like xCase or Stonefield Data Toolkit to generate the design meta-data for preservation within SourceSafe.
The SourceSafe web site also includes an add-on program to Microsoft Office 97 to add a SourceSafe menu to those products. Consider maintaining all project documentation under source code control, as well.
Under some circumstances, projects under source code control perform unacceptably slowly. Ensure you are using the latest version of FoxPro - 5.0a had major speed improvements over 5.0. Ensure your network is performing correctly. Use the SourceSafe admin looks like ANALYZE.EXE to test and correct problems with the SourceSafe data store.
There is no concept within the SourceSafe model of "synching" between two SourceSafe repositories, nor significant support for remote sites or developers who want a separate SourceSafe installation for their laptop. The solutions at this point are manual: check the files out from the "master" database and check them in to the "slaves." The process is arduous and requires close attention by the operators.
When duplicating SourceSafe-controlled projects between machines, a number of errors can be generated if the project's status, as stored in the PJX, does not match that of SourceSafe. For example, if you attempt to open a SourceSafe-controlled project on a machine connected to a different SourceSafe database, you could receive the error 'SCC API error "Project created" occurred. The project will be opened without source control.' - proof positive that two wrongs don't make a right.
Two fields in the PJX table appear to control how files are controlled within the project: the LOCAL field is a logical to determine whether the file is only used locally (.T.) or if it is controlled via source code control (.F.). In the project header record (the first record in the table), SCCDATA stores path names and SourceSafe control information. In the records for the individual files, the SCCDATA memo field appears to contain flags for the status of the associated file. Thanks to fellow MVP Christof Lange for hacking his way through this one: Bytes 260 and 261 (or 0x104 and 0x105) determines whether the file is checked in or out, by this developer or another, within this project or another project. These flags seem to be updated automatically by the Project Manager; however, the LOCAL switch must be set properly
There is no native support for remote access, and Visual SourceSafe over RAS can be unacceptably slow on slower dial-up lines. Recognizing this, the VSS team worked hard at improving the performance of VSS over dial-up in the 6.0 product. Look for significant performance improvements. You should also consider alternatives such as using a shadow directory structure to allow developers to "get" all current source code without invoking VSS, using an store-and-forward process, like e-mail, to transfer files to and from remote users, or setting up an Automation server locally with a better remote interface.
Microsoft has provided us with hooks into the project manager and source code control to allow us to reliably maintain source code shared among multiple developers. A little time spent understanding how the mechanism works and how it can be used to best advantage can pay off for the multi-developer team.
Ted Roche is a full-time software developer working at Blackstone, Incorporated in Waltham, Massachusetts. . He has written for numerous magazines and spoken at user groups and over a dozen professional conferences in four countries. Ted contributed to four books on FoxPro 2.5 and co-authored the critically acclaimed Hacker's Guide to Visual FoxPro 3.0. He's has just completed the Hacker's Guide to Visual FoxPro 6.0. Ted is a Microsoft Certified Solution Developer, a five-time Microsoft Most Valuable Professional award winner and a Contributing Editor to FoxPro Advisor. Contact Ted at mailto:firstname.lastname@example.org.