.! Last modified Sep. 11th, 1987 (minor changes)
.lm 0
.rm 70
1 FIND
.lm 1
  FIND [device-name]
.blank
    FIND is a utility to allow you to display information about
a file, based on information stored in the files header. FIND
operates in one of two modes, it either displays information
read directly out of the index file, or it asks the disk ACP
to return header information to it. The first mode of operation
is used for general searches, and does not necessarily return
the most current up to date information, as there may be many
headers cached in memory, and thus out of synch with the index file.
The second mode of operation is used when you specify a /FILE__ID
or /FULLNAME qualifier, giving it an explicit list of files to
work with. In this case it asks the disk ACP for the headers, thus
getting the most current, up to date information available, if
possible. Note that in either case, the index file is opened for
read acces, thus to use this utility, you must have read access to
the file [000000]INDEXF.SYS, and if using /FILE__ID or /FULLNAME
you must also have read access to the requested files.
.blank
    FIND takes one paramater, the name of the device whose index
file is to be searched. If device-name is not specified it defaults
to SYS$DISK (your current default disk). It correctly handles
rooted device names, and can handle multi-volume disk sets.
.blank
    You may limit what files will be displayed by using the appropriate
qualifiers. Most of the qualifiers that affect what files will be
displayed allow a minimum and maximum value, if you do not specify
a maximum value, then it is assumed you want all things greater than
the minimum. If you want a specific value, than you must enter it as
both the minimum and maximum value, i.e.
.i+5;$ FIND/ALLOCATED=(1497,1497)
.break
would display all files with exactly 1497 blocks allocated.
.lm 0
2 Examples
.lm 1
  The following examples are meant to demonstrate some of the uses
of FIND.
.lm 0
3 ACL
.lm 1
  Suppose you are going delete a user, and you want to be sure that
no one has a file that specifically refers to that user, you could
specify:
.i+5;$ FIND/DISPLAY=ACL/ACE=([USER1],[USER2],PROJECT$P001)
.break
This would display all files (and their access control lists) which
had any ACLs that refered to the uic identifiers [USER1], [USER2],
or the 'project' identifier PROJECT$P001
.lm 0
3 Activity
.lm 1
  Suppose you wanted to get an idea of disk usage, you could generate
a report showing all the files created in a specified time period:
.i+5;$ FIND/DISPLAY=(CREATION,ALLOCATED,USED)-
.i+5;$__ /CREATION=(YESTERDAY,TODAY)
.break
would display all files created today
.blank
or all the files modified in a specifid time period:
.i+5;$ FIND/DISPLAY=(CREATION,REVISION,ALLOCATED,USED)-
.i+5;$__ /REVISION=(YESTERDAY,TODAY)
.break
would display all files revised today
.lm 0
3 Big__Directories
.lm 1
  Suppose you want to find all the directory files that are bigger
than 50 blocks, you could use:
.i+5;$ FIND/DISPLAY=(USED,ALLOCATED) -
.i+5;$__ /CHARACTERISTICS=DIRECTORY/ALLOCATED=50/MATCH=AND
.break
Notice the use of the /MATCH qualifier. Normally this defaults
to OR, so that if any one of the conditions are met then the file
will be displayed.
.lm 0
3 FID
.lm 1
  If you know a file id, you can display the info on that file via:
.i+5;$ FIND/DISPLAY=ALL/FILE__ID=(1,4)
.break
This would display INDEXF.SYS [fid = (1,1,0)] and
000000.DIR (4,4,0). Note that only the first number of the
File ID should be specified.
.lm 0
3 Fragmentation
.lm 1
  Suppose you want to know how badly fragmented the system is:
.i+5;$ FIND/DISPLAY=(EXTENTS,HEADERS)/HEADERS=1
.break
would display all the files with more than one extention header,
of course, you needn't wait till your system gets that fragmented,
you may have a different idea of what is too fragmented:
.i+5;$ FIND/DISPLAY=(EXTENTS,HEADERS)/EXTENTS=20
.break
would display all the files broken into 20 or more peices.
.lm 0
3 LBN
.lm 1
  Suppose you have a block go bad, you know the LBN, and you want to
know the file which contains it:
.i+5;$ FIND/LBN=19500
.break
would display the file containing that LBN.
.blank
  Another way (is this cheating?) would be to search for any
