From:	CRDGW2::CRDGW2::MRGATE::"SMTP::CRVAX.SRI.COM::RELAY-INFO-VAX" 15-JUN-1991 16:16:31.18
To:	ARISIA::EVERHART
CC:	
Subj:	Re: File information from VMS - DIRBYDATE Pt 2 of 2

From:	RELAY-INFO-VAX@CRVAX.SRI.COM@SMTP@CRDGW2
To:	Everhart@Arisia@MRGATE

Received:  by crdgw1.ge.com (5.57/GE 1.100)
	 id AA26260; Sat, 15 Jun 91 15:10:56 EDT
Received: From ucbvax.Berkeley.EDU ([128.32.133.1]) by CRVAX.SRI.COM with TCP; Sat, 15 JUN 91 11:58:21 PDT
Received: by ucbvax.Berkeley.EDU (5.63/1.42)
	id AA04227; Sat, 15 Jun 91 11:47:25 -0700
Received: from USENET by ucbvax.Berkeley.EDU with netnews
	for info-vax@kl.sri.com (info-vax@kl.sri.com)
	(contact usenet@ucbvax.Berkeley.EDU if you have questions)
Date: 15 Jun 91 17:41:54 GMT
From: portal!cup.portal.com!Chris_F_Chiesa@apple.com
Organization: The Portal System (TM)
Subject: Re: File information from VMS - DIRBYDATE Pt 2 of 2
Message-Id: <43352@cup.portal.com>
References: <1991Jun8.232439.5833@ringer.cs.utsa.edu>
Sender: info-vax-request@kl.sri.com
To: info-vax@kl.sri.com

Here's part 2.
-+-+-+-+-+-+-+-+ START OF PART 2 -+-+-+-+-+-+-+-+
X;`009required extra space for LIB$INSERT_TREE internal structure.
X;`009Copy file's creation date and its name, into the newly allocated
X;`009memory, which will become a "node" of the binary tree built by
X;`009LIB$INSERT_TREE.
X;
X;      4(AP) = sym-str          -- pointer to date_time quadword (ignored)
X;      8(AP) = newnode          -- pointer (returned) to node created herein
X;
X
X`009`009`009.entry`009allocate_routine,`094m<r6,r7>
X;
X`009`009`009movaq`009found_spec,r7`009`009; R7 => filespec
X`009`009`009`009`009`009`009; descriptor addr
X`009`009`009addl3`009#19,(r7),node_size`009; We need room for
X`009`009`009`009`009`009`009; the filespec, a
X`009`009`009`009`009`009`009; date-time, and`032
X`009`009`009`009`009`009`009; tree link pointers.
X`009`009`009pushal`009temp_node
X`009`009`009pushal`009node_size
X`009`009`009calls`009#2,g`094lib$get_vm`009`009; Get memory.
X`009`009`009blbc`009r0,alloc_err
X;
X`009`009`009movl`009temp_node,r6`009`009; R6 => base of`032
X`009`009`009`009`009`009`009;  new node-to-be
X`009`009`009movl`009r6,@8(ap)`009`009; Return node-address
X`009`009`009`009`009`009`009; to LIB$INSERT_TREE
X`009`009`009addl2`009#10,r6`009`009`009; R6 => base of user
X`009`009`009`009`009`009`009; accessible part of
X`009`009`009`009`009`009`009; node
X;+
X; Insert file Creation Date quadword, and filename-as-an-ASCII-counted-
X; string, into the new node.
X;-
X`009`009`009movq`009date_block+xab$q_cdt,(r6)
X`009`009`009movb`009(r7),8(r6)
X`009`009`009movc3`009(r7),@4(r7),9(r6)
X;+
X; Return success status, always, if we got through all of this.
X;-
X`009`009`009movl`009#SS$_NORMAL,r0
X
Xalloc_err:`009`009ret
X;===========================================================================
V===
X; "Action_routine" - called for every node in the tree, by LIB$TRAVERS_TREE.
X;  Displays the date and filename contained in a node.
X;
X;      4(AP) -- pointer to node data
X
X`009`009`009.entry`009action_routine,`094m<r6,r7,r8>
X
X`009`009`009moval`009@4(ap),r6`009; R6 => base of node memory
X`009`009`009addl2`009#10,r6`009`009; R6 => user-data part of`032
X`009`009`009`009`009`009;       node`032
X`009`009`009movl`009#132,report`009; Initialize $FAO output
X`009`009`009`009`009`009; string
X;+
X; I find that the $FAO_S macro doesn't always do what I want with my $FAO
X; arguments, so I often call $FAO explicitly, as done here.
X;-
X`009`009`009pushal`0098(r6)`009`009; Counted-ASCII filespec str
X`009`009`009pushal`009(r6)`009`009; Creation-date quadword
X`009`009`009pushaq`009report`009`009; Output string by descr.
X`009`009`009pushal`009report`009`009; Output length return word
X`009`009`009pushaq`009report_format`009; $FAO formatting string
X`009`009`009calls`009#5,SYS$FAO`009; Format it!
X`009`009`009blbs`009r0,10$
X`009`009`009jmp`009show_err
X
X10$:
X`009`009`009pushaq`009report`009`009`009; Send formatted`032
X`009`009`009calls`009#1,g`094lib$put_output`009; info to SYS$OUTPUT
Xshow_err:`009`009ret
X
X`009`009`009.end`009dir_by_date
$ CALL UNPACK DIRBYDATE.MAR;3 755450983
$ create/nolog 'f'
XREADME file for DIRBYDATE - Chris Chiesa - Rochester, NY - 15-Jun-1991
X----------------------------------------------------------------------
X
X   This is the README file for the June 1991 Usenet distribution of
XDIRBYDATE.MAR v01.1 source code.  I am posting this code in response to
Xa previous posting which asked for an example of "reading a directory`032
Xfrom within a program."  Approximately one-third to one-half of the`032
XDIRBYDATE code deals with this issue; the remaining one-half to two-
Xthirds deals with sorting the resulting list of filenames and can either
Xbe IGNORED or taken as an example of using LIB$INSERT_TREE and
XLIB$TRAVERSE_TREE.
X
X...
X
X   As you know, the VMS "DIRECTORY" command accepts numerous qualifiers`032
Xfor selecting files (/BEFORE, /SINCE, /BY_OWNER, /EXCLUDE, etc.), selecting`
V032
Xinformation to be displayed (/PROT, /ACL, /SECURITY, /FULL, etc.), and`032
Xcontrolling the format of output (/WIDTH, /COLUMN, etc.).  DIRECTORY does
XNOT, however, provide any options for controlling the ORDER or SEQUENCE
Xin which files are listed: DIRECTORY always lists files in alphabetical
Xorder by NAME.EXT.
X
X   DIRECTORY is useful for 99% of the occasions for which one might want
Xto display files.  But I frequently find that I want/need to know which`032
Xfiles in a directory were created most recently, least recently, or in`032
Xwhat order among themselves.  Using DIRECTORY would involve, at best, a
Xtedious manual "binary search" with /BEFORE and /SINCE; hence I created
XDIRBYDATE.
X
X   As its name suggests, DIRBYDATE reads directory information and lists
Xfiles "in order by date."  This version of DIRBYDATE is extremely simple and
Xprovides NO bells-and-whistles: files are listed in newest-first order
Xby Creation date, PERIOD.  Sorting in oldest-first order, sorting by other-
Xthan-CREATION date, or any sub- or super-set of the qualifiers available`032
Xwith DIRECTORY, are NOT supported.  (Reversal-of-order, and sorting-by-other
V-
Xthan-Creation-date, would be trivial to add; see the comments in the source
Xcode.)
X
X   DIRBYDATE also has one known bug, a consequence of the naive technique I
Xused to obtain file DATE information.  I obtain the dates in an RMS XAB as a
Xresult of a RMS $OPEN; this $OPEN fails if a file is already open, causing`0
V32
XDIRBYDATE to abort with an error and without displaying any files.  I believ
Ve
Xthis can be fixed by changing the program to use the QIO-ACP interface to`03
V2
Xperform an IO$_ACCESS of each file, bypassing RMS (this is what DIRECTORY`03
V2
Xdoes), but have not gotten around to doing this yet.`032
X
X   DIRBYDATE _does_ accept a single, optional command-line argument, a
Xsearch specification, just like DIRECTORY.  Wildcard specifications ARE`032
Xsupported.
X
X   To build DIRBYDATE, after extracting this archive, issue the following
Xtwo commands:
X
X`009MACRO DIRBYDATE
X`009LINK DIRBYDATE
X
XThis will yield the file DIRBYDATE.EXE.
X
X   DIRBYDATE is designed to be invoked by a DCL "native command
Xverb," as defined by the VMS Command Definition Utility.  To make
Xa long story short, extract the DIRBYDATE.CLD file from this
Xdistribution (you've done that already if you're reading this),
Xedit the line that contains "UTILDIR" (or define a logical name
XUTILDIR to point to the directory containing DIRBYDATE.EXE)
Xand issue the DCL command SET COMMAND DIRBYDATE.  You now have
Xthe DIRBYDATE command verb!  (Note that you must now distinguish
Xbetween "DIRE" (VMS "DIRECTORY") and "DIRB" (DIRBYDATE) when
Xabbreviating your commands!  "DIR" will produce an "ambiguous
Xcommand verb" error.
X
X   Most comments in the source code were added recently, specifically for
Xthe purposes of this (June 1991 Usenet) distribution, and may or may not
Xentirely accurately reflect the thoughts in my mind at the time I created
Xthe program.  I.e., I may have forgotten the precise reasoning behind doing
Xcertain things certain ways.  Use at your own risk; it DOES WORK, though.
XSee the accompanying .TECH text file for internals information.
X
X   If anyone receiving this code does bother to add features/functionality,
Xplease leave my name in there somewhere, and send me a copy of your update!
X
X   Chris Chiesa
X     Software Engineer
X     Light Valve Technology, A Kodak Company
X     100 Kings Highway, Suite 1400
X     Rochester, NY  14609
X        (716) 724-2029
X
X   Posting from The Portal System on my own time, at my own expense, and
X   without association with, knowledge of, or permission of my employers.
X
X   Chris_F_Chiesa@cup.portal.com
$ CALL UNPACK DIRBYDATE.README;4 1177652130
$ create/nolog 'f'
XTECH file for DIRBYDATE - Chris Chiesa - Rochester, NY - 15-Jun-1991
X--------------------------------------------------------------------
X
X   This is the TECH file for the June 1991 Usenet distribution of
XDIRBYDATE.MAR v01.1 source code.  See the accompanying .README
Xfile for general information.
X
X   DIRBYDATE calls RMS $PARSE to build a directory search context
Xbased on an optional user-provided, and a built-in default, search`032
Xspecification, then repeatedly calls RMS $SEARCH to retrieve file
Xspecifications (one per $SEARCH call) which match the search
Xcontext.  This is the portion of the program which fulfills the
Xoriginal June 1991 Usenet question-poster's request for "code
Xwhich demonstrates reading a directory!"  The remainder of the
Xprogram (and this file) deals with sorting and displaying the
Xfilenames thus retrieved.
X
X   For each file retrieved by $SEARCH, DIRBYDATE calls RMS $OPEN
Xto fill a XABDAT with the file's Creation, Modification, Backup,
Xand Expiration dates.  Note that the $OPEN fails on any file
Xwhich is ALREADY open, causing DIRBYDATE to abort without
Xdisplaying ANY files.  (I believe, but have not yet proven, that
Xthis problem can be overcome by using the QIO-ACP interface to
Xobtain file dates without recourse to RMS.  This appears to be
Xwhat VMS DIRECTORY does.)
X
X   After obtaining a file specification and Creation Date,
XDIRBYDATE invokes LIB$INSERT_TREE to build a binary tree which
Xcan then be traversed by LIB$TRAVERSE_TREE.  Both of these`032
XLIB$...TREE routines require caller-specified procedures to
Xhandle the tasks of allocating memory for "nodes" of the tree,
Xand to make the low-level comparison between nodes which,
Xrecursively applied, determines the structure of the tree.`032
XDIRBYDATE's particular node-allocation routine consists of
Xcopying the "current file's" NAME, TYPE, and VERSION, and its VMS
XCreation-date-time quadword, into a piece of VM allocated to hold
Xthat information in addition to pointers used by LIB$...TREE.`032
XTo change the particular date-field by which files are sorted,
Xchange the particular date field referenced by this portion of
Xthe program.
X
X   The "comparison" routine provided by DIRBYDATE to LIB$INSERT_TREE`032
Xsimply compares the date-time quadwords stored in two tree-nodes; to`032
Xreverse the order in which DIRBYDATE lists files, simply reverse the`032
Xsense of this comparison (see the comments in the source code).
X
X   Finally, the "action routine" provided by DIRBYDATE to
XLIB$TRAVERSE_TREE performs $FAO formatting and LIB$PUT_OUTPUT
Xdisplay to SYS$OUTPUT, of the date-time and filename stored in
Xa tree-node; LIB$TRAVERSE_TREE takes care of providing these`032
Xin the order established by LIB$INSERT_TREE (i.e., by the
X"comparison" routine discussed in the previous paragraph).
XIf you wish to change the format of DIRBYDATE's output, change
Xthe format string used by $FAO.
X
X   For invocation of DIRBYDATE I provide a DIRBYDATE.CLD file
Xwhich defines a "standalone" verb -- what else? -- "DIRBYDATE."`032
XIf you use this .CLD file, you'll find that "DIR" is now an
Xambiguous verb, and that you have to type "DIRE" to use VMS
X"DIRECTORY," or "DIRB" to use DIRBYDATE.  (This gets to be a habit
Xvery quickly, trust me!)  Other styles of invocation are
Xpossible:
X
X   - use Joe Meadows' VERB utility (thank you, Joe!  There's a
X     place in VMS Heaven for you) to extract the .CLD definition
X     of the standard DIRECTORY command.  Add a /BY_DATE qualifier
X     with SYNTAX=DIRBYDATE, and a DEFINE SYNTAX DIRBYDATE that`032
X     looks exactly like the DIRBYDATE.CLD file I provided with`032
X     this distribution.
X
X   - if you (or I) later give DIRBYDATE the ability to sort by
X     other dates, or in other sequences, something like
X
X        DIR/BY_DATE=(NEWEST_FIRST,MODIFICATION)
X                         or            or
X                     OLDEST_FIRST    BACKUP`032
X                                       or
X                                   EXPIRATION
X                                       or
X                                    CREATION`032
X
X     might work well.
X
X
$ CALL UNPACK DIRBYDATE.TECH;1 72361130
$ v=f$verify(v)
$ EXIT

