The acediff utility

acediff compares two versions of an ace file (e.g., old and new) and reports the differences. What makes the utility so useful is that the difference file is also in .ace format and the differences are expressed as the minimum number of transactions necessary to convert the old file to the new.

That is, suppose a database in state 1 is dumped to a file called "dump1.ace". The database is now interactively edited to add, delete and modify data, bringing it to state 2. Again the database is dumped, this time to "dump2.ace". Acediff will create a third file (diff.ace) that, if read into the state 1 database, will take it state 2.

One use of acediff is to help the curator with various error checking tasks. It can also be used to prepare update files. These files, which can contain the full range of .ace commands for addition, deletion, aliasing, and renaming, allow the curator to keep remote copies of the database in the same "state" or data release version. Updates will be discussed in more detail below.

Using acediff

Acediff can be obtained as part of the standard ACEDB distribution or compiled from the source code. Install it in your path or in some other convenient place. Acediff does not depend on the ACEDB environment variable; it is simply run at the command line as

% acediff older newer > diff
"older" and "newer" represent the pre-existing .ace files you intend to compare (they can have any name). "diff" is the new file (again with any name) where the differences will be reported.

An example

Below are two files, "old.ace" and "new.ace", compared side-by-side so you can see their differences. With respect to "old.ace", "new.ace" is missing an object (sam2) and contains additions, changes, and deletions to both sam1 and sam3. Immediately following the files is the output from the acediff command.

--------------------------------------------------
old.ace                            new.ace
--------------------------------------------------
TShirt : sam1                      TShirt : sam1
Price 12.95                        Price 14.95
Purple                             Red
Damage "Sept, 1990" "stain"

TShirt : sam2
Remarks "very nice"

TShirt : sam3                      TShirt : sam3
Faded                              Faded
                                   Resembles sam5
--------------------------------------------------
// acediff difference from old.ace to new.ace

TShirt "sam1"
-D Price 12.95
-D Purple
-D Damage "Sept, 1990" "stain"
Price 14.95
Red

TShirt "sam2"
-D Remarks "very nice"

TShirt "sam3"
Resembles sam5
--------------------------------------------------
Although the objects and their data in "old.ace" and "new.ace" could be in any order, acediff sorts the files by object and then, within each object, by line. The net result is that acediff is able to compare the data within each object, decide if there is new or missing information, and generate .ace commands for either deletions or additions.

Deletions come about in two ways. First, frank deletions in the new file (for example, the complete removal of the "Damage" line in sam1) generates a deletion command for the corresponding object in the difference file, e.g.

-D Damage "Sept, 1990" "stain"
Second, modification of data (for example, changing the price of sam1 from 12.95 to 14.95) is interpreted as a request to delete the original price:

-D Price 12.95
Additions also arise in two ways. First, the frank addition of information to the new file (for example, the "Resembles" line in sam3) generates an addition in the difference file:

Resembles sam5
Second, modification of data (for example, changing the price of sam1 from 12.95 to 14.95) is interpreted as a request to add the new price:

Price 14.95
Data modification (as opposed to frank deletion or addition) therefore generates two .ace commands involving deletion of the old information and addition of the new.

Finally, when acediff detects that a line is the same in the old and new files, the line does not appear in the difference file at all (note "Faded" in sam3). If this confuses you, remember that the difference file contains the transactions necessary to move from the old to new state. If data does not change, no transactions are required.

It is extremely important to understand acediff rules before reading a difference file into your database. Practice with throwaway files until you are confident. Acediffing identical files results in an empty difference file which will not change your database at all. But if you acediff an old file containing 1000 objects with a new file containing nothing, the difference file will contain the commands required to delete all 1000 objects. And switching old and new files can cause great confusion--be careful.

Updates

Very often acediff is used in the following way. A .ace file (perhaps dumped from your database) is copied and the copy is edited until it contains exactly the data you want--no more, and no less, either. Then acediff is run and the difference file is read back into the database. This has the effect of changing objects in the database to "look" like those in the edited version of the file.

This same process can be used on a grander scale to make remote copies a database identical to the canonical version. Briefly, the curator copies the canonical version, makes changes to it, dumps both versions and acediffs them class by class, and then distributes the difference files as an update. Reading the update into a remote database causes it to be synchronized with the new canonical version.

If you decide to make use of update files, you must understand that they are recognized by the update utility (main window pop-up menu) by virtue of their name and first line. The naming scheme allows the database to load multiple update files in the correct order. An example of a legal name is "update.3-1"; this file could be read into a database at state 3-0 (newly initialized). Applying the update brings the database to state 3-1. A 3-1 database will refuse to parse the 3-1 update file a second time because the next valid update file is "update.3-2".

The first line of the update must agree with the file name. For update file "update.3-1" the first line must read

// acedb update 3 1
You can always determine the current state by using the "Program status" option in the pop-up menu of the main window; the data release version is reported on the first line of the Status window. The Update window shows this information as well.

Update files need not be generated entirely by acediff and in fact ordinarily they are not. They can be edited by hand and will probably contain data from a variety of sources. Updates can also contain commands to rename objects or give them aliases.

An update always begins by reading in the models (as if you had first selected "Read models" on the pop-up menu of the main window). This makes it feasible to distribute new models along with new data that requires those models.

Show me the whole t-shirt model again.

Back to Table of Contents