file marked corrupt:
.i+5;$ FIND/CHARACTERISTICS=FILE__CORRUPT
.break
.blank
  Perhaps you want to see what LBNs are in a specific file,
.i+5;$ FIND/DISPLAY=LBN/FULLNAME=EXAMPLE.TXT
.break
.lm 0
3 WASTE
.lm 1
  If you want to know how many blocks are being wasted (the difference
between used and allocated), you could display it via
.i+5;$ FIND/DISPLAY=WASTED/FULLNAME=EXAMPLE.TXT
.break
Or find all files wasting space...
.i+5;$ FIND/DISPLAY=WASTED/WASTED=100
.lm 0
2 Input__Qualifiers
.lm 1
  Besides searching through the index file directly, you can select what
files will be used (and still subject to the "selection qualifiers"),
via /FILE__ID and /FULLNAME .
.blank
  You may search through all the index files in a multiple volume
set by specifying /VOLUME. This is especially usefull in doing
searches based on LBN, ACE, and ACL, as one or more of a files
extension headers may reside on a separate disk, and extension
headers which are on their own would otherwise be ignored.
.lm 0
/FILE__ID
.lm 1
.i+5;/FILE__ID=(list-of-file-id's)
.blank
  This allows you to display selected files without the overhead
of searching through the entire index file. This limits the
search to only the selected files, as indicated by their file-id.
This searches through the index file to complete the file-id,
then if the file-id is valid, it asks the disk acp for the header
to this file, forcing the information to be as accurate as possible.
If the file id is no longer valid, it will display the file header
as stored in the index file, with an asterisk in front of the
file id (if it is being displayed). Note that if the file id is
valid that you will need read access to the file requested, as
well as read access to the index file.
.lm 0
/FULLNAME
.lm 1
.i+5;/FULLNAME=(list-of-full-file-specs)
.blank
  This allows you to display selected files without the overhead
of searching through the entire index file. This limits the
search to only the selected files.
.blank
  This requires read access to the requested files, but does not
access the index file.
.lm 0
/VOLUME
.lm 1
.i+5;/VOLUME
.blank
  This forces FIND to search through all the index files in a
multi-volume disk set. This is especially usefull in doing searches
based on LBN, ACE, and ACL, as one or more of a files extension
headers may reside on a separate disk, and extension headers which
are on their own would otherwise be ignored.
.blank
  For example, suppose that DUA1 and DUA2 are set up as a multiple
volume set called MULTI$DISK. If the file TEST.DAT were created
on DUA1, but half of TEST.DAT was placed on DUA2, from logical
block number 100 through 500, then the command:
.i+5;FIND/LBN=250/DISPLAY=LBN DUA2:
.break
would not return any info on TEST.DAT, since the first file segment
was located on DUA1. However, the command:
.i+5;FIND/LBN=250/DISPLAY=LBN/VOLUME MULTI$DISK  ! (or "DUA1", or "DUA2")
.break
would report that DUA1:TEST.DAT contained the LBN 250.
It may also report some other files as containing LBN 250, since
each disk is being searched, hence you would want to display
the LBN information, to be able to determine which file was the
one you were really concerned about.
.lm 0
2 Output__qualifiers
.lm 1
  You may redirect output to a file, via /OUTPUT, and you may choose
what is to be displayed via /DISPLAY.  By default the full file name
is always displayed. The only way to disable this (should you so desire)
is to select NOFULLNAME as a display option.
.lm 0
/OUTPUT
.lm 1
.i+5;/OUTPUT[=filename]
.blank
  Controls where output will go to. If qualifier isn't present
then all output will be to screen.
.blank
    If qualifier is present but a filename is not specified, it will
default to INDEXF.LIS.
.lm 0
/DISPLAY
.lm 1
.i+5;/DISPLAY=(list-of-display-keywords)
.blank
  Controls what will be displayed from the file header.
.blank
  All off the DISPLAY keywords are negatable, so that you could say:
/DISPLAY=(ALL, NOLBN) to get a listing including all the header
information except for the list of logical block numbers. By default
FULLNAME is always displayed. If you really don't want to see it
you must specify NOFULLNAME.

.! I'm cheating here, I'll fix this sometime.. really....
.literal
   ALL
     Display everything about the file (except negated items)
   ACL
   ACCESS_MODE
   ACTIVE_RECOVERY_UNITS
   ALLOCATED
   ATTRIBUTES
   BACKUP_DATE
   BUCKET_SIZE
   CHARACTERISTICS
   CREATION_DATE
   DEFAULT_EXTEND_QUANTITY
   DIRECTORY_FILE_ID
   EXPIRATION_DATE
   EXTENTS
   FILE_ID
   FULLNAME (The name as returned by the disk ACP, if possible, otherwise
             it will return the name in the file header preceded with [?],
             and on the next line it will display the name of the file that
             this files backlink points to, if possible)
   GLOBAL_BUFFER_COUNT
   HEADERS
   HIGHWATER_MARK
   JOURNAL
   LBN
   MAXIMUM_RECORD_SIZE
   NAME (this is the name as it exists in the file header, this name may
         be different than the name returned by FULLNAME due to multiple
         links to the same file, esp. when selecting based on /FULLNAME)
   NUMBER_OF_REVISIONS
   ORGANIZATION
   OWNER_UIC
   PROTECTION
   RECORD_SIZE
   REVISION_DATE
   TYPE
   USED (displays blocks used, and first free byte)
   VERSION_LIMIT
   VFC_SIZE
   WASTED_BLOCKS
.end literal
.lm 0
2 Selection__qualifiers
.lm 1
.lm 0
/MATCH
.lm 1
.i+5;/MATCH=(match-option)
.blank
  Match-option can be AND or OR, and signifies wether a file will be
displayed only if all criterion pass (AND) or if any one criteria
passes (OR). OR matching is used by default.
.blank
example:
.i+5;$ FIND/CHAR=DIR/OWNER=[USER]/MATCH=AND
.break
Display all directories owned by [USER].
.blank
.i+5;$ FIND/WASTED=50/ALLOC=100000/MATCH=OR
.break
Is equivalent to:
.i+5;$ FIND/WASTED=50/ALLOC=100000
.break
Which displays all files wasting 50 blocks or more, or which have
100,000 (or more) blocks allocated.
.lm 0
/ACE
.lm 1
.i+5;/ACE=(list-of-identifiers-or-uics)
.blank
  Allows you to select files which have an identifier ace containing
one (or more) of the specified ids.
.blank
example:
.i+5;$ FIND/DISPLAY=ACL/ACE=([PROJECTS,P001],[SYSTEM],BATCH)
.break
Would display all files that referenced any of those identifiers in their
ACL.
.lm 0
/ACL
.lm 1
.i+5;/ACL
.blank
  Allows you to display all files that have an ACL of any kind.
.lm 0
/ATTRIBUTES
.lm 1
.i+5;/ATTRIBUTES=(list-of-attributes-keywords)
.blank
   Allows you to specify what record attributes a file must have or
not have, to be displayed.
.blank
.literal
   FORTRANCC   Fortran carriage control
   IMPLIEDCC   Implied carriage control
   PRINTCC     Print carriage control
   SPAN        Records can span blocks
.end literal
example:
.i+5;$ FIND/DISP=ATTRIBUTES/ATTRIB=(FORTRAN,PRINT)
.break
Display all files that have either fortran or print carriage control.
.lm 0
/CHARACTERISTICS
.lm 1
.i+5;/CHARACTERISTICS=(list-of-characteristics-keywords)
.blank
   Allows you to specify what file characteristics a file must have
or not have, to be displayed.
.blank
.literal
   ACL_CORRUPT          File contains corrupt ACL
   BACKUP               File can be backed up
   BEST_TRY_CONTIGUOUS  Keep file as contiguous as possible
   CHARGE               File space is charged to owner
   CONTIGUOUS           File is contiguous
   DIRECTORY            File is a directory
   ERASE_ON_DELETE      File is to be erased when deleted
   FILE_CORRUPT         File contains suspected bad blocks
   LOCKED               File is deaccess locked
   MARKED_FOR_DELETE    File is marked for delete
   SPOOL                File is a spool file
   READ_VERIFY          Verify all read operations
   WRITE_BACK           File may be write-back cached
   WRITE_VERIFY         Verify all write operations
.end literal
example:
.i+5;$ FIND/DISP=(CHAR,FILE__ID)/CHAR=SPOOL
.break
Display all spool files..
.blank
.i+5;$ FIND/DISPL=CHAR/CHAR=(READ__VERIFY,WRITE__VERIFY, -
.i+5;$__ NOFILE__CORRUPT,NOACL__CORRUPT,NOMARKED__FOR__DELETE)
.break
This displays all file that are set to either read or write verify,
but aren't corrupt in any way, nor deleted.
.lm 0
/JOURNAL
.lm 1
.i+5;/JOURNAL=(list-of-journal-keywords)
.blank
   Allows you to specify what journal attributes a file must have or
not have, to be displayed.
.blank
.literal
   JOURNAL    This is a journal file
   AIJNL      Enable after image journal
   ATJNL      Enable audit trail journal
   BIJNL      Enable before image journal
   RUJNL      Enable recovery unit journal
   NEVER_RU   File is never accessible in recovery unit
   ONLY_RU    File is accessible only in recovery unit
.end literal
.lm 0
/ORGANIZATION
.lm 1
.i+5;/ORGANIZATION=(list-of-organization-keywords)
.blank
   Allows you to specify what file organization a file must have or
not have, to be displayed.
.blank
.literal
   SEQUENTIAL
   RELATIVE
   INDEXED
   DIRECT
.end literal
example:
.i+5;$ FIND/ORG=INDEX
.break
Display all indexed files.
.blank
.i+5;$ FIND/ORG=NOSEQUENTIAL
.break
Display all non-sequential files.
.blank
.i+5;$ FIND/ORG=(INDEX,RELATIVE)
.break
Display all files that are either indexed, or relative.
.lm 0
/TYPE
.lm 1
.i+5;/TYPE=(list-of-type-keywords)
.blank
   Allows you to specify what record type a file must have or
not have, to be displayed.
.blank
.literal
   UNDEFINED Record type is undefined
   FIXED     Records have a fixed length
   VARIABLE  Record have variable length - stored in the file
             as a 2 byte integer storing the record length, followed
             by the record, possibly null padded to make next record
             start on a word boundary.
   VFC       Variable with fixed control
   STREAM    Stream format (unix-ish, records? what records?)
   LFSTREAM  Stream format, records are separated by line feed
   CRSTREAM  Stream format, records are separated by carriage return
.end literal
example:
.i+5;FIND/DISPL=TYPE/TYPE=(STREAM,LFSTREAM,CRSTREAM)
.break
Display files having a stream format of some type.
Note that this is in effect an OR search, a file must have,
or not have, only one of the types specified.
.lm 0
/ACCESS__MODE
.lm 1
.i+5;/ACCESS__MODE=(list-off-access__mode-keywords)
.blank
   Allows you to specify what access mode a file must have or not have,
to be displayed. Note that I am not sure if VMS even uses this... As
a wild guess I would imagine that if it does use it, it would only be
for open files, and the header would be cached in memory, not in the
index file, so it probably could never be accessed except when an
ACP QIO function is performed to get the absolute most current/correct
header, as is done when /FILE__ID or /FULLNAME is specified.
.blank
.literal
   USER
   SUPERVISOR
   EXECUTIVE
   KERNEL
.end literal
.lm 0
/CREATION__DATE
.lm 1
.i+5;/CREATION__DATE=(min,max)
.blank
  Display files created between the 'min' and 'max' dates.
.blank
example:
.i+5;$ FIND/DISPL=CREAT/CREAT=(YESTERDAY,TODAY)
.break
Display all files created today.
.lm 0
/REVISION__DATE
.lm 1
.i+5;/REVISION__DATE=(min,max)
.blank
  Display files created between the 'min' and 'max' dates.
.blank
example:
.i+5;$ FIND/DISPL=(CREATION,REVISION)/REVISION=(YESTERDAY,TODAY)
.lm 0
/EXPIRATION__DATE
.lm 1
.i+5;/EXPIRATION__DATE=(min,max)
.blank
  Display files expiring between the 'min' and 'max' dates.
.blank
example:
.i+5;$ FIND/DISPL=(CREATION,EXPIRATION)/EXPIRATION=(YESTERDAY,TODAY)
.lm 0
/BACKUP__DATE
.lm 1
.i+5;/BACKUP__DATE=(min,max)
.blank
  Display files backed up between the 'min' and 'max' dates.
.blank
example:
.i+5;$ FIND/DISPL=(CREATION,BACKUP)/BACKUP=(YESTERDAY,TODAY)
.lm 0
/ACTIVE__RECOVERY__UNITS
.lm 1
.i+5;/ACTIVE__RECOVERY__UNITS=(min,max)
.blank
.literal
  1 = by RMS
  2 = by DBMS
  3 = by Rdb/VMS
  4 = by Checkpoint/Restart
  > 4 = by other recoverable facility
.end literal
.lm 0
/ALLOCATED
.lm 1
.i+5;/ALLOCATED=(min,max)
.lm 0
/BUCKET__SIZE
.lm 1
.i+5;/BUCKET__SIZE=(min,max)
.lm 0
/DEFAULT__EXTEND__QUANTITY
.lm 1
.i+5;/DEFAULT__EXTEND__QUANTITY=(min,max)
.lm 0
/DIRECTORY__FILE__ID
.lm 1
.i+5;/DIRECTORY__FILE__ID=(list-of-directory-file-id's)
.blank
  You can use this to find all files that are (should be?) in a specified
directory, so long as you know the file-id of the directory.
.lm 0
/EXTENTS
.lm 1
.i+5;/EXTENTS=(min,max)
.lm 0
/FIRST__FREE__BYTE
.lm 1
.i+5;/FIRST__FREE__BYTE=(min,max)
.lm 0
/GLOBAL__BUFFER__COUNT
.lm 1
.i+5;/GLOBAL__BUFFER__COUNT=(min,max)
.lm 0
/HEADERS
.lm 1
.i+5;/HEADERS=(min,max)
.lm 0
/HIGHWATER__MARK
.lm 1
.i+5;/HIGHWATER__MARK=(min,max)
.lm 0
/LBN
.lm 1
.i+5;/LBN=(list-of-LBNs)
.lm 0
/MAXIMUM__RECORD__SIZE
.lm 1
.i+5;/MAXIMUM__RECORD__SIZE=(min,max)
.blank
  Maximum allowable record length. 0 means there is no maximum.
.lm 0
/RECORD__SIZE
.lm 1
.i+5;/RECORD__SIZE=(min,max)
.blank
  Longest record length.
.lm 0
/NAME
.lm 1
.i+5;/NAME=filename
.blank
  This allows you to search based on the name stored in the header.
Note that this is slower than using /FULLNAME but is usefull if
you know the name of a file but not its location.
.lm 0
/NUMBER__OF__REVISIONS
.lm 1
.i+5;/NUMBER__OF__REVISIONS=(min,max)
.lm 0
/OWNER__UIC
.lm 1
.i+5;/OWNER__UIC=(list-of-UICs)
.blank
  This accepts any valid UIC. Valid UIC formats include
.literal
   [octal-number,octal-number]
   <octal-number,octal-number>
   [identifier,identifier]
   <identifier,identifier>
   [identifier]
   <identifier>
   %xHexadecimal-number
.end literal
.lm 0
/PROTECTION
.lm 1
.i+5;/PROTECTION=(SET=(protection),CLEAR=(protection))
.blank
  This allows you to search for all files that have specified protection
bits SET and or CLEAR, for example, to find all files that are world
writeable, but not world readable, you could specify :
.i+5;/PROTECTION=(SET=(WORLD=W), CLEAR=(WORLD=R))
.break
or just all files that are set to WORLD:RWED, use
.i+5;/PROTECTION=(SET=W:RWED)
.break
or all files that are set to owner not readable, use
.i+5;/PROTECTION=(CLEAR=O:R)
.break
.lm 0
/USED
.lm 1
.i+5;/USED=(min,max)
.lm 0
/VERSION__LIMIT
.lm 1
.i+5;/VERSION__LIMIT=(min,max)
.blank
  Note that this is the directory version limit, i.e. this is set by
the command SET DIRECTORY/VERSION=n
.lm 0
/VFC__SIZE
.lm 1
.i+5;/VFC__SIZE=(min,max)
.lm 0
/WASTED__BLOCKS
.lm 1
.i+5;/WASTED__BLOCKS=(min,max)
.lm 0
/PLACEMENT
.lm 1
.i+5;/PLACEMENT=(list-of-placement-keywords)
.blank
.literal
  EXACT                   Exact placement specified
  ON_CYLINDER             On cylinder allocation desired
  RELATIVE_VOLUME_NUMBER  Place on specified RVN
  LBN_SPECIFIED           Use LBN of next map pointer
.end literal