DATEREG.DOC
Rick Charnes, 25 October 1987, San Francisco

    In Z80DOS the date is stored in memory locations 0050 and 0051.  The 
hex values contained therein are the number of days in hex since 
December 31, 1977.  In this form the date is entirely inaccessible for 
use in aliases.  DATEREG takes the contents of these bytes and 
transforms it to the actual month, day and year, then puts these in the 
ZCPR3 registers in hexadecimal form.  Thus the $Rn symbol in ARUNZ can 
be used to represent the date.
                              
    The components of the date will be stored as follows:
                  
REGISTER 5 = mm, where 'mm' is the month
REGISTER 6 = dd, where 'dd' is the day 
REGISTER 7 = yy, where 'yy' is the 20th century year
              
    Thus an alias like the following becomes possible:
              
TODAY echo t%>oday is the $r5th day of the $r6th month in   <<
the year 19$r7.
    
    Note that both REG.COM and the RCP-resident REG display the decimal 
equivalent of the hex values held in the ZCPR3 registers.  Therefore, 
using these commands will NOT display what you might have hoped.  
ARUNZ's '$Rn' symbol, however, displays the ZCPR3 registers in their 
native hex form, which is exactly how we want it to appear since it
is only in the hex format that the date reads accurately.

    I recommend including DATEREG in your startup alias so that the 
system date is always available to you via the ZCPR3 registers.  It is 
important to note in this regard that an ARUNZ alias will expand its 
symbols such as $Rn or $Mnnnn to the value(s) in effect AT THE TIME THE 
ALIAS IS INVOKED.  No change made to the ZCPR3 registers or memory in 
the course of the execution of the alias will be reflected in the 
expansion of these symbols.

    In other words, if DATEREG is not in your startup alias or run 
previously elsewhere, then the TODAY alias above, even if DATEREG is 
included in it:

TODAY datereg;echo t%>oday is the $r5th day of the $r6th month in   <<
the year 19$r7.

will NOT produce the desired effect of displaying the system date.  
Rather, the $R parameters will expand to whatever was in those registers 
before the alias was invoked, most probably 00's.

    DATEREG would of course not be possible without Carson Wilson's 
superb Z80DOS.  This program in particular uses DATEHL.REL written by 
Carson and supplied in Z80DOS10.LBR.

Further notes
-------------

    DATEREG is my first attempt at assembly language programming where I 
did more than 50% of the work.  It's so satisfying!  I've spent a year 
writing aliases and ZEX files that were very fulfilling to me, but at a 
certain point your repertoire begs to expand...

    My ultimate purpose in writing DATEREG, ironically though, was for 
use in an alias inspired by the absolutely brilliant one developed by 
Carson Wilson.  Carson's logs the beginning and ending times a COM file 
was in use, then writes this information to a file.  It of course needs 
a real time clock.  Being without a clock, however, I wanted something 
that would keep track of the date of every editing of any specific word- 
processed file.  As far as I know such a utility has never before been 
available for Z80 machines.  Why?  I don't know.  It seems like a fairly 
obvious and wonderful thing to have and it seems that there must be a 
way to do it in CP/M 3.0 or with DateStamper and 2.2.  I'm quite pleased 
at having done it for Z80DOS.  It's really quite simple.

    Both my and Carson's alias use a program ECHO.COM (not the ZCPR3 
ECHO.COM) written by one Eugene H. Mallory in 1983.  It's one of a 
fairly large number of unix-style CP/M utilities Mr. Mallory wrote way 
back in the good old days of CP/M.  It appends any parameters entered on 
its command line to the file specified after the traditional 'piping' 
symbol '>' (here actually two are used, as in '>>' entered after the 
parameters.  I've included both ECHO.COM, which should be renamed to 
LOGECHO.COM, and its help file, ECHO.HLP, in this library.  Thanks go to 
Mr. Mallory for writing such a useful tool, and Carson Wilson for re- 
discovering it, that allowed us 4 years later to do such a nice thing 
with Z80DOS.

The logging alias is:

LOG e l%>ogging use of %<$2...;echolog $r5/$r6/$r7 >>$2.dat;$*

Syntax to log date of use of text file SMITH.LTR would be:

                  'log vde smith'

The alias will write the date in the format '10/25/87' to the end of the 
file SMITH.DAT.  Finally the command line 'vde smith' is actually run.  
Each time this file is accessed through the LOG alias the system date at 
that time will be appended to SMITH.DAT.  I've been using it myself for 
several days and it's very exciting to have this record of editings.

    But there I go again -- using aliases to do stuff that can and 
should be done in a real assembly (or other, I suppose) language 
utility.  Well, I'm learning -- slowly but surely.  This alias is fairly 
slow as ECHO.COM seems to take its time in opening and writing to our 
*.DAT file.  My next project therefore is what should actually be a 
fairly simple utility to do -- one that will do exactly what this alias 
does.  Using Carson's DATEHL.REL again it will simply write/append the 
contents of the chip registers H, L and A to our output file.  Please no 
one else write this; I'd like to do it myself within the next week or so.

    I would welcome comments, which can be sent to me through either of 
the Lillipute Z-Nodes in Chicago, Z-Node Central in California, or 
Newton Centre outside of Boston, or by voice at (415) 826-9448.