VCS stands for Version Control System. One of the main purposes of VCS programs is to help maintain and track versions or revisions of a set of files.

Since you are probably using Multi-Edit to write programs, think about what it would take to maintain a single program after releasing three or four versions with a couple of maintenance releases along the way. Next add tracking of all the new feature requests and bug reports that you get and implement. After thinking about this, add the possibility of creating three or four other programs and since you haven't enough time to develop them yourself, plan on having five or six other programmers help in their development. How do you maintain this?

One possibility would be to keep a copy of every file of every program for every version that you produce, making sure you maintain a document that describes all of the changes that you make. This may not be too hard when it's just you doing all of the work. When you have others working with you and they also need to document their changes, it becomes more difficult. Then there is the issue of who gets what file when. As deadlines approach, documentation is often the first thing that suffers. As a result, maintaining control over who edits each file becomes increasingly difficult.

On top of all of this, there is the problem of storage space. Keeping complete copies of every file, even when it is compressed into an archive, still takes up quite a bit of space.

It is situations like the above that VCS programs were designed to handle. The first thing you should do is put all of your source files under VCS control. This is done by first creating and checking in a copy of each of your source files into a VCS archive and adding a description for each file. Once the VCS package has “control” of your source files, you can think of the VCS package as you would a public library. To get a book to read out of a library, you will need to check it out. In order to make changes to a source file, you need to check it out of the VCS library.

The VCS program tracks who has each file checked out and prevents another programmer from modifying a file already checked out. Thus, the same file is prevented from being changed by two programmers at once. After a file has been modified and tested, you will then check it back into the VCS library or archive and add a comment about what changes you made. This information is saved along with the new revision of the file. All changes are tracked and documented without much extra effort.

The way VCS programs help the storage space issue is two fold. First, all versions or revisions of a file are stored in one file or project instead of being split between different version archives. Second, most VCS programs only store the full text of only one version of the file and save a “delta” or a set of changes for each of the other revisions. There are two methods used to implement this, forward and reverse delta. Both methods serve the same function, but implement it differently.

In the forward delta method that TLIB uses, the first version of a file is saved in the archive. Every new version is saved as a set of changes that create a newer version when applied to a previous version of the file. Thus with a TLIB archive contains 5 revisions, the original file is stored first, followed by four deltas. When these deltas are applied to the original file, a newer revision of the file is created.

The reverse delta method, as used by VCS and most of the other supported packages, does the same except in reverse. The latest version is saved and then deltas are saved that change the newer file into a previous revision.

SCC is an API designed by Microsoft to allow programs to interface to their Visual SourceSafe version control program. After its release, many other companies that provide VCS programs added support to their programs to support this API.

The advantage of using the API is that Editor and IDE authors can develop a common interface that will work with a number of VCS programs. Also, since it is an API, Multi-Edit has direct access to the routines and doesn't need to run an external executable, capture the output and then parse the output when doing a VCS operation.

All of the benefits of a VCS system are moot if the program is never used. Even in a Windows environment where multiple applications can be run simultaneously, a programmer must switch from his or her editor to the VCS program, perform a VCS action, then switch back to the editing environment. The Multi-Edit VCS support was developed in order to allow users to access their VCS system from within the Multi-Edit environment.

Early programming was mostly done from a command line. You ran a command to check a file out of its archive, another command to edit it, another to compile it, another to test. You would repeat the edit, compile and test cycle until the program ran as you wanted and then you would run a command to check it back into its archive.

Since Windows is becoming a popular programming environment, programmers are moving away from using command line and individual programs to using an Integrated Development Environment (IDE).

With the newer IDEs and programmer's editors like Multi-Edit, where the editing, compiling and testing can be done in one place, it makes sense to add the VCS stages of the cycle into this environment as well.

Since every programmer works differently, the VCS support was designed to make it easy for programmers to work with the VCS programs. Currently there are four different interfaces provided and they are documented under the section heading “The VCS Interfaces”. By learning how to use these different interfaces you will be able to do most, if not all, of your VCS work from within Multi-Edit.

The first version of the VCS macros was designed to work with one VCS program. It allowed the end user to configure it to do most of the simple VCS operations. As new features and new VCS packages were added, the code went through some major restructuring, but was successfully integrated into one set of macros. With the previous release of the VCS macros in Multi-Edit for DOS version 7.0, the VCS support macros were getting quite complicated. With this release, these macros were redesigned to allow a more flexible and powerful way of implementing and expanding the VCS support.

The new design, while still maintaining the capabilities of the previous versions, has been expanded from one macro file into a number of macro files. Instead of the “VCS.MAC” file containing all the VCS support code, it now only contains the high level API code and some common support code. The VCS package specific driver code has been moved into separate macro files, one for each of the supported VCS packages. This change to the code has made VCS integration cleaner and easier to test and update. It is now possible to add features that are specific to one VCS package without the possibility of “breaking” support for another package.

The VCS macros were designed in a layered structure, much like an operating system, with APIs and drivers. The VCS support's high level APIs, designed to provide a common interface to all of the specific VCS programs, consist of a set of macros called by the file open and close system macros, menus and toolbar commands. No matter which of these macros is run, the “VCSCmds” macro is eventually called. This macro determines the currently selected VCS package and causes the appropriate lower level driver macro, located in the one of the VCS specific macro files, to be run.

The low-level driver macro will convert the desired API command to a specific VCS command line, execute it and check to make sure there were no errors. This information is then passed back to the “VCSCmds” macro, which will display an error message or manage the file loading and closing, depending upon the command.

Once the VCS support is configured and set up properly, doing VCS operations is almost as easy as loading and closing files.

The VCS menu, accelerator keys, and toolbar buttons can be fully customized to your liking.

Before the VCS system is used the first time, it must be configured for your working environment. To accomplish this there are two main configuration dialogs, VCS Configuration and VCS Package Setup.

The first dialog, VCS Configuration, can be started either from the Customize dialog in the Tools Menu or from the VCS Menu. It is used to set up the common configuration items, which determine the operating features of the VCS support. These options have the same effect regardless of the VCS package you use. There are options to enable the VCS support, which VCS package to use by default, the kinds of information to be saved and many more.

The second dialog, VCS Package Setup, enables you to set up items specific to the VCS program that you are using. This dialog box is started from the main Configure Dialog. It allows you to specify the archive path and extension, user I.D. and other VCS specific options. In addition, the command lines for each of the VCS functions can be changed here. However, the default commands should suffice for most users.
If you will be using the <LOOKUP> archive path alias, you will need to set up the <LOOKUP> database.

The last item related to configuring the VCS support is Setup Verification. Though rarely used, this is provided to help diagnose set up problems with the VCS support. When run, checks on the VCS system are executed and the results are shown in a list window dialog.

This dialog gives a list of file directories with their associated archive directories. Adding or changing these association is done by selecting the Insert or Edit buttons. This brings up the Associate Directories Setup dialog to appear where the desired directories can be entered or edited.

Hitting 'Alt+I' or the 'Insert' key, or by selecting the Insert button, will cause the Create New Record dialog to appear asking for a New File Directory. Enter the full path name of a working directory here and hit 'ENTER' or select 'OK' to create a new entry into the associate directory database and bring up the Associate Directories Setup dialog.

The Associate Directories Setup dialog is where the file directory and the archive/lock directories are entered. This information is then stored in the VCS.DB file and is later used when checking for archive and lock files.

Files…

This field is used to enter the directory where your files are located or being edited. The VCS macros, when trying to find an archive for a specified file, will use the path of the specified file and search the “Associate Directories” database for an exact match to this field. When a match is found, the “Archive” entry would be returned. There can be multiple entries with the same path, thus allowing a single working directory to be associated with multiple archive directories. If multiple entries are found then the combined archive paths are returned with a ”;” between each entry.

Archive

This field is used to enter the directory where the archives for the files in the directory specified in the above “Files” field are located. There can be a single path or a series of paths separated by ”;”. The preferred method is to use multiple records with a single path per field.

Work…

This field is used to enter the work directory where the extracted files will be edited. This field usually contains the same directory as the “Files” field and can be left blank. The main reason for entering a path here is to specify a directory to extract a file to for editing that is different from the directory the loaded read-only in located. Good for loading a “reference” file from a directory on a network and checking out the file to a local directory to change it.

Project

This field is used to enter the base project directory for a “named project”. Since named project support does not exist yet, this field should be left blank.

LOK… (TLIB Only)

This field is used to enter the directory where TLIB Lock files are to be stored.

Base… (LCM Only)

This field is used to enter the LCM base directory for the project located in the “Files” directory. This would be the same as the base= entry in the LCMPROJ.CFG.

When Setup Verification is run from the VCS menu, a window is displayed that shows the results of a series of tests that check the VCS support setup dialog. By understanding the information shown in this window you will be able to troubleshoot problems that occur when setting up the VCS support.

The VCS support consists of a main interface macro file, “VCS.MAC”, and a number of specific VCS support macro files. Since these support macros depend upon a consistent interface between them and the main macro, a form of version checking was implemented. Every VCS macro file has a version number and revision information embedded into them, which gets checked every time the VCS support is initialized.

The version number consists of two parts: a Multi-Edit version number and an update letter, i.e. 10.00.01a. The Multi-Edit version number, which is not checked, is the version/revision of Multi-Edit that is required for the VCS support macros to be fully functional. It is the VCS release number of the main interface macro “VCS.MAC” and the selected VCS package support macro that is checked during initialization.

The release number is changed whenever a major release of the VCS macros is released, i.e. a change to some interface where all macros needed updating, and this number must match exactly for the VCS support to be enabled. The update letter is changed when a minor update is released, i.e. changes to one or more of the support macros or main macro that doesn't affect another macro. The update letter does not need to match and is provided for tracking purposes only.

The top three lines in this window form a header that presents the information in columns or fields.

• Macro: The file name of a specific VCS support macro.
• Mac Chk: This field will have an “x” shown when the specific VCS macro has passed all checks and the support for that package would successfully be installed.
• Ver Chk: This field will have an “x” shown when the specific VCS macro version number matches the main VCS macro version number.
• EXE Chk: This field will have an “x” shown when the “GET” command executable for the specific VCS package is found.
• Version: This field contains the version number of the specific VCS macro.
• Revision Info: This field will show the internal revision string of the specific VCS macro.
• Executable Path: This field will show the path and filename of the specific VCS package “GET” command.

The fourth line shows the above information for the main VCS interface macro “VCS.MAC”. The number of lines that follow depend upon the number of supported VCS packages. There will be three lines for each support macro, a blank line followed by the Macro to Revision Info on the next line and the EXE Chk and Executable Path field on the third line.

The VCS support actually contains four different interfaces to the selected third-party VCS programs. This was done to provide convenience and to help increase your productivity. With these interfaces most if not all of your VCS work can be done without exiting Multi-Edit.

The first interface is essentially the same interface used to open and close files. When the VCS support is enabled, the file open and close functions have the ability to check files out from VCS archives when loading non-existing files and to check files back into VCS archives when closing them or upon exiting Multi-Edit. For more detail on how these functions work, refer to Using The File Open And Close Interface.

The other three interfaces are all accessed through the VCS menu or toolbar buttons. Probably the most used interface would be Using The Current File Menu/Toolbar Interface. This allows you to do most of your VCS operations using the file that is loaded into the current window.

Using the “Directory Of Archives Dialog” and “Using Multi-Edit Files From Archives Dialog” dialogs allow you to pick and choose the files that you want the VCS operations to run on. These are very powerful ways to check files and functions in and out and are very similar to the file manager that comes with Windows.

The last interface involves selecting the “Run VCS Interactively” command from the VCS menu. This starts the “User Interface” that comes with your VCS program without exiting Multi-Edit. This would be used for features that you require that are not currently fully supported in the VCS support macros.

This interface provides seamless integration of checking files into and out of VCS archives by “hooking” into the standard open and close file functions. Every time the VCS support is started, three global variables are initialized. These variables are set to contain macro command lines and are used by some of the Multi-Edit system macros to allow “hooking” or adding functionality.

The first variable, ”@FNF_LOAD_MACRO@“ is set to contain the string “VCSGetFile” which is a macro located in the main VCS.S file. When this variable is set and you try to load a file that isn't found, Multi-Edit will try to execute the string that is contained in this variable as a macro and pass the filename as a parameter. Since the VCS support has set this variable to point to the “VCSGetFile” macro, this macro will be executed.

The “VCSGetFile” macro first checks to see if there exists a VCS archive for the file being loaded. If there isn't an archive for that file, then a return value of “False” is returned and Multi-Edit will assume you are loading a new file.

On the other hand, if there is an archive for this file, then what happens next will depend upon how the “Get Mode” option is configured (see “Get Mode” under the VCS Configure Dialog topic in the program help). If the default setting of “PROMPT” is still active, a dialog box, shown below, will appear and prompt you for an action to take. If one of the other options was selected, then that action will be taken without a prompt being shown.

• To Modify: Selecting 'Enter' or 'Alt+M' or selecting this button will cause the specified file to be extracted by the VCS software for modification.
• To View: Selecting 'Alt+V' or selecting this button will cause the specified file to be extracted by the VCS software for viewing only (read-only).
• To Lock: Selecting 'Alt+L' or selecting this button will cause the specified file to be locked by the VCS software. The file will not be extracted, only locked, to prevent another person from checking it out to modify.
• Cancel: Selecting 'Esc' or selecting this button will return to the editor without extracting a file. If this dialog was caused by loading a new file (i.e., macro LOADFILE), then a new file window will be created.

The other two global variables, ”@DEL_VERIFY_MACRO@“ and ”@ME_EXIT_MACRO@“, are used to tell Multi-Edit what macros to call when closing a file and upon exiting. Both of these variables actually point to the same VCS macro, “VCSCleanup”, but produce different results depending upon which function it was called from.

When the “VCSCleanup” macro is called from the close file function, it first checks the VCS checkout status that is maintained by the VCS support to see if the file being closed was previously checked out of a VCS archive. If the file does have a checkout history, then one of two dialogs will be shown prompting you to select an action to take.

The first dialog that could appear is displayed when the file has been checked out of an archive for modification. The dialog states that the file is checked out and asks if you want to check the file into its archive.

• Yes: Selecting 'Enter', 'Alt+Y' or selecting this button will cause the current file to be checked into its VCS archive.
• No: Selecting 'Alt+N' or selecting this button will cause the window to be deleted, but the file will not be checked into its archive.
• Cancel: Selecting 'Esc' or selecting this button will abort the “close file” function and will cause the file to remain checked out and load.
• Unlock/Abandon: Pressing 'Alt+U' or selecting this button will unlock the current file and delete it from disk if the “Delete Source” option is checked in “Using The VCS Package Setup Dialog”.

The other dialog that could appear is displayed when the file has been checked out of an archive for viewing and has been loaded as read-only. It states that the file is checked out and asks if you want to delete the file.

• Yes: Selecting 'Enter, Alt+Y' or selecting this button will cause the file to be closed as well as deleted from the disk.
• No: Selecting 'Alt+N' or selecting this button will cause the window to be closed but the file will not be deleted.
• Cancel: Selecting 'Esc' or selecting this button will abort the “close file” function.

When the “VCSCleanup” macro is called just before Multi-Edit shuts down, it also checks the VCS checkout status to see if any files have been checked out of a VCS archive. If a file has been checked out of a VCS archive then a dialog is shown that lists all of the files checked out. This gives you a chance to check them in before exiting or leaving them checked out. This is the same dialog that is shown and documented under “Using Multi-Edit Files From Archives Dialog”.

The information shown in the Difference list is the output of either the VCMPR.EXE program or the VCS DIFF program specified under the DIFF command in the VCS Package Setup Dialog for the selected VCS program.

When the VCS macro finds an error condition after running a VCS program, a dialog will pop up that shows the results of the failing program. All VCS specific errors start at 9000 and are just the error number returned by the failing VCS program + 9000.

An error of 9100 with a blank list is an indicator that the VCS program did not actually run or that it did not generate any output.

TLIB by Burton System Software's stands for Text LIBrarian. This package is currently available in text based DOS and OS/2 versions. The TLIB support macros were originally developed and tested using TLIB version 4.12g but all of the newest development and testing has been done using the latest version 5.01m. See the TLIB manual for configuration information.

Support for running the TLIB 5.x VCS program via their DLL has been added. It is enabled by selecting the TLIBD entry in the VCS Packages dialog. It is configured the same as if you were using the command line version of TLIB.

CVS support uses the WinCVS 1.2 command line programs to access the source archives. It will work with local archives or archives on the Internet.

PVCS is MERANT Version Control Software that allows the user to keep a history of changes made to text files such as source code and help files. This program has been around the longest and is available for many different platforms. The PVCS support macros should work with any Personal, Corporate, or Network version of PVCS version 2.1c or later. The original development and testing was done using a copy of the Personal Version of PVCS version 2.1c but current development and testing is being done using a copy of PVCS version 5.1. There is an API for PVCS but the VCS support macros are not using this. Instead, they are using the dual mode DOS command line programs.

RCS is Mortice Kern, Inc.’s Revision Control System that allows the user to keep a history of changes made to text files such as source code and help files. The RCS support macros where originally written and tested using version 4.3a but current development and testing is being done using version 6.2. Some DOS versions of the GNU RCS programs also work with the existing RCS support macros.

SourceSafe, originally developed by One Tree Software but now owned by Microsoft, is a project oriented version control software that allows the user to keep a history of changes made to a text file such as source code and help files. The original support for SSAFE was written and tested using version 2.00. The current development and testing is being done using version 4.0 of Visual SourceSafe. The current support macros are using the new SSWCL.EXE and SSWLOGIN.EXE programs that come with the 3.0 and later versions of the Windows version of SourceSafe and are not compatible with older versions of SourceSafe. Older versions can be used but there needs to be some code changes made and the commands will need to be modified to do this.

Subversion by Tigris is meant to be a better CVS, so it has most of CVS's features. Generally, Subversion's interface to a particular feature is similar to CVS's, except where there's a compelling reason to do otherwise.

PAN/LCM by Computer Associates is version control software that allows the user to keep a history of changes made to a text file such as source code and help files. The original support for LCM was written and tested using version 3.3

Sourcerer's Apprentice originally sold by Solution Software and now owned by Borland International, is a Version Control Systems package that allows the user to keep a history of changes made to a text file such as source code and help files. The SAP support was originally written and tested using version 1.02. There has been a newer release but we haven't ordered a copy. Since Borland is not supporting this program it is very unlikely that we will support the updated version.