FileCmdsDoc.tioga
Spreitzer, April 7, 1986 5:38:43 pm PST
FileCmds
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
FileCmds
Mike Spreitzer
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: FileCmds provides command-tool commands for computing and operating on sets of files.
Keywords: File, Set, Pattern, Enumeration, DF-File, Command, List, Directory, Delete, Archive, Retrieve, Message, Version Map, Walnut
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. FileCmds
The FileCmds package provides a number of commands which deal with file sets, and an algebra for constructing those file sets. It can be accessed through Cedar, Misp, or the command tool. Following is the command tool interface, then the Misp values. The Cedar interface is in FileSets.Mesa and MoreFileSets.Mesa.
name CmdPerFile:
syntax
CmdPerFile option* perFilePattern option* fileSetExpression option*
execute a command for every file in a given set. The set is computed by Boolean operators from elementary sets we know and love (all the files matching a given name pattern, the files in a DF-file seen through a filter, &etc). The command is what you get after performing the substitutions on the perFilePattern.
name ListFileSet:
name lfs:
syntax
ListFileSet option* fileSetExpression option*
list the files in the file set. This command has two options peculiar to it:
-l
long listing (includes date).
-s
short listing (no date). This is the default.
name DeleteFileSet:
name dfs:
syntax
DeleteFileSet option* fileSetExpression option*
delete the files in the file set.
name ArchiveFileSet:
name afs:
syntax
ArchiveFileSet option* fileSetExpression option*
print an archive request for the files in the set.
name RetrieveFileSet:
name rfs:
syntax
RetrieveFileSet option* fileSetExpression option*
print a retrieve request for the files in the set.
name CmdAllFiles:
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's in the version maps, indexed by short-name or create date; 3) what Bringover or SModel will see in a DF-file, modified by an arcane set of options; and 4) 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 file name, possibly with or without a directory part, possibly with or without version, maybe or maybe not with create date, what file are we talking about? FileCmds will use one of thirteen answers (as directed by the user). One is to always consult FS, and take the fullFName and create date 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). The other twelve consult FS only if needed to get information not initially given. These twelve answers are characterized by what subset of the total possible information they use; the choices are the twelve combinations of: (2: using or ignoring the version) * (2: using or ignoring the create date) * (3: using the server and directory part, the directory part only, or none). In all these cases, it is possible for some enumeration sources (plus whatever help FS can give) 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.
A fileSetExpression is a Misp expression designating a file set. FileCmds registers the following primitives with Misp, to aid in the construction of file sets.
(filesMatching fileNamePattern:ROPE) => FileSet
designates the files whose names match the pattern. A number sign (#) is just like an asterisk, except that it won't match directory delimiters. If a number sign is used, the pattern should be in the IFS-style, rather than the slashy style.
(versionMapFilesMatching fileNamePatter:ROPE [WhichMap]) => FileSet
designates the files in the indicated version map whose names match the pattern. The WhichMap should be either $Source or $Symbols, and defaults to $Source.
(versionMapFilesCreated from:Time to:Time [WhichMap]) => FileSet
designates the files in the indicated version map whose create date lies in the given range. The WhichMap should be either $Source or $Symbols, and defaults to $Source.
(archive date:ROPE) => FileSet
designates the files listed in the archive message of the given date. There must be a Walnut message viewer on that message.
(online date:ROPE) => FileSet
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).
(archived fileNamePattern:ROPE) => FileSet
designates the files, backed up by the archivist, whose names match the pattern.
(dfContentsq DFOption .. DFOption) => FileSet
like dfContents, except that the arguments are not evaluated.
(dfContents DFOption .. DFOption) => FileSet
designates the results of the analyses of the indicated DF files. Valid values for 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.
a UsingList
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.
"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..
a FileSet containing only DF files
this also specifies some DF files to use.
(using fileName1 ... fileNameN:ROPE) => UsingList
(fsFromFile fileName1:ROPE ... fileNameN:ROPE) => FileSet
each named file should contain text: a list (space delimited) of file names.
(fsFromROPE fileList1:ROPE .. fileListN:ROPE) => FileSet
each argument should be a list (space delimited) of file names.
(fsUnion fileSetExpression1 ... fileSetExpressionN) => FileSet
this constructs the union of the given file sets.
(fsIntersection fileSetExpression1 ... fileSetExpressionN) => FileSet
this constructs the intersection of the given file sets.
(fsDiff fileSetExpression1 ... fileSetExpressionN) => FileSet
this constructs the set difference fileSetExpression1 - fileSetExpression2 - ... fileSetExpressionN.
(fsSDiff fileSetExpression1 ... fileSetExpressionN) => FileSet
this constructs the symmetric difference fileSetExpression1 XOR fileSetExpression2 XOR ... fileSetExpressionN.
(fsRealify fileSetExpression) => FileSet
constructs a new file set by mapping all the files on pseudo-servers to ones on real servers (by simply substituting server names).
(fsFilter pred fileSetExpression) => FileSet
this constructs the subset of fileSetExpression that satisfies pred. The function pred gets to examine each file note in the file set in turn, and return a Misp truth value saying whether it passes.
(enumFileSet fileSetExpression consumer) => FileSet
this calls the consumer once for each file in the file set.
(fnID fn:FileNote) => (name:ROPE created:TIME)
this extracts the ID of a file note.
(fnName fn:FileNote) => ROPE
this extracts the name of the file being noted.
(fnCreated fn:FileNote) => Time
this extracts the create date of the file being noted.
(fnRead fn:FileNote) => Time
this extracts the latest-read-time of the file being noted.
(consIDS idsPart ... idsPart) => IndentificationScheme
Makes an IndentificationScheme. Each idsPart must evaluate to one of: $withServer, $withoutServer, $withDirectory, $withoutDirectory, $withVersion, $withoutVersion, $withCreate, $withoutCreate, $askFS. The defaults are $withDirectory, $withVersion, $withoutCreate.
(consIDSq idsPart ... idsPart) => IndentificationScheme
Like consIDS, except that its arguments are not first evaluated.
option is one of:
-withoutServer
this says that the server part of file names is not significant when identifying files.
-withServer
this says that the server part of file names is part of what identifies files. This is the default behavior.
-withoutDirectory
this says that the server and directory parts of file names are not significant when identifying files.
-withDirectory
this says that the directory part of file names is part of what identifies files. This is the default behavior.
-withoutVersion
this says that the version part of file names is not significant when identifying files.
-withVersion
this says that the version part of file names is significant when identifying files. This is the default behavior.
-withoutCreate
this says that the create date is not significant when identifying files. This is the default behavior.
-withCreate
this says that the create date is significant when identifying files.
-askFS
this says that files are identified by what FS returns as their fullFName and create date 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 (fsSDiff (dfContents (quote local) "Foo.DF") (dfContents "[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.
% lfs -shortAndCreate (fsSDiff (dfContents (quote local) "Foo.DF") (dfContents "[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.
% lfs -l (fsFilter (lambda (fn) (gt (timeDiff (fnCreated fn) (timeNow)) 3.1E7)) (filesMatching "[User]<JoeBloe>*"))
Joe Bloe asks for a list of the files he created more than a year ago.
% lfs (fsDiff (dfContents "[Indigo]<Barzoom>Top>Foo.DF!11") (dfContents "[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 (dfContents "[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>" (fsDiff (filesMatching "[Indigo]<Barzoom>Foo>*") (dfContents "[Indigo]<Barzoom>Top>Foo.DF"))
Nearly the same as the DeleteFileSet example. Exercise for the mind-reader: what's the difference?
% CmdAllFiles "Print" " <fileName>" "" "" (dfContents (quote 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.
stop/undo
STOP! button in the command tool.
contact
Sprietzer.pa