syntax
CmdAllFiles option* cmdPrefix perFilePattern sepPattern cmdSuffix fileSetExpression
execute one command, with a lot of arguments (one per file). The command is composed from the strings and the file set in the obvious way. The options may in fact be interspersed among the other arguments in any way.
description
This package takes care of all those random things you've wanted to do with sets of files. There are four specific commands, for: listing, deleting, creating archive requests, and creating retrieve requests. There are also two general-purpose commands, that let you do string operations to create the commands you really want. All the commands have the same idea of what file sets are, and take some common switches. Some commands take switches or arguments peculiar to them. The common arguments and switches are explained below.
Cedar has a number of different things that can be viewed as sets of files. Most interesting among these are: 1) what FS will enumerate, given a file name pattern; 2) what Bringover or SModel will see in a DF-file, modified by an arcane set of options; and 3) the files listed in a message to or from the Archivist: an archive request, an archive response, a retrieve request, and a retrieve response.
This package takes those primitive kinds of sets of files as building blocks, and lets you combine them with Boolean set operations (union, difference, &etc.) and then do something with the result.
Cedar also has a number of different opinions on exactly what a file is and how a file is identified. FileCmds takes the view that the question is: given a global name, possibly with or without version, maybe or maybe not with create date, what file are we talking about? FileCmds will use one of three answers (as directed by the user). One is to always consult FS, and take the fullFName that comes back as uniquely identifying a file. Of course, this will fail for files that don't happen to exist at the moment (e.g., archived and deleted files). Another is to take the first global name and version you can get; this may involve FS, or it may not, depending on what you started with. The third answer says files are uniquely identified by create date and short name (without version). This tries to identify contents, regardless of where they are sitting in the global name space. In all these cases, it is possible for some enumeration sources to not provide enough information to identify a file. When this happens a warning message is printed, and the file is not included in the primitive set. If the command we are doing this for is touchy (see switches below), such identification failures will prevent the command from doing work beyond computing the file set.
fileSetExpression is one of:
"fileNamePattern"
designates the files whose names match the pattern
fileNamePattern
designates the files whose names match the pattern (these patterns must look like Cedar identifiers)
(archive "date")
designates the files listed in the archive message of the given date. There must be a Walnut message viewer on that message.
(online "date")
like archive, except that if the message is a retrieve response, this designates the places the files were retrieved to (this is potentially distinct from where they were archived from).
(DFOption DFOption .. DFOption)
designates the results of the analyses of the indicated DF files. Valid DFOptions are:
source, derived, sourceAndDerived
these specify part of the filter. Default is sourceAndDerived.
public, private, publicAndPrivate
these specify another part of the filter. Default is publicAndPrivate.
defining, imported, definingAndImported
these specify yet another part of the filter. N.B.: Default is defining.
(using "fileName1" ... "fileNameN")
this gives the using list. There can be no more than one using list given. The using list may be omitted.
remote, local
these specify whether to use the local files (the files in the current working directory whose short names are in the DF files) or the remote files (the ones specified in the DF files). Default is remote.
df
this says nothing new. It is here because the first option can't be a rope literal.
"DFFileNamePattern"
this specifies some DF files to use. These patterns differ from the FS norm in that the version part defaults to !H instead of !*. There can be more than one pattern. The first DFOption in the list can't be a pattern.
(union fileSetExpression1 ... fileSetExpressionN)
this specifies the union of the given file sets.
(intersection fileSetExpression1 ... fileSetExpressionN)
this specifies the intersection of the given file sets.
(diff fileSetExpression1 ... fileSetExpressionN)
this specifies the set difference fileSetExpression1 - fileSetExpression2 - ... fileSetExpressionN.
(sdiff fileSetExpression1 ... fileSetExpressionN)
this specifies the symmetric difference fileSetExpression1 XOR fileSetExpression2 XOR ... fileSetExpressionN.
option is one of:
-longWithVersion
this says that files are identified by global names that include versions. This is the default behavior.
-shortAndCreate
this says that files are identified by short names (without versions) and create dates.
-askFS
this says that files are identified by what FS returns as their fullFName after some kind of lookup.
-touchy
this says that if there is any problem evaluating the fileSetExpression, then proceed no further after finishing evaluating the fileSetExpression. This is the default behavior.
-tough
this says to push on as doggedly as possible.
perFilePattern is a ROPE literal that will be subjected to the following substitutions:
<fileName>
gets replaced with the name of the file
<created>
gets replaced with the create date of the file. If the perFilePattern contains <created>, but no create date is available for the file, a warning message is printed, and the command does nothing after enumerating the file set.
<primaryVolume>
gets replaced with the primary volume on which the file was archived (empty string if file not known to be archived)
<backupVolume>
gets replaced with the backup volume on which the file was archived (empty string if file not known to be archived)
examples
% lfs -shortAndCreate (sdiff (local "Foo.DF") (df "[Indigo]<Barzoom>Top>Foo.DF"))
What's the difference between what's in the local directory and what's on the server? Note that -shortAndCreate is the proper way to identify files for this use.
% dfs -askFS (diff "[Indigo]<Barzoom>Foo>*" (df "[Indigo]<Barzoom>Top>Foo.DF"))
Delete everything in [Indigo]<Barzoom>Foo> that's not defined in [Indigo]<Barzoom>Top>Foo.DF!H. Since this is touchy (by default), if the enumeration of [Indigo]<Barzoom>Top>Foo.DF!H finds any defined files missing, no deletions will be performed. The -askFS was necessary to make sure we ask FS about every file.
% lfs (sdiff (df "[Indigo]<Barzoom>Top>Foo.DF!11") (df "[Indigo]<Barzoom>Top>Foo.DF!12"))
What changed between releases? In this case -longWithVersion suffices, and we don't have to touch the server for every file (DF-files usually list versions).
% afs (df "[Indigo]<Barzoom>Top>Foo.DF")
Print an archive request for everything defined in [Indigo]<Barzoom>Top>Foo.DF!H. You then have to manually stuff this into an archive request message, and send it.
% rfs (archive "29 Nov 84 12:16:43 PST")
Print a retrieve request, asking for all the files in an archive response dated 29 Nov 84 12:16:43 PST.
% CmdPerFile -askFS "Delete <fileName>" (diff "[Indigo]<Barzoom>Foo>*" (df "[Indigo]<Barzoom>Top>Foo.DF"))
Nearly the same as the DeleteFileSet example. Exercise for the mind-reader: what's the difference?
% CmdAllFiles "Print" " <fileName>" "" "" (source "[Indigo]<Barzoom>Top>Foo.DF")
Submit one big print request, covering all the sources defined in [Indigo]<Barzoom>Top>Foo.DF!H.
warnings
Because of a bug in the command tool, the first command will fail if it uses quotes.
DeleteFileSet is a power tool. You may want to do a ListFileSet first to see what will happen.