TECH file for DIRBYDATE - Chris Chiesa - Rochester, NY - 15-Jun-1991
--------------------------------------------------------------------

               - UPDATED 3-OCT-1991 -
	       
   This is the TECH file for the October 1991 Usenet distribution of
DIRBYDATE.MAR v01.2 source code.  See the accompanying .README
file for general information.  Except for this paragraph, this file
is identical to the DIRBYDATE.TECH file which appeared in the June
1991 Usenet distribution of DIRBYDATE.

   DIRBYDATE calls RMS $PARSE to build a directory search context
based on an optional user-provided, and a built-in default, search 
specification, then repeatedly calls RMS $SEARCH to retrieve file
specifications (one per $SEARCH call) which match the search
context.  This is the portion of the program which fulfills the
original June 1991 Usenet question-poster's request for "code
which demonstrates reading a directory!"  The remainder of the
program (and this file) deals with sorting and displaying the
filenames thus retrieved.

   For each file retrieved by $SEARCH, DIRBYDATE calls RMS $OPEN
to fill a XABDAT with the file's Creation, Modification, Backup,
and Expiration dates.  Note that the $OPEN fails on any file
which is ALREADY open, causing DIRBYDATE to abort without
displaying ANY files.  (I believe, but have not yet proven, that
this problem can be overcome by using the QIO-ACP interface to
obtain file dates without recourse to RMS.  This appears to be
what VMS DIRECTORY does.)

   After obtaining a file specification and Creation Date,
DIRBYDATE invokes LIB$INSERT_TREE to build a binary tree which
can then be traversed by LIB$TRAVERSE_TREE.  Both of these 
LIB$...TREE routines require caller-specified procedures to
handle the tasks of allocating memory for "nodes" of the tree,
and to make the low-level comparison between nodes which,
recursively applied, determines the structure of the tree. 
DIRBYDATE's particular node-allocation routine consists of
copying the "current file's" NAME, TYPE, and VERSION, and its VMS
Creation-date-time quadword, into a piece of VM allocated to hold
that information in addition to pointers used by LIB$...TREE. 
To change the particular date-field by which files are sorted,
change the particular date field referenced by this portion of
the program.

   The "comparison" routine provided by DIRBYDATE to LIB$INSERT_TREE 
simply compares the date-time quadwords stored in two tree-nodes; to 
reverse the order in which DIRBYDATE lists files, simply reverse the 
sense of this comparison (see the comments in the source code).

   Finally, the "action routine" provided by DIRBYDATE to
LIB$TRAVERSE_TREE performs $FAO formatting and LIB$PUT_OUTPUT
display to SYS$OUTPUT, of the date-time and filename stored in
a tree-node; LIB$TRAVERSE_TREE takes care of providing these 
in the order established by LIB$INSERT_TREE (i.e., by the
"comparison" routine discussed in the previous paragraph).
If you wish to change the format of DIRBYDATE's output, change
the format string used by $FAO.

   For invocation of DIRBYDATE I provide a DIRBYDATE.CLD file
which defines a "standalone" verb -- what else? -- "DIRBYDATE." 
If you use this .CLD file, you'll find that "DIR" is now an
ambiguous verb, and that you have to type "DIRE" to use VMS
"DIRECTORY," or "DIRB" to use DIRBYDATE.  (This gets to be a habit
very quickly, trust me!)  Other styles of invocation are
possible:

   - use Joe Meadows' VERB utility (thank you, Joe!  There's a
     place in VMS Heaven for you) to extract the .CLD definition
     of the standard DIRECTORY command.  Add a /BY_DATE qualifier
     with SYNTAX=DIRBYDATE, and a DEFINE SYNTAX DIRBYDATE that 
     looks exactly like the DIRBYDATE.CLD file I provided with 
     this distribution.

   - if you (or I) later give DIRBYDATE the ability to sort by
     other dates, or in other sequences, something like

        DIR/BY_DATE=(NEWEST_FIRST,MODIFICATION)
                         or            or
                     OLDEST_FIRST    BACKUP 
                                       or
                                   EXPIRATION
                                       or
                                    CREATION 

     might work well.