find.13

New-style documentation for FIND.	Last updated 6/1/79 by PDL.
Documented /BRIEF switch - 5 February 1982 --Gren

File: FIND, Node: Top, Next: Details, Up: (DIR)

	The most common use of FIND is to look for a file whose name you
remember (or almost remember) that is somewhere on the disk.  If you are
looking for FOO, for example, say

:FIND FOO

which will find all files on the local ITS which have first name FOO.

	Another common use of FIND is to see which of several possible
directories a file lives on

:FIND A;B;C;FOO BAR

looks only at directories A B and C for the specific file FOO BAR.

	The third common use of FIND is to see if a given file is
up-to-date on all four ITS systems

:FIND **:SYS;TS ZORK

will show you the state of TS ZORK on AI, DM, MC, and ML.

	In all cases the DDT print-default will be set to the last file
found by FIND.

	FIND also recognizes many switches which allow file selection
based on one or several of the salient aspects of a file.

* Menu: For a quick reference on switches FIND knows about, or recent
	info on changes/bug fixes, visit these menu items.

* Order::	FIND's switches in functional groupings.

* Recent: (MC:.INFO.;FIND RECENT)*	Recent information.

File: FIND, Node: COMB, Next: Details, Up: (DIR)

	To use COMB (in the simple case):

:COMB <dir>;<fnm1>

will print all files on <dir> whose <fnm1> matches the spec given.  The
printing will be done in essentially the same manner as it is done by
:MSGS.

:COMB is like :FIND except that files found are printed.  It defaults to
"comb" DSK:COMBAT;PLAN *, which is only useful on DM.

	In general COMB is like FIND:  You can comb the same things you
can find.  The default to find/comb is just treated differently.  For
example :COMB *;* MAIL &TODAY will print all recently created mail files
(note that the "*;" is needed because the <dir> defaults to COMBAT).

File: FIND, Node: LF, Next: Details, Up: (DIR)

	To use LF (in the simple case):

:LF

:LF (or linked as any other name beginning with L) another entry to TS
FIND, which defaults to "find" one <dir>;<dev>: combination:  the one
that is the current DDT default.  Its only advantage over the system's
LISTF is that it gives some information that the system LISTF does not:
Reap-bit, Reference-date, Author of a file, and so on.

File: FIND, Node: Details, Next: Files, Up: Top

:FIND <output-file> _ <directories> <devices> <files> <switches>

* Menu:	Visit these nodes for details on various aspects of FIND.

* Files::	How to specify which files FIND should look for.
* Directories::	How to specify which directories FIND should search.
* Devices::	How to specify which devices FIND should look at.

* Switches::	General information on switches.
* Order::	Summary of switches.

* Input::	Details of typing to FIND.
* Output::	How to make FIND generate hard-copy.

* Search::	Internals of search specification.

* Examples::	Many annotated examples.

File: FIND, Node: Directories, Next: Devices, Previous: Files, Up: Details

	FIND normally tries to search every directory in the MFD.  It is
often the case that you can narrow the search from your own knowledge of
where a file is likely to be.  Assume you are searching for FOO BAR.

:FIND FOO BAR		;will search every directory on the DSK.

	Giving a directory name says to search only that directory.

:FIND A;FOO BAR		;will only look at directory A.

	You may give any number of directory names.

:FIND A;B;C;FOO BAR	;will look at A B and C.

	If a nil directory specification is given, this implies to
search the XUNAME directory.

:FIND ;FOO BAR		;will only look on the XUNAME directory.

	You may give directories in * format a la DIRED.

:FIND LIB***;FOO BAR	;only look on directories with LIB as the first
			;three characters of the name.

	FIND also recognizes a few "device" specifications which are
really directory specifications.

	To search all the SYS<n>; directories (SYS, SYS1, SYS2), use the
SYS device.

:FIND SYS:TS FIND	;this is almost the same as SYS*;

	The COM device maps into the COMMON; directory.

	The TPL device maps into the .LPTR.; directory.

File: FIND, Node: Devices, Next: Switches, Previous: Directories, Up: Details

	You may specify any combination of DSK-like devices.  These
include DSK, COM, TPL, SYS, and AR*.  If no device is given explicitly
the default is DSK.

