DFDoc.tioga
Russ Atkinson (RRA) January 20, 1987 6:55:58 pm PST
Mike Spreitzer February 26, 1987 3:40:20 pm PST
Rick Beach, March 13, 1987 11:14:36 am PST
Willie-sue, January 22, 1991 1:25 pm PST
Michael Plass, January 23, 1992 2:15 pm PST
Last changed by Pavel on February 8, 1990 2:49 pm PST
DF
Cedar10.0 FOR INTERNAL XEROX USE ONLY
DF Files and Torches
BringOver, SModel, and the Torch Service
Russ Atkinson
© Copyright 1985, 1986, 1987, 1990, 1991, 1992 Xerox Corporation. All rights reserved.
Abstract: DF provides the basic client support for DF files, plus a Commander interface to the basic DF functions: BringOver and SModel. Various options are available through switches. It also provides the Torch Service, accessible through a set of commands for taking and giving up ``torches'', informal locks on packages.
Keywords: DF file, programming tools, version management
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
0. News
January 23, 1992
Bringover and SModel now report warnings if the user does not hold the package torch. For Bringover, this happens only it no filters are used. The check may be skipped with the -j switch.
The -f switch for Bringover now means really copy the file, don't make a symbolic link.
The -q switch for Bringover now means "quiet" instead of "use caching" - caching is always used.
1. DF File Manipulation Tools
1.0. Conventions
By convention, all of the switches default to FALSE except those that are described as {default}. Also, all switches are accumulated for their effects, except that the -u switch takes place immediately (rests the options to their defaults). The -~ switch is used to invert the sense of the following switch. Case does not matter, so switch -A is the same as switch -a. Also, switch sepcifications can be mixed with file names on the command line, and are active until the next switch specification is encountered in the command line.
1.1. BringOver (aka QBO)
BringOver is the command used to bring the files listed in a list of DF files into the local naming environment. BringOver normally works by making attachments (iff possible) in the current working directory to the files described by the specified DF files.
BringOver normally does caching, that is, once it's done a BringOver of a certain DF with a certain filter, it does not do it again. The scope of the caching is one command. It assumes that no other FS activity that would invalidate the cache occurs during that time. QuickBringOver also refrains from trying to localize DF files because of `Imports' or `Includes' clauses. Both the caching and the restraint can be turned off by command line switches.
Some actions require confirmation, which is an action that can either be performed by program or by the user. The default action is to automatically refuse confirmation if the action looks like a blunder, and accept it if it does not. Switches can change this behavior: -y will always accept the action; -h will always ask the user via the command tool; and -a will consult the user for apparent blunders and automatically accept non-blunders.
If a directory is given instead of a switch or file name, then that directory is used instead of the current working directory for the rest of the short DF file names (those without explicit directories).
Switches
-a (auto confirm) - confirm all operations, unless they look like blunders, in which case the user is queried via the command tool
-b (origin: derived) - accept only derived files (*.bcd, *.boot, *.press, *.signals)
-c (check remote) - check that remote versions exist
-d (date check) - trying to fetch or attach remote files that have earlier dates than the local files requires confirmation {default}
-e (enter attachments) - check that remote versions exist {default}
-f (action: fetch) - force the actual transfer of the accepted files - implies ~e
-h (confirm by hand) - yes/no choices passed to the user in the command tool streams
-i into following directory
-j (just trust me) - skip torch check
-m (try map) - for short DF names try using the source version maps to fill out the prefix
-o (selected files) - accept only the files following the -o switch up to the last file specified or the -x switch (the last file listed OR the file following the -x switch is the DF file)
-p (access: public) - accept only exported files
-q (quietly) - print only warnings, errors, and summary
-r (reference: imported) - accept only imported files
-s (origin: source) - accept only non-derived files
-t (touchy) - let warnings cause the command to fail; ordinarily only errors do
-u (uh) reset switches to default values
-v (verify) - don't do actions, just see what's needed
-w (reference: defining) - accept only files directly listed in the DF file (not imports)
-x (execute) - start execution with the next file (useful after the -o switch when used on multiple files)
-y (yes always) - confirm all operations, even if they look like blunders
-z (zounds) - bring over DF files being processed {defaults FALSE}
Examples
BringOver -p /Cedar10.0/Top/DF.df
takes the exported files specified by /Cedar10.0/Top/DF.df and creates local attachments for them in the current working directory
BringOver Rope -p IO
takes all files described by Rope.df and the exported files described by IO.df and creates local attachments for them in the current working directory
BringOver -o RopeDoc.tioga Rope
takes the version of RopeDoc.tioga described by Rope.df and creates a local attachment for it in the current working directory
QBO -mp Rope
uses the version maps to find the prefix for Rope.df ([PCedar2.0]<Top>Rope.df) and brings over the public files from that DF file. Note that the highest version number on the remote server is used, not the version named in the version map, so slightly out-of-date version maps will not cause confusion.
1.2. SModel
SModel is the command used to store changes to the set of files described by the specified DF files. Normal users should avoid giving any switches, since using them (except for a) can cause inconsistencies in the DF files.
Switches
-a (make attachment: default yes, -~a to not make attachment)
-c (Check remote: default yes)
-j (just trust me) - skip torch check
-n (Store changed files: no)
-t (touchy) - let warnings cause the command to fail; ordinarily only errors do
-u (uh) reset switches to default values
Examples
SModel Foo
stores the changed version of files described by Foo.df to the remote server given in Foo.df, and stores the updated version of Foo.df as well
SModel Foo Bar
stores the changed version of files described by Foo.df and Bar.df to the remote server(s) given in Foo.df and Bar.df, and stores the updated version of Foo.df and Bar.df as well
1.3. VerifyDF
VerifyDF is the command used to check the specified DF files for consistency. VerifyDF that each of the specified DF files has been SModel'd before being checked.
Switches
-t (touchy) - let warnings cause the command to fail; ordinarily only errors do
2. The Torch Service
A ``torch'' is a kind of informal lock on the files controlled by a particular DF file; only the person holding the torch for a particular package is allowed to SModel new versions of that package. There are four commands for manipulating those locks. In addition, there is a programmer's interface to the service, provided by the GiveAndTake Cedar interface.
Most torch service commands have the syntax:
command-name [-w world-name] package-name ...
where world-name is the name of a set of DF files, such as PCedar2.0, Cedar7.0, etc., defaulting to PCedar, and package-name is the ``short name'' of a package controlled by one of those DF files. For example, ``Tioga'' is the short name of the package controlled by the ``Tioga-Suite.df'' file. The exception is the TorchTaken? command:
TorchTaken? [-w world-name] [-o owner-pattern] package-name ...
where owner-pattern is a pattern (using only * and literals, case-insensitive) that matches some owner names.
The GiveTorch and TorchTaken? commands have special behavior when no package-names are specified. The TakeTorch and StealTorch commands simply do nothing in that case.
TakeTorch
This command attempts to grab the torches for the named packages in the named world, failing in each case if some other user already has that torch.
StealTorch
This is just like TakeTorch except that it never fails. If some other user already has one of the torches in question, it is forcibly removed from their care. In general, StealTorch should only be used in extreme circumstances, where you are willing to help the previous torch-holder integrate their changes into yours. In any case, you should always notify the previous torch-holder that you've robbed them.
GiveTorch
This command releases the torches for each of the named packages; of course, you can only release torches that you already hold. If no packages are specified on the command line, GiveTorch will prompt you for each of the torches you currently hold in the named world, allowing you to choose on a case-by-case basis whether or not to release that torch.
TorchTaken?
The TorchTaken? command prints out the current holder of the torch for each of the named packages, along with the date and time at which it was grabbed. If no packages are specified on the command line, this information is printed for every torch currently grabbed in the named world. If an owner-pattern is given, only torches held by owners matching the given pattern are reported.