Overview

Visual Studio 98 offers greater possibilities for tight integration of Visual FoxPro projects with the other tools supplied in the Visual Studio package. In this session, we'll have an in-depth examination of the tight integration of Visual SourceSafe98 with Visual FoxPro.

Introduction

Source code control can be a very useful tool to the solo developer as well as a key tool for multiple-developer teams. For the solo developer, source code control provides backup facilities and the ability to perform a "grand undo" as well as retrieve early builds or versions. With a multiple-developer team, source code control can ensure that all members of the team work with the latest revision of source code, protect the members of the team from inadvertently overwriting each others work, and provides a simple method to keep track of multiple releases of the software to the same or different clients.

Source code control programs have been around for quite some time but, like difficult backup programs, programs that prove too hard to use are too easy to avoid. With the increasing complexity of projects and the improved accessibility of these products, they are tools are worth the effort to learn. Integration of source code control directly into the development environment is a relatively recent feature that makes these programs easier to use.

Bear in mind that Visual SourceSafe, or any other source code control program, is its own product and you must learn its terminology and operations to get the greatest benefit from it. While many operations can easily be performed from within the FoxPro interface, you should become familiar with the less frequently needed maintenance functions that may only be available within the program itself.

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.

The logic FoxPro uses to access Visual SourceSafe:

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

Key items to remember during installation:

· Full install should be performed once to your network file server

· Each workstation must run NETSETUP.EXE to install client software on local machine

· Administrative setup: must change multiple checkouts option (see figure below)

· In VSS 5.0, you also need to add .PRG to file extensions for Visual FoxPro (second figure below)

· Each workstation needs to turn on Visual SourceSafe from Tools/Options:

· SourceSafe should be selected as active source control provider

· Change other options as your work style dictates

· Text generation program source is included; consider modifying to meet your needs

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

Opera

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

Advanced Topics

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:

VSSDatabase: A SourceSafe database.

VSSItem: A project or file. Note that there is also a VSSItems that is a collection for all the children in one project.

VSSVersion: 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.

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

* Abstract...:

* Changes....:

**********************************************************************

lparameters lcPath

IF TYPE("lcPath") <> "C"

lcPath = "$/"

ENDIF

local loSSAfe, loVSSItems, loRoot, loNode

loSSafe = CREATEOBJECT("SourceSafe")

loSSafe.Open("C:\Program Files\DevStudio\Vss\SrcSafe.INI","troche","")

loRoot = loSSafe.VSSItem(lcPath)

loVSSItems = loRoot.Items()

FOR EACH loNode in loVSSItems

* loNode = loVSSItems.Item(lnCount)

? loNode.Name

NEXT

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

* Changes....:

**********************************************************************

oSSafe = CREATEOBJECT("SourceSafe")

* Syntax is object.open(path to srcsafe.ini, username, password)

oSSafe.Open("C:\Program Files\DevStudio\Vss\SrcSafe.INI","troche","")

* The following lines show some of the object's properties

? oSSafe.UserName

? oSSafe.CurrentProject

? oSSafe.SrcSafeINI

* The next line assumes FoxApps is the Visual SourceSafe project and

* Tastrade is a subproject

oFile = oSSafe.VSSItem("$/folkview/prg/ffmain.prg")

oFile.Checkout()

? oFile.IsCheckedOut = 2

? oFile.Binary

? oFile.IsDifferent

? oFile.VersionNumber

oFile.Checkin()

Annoying SCC Window

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."mes

Files Outside of the Project Tree

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.

Advanced Options: Pinning and Labeling

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 Shared files Always in Project Root

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.

Extending the Files under Source Code Control

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.

Troubleshooting Speed Problems

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.

Sharing Files between Multiple SourceSafe sites

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

Remote Access

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.

Source Code Control Conclusion

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.

About the Author

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:tedroche@compuserve.com.