            DIRSORT V2.0-0, 2022-10-31
            ==========================

------------------------------------------------------------------------

      Description
      -----------

   DIRSORT is an alternative to the DCL DIRECTORY command.  It lists
only filename and date-time information for the specified
directory/files.  The output is sorted by date-time rather than
filename, and can be in either ascending (default) or descending order.

------------------------------------------------------------------------

      History
      -------

   DIRSORT was written by Lyle W. West.  Version V1.2-4 bears a
copyright date of 2004.

   This version includes (extensive) changes by Steven M. Schweda.

   For details on V1.x, see changes-1.txt (extracted from version.h of
V1.2-4).  For details on V2.x, see changes-2.txt.

------------------------------------------------------------------------

      Building DIRSORT
      ----------------

   The kit includes MMS/MMK builders and a DCL script.  Comments in the
main builder files (build_dirsort.com, descrip.mms) explain usage
details.  Typical build commands are shown below.

        $ @ BUILD_DIRSORT.COM

        $ MMS                           ! Or MMK.

   Product (object, link option, and executable) files should be created
in an architecture-specific subdirectory:

      [.ALPHA]          Alpha, no large-file support.
      [.ALPHAL]         Alpha, large-file support.
      [.IA64]           IA64, no large-file support.
     [.IA64L]          IA64, large-file support.
      [.VAX]            VAX, DEC C.
      [.VAXV]           VAX, VAX C.
      [.X86_64]         x86_64, no large-file support.
     [.X86_64L]        x86_64, large-file support.

(Large-file support shouldn't matter to DIRSORT operation, but these
builders were adapted from others where it did.  Should be harmless.)

------------------------------------------------------------------------

      Installation
      ------------

   To complete the installation, the executable may be left in place, or
moved (or copied) to a convenient place.  Although other methods (like
DCL$PATH) exist, typical users define a DCL symbol to make DIRSORT
available as a foreign command.  This symbol definition may be placed in
a user's SYS$LOGIN:LOGIN.COM, or in a more central location, like
SYS$MANAGER:SYLOGIN.COM.  A typical symbol definition might look like
this:

        $ DIRSORT :== $ dev:[dir]DIRSORT.EXE


   Alternatively, the executable could be placed into SYS$SYSTEM, and
a command like the following would add the DIRSORT command to the user's
process command table:

        $ SET COMMAND DIRSORT_CLD.CLD

   The executable could, instead, be placed outside SYS$SYSTEM, but then
the .CLD file would need to be edited to change its IMAGE directive
(currently a comment) to specify the actual location of the executable
image.  (SYS$SYSTEM:DIRSORT.EXE is the default location.)


   No VMS HELP file is provided, but the program has a "DIRSORT /HELP"
option, and its output is included below.

------------------------------------------------------------------------

      Bugs
      ----

   The V1.2-4 code was unsatisfactory enough to stimulate the
development of this V2 kit.  No claims of quality are made by its
creator.  Perhaps viewing it as "experimental" would be appropriate.

   V2.0 was intended to provide a (mostly) compatible user interface:
command-line options, and program output.  See changes-2.txt for some
potential changes/improvements which would affect both.

   After extensive changes to the functional code since V1.2-4, many
things are possible, and testing has been minimal (zero on X86_64, since
the X9.2 field-test program expired).  Complaints are always welcome, but
low expectations are probably more realistic than high ones.

------------------------------------------------------------------------

      DIRSORT /HELP

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

  DIRSORT (V2.0-0)

        DIRSORT is an alternative to the DCL DIRECTORY command.
        It lists only filename and date-time information for the
        specified directory/files.  The output is sorted by date-time
        rather than filename, and can be in either ascending (default)
        or descending order.

        By default, date-times are displayed in the YYYY-Mmm-DD format,
        but the user can specify a different format by defining the
        logical name DIRSORT_FORMAT.  (Typically, this definition is made
        in the process logical name table, but anyplace in
        LNM$DCL_LOGICAL works.)  For example:

          $ define DIRSORT_FORMAT "|!DB-!MAAU-!Y4 !H04:!M0:!S0.!C2|

        which would change the date format to the usual VMS DD-MMM-YYYY
        form.  Specify a white-space value (like " ") to restore the
        default format if an existing definition in a lower-priority
        table is undesired.  See the OpenVMS Programming Concepts
        Manual (System Time Operations > Date/Time Formatting Routines >
        Formatting Run-Time Mnemonics) for date-time format details.

    Parameter:

        DIRSORT accepts one parameter, a VMS filepath which is the
        target directory/file specification.  RMS wildcards (* and %
        (or ?, lately)) are accepted in the file specification.  As with
        DIRECTORY, if the parameter is omitted, the default directory
        is used.

    Qualifiers:

        /DATE=xxxx - selects the particular file date-time value to be
                displayed and used for sorting.  Valid keywords are
                BACKUP, CREATE, EXPIRE, and REVISE (default).

        /DELTATIME - causes the date-time for each file to be displayed
                as a delta-time value: the difference between the current
                date-time and the file date-time.

        /LAYOUT=xxx - specifies the display layout for filenames and
                date-times.  Valid keywords are DATEFIRST (default),
                FILEFIRST, and TRUNCATE.  DATEFIRST puts the date-time
                before the file name; FILEFIRST and TRUNCATE put the
                file name first.  With FILEFIRST, a long name will cause
                the date-time to appear on a second line; with TRUNCATE,
                a long name will be truncated (at 31 characters) to fit
                with the date-time on one line.  A truncated name is
                displayed with ">" as its last character.  For example,
                "123456789012345678901234.txt;1>" would indicate a
                truncated 32-character (or longer) name.

        /SORT=xxx - selects the sort order.  Valid keywords are ASCENDING
                (default, oldest first) and DESCENDING (newest first).

        /HELP - Displays this text.

        /VERSION - Displays the program version and build date, and the
               date-time format strings (default, and user-defined, if
               the logical name DIRSORT_FORMAT is defined).

------------------------------------------------------------------------