:FIND FOO BAR		;will only look at DSK directories.

	Giving *: means "the DSK and all ARC-style devices".

:FIND *:FOO BAR		;will look at DSK and all AR*'s.

	Giving AR*: means "all ARC-style devices".  You may also give
archives explicitly: ARC:AR1:, and so on.

:FIND AR*:FOO BAR	;will look at AR1, AR2, etc.

:FIND AR1:AR3:FOO BAR	;will look only at AR1: and AR3:.

Note:  there are currently a few "features" of FIND's understanding of
archives:

	(a) it looks only at ARC and AR0 through AR9.  This will
hopefully be fixed some day.

	(b) it does not search based on or print correctly the lengths
of files in new-style archives.  This is due to the way such lengths are
stored in the archive and is unlikely to be "fixed".

	SYS: maps into the SYS; SYS1;, etc., directories, COM: into
COMMON; and so on.

	You may specify other ITS sites in the search path via their
device names:  AI:, MC:, DM:, ML:.  **: means to search all four ITS's.
There is a restriction in that only three foreign directories may be
searched in (enough to do :FIND **:SYS:).  This is to reduce the amount
of SYStem console printout and JOBDEV lossery.  Normally, only the local
ITS is examined.  Someday the JOBDEVs will be reused and this
restriction will be removed.

	Funny devices:  FIND will search for any device that you tell it
is "like" either a disk or an archive.  For example, an archive you have
renamed to be the file ZORK > can be searched by using a special switch,
the ARC or ARCHIVE switch:  /ARC ZORK: says to look for the ZORK device
which is accessed like the ARC device (that is, has a directory like the
ARC device and is called ZORK > on some directory).  Additionally, you
may specify DSK-like (but unknown) devices by /DSK <device>:, which
assumes the UFD of the device is available by OPENing .FILE. (DIR) on
that device.  Note:  "Funny" DSK-like devices cannot be searched on
remote ITS hosts.

	In :LF the DDT-default <device> and <directory> are used if they
are not specified.

File: FIND, Node: Files, Next: Directories, Up: Details

	You may give any number of DIRED-style file specs.  If you give
only one name (as in :FIND TS) the second defaults to *.  If you want to
give several single names, separate them by ,:

:FIND FOO,BAR,BLECH,TS		;looks for FOO *, BAR *, BLECH *, and
				;TS *.

File: FIND, Node: Output, Next: Input, Previous: List, Up: Details

	A file specification followed by an _ as the first thing input
causes output to be put into that file.  Default of course, is to go to
TTY:.  If you give an output file, the default is <MSNAME>;FIND OUTPUT.

Note:  If your file search specification has _'s in it, and they could
be confused with an output specification, quote them using ^Q.  For
example:

:FIND PDL;_MSGS_  ;is ambiguous.  Do you mean output to PDL; all files
		  ;which match MSGS_ or do you mean all files on PDL;
		  ;which match _MSGS_?  Quote the _'s in the latter
		  ;case.  However,

:FIND _MSGS_	  ;is not ambiguous, because nothing precedes the first
		  ;_, meaning it can't be the signal for an output file.

	What actually happens is that the first unquoted _ is examined
when read, and if there is something that looks like it might be a file
specification to the left of it, that file spec is used as the output
file.

File: FIND, Node: Switches, Next: List, Previous: Devices, Up: Details

	Any number of switch names, each prefixed by a / or a &.  The /
and & delimiters have a special meaning.  / means "OR" and & means
"AND".  This allows complicated Boolean expressions to be set up to
select files.

	If only one switch is given, it doesn't matter which delimiter
is used, but if more than one is given or a switch is given in
conjunction with file names, it can become quite important.  For
example, one of the most commonly used switches is the TODAY switch,
which selects files created on the same day is the program is being run.
If you type

:FIND ME;/TODAY		or	:FIND ME;&TODAY

you will get all the files on ME; created today; switch delimiter
doesn't matter.  However

:FIND ME;FOO /TODAY

is NOT the same as

:FIND ME;FOO &TODAY

	The / ("OR") switch version means "all FOOs on ME; or all files
on ME; created today".  The & ("AND") switch version (which is probably
what you really wanted) says "all FOOs on ME; created today".

	Many situations where FIND "doesn't work" can be traced to
improper use of / and &.  This has given rise to the speculation that
FIND has one of the more obscure user interfaces in the universe.

File: FIND, Node: List, Next: Output, Previous: Switches, Up: Details

* Menu:			More details on switches

* Order::	An inclusive list of switches for reference.
* Flags::	Switches that set a flag for FIND.
* Simple::	Simple switches (with no or simple arguments).
* Range::	Switches that take a range of values.
* Compare::	Switches that compare aspects of several files.
* Multiple::	Details of the multiple search switch /OR.

File: FIND, Node: Order, Next: List, Up: Details

	Switches recognized by FIND are listed here.  They must be
preceded by / ("OR"), & ("AND"), /NOT ("NOR"), or &NOT ("NAND").

--Switch--	--Synonyms--	--Brief Description--

OR		(or FIND,ELSE)	Delimit searches.
NOT				Complement effect of following switch.

	Switches dealing with size.

SIZE <range>	(or SIZEB)	File size in blocks.
SIZEW <range>			File size in words.
EXTRA <range>			Number of extra words in last block.

	Switches dealing with time.

DATE <range>	(or CDATE)	Creation date of file.
TODAY				Created today.
RDATE <range>	(or REF)	Reference date of file.
TIME <range>	(or CTIME,T)	Creation time of file.

	Miscellaneous file characteristics.

TO <file>			Files which are links to <file>.
LINKS		(or L,LINK)	Files which are links.
AUTHOR <uname>			Files created by author <uname>.
DUMPED				Files that have been dumped.
REAP		(or SAFE,PROTECTED)	"Do Not REAP" files.
OPEN		(or WRITE)	List files open for writing.
DELETED				List files to be deleted when closed.
PACK <number>	(or PCK,DRIVE)	List files on a given disk pack.

	Switches that require looking at other files:

NEW <name>			Print files with same first name and a numeric
				second name which are newer than this file.
VERSIO <n>	(or V,VER)	Print files which have numeric second names
				and which have <n> or more "relatives" with
				the same first name.

	Switches dealing with directories.

ALLOC				Only list files on allocated packs.
ARC <dev>:	(or ARCHIVE)	Tell FIND <dev> is like an archive.
DSK <dev>:	(or DISK)	Tell FIND <dev> is like a disk.

	Switches that set Flags.

PR		(or PRINT)	Print files as though FIND were COMB.
TOTAL		(or TOTALS,SUM)	Print totals of files found.
NOLF		(or NOLIST)	Don't print names of matches.
BRIEF		(or B)		Print ONLY the filename of matches.
WORDS		(or W,WORD)	Print file sizes in words.
FLOATS		(or F,FLOAT)	Print file sizes in floating point.
TECO				Print file names in TECO format.

	Range specifiers (which occur with those switches which want a
<range> as an argument):

GT <n>		(or >,GREATER)	Arithmetic Greater-than.
LT <n>		(or <,LESSER)	Arithmetic Less-than.
EQ <n>		(or =,EQUAL)	Arithmetic Equals.
BTW <n1> <n2>	(or BETWEEN)	Arithmetic Greater-than X, Less-than Y.

File: FIND, Node: Flags, Next: Simple, Up: List

	First are the "switches" that either are not delimited by / or
&, or which are never interested in which is their delimiter.

$ <altmode>

	Normally FIND sets the DDT print default to the last file found. 
Including an $ on the command line disables this feature.

/TOTAL  (or SUMMARY, TOTALS, SUM)

	Print totals of files, blocks, and links found at end of run.

/OR  (or FIND or ELSE)

	This switch delimits search specifications.  It is described in
detail below.

/ARC <device>:  (or ARCHIVE)

	See (FIND)Devices.

/DSK <device>:  (or DISK)

	See (FIND)Devices.

/NOLF  (or NOLIST)

	Don't print the LISTF lines for matches, only print the summary
at the end.  Primarily useful along with /TOTAL.

/PR	(or PRINT)

	Makes FIND print the files it finds, like COMB.  (COMB is almost
exactly :FIND with /PR set and funny file defaults.)

/BRIEF	(or B)

	Makes FIND print ONLY the filename of matchs, 5 fn1-fn2 pairs
to a line (good for people with horribly slow terminals)

/WORDS  (or W or WORD)

	Print total words in file in LISTF lines, not BLKS+WDS.

/FLOATS  (or F or FLOAT)

	Print floating point size of file:  BLKS.<words*100./1024>.

File: FIND, Node: Simple, Next: Range, Previous: Flags, Up: List

	The following switches are truly Boolean, so their delimiter is
significant.

/TO <file-spec>

	Selects files which are links to the file-spec given (the spec
may contain *'s and so on).

/LINKS (or L or LINK)

	Select files which are links.

/AUTHOR <uname>

	Select files created by the author specified.  To specify "any
non-directory author" give authorname "?".  This switch is not too
useful unless you are looking on a machine where the author feature is
defaultly turned on.

/DUMPED

	Select files that have been dumped.  By convention, LINKs are not
dumped, and therefore it is often useful to couple this switch with &NOT
LINK as well.

/REAP (or SAFE or PROTECTED)

	Select files whose "Do not REAP" bits are turned on.  These are
indicated in the normal "LISTF" line by having a $ (mnemonic for
expensive) next to the dump bit character.

/OPEN (or WRITE)

	Select files open for writing.  This is useful mostly to find
losing files in Archives, unless you are just nosy.

/DELETED

	Select files to be deleted when closed or deleted from unmounted
pack.

/PACK <number>  (or PCK or DRIVE)

	Select files on a particular disk pack.

/ALLOC

	Select files on allocated packs.

File: FIND, Node: Range, Next: Compare, Previous: Simple, Up: List

	Several switches take as their argument a "range".

	To specify a range, give one of the following:

GT <number>	(or >,GREATER)

	Means "match any number greater than my argument".

LT <number>	(or <,LESSER)

	Means "match any number less than my argument".

EQ <number>	(or =,EQUAL)

	Means "match any number equal to my argument".

BTW <num1> <num2>	(or BETWEEN)

	Means "match any number within the range specified by my arguments.

	If no range indicator is given but a number is, the marker "EQ"
is understood.

	As a convenience, "BEFORE" "SINCE" and "ON" work as well, since
they are mnemonic with dates.  Additionally, the switches with these
names map into "CDATE <switch>".
	When the range is a range of dates, "TODAY" is understood to
have its obvious meaning.  Also "TODAY" as a switch is understood to
mean "CDATE TODAY".

	Switches which take a range as argument are:

/SIZE <range>  (or SIZEB)

	Select files which are within the range of the number of blocks
specified.

/SIZEW <range>

	Like SIZE, only specifies file sizes in words, rather than
blocks.

/EXTRA <range>

	Select files with the indicated number of unused words in the
last block.  For example, /EXTRA > 1000 would be files whose last blocks
are almost empty.  This is useful for finding candidates for archiving.

/DATE <range>  (or CDATE)

	Select files created within the range of date specified.  Dates are
specified in one of several ways:

a) as though they were large fixes, i.e.; January 1 is 760101 and
   December 31 is 761231.

b) as up to three numbers separated by slashes, i.e.; 1/30/76. If
   specified in this mode the year is expected to be last.

c) as (b) but separated by dots, i.e.; 76.1.30.  In this format the year
   is expected to be first.

	The default date when a date is asked for is today.  It may be
given directly (:FIND /CDATE TODAY, for example) or used as a base date.
For example, :FIND /CDATE 2/20 implies February 20 of the current year,
and :FIND /CDATE 10 implies the 10th of the current month.

	A date specification may be combined with a time specification:
"/CDATE SINCE 5/1 13:00" means May 1 at 1pm.

/RDATE <range>  (or REF)

	List files whose reference date is within the range given.

/TIME <range>   (or CTIME or T)

	List files whose creation time is within the range given.  Times
are specified in standard form on a 24 hour clock:  20:30 for 8:30 pm,
for example.  Note that a TIME spec does not combine with a date spec:
"/DATE 5/1 /TIME 13:00" is different in meaning from "/DATE 5/1 13:00".
The former implies "Created on May 1 or created on any day after 1pm."

File: FIND, Node: Compare, Previous: Range, Next: Multiple, Up: List

	Two switches require looking at several file data blocks to
determine whether a file matches:

/NEW <name>

        This switch is useful for finding files which need reassembling,
recompilation, or whatever.  <Name> is a matching specification for
second file names.  Popular choices for <name> could be BIN, NBIN, or
FASL.  When a file which has the appropriate second name is found, FIND
searches for files with the same first name and a numeric second name. A
numeric name is defined as one with any number of trailing digits
(including the case of all digits, of course).  The files found this way
which were created more recently than the <name> file "match" the /NEW spec.

/VERSIO <n>	(or V, VER)

	Finds files with numeric second names for which there are <n> or
more "relatives"; files with the same first name and a numeric second
name.


File: FIND, Node: Multiple, Up: List, Previous: Compare

	There is a special switch, called either OR, ELSE, or FIND,
whichever you prefer, for delimiting entire search specifications.  For
example:

:FIND TS DDT &LINK TS FIND &NOT DUMPED

gives an infulfillable search path, a file simultaneously named "TS DDT"
and "TS FIND".  You could do two separate FINDs, but most people are
lazier than that.

	Using the OR switch:

:FIND TS DDT &LINK /OR TS FIND &NOT DUMPED

causes two search specifications to be created:  Links named "TS DDT"
and files named "TS FIND" which are also not dumped.

File: FIND, Node: Examples, Up: Details

	Some examples of use of FIND:

:FIND SYS;			like :LISTF SYS; to DDT

:FIND SYS;SYS1;			two :LISTFs in a row

:FIND *:PDL;			list all the files on PDL's disk and in
				his archives.

:FIND $AR9:			list everyone's AR9, don't set print
				default.

:FIND AR9			give the names of all the AR9s in the
				world (note absence of :).

:FIND AR*:MAZE			find all the MAZEs in archives.

:FIND *MUD**;FOO,BAR		find all the FOOs and BARs on 0MUD51,
				1MUD51 and so on.

:FIND TPL:_PDL;TS *		find all TS files on PDL;, printing
				list on TPL:.

:FIND /TO SYS;TS NNDDT		find all files which are links to
				SYS;TS NNDDT.

:FIND PDL; &SIZE > 10		find all files more than 10 blocks long.

:FIND PDL; &BEFORE 760000	find files before 1976.

:FIND PDL; &REF BETWEEN 760120 760000
				find files referenced between Dec.
				31 and Jan 20.

:FIND PDL; /CDATE BETWEEN 5/4 5/5 10:30
				find files created on May 4 or on
				May 5 before 10:30 am.

	Examples with more than one switch:

	Using the AND form to restrict the search:

:FIND TS DDT &LINK		will find only links called TS DDT.

whereas

:FIND TS DDT /LINK		will find all links and all TS DDTs.

and finally

:FIND TS DDT &NOT LINK		will find all non-link TS DDTs.

	Note that

:FIND TS DDT /NOT LINK

will find all TS DDTs AND(!) all non-links.  Moral:  Be careful with
your /'s and &'s.

File: FIND, Node: Input, Up: Details, Previous: Output

	If you terminate a command line with +, you will be asked to
give more commands.  Ditto if you give an empty JCL line.

	To quote special characters (like _ ; :), put a ^Q in front of
them. This will turn them into normal symbol constituents.

	Typing ^S or ^G at any time during the running of FIND will
cause it to kill itself.

File: FIND, Node: Search, Up: Details

	When you give a command to FIND, you are really delimiting FOUR
separate searches:

0) A list of ITS's to get M.F.D.s from.
1) A list of directories to search.
2) A list of devices to search.
3) A list of tests to apply to each file in each directory searched.

	Zeroth, the ITS whose M.F.D to read is selected.  The local
ITS (DSK:) is always done first if it is one of the ITS's asked for.

	First, the MFD is read in and the list of directories matching
the directory specifications given is kept.  All other directories are
ignored.  This number of directories may be as few as one or as many as
the whole MFD.

	Secondly, the directories of the devices in the second list are
read in one by one.  The default in this case is the DSK: device, but of
course may include ARC devices as well.

	Thirdly, the tests specified are applied to each file in each
directory.  The files which match any search spec have their directory
lines printed out.  Once a file matches a search spec it is no longer
tested with subsequent specs.

	Note that currently (forever, perhaps) the file search specifications
given are done in all directories.  There is no way to do a given search
in only a few of the specified directories.  This may change someday.