PDP-10.its/doc/_info_/dir.order

The DIR device

A new device has been defined (it will work only on ITS with version
number greater than 886).  This device allows users and programs to
see sorted directories or subsets of directories.  The DIR device
supports both image and ascii mode directories which means that it can
be PRINTed or used in programs like DIRED and FIND.

The DIR device requires a file name much like a disk path name.
It takes a device name (DIR), a user's directory name, and two file
names.  The directory name identifies the disk directory to be sorted
or subsetted, while the two file names indicate what to do with the
directory.  The device name may also be DIRxxx, which will cause
device xxx:  to be used instead of DSK.  For example, DIRML:  will go
over the net to the ML machine, and DIRAR3:  will look at the
specified user's AR3 archive.

There are currently two types of operations - sorting and subsetting.

If you wish to sort, the first file name you supply will identify the
sort key and the second file name will determine whether an ascending
or descending sort is used (DOWN => descending, UP implies ascending).
The following table gives the currently recognized first file names
for sorting:

	file name	=>	sort key

	NAME1			sort on first file name
	NAME2			sort on second file name
	LENGTH or SIZE		sort on file length 
				 (links have len = 0)
	CDATE			sort on creation date
	RDATE			sort on reference date

Note that numeric names are sorted specially:  The numeric names come
before any non-numeric names, and the numeric names are ordered by
number, not by name (so for example, 10 comes after 9, instead of
before it.)

For subsetting, the directory subset will be sorted like NAME1 UP.

If the first file name you supply is NOT or ONLY, it indicates whether
only those things with the named attribute (if ONLY) or only those
things without the named attribute (if NOT) are retained.  The second
file name indicates the attribute upon which the decision should be
made:

    file name	   ==>	attribute

    LINKS or LINK	whether file is a link
    DUMPED		whether file is backed up
    PACKnm		whether file is on disk pack nm

If the first file name is one of: CDATE> CDATE= CDATE< RDATE> RDATE= RDATE< 
then the second file name must be a date in YYMMDD format.

The directory subset returned consists of only those files which pass
the test, such as:
    all files created since new years: 	CDATE> 750000
    all file created on last July 4:	CDATE= 740704
and similarly for reference date.  Note that you can use 00's even
though those are normally not legal dates.  Additionally, these work
on links just like CDATE UP and CDATE DOWN, even though you usually
don't see creation dates for them.

If the first file name is FIRST, FIRST#, or SECOND, the second file
name specifies a pattern in DIRED-style "* format".  Examples:
    all files named NBIN:			SECOND NBIN 
    all files with 1st name starting with BAR:	FIRST  BAR***

FIRST# is like FIRST, except that it will only consider files with a
numeric fn2.  Thus FIRST# ****** will give you all the files with
purely numeric second names (and any first name).  Also, FIRST# cause
the numeric fn2's to be right-justified in the listing.

If the file names given are not one of the valid forms listed above,
you will get a "mode not available" error.  If the file names are
valid but the directory can not be opened, you will get whatever that
open error is.  For example:	DIR:BLECH;NAME1 UP will cause a
"non-existent user name" error.

Examples:

    DIR:.INFO.;CDATE DOWN
	will give a directory of all the .INFO. files with the
	most recently created ones listed first.


    DIR:SYS;ONLY LINKS
	will give a directory with those files in SYS 
	that are links


The DIR device handler can also be used to intercept DSK (or AI, DM,
ARC, etc.) device requests by means of translation entries.  Saying
the following to DDT (eg. in your .DDT. (INIT) file)
	 *: *; .FILE. *, JOB:DEVICE;JOBDEV DIR
	 *: *; ****** *, JOB:DEVICE;JOBDEV DIR
	 *: *; * ******, JOB:DEVICE;JOBDEV DIR
	 *: *; * ######, JOB:DEVICE;JOBDEV DIR
will allow you to use the following features of the DIR handler:

    .FILE. (DIR)	acts like  DIR: NAME1 UP, 
which will give you a DIR-style directory listing 
(with tenths-of-blocks and reference dates) instead of the normal
system listing.  (Note that .FILE. (DIR) is what TECO reads to do the
EY command, so EY will give you the new format.

    .FILE. +<foo>	acts like  DIR: ONLY <foo>
    .FILE. -<foo>	acts like  DIR: NOT  <foo>
    .FILE. /<foo>	acts like  DIR: <foo> UP
    .FILE. \<foo>	acts like  DIR: <foo> DOWN
    ****** <name>	acts like  DIR: SECOND <name>
    <name> ******	acts like  DIR: FIRST  <name>
    <name> ######	acts like  DIR: FIRST# <name>

Note the fact that all .FILE. (DIR) requests must go through the DIR
handler will significantly slow down the FIND program.  Thus the
translation entry should be removed (via  .FILE.) before running FIND.


Using the DIR device:

There are basically four ways to use the DIR right now:

(1)  Print it using DDT, etc.  
     For example, try typing :PRINT DIR:SYS;ONLY LINKS to DDT.
     This will get you a ":LISTF" of the links in the SYS directory.

(2)  Use it in TECO macros for getting at various directory subsets.
     For example, DIR: FIRST <whatever> or <whatever> ****** (with the
     appropriate DDT translation entry) can be used in the M..G
     directory display macro to only display the appropriate files.
     Also, DIR:  FIRST# <whatever> (or DSK: <whatever> ######) can be
     used in the "erase all but the last few numerically-named copies
     of <whatever>" macro.  Doing these kinds of subsetting via the DIR
     device is usually faster than reading in the whole directory
     (which the system must convert to acsii) and then subsetting it
     using TECO commands.  The file AI:GROSS;^TECO^ > contains some
     examples (see the macros .F, F, Z, and D)

(3)  Use it in DIRED.  NDIRED now knows about the DIR device.
     For example, try typing    ACT DIR:SYS;ONLY LINKS to NDIRED.
     This will activate a directory consisting of only the links in the
     SYS directory.  NDIRED will do all copies, deletes, etc. via the
     DSK for efficiency.

(4)  Use it with DFIND.  This is a special version of FIND for use with the
     DIR device.  You may NOT do file name pattern matching since the file
     names you specify will be interpreted as names for the DIR device.
     You can, however, use it for other purposes.  For example try typing
     the following to DDT: :DFIND ONLY PACK20 
     This will cause every directory on the system to be searched for
     files that are on pack 20.

Report problems to BUG-ITS@MIT-MC.
Reasonable suggestions for modifications will be considered.
(Formerly maintained by GROSS@AI or PDL@DM.)