Source Code Tracking on the VS File comparison and installation
From "Migration",  Access to Wang, April 1995
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Long ago, when I managed a two-person Wang VS shop for a manufacturing company, tracking source code changes was little more than a academic pursuit - interesting but not particularly important. Since the entire department was in constant communication (we sat inches away from each other) it was not necessary to impose formal change control; we could simply inform the other whenever starting modifications on a program. And the program modifications were primarily maintenance changes, easily tracked with modification codes applied by the editor.

Naturally, things have changed. Program changes are made very quickly, and several contract programmers are involved. There is little time to converse between ourselves about our projects, more changes made, and less room for error in production jobs. In short, we needed more control on our source files.

This month we'll look at a simple source code control process I use to track my own changes when working on the VS. This system - constructed from available Wang utilities and Procedure language - has aided in the visibility of source code changes with only small changes to the development process. Hopefully, you'll find it as useful in your shop.

Building a change control process

There are many aspects to program design and maintenance that could be tracked, including test versions, releases, installation parameters, difference ("diff") files, and many other items. The development process also requires consistency in application - a standard process used by all. From all of these items I chose the following goals:

1. Establish a means of controlling access to program code and detecting when a program is under modification.

2. Record the installation of program code (date, name, etc.).

3. Identify the changes made - line by line - without relying on modification codes or the memory of the programmer.

4. Intrude as little as possible into the development process.

There are a number of possible ways to meet these needs. Of these, I chose to work with copies of programs and use a comparison tool to detect differences between the original and working copies of a program. The comparison tool is the SRCDIFF option of Wang's COMPARE utility, which was first shipped with the 7.20 operating system. (Those of you who have operating systems prior to 7.20 should look for the SRCDIFF utility in the USERAIDS collection, which has a similar function.)

The purpose of the COMPARE utility is to discern lines that have changed and show them as inserted or deleted lines. If you have not used such "diff" tools before, they require a little practice to understand (see Figure 1 (below) for an example). Think in terms of effects to the original file - that is, a comparison of the first file listed (the "original") with the second ("newer") version. Lines are shown as either inserted (not part of the original file) or deleted (removed from the original file). Lines that have been moved will show as deleted in the original location and inserted in the new location.

In the example, a COBOL phonetic encoding subroutine (SOUNDEX) has been modified to remove references to a VS subroutine, incorporating the upper-case conversion directly into the program. The report shows line numbers deleted from the old source (marked with a D) and those added to the new source (marked with a I). For example, the original line 17 showed a comment referring to the UPLOW routine; this line was "deleted" from the original and the next line "inserted", effectively replacing the first comment line with another comment. Similarly, the next group of lines (25-27) shows three new lines inserted. Lines that match in both files are not shown - although all lines in the file can be included in the listing by changing the LISTOPT option on the DIFFOPTS screen within COMPARE to NO (e.g. list all lines, not just changed lines).

Procedure SC: a comparison tool

In order to make program comparisons as simple as possible, I constructed a procedure to automate the process. This procedure is SC (Source Compare), shown in Figure 2. SC accepts the file names and language type and runs COMPARE with the options specified above. In addition to finding differences, SC will also allow you to install the final source (and object, where appropriate) by replacing the originals with the new files.

SC makes a number of assumptions about the production environment that must be changed to fit your needs. The source library is assumed to be ABCSRC on SYSTEM, with working programs in ABCNEW on the same volume. Working object is in ABCOBJ on SYSTEM, while the production object files go into ABCOBJ on SYSOBJ. All of these items are defined in the DECLARE statements at the top of the procedure. Difference listings will be put into the user's spool library with a file name beginning with DIFF, and object files will be set with a protection class of @ (execute rights only). There is minimal error checking; the procedure assumes that the user can understand any errors that occur and fix them manually. It is also assumed that the user has sufficient access privileges to perform the file operations involved.

SC also depends on the availability of COMPARE in the system library and calls the DL (Display Library) program to show print files, if requested. These program locations can be changed to fit need or personal preference.

Putting it all together

With all of the elements described above - plus a few procedures to drive the EDITOR with appropriate defaults - our source file control system is now ready for use. Here are the steps required to use it:

1. The source file is copied from its normal location (ABCSRC) to a work library (ABCNEW). If the file is already present with that name, it has already been "checked out" by someone else. Thus, the presence or absence of a source file in ABCNEW signals whether the program is in work, fulfilling the first requirement.

2. Changes are applied to the working copy of the program and tested. Procedures are used to drive the EDITOR so that all working parameters - compiler options, link libraries, modification codes, etc. - are consistent.

3. When all modifications have been made and tested, the old and new versions of the program are compared using SC. The "diff listings" (reports) created by this comparison are archived, meeting our second and third requirements.

4. If the changes are acceptable, the new version of the source file (in ABCNEW) is copied over the original version in the source library (ABCSRC) through the installation option of SC. If the source file is COBOL, the object file is also copied into the production object library, located on another volume.

Results

This process has worked reasonably well for our small development shop (three programmers), but it is not perfect. Some issues:

• It is often difficult to see the exact nature of program changes from the COMPARE listings.

• The process is oriented around source code for a compiled language (COBOL). It does not gracefully support non- compiled languages (Procedure, shell scripts) or COPY files (FDs, SELECTs, etc.).

• All files must be consecutive, 80-character text files.

• There is an assumption that only one programmer is working on any one program. Sub-versions are not possible.

• There is no direct version identification attached to the source or object code.

A full configuration control system would answer all of these issues, but there would be additional effort to use such a system. This system has proven to be an effective compromise.

Next month: Unix source control tools.

Figure 1: Sample SRCDIFF Listing

VS File Comparison Utility - Version 3.02.00 (c) Copr. Wang 1986 COMPARISON OF FILES SOUNDEX IN ABCSRC ON SYSTEM AND SOUNDEX IN ABCNEW ON SYSTEM RUN ON 01/12/95 AT 08:24 COLUMNS 07 - 72 >------------------------------------------------------------------< 00017 D 001700* LINKAGE: UPLOW in VSSUBS (a VSAID) 00017 I 001700* LINKAGE: None. (removed 1/12/95 for Unix transporability) 00025 I 002500 FIGURATIVE-CONSTANTS. 00026 I 002600 DISPLAY-CODE IS "20". 00027 I 002700 00051 D 005100 01 UPLOW-LENGTH. 00052 D 005200 05 FILLER BINARY VALUE ZERO. 00053 D 005300 05 FILLER BINARY VALUE +30. 00054 D 005400 01 UPLOW-TYPE PIC X(01) VALUE "U". 00055 I 005500 01 WS-ARRAY-IN. 00056 I 005600 05 WS-CHAR-IN PIC X(01) 00057 I 005700 OCCURS 30 TIMES. 00058 I 005800 01 IDX-IN BINARY VALUE ZERO. 00059 I 005900 01 WS-ARRAY-OUT. 00060 I 006000 05 WS-CHAR-OUT PIC X(01) 00061 I 006100 OCCURS 30 TIMES. 00062 I 006200 01 IDX-OUT BINARY VALUE ZERO. 00066 D 006600 CALL "UPLOW" USING UPLOW-LENGTH 00067 D 006700 UPLOW-TYPE 00068 D 006800 SOUNDEX- TEXT. 00075 I 007500 MOVE +1 TO IDX-IN 00076 I 007600 IDX-OUT. 00077 I 007700 MOVE SOUNDEX-TEXT TO WS-ARRAY-IN. 00078 I 007800 PERFORM CONVERT-TO-UPPER 00079 I 007900 VARYING IDX-IN FROM 1 BY 1 00080 I 008000 UNTIL IDX-IN > 30. 00081 I 008100 MOVE WS-ARRAY-OUT TO SOUNDEX-TEXT. 00156 I 015600 CONVERT-TO-UPPER. 00158 I 015800 IF WS-CHAR-IN ( IDX-IN ) = SPACE 00159 I 015900 OR WS-CHAR-IN ( IDX-IN ) = "." 00160 I 016000 OR WS-CHAR-IN ( IDX-IN ) = "," 00161 I 016100 OR WS-CHAR-IN ( IDX-IN ) = "'" 00162 I 016200 OR WS-CHAR-IN ( IDX-IN ) = """" 00163 I 016300 MOVE SPACE TO WS-CHAR-OUT ( IDX-OUT ) 00164 I 016400 COMPUTE IDX-OUT = IDX-OUT + 1 00165 I 016500 ELSE 00166 I 016600 IF WS-CHAR-IN ( IDX-IN ) NOT > "z" 00167 I 016700 AND WS-CHAR-IN ( IDX-IN ) NOT < "a" 00168 I 016800 SET DISPLAY-CODE OF WS-CHAR-IN ( IDX-IN ) OFF 00169 I 016900 MOVE WS-CHAR-IN ( IDX-IN ) 00170 I 017000 TO WS-CHAR-OUT ( IDX-OUT ) 00171 I 017100 COMPUTE IDX-OUT = IDX-OUT + 1 00172 I 017200 ELSE 00173 I 017300 MOVE WS-CHAR-IN ( IDX-IN ) 00174 I 017400 TO WS-CHAR-OUT ( IDX-OUT ) 00175 I 017500 COMPUTE IDX-OUT = IDX-OUT + 1. LINES INSERTED: 38 DELETED: 8 MATCHED: 133

Figure 2: Procedure SC (Source Compare)

PROCEDURE SC - Source file comparison and installation * Compares two source files, yielding differing lines; optionally, * installs the new source and object files in place of the old * files. * * Dennis S. Barnes DECLARE &SRCFIL STRING (08) DECLARE &SRCLIB STRING (08) INITIAL "ABCSRC " DECLARE &SRCVOL STRING (06) INITIAL "SYSTEM" DECLARE &OBJLIB STRING (08) INITIAL "ABCOBJ " DECLARE &OBJVOL STRING (06) INITIAL "SYSOBJ" DECLARE &NEWFIL STRING (08) DECLARE &NEWLIB STRING (08) INITIAL "ABCNEW " DECLARE &NEWVOL STRING (06) INITIAL "SYSTEM" DECLARE &LANG STRING (09) INITIAL "COBOL" DECLARE &KEY STRING (03) INITIAL "@ " DECLARE &SPOOLIB STRING (08) EXTRACT &SPOOLIB = SPOOLIB S00: PROMPT PFKEY = &KEY (2,2) CENTER BRIGHT LINE "SC: Source file compare and installation";; CENTER "Old file =", UPPER &SRCFIL, UPPER &SRCLIB, UPPER &SRCVOL; CENTER "New file =", UPPER &NEWFIL, UPPER &NEWLIB, UPPER &NEWVOL;; CENTER "Language =", UPPER &LANG;; CENTER "Press PF14 to display print files"; CENTER "Press PF16 to end ";; CENTER "Press PF19 to install the source ";; IF &LABEL (&KEY) CALL &KEY GOTO S00 @0: IF NOT EXISTS FILE &SRCFIL IN &SRCLIB ON &SRCVOL END IF &NEWFIL = " " ASSIGN &NEWFIL = &SRCFIL IF NOT EXISTS FILE &NEWFIL IN &NEWLIB ON &NEWVOL END S01: RUN COMPARE IN @SYSTEM@ ENTER INPUT FILE1 = &SRCFIL, LIBRARY1 = &SRCLIB, VOLUME1 = &SRCVOL, FILE2 = &NEWFIL, LIBRARY2 = &NEWLIB, VOLUME2 = &NEWVOL, MODE = SRCDIFF ENTER DIFFOPTS LANGUAGE = &LANG, LIBRARY = &SPOOLIB, REPLACE = NO, LISTOPT = YES ENTER PRINT FILE = ##DIFF ENTER EOJ 14 ENTER EOJ 16 END @14: RUN DL END @16: RETURN *************************************************************** @19: PROMPT PFKEY = &KEY (2,2) CENTER "Program installation";; CENTER "Old file: ", &SRCFIL, " ", &SRCLIB, " ", &SRCVOL; CENTER "New file: ", &NEWFIL, " ", &NEWLIB, " ", &NEWVOL;; CENTER "Press PF19 again to confirm installation";; IF &KEY <> "@19" END IF &SRCVOL = &NEWVOL GOTO C19A PROMPT CENTER "ERROR!! CANNOT RENAME ACROSS VOLUMES!";; END C19A:SCRATCH &SRCFIL IN &SRCLIB ON &SRCVOL IF C19A = 0 GOTO C19B PROMPT CENTER "Error scratching old source file!" END C19B:RENAME &NEWFIL IN &NEWLIB ON &NEWVOL TO &NEWFIL IN &SRCLIB IF C19B = 0 GOTO C19C PROMPT CENTER "Error moving new source file into production!" END C19C:IF &LANG = "COBOL" GOTO C19D END C19D:SCRATCH &SRCFIL IN PHSOBJ ON SYSONE IF C19D = 0 GOTO C19E PROMPT "Error scratching old object file!!" END C19E:RUN COPY IN @SYSTEM@ ENTER INPUT FILE = &SRCFIL, LIBRARY = ABCOBJ, VOLUME = SYSTEM ENTER OPTIONS ENTER OUTPUT FILE = &SRCFIL, LIBRARY = &OBJLIB, VOLUME = &OBJVOL, FILECLAS = "@" ENTER EOJ 16 END