If the create date entry is a "~=" rather than a normal date, BringOver will retrieve the file only if the version on the remote server is different than the version on the local disk. If the file is not on the local disk, it will be retrieved. For example,

If the create date entry is a ">" rather than a normal date, BringOver will retrieve the file only if the version on the remote server is newer (or more recent) than the version on the local disk. If the file is not on the local disk, it will be retrieved. For example,

will retrieve from the remote server only if there is a newer version on the remote server.

There are two common, distinct uses of one or more DF files by another. The first is syntactic inclusion, similar to macro-expansion, where a DF file references another and all programs treat these DF files as if they were a single DF file with the text of the inner DF file substituted in the outer one at the point of reference. The second use is as an "Importer" of another system, package, or set of files controlled by someone else. By analogy with these concepts in Mesa, there are Exports as well.

The DF file syntax allows both forms of use, which are indicated by different keywords before the name and date of the nested DF file.

Since, in general, CoPilot.DF (in the example above) may have internal structure (i.e. it references other DF files with Include and Imports lists), CPSwapDefs.Bcd and CPSwap2.Bcd may be defined in some of the DF files referenced by CoPilot.DF. To avoid an explosion in search time, these restrictions apply when using Using lists on a DF file with internal structure:

A option (/v) will run BringOver in verify mode, where it will verify that the files listed in the DF file are present on the remote servers. (No files are retrieved in this mode.) If the file is listed correctly and a local copy exists, BringOver will add the RemoteFileName property to the leader page. Note for large DF files the verify option takes a few minutes. BringOver will inform the user if there are newer versions of files on the remote file servers, and will make a new DF file (on a file called "NewDFFile.DF") listing the newer versions of files listed in the original DF file. If any files were listed in the DF file without their IFS version numbers (e.g. !5), BringOver will make a new DF file with those version numbers filled in (also on "NewDFFile.DF").

An option (/o) will instruct BringOver to only BringOver the file(s) listed after the /o. For example,

will examine only the file "x.mesa" in files.df, even if other files should be brought over. If no "." is given, BringOver will append ".Mesa", so this is equivalent to the preceding example:

More than one file can be listed after /o, in which case the last DF file on the command line is searched.

Five options are available to reduce the number of files that are retrieved when BringOver is run. /b causes BringOver to retrieve only those files that are "derived" from source files, i.e. files that end in ".Bcd", ".Signals", ".Boot", and ".Press". /s causes BringOver to retrieve only non-derived files, i.e. all files that do not end in ".Bcd", ".Signals", ".Boot", and ".Press". /r causes BringOver to retrieve files that are in directories marked ReadOnly in the DF file and to retrieve files that are imported from other DF files. /w is the inverse of /r: only files that are not marked ReadOnly or imported are retrieved. Finally, /u causes BringOver to retrieve a file if a version is already on the local disk and the version listed in the DF file differs from the version on the local disk.

The /f option causes BringOver to ignore local files when it decides to retrieve a version of a file, thus /f "forces retrieval" of files on the local disk.

When the filename on a line in a DF file is preceded by a tilde ("~"), BringOver will retrieve the indicated version if it is not present on the disk. If there is already a version on the disk, then it will not be overwritten, regardless of its create date.

BringOver listens for Control-DEL. When typed, BringOver will abort itself.

BringOver can handle DF files with fewer than 500 files.

Should you need to supply a connect name and password, BringOver will prompt you for them. When a CR for the connect name and a CR for the connect password are typed, BringOver will ask if you want to use a different login name or abort the program.

BringOver can be given a list of DF files on the command line. It will behave as if each file had been given separately.

BringOver can be used to retrieve files that are not listed in DF files by putting them on the command line

will retrieve those two files. If a file ends in ".DF", BringOver will retrieve the contents as well.

If the version of a file on the local disk is newer than the one BringOver is retrieving, BringOver will first rename the local version by appending "$$" to the filename and then retrieve the local file. If the file ends in ".Bcd", BringOver does not bother to rename the file.

When you don't want any of the files in a directory to be changed by SModel, regardless of any changes you may make, you can indicate the files in the directory are read-only by preceding the Directory keyword with ReadOnly. For example:

indicates the files listed below should NEVER be stored back on <Mesa>System>.

It is important to remember that SModel NEVER enumerates the remote file system, so SModel may not detect that certain files listed in a DF file are not present on remote servers.

A common mistake is to assume that if you run SModel on a DF file successfully, and then simply change a Directory in the DF file, then all the files will be transferred (again) to the new directory. This is WRONG! After SModel has been run the first time the create dates listed in the DF file will agree with the dates of the files on the local disk. Since SModel checks the create dates listed in the DF file, on the second invocation SModel will not detect that any files need be transferred EVEN though the Directory has been changed.

To resolve these problems, SModel will take a /v option (/v stands for verify.) If given this /v option, SModel will not only apply the algorithm described above to store files, but if it decides a file does not need to be stored, it will look on the remote file server and check that in fact the file does not need to be stored. If the file is not on the remote directory, or the version listed in the DF file is not on the remote directory, then SModel will store the file. In this way SModel /v will try to force the remote directory to agree with the DF file.

SModel will invoke itself recursively on DF files that are specified in Include statements (and non-ReadOnly DF files preceded by @.) SModel will NOT invoke itself on DF files listed in Imports statements (or on DF files listed in ReadOnly directories preceded by @.)

If the Include or Imports statement is not followed by an Of <date> clause, SModel will insert such a clause in its output DF file with <date> replaced by the create date of the file on the local disk.

If the /p option is given, SModel will store all files listed in the DF file on a PreRelease directory. The name of the PreRelease directory is formed by inserting "Pre" in front of the directory specified in the ReleaseAs clause. If (any of) the normal working directories in the DF file do not match the corresponding PreRelease directories, the copy of the DF file on the local disk is not rewritten by SModel /p. If the working directories match the PreRelease directories, then /p is equivalent to /v.

For example, consider Foo.df, shown below:

Executing SModel /p Foo.df will create the following new DF file:

and store it and the rest of the files on [Indigo]<PreCedar>. However, the version of Foo.df on the local disk will not be changed.

1. The "/n" option instructs SModel to do everything it would normally do BUT it never transfers any files. For example,

2. If you give the "/s" option to SModel, it will store onto the remote server(s) all the files you've listed in the DF file, except those marked ReadOnly, whether or not local create dates match the ones in the DF file. For example,

3. If the /r option is given, then SModel will store files it decides should be stored by the above algorithm even if the directory they are stored onto in marked ReadOnly.

New users are often confused about the relationship of the entries in a DF file to the local and remote directories, and what SModel will do in certain cases. The easiest way to understand it is that SModel assumes 1) that the DF file was an accurate description of the remote directory at some point in the past and 2) files with differing create dates that it finds on the local disk are the "Truth" and that it should transfer any files that are different. However, assumption #1 allows SModel to assume that files with the same create date in the DF file and on the local disk ALSO exist on the remote server. This assumption is often not true when a new DF file is being created. To get started, there are at least these things you can do:

1. Make a DF file of just file names (no create dates) and run SModel on it. The files will be transferred and the create dates will be filled in.

2. Use VerifyDF (see below) to automatically generate a DF file, edit the DF file as you need to, and use the /s option to store all the files out onto remote servers.

3. If you have a complete consistent world out on remote servers, simply retrieve all those files onto the local disk and make a DF file with all their filenames but no create dates. Run SModel with the /n option to get the DF file filled in with all the create dates. (/n will not needlessly make extra copies of the files on your remote directories).

If you are maintaining a system for others, you may need to have entries in the DF file that are ReadOnly (such as for <Pilot>Defs>, etc.) Filling in all the create dates by hand is painful, so you may combine the /r and /n options to fill in all the create dates in the DF file but not transfer any of the files! For example,

will fill in all the create dates for files in Foo.DF but none will be stored.

SModel normally changes entries like

into lines like

and changes Imports like

into

since the CameFrom is inserted by the Release Tool. If you want to prevent SModel from making these changes, give SModel the /f option.

SModel listens for Control-DEL. When typed, SModel will abort itself.

SModel handles Connect user names and passwords exactly as BringOver does (see above).

If a file is transferred, the RemoteFileName property (see above) is added to the leader page of the file on the local disk to record where a remote copy can be found.

Releasing large systems is a tricky business. SDD has known this for a long time and has developed elaborate release procedures to cope with the matter. We're only just discovering how messed up things can get. However, since we have many fewer human cycles to expend on this problem than SDD does, it is imperative that we devise natural, easy-to-use, and efficient (of people time) procedures for our releases of Cedar.

The [Indigo]<Cedar> directory will be used exclusively for Cedar releases; that is, a file will appear on this directory if and only if it is a part of a (reasonably current) Cedar release. There will be a "release master" (initially Levin) who is responsible for insuring this invariant. Only the release master will be permitted to create or delete files on the release directory.

In the future, we expect to use system modelling facilities to describe and issue releases. Until the necessary software is in service, we will use DF files and a number of manually-executed conventions to achieve a similar effect. The procedures I will describe have the virtue that: (1) they place only a slight additional burden on the individual implementor, (2) they enable the release master to insure the release invariant without building the release files from the original sources, and (3) they are amenable to substantial automation. The software needed to perform this automation is nearly complete.

Since the DF file is the sole descriptive mechanism presently at our disposal, we will use it in a stylized way as a "poor man's system model". Cedar implementors will observe the following conventions in producing components for release as part of the Cedar system:

The following summary of qualifiers that appear in DF files may be helpful:

Within a DF file that is intended to conform to the guidelines for release:

However, there is an important exception to (b). It occasionally happens that a single person is concurrently developing both the implementation of an interface and a client of the same interface. (Example: a collection of BCD manipulation facilities is imported by both the compiler and the binder. Ed Satterthwaite is the implementor of the BCD facilities as well as these two illustrious clients. When developing a new version of the BCD stuff, Ed frequently and rapidly switches between his roles as implementor-of-BCD-package and implementor-of-client-of-BCD-package.) In such situations, specifying "#" in the client's DF file will cause the wrong thing to happen; it was to accommodate this situation that the ">" form of date specification was originally added to DF files. Implementors who find themselves in this predicament should use ">" instead of "#" where necessary.

It should also be understood that when the ReleaseTool is constructing the DF files to be stored on the release directory, it will uniformly replace "#" and ">" specifications by explicit dates. This is important for a release, since it is intended to be a snapshot of the state of the files at some instant of time, and the loose binding implied by "#" and ">" is inappropriate. During the development process, however, these "dynamically bound" date specifications are very useful, and it is unreasonable and unnecessary to expect people to perform the manual translation to specific dates when release time arrives.

How, then, does this transformation of dates fit in with the ongoing development process? When an implementor finds it necessary to change a component following a release, he/she has the choice of starting from the DF file on the release directory or from the one used to build the component in preparation for the release. (Of course, the latter may validly disappear after the release; only the DF file on the release directory is guaranteed to be retained.) In the former case, the maintainer will have to edit the released DF file to make it convenient for subsequent development, e.g., by adjusting Directory headings to reference working directories and by replacing specific dates with "#" or ">". In the latter case, the DF file is already (still) suitable for development work. If a particular component is frequently changed and usually by the same person, the latter approach will likely be followed. If the component is infrequently modified or if many different people have occasion to change it, the former approach will be less error-prone. The choice should be made on a package-by-package basis.