!pr1
DATE Command for ProDOS.............................Bill Morgan

One of the nice new features in ProDOS is the way the diskette catalog shows the date of creation and last modification for each file, IF you have a clock/calendar card installed in your Apple.  Well I don't have such a card in either of the Apples I use regularly, at work or at home.  And no //c has a clock!  (Yet, at least.  I'll bet someone will come up with a way...)

Anyway, I got tired of always seeing <NO DATE> and started figuring out how to set a date without a clock to do it for me.  A look at Beneath Apple ProDOS informed me that the current date is transformed into the format YYYYYYYMMMMDDDDD and stored (in the usual 6502 low byte/high byte sequence) at $BF90-BF91 in the ProDOS Global Pages (the fixed locations of all of the accessible system variables).  The first thing I did was manually convert the current date into that format and poke it in from the Monitor.  That went like this:

!lm+9
                         $BF90      $BF91
May =  $5 = 0101       MMM DDDDD  YYYYYYY M
 10 =  $A = 01010      101 01010  1010101 0
'85 = $55 = 1010101       $AA        $AA
!lm-9

So, the values to poke into $BF90-91 were $AA and $AA.  What better time than a four-A day to start such a project!

That experiment worked just fine:  the next file I saved on the disk showed creation and modification dates of 10-MAY-85, just as I had hoped.  With that success under my belt the next step had to be to come up with a program to read and/or set those date bytes.  And, while I'm at it, why not take advantage of ProDOS' built-in hooks for installing new commands and add a DATE command to the operating system?

How do I go about adding a command?  The ProDOS Technical Reference Manual is pretty sketchy on the subject, but two other books, Beneath Apple ProDOS and the new Apple ProDOS:  Advanced Features for Programmers, have good descriptions and examples of the procedure.  If you're going to do much assembly language programming under ProDOS you should have one or both of those books.

When ProDOS fails to recognize a command it does a JSR EXTRNCMD ($BE06) to find out if an external command processor will claim this one.  What I have to do is install the address of DATE in $BE07-08, after moving the address that was already there into a JMP instruction.  This way, if DATE doesn't recognize the command it can pass it along to any other processor that might have been there before.

Processing of an external command is normally divided into two phases, a parser and a handler.  The parser section will scan the command name at the beginning of the line.  If the command is not recognized, the parser should set the carry bit and JMP on to the address found in EXTRNCMD to see if another external processor will claim it.

If the command is recognized, the parser can set certain bits in PBITS ($BE54-55) to signify which parameters are permitted or required on the command line, and store the address of the handler in EXTRNADDR ($BE50-51).  After storing the command length minus one in XLEN ($BE52) and a zero in XCNUM ($BE53), to signify that an external processor did claim the command, the parser then returns control to ProDOS to scan the rest of the line.  If the line was syntactically correct, ProDOS will return the values of the parameters in a set of standard locations ($BE58-6F) and pass control back to the handler address specified.

Since DATE is a simple processor that uses a nonstandard parameter, I just set PBITS to zero, to indicate no parsing necessary, and store the address of an RTS instruction in EXTRNADDR.  I then proceed to do all my processing before returning to ProDOS.

There is one additional wrinkle to using an external command with ProDOS:  where do I put my code so ProDOS, Applesoft, and others don't stomp all over it?  In the interest of simplicity I have ignored that problem here.  The best procedure, as shown in the books mentioned above, is to call ProDOS to assign me a buffer and then relocate my code into that buffer.  The examples in the books provide details of this process.

Now, let's take a look at the code:

Lines 1310-1400 install DATE by moving the current External Command address to my exit JMP instruction and storing DATE's address in the vector.

Lines 1440-1540 check the input buffer to see if this is a DATE command.  If not we branch on down to that JMP instruction where we earlier put the address found in the External Command vector.  This passes control either on to the next external command in the chain, or back to ProDOS for a SYNTAX ERROR.

If the command matched we go on to lines 1560-1650 to do the necessary housekeeping.  This involves storing the command length-1 in the Global Page, setting a couple of flags to tell ProDOS not to parse the rest of the command line, and that an external command has taken over.  Then we supply a handler address for the second half of ProDOS' processing, which in this case is just an RTS instruction.  Finally we reach lines 1670-1690, where we check to see if the character following DATE is a Carriage Return.  If so we branch forward to RETURN.DATE to display the existing date.

If there is more than just DATE on the command line, we must want to set a new date, so we fall into SET.DATE at line 1710.  This routine makes heavy use of ACCUMULATE.DIGITS at line 2400, so we'll examine that code first.  The first step is to zero the byte where we'll be accumulating the value typed in.  Then we scan forward in the input buffer, looking for a nonblank character.  When we find one we first check to see if it is a slash, which marks the end of a number, or a Carriage Return, which marks the end of the line.  If it was either of those we exit, setting the Carry bit to indicate which one we found.

If the character found was not a delimiter we next check to see if it is a number.  If not, we have a SYNTAX ERROR.  When we do get a number, we strip off the high bits to convert the ASCII code to a binary value, and save that value.  We then multiply the previous value in ACCUM by 10 and add in the new value.  Then it's back to line 2440 to get another character.  Lines 2710-2730 load the A-register with the value found and branch to the error exit if that value was zero.

Now, back to SET.DATE.  That routine begins at line 1720 with a DEY to get ready for the INY at the beginning of ACCUMULATE.DIGITS.  We then get the month, check for a legal value, and store it.  Next we get the day, save the status, and check and save that value.  Then it's time to check the status to see if the day was followed by a slash, or by a Carriage Return.  If it was a slash then a year was specified, so we go get that value.  If it was a Return no year was present, so we use 1985.  (I guess that means we'll have to reassemble or patch this program every year.  I think I can handle that.)

The last step in SET.DATE is to fold the year, month, and day together as described above and store the results in the Global Page.  The comments in the listing illustrate how the bits are shuffled around to the correct format.  After setting the date we fall into RETURN.DATE to display the result.

RETURN.DATE, at lines 2080-2290, is quite straightforward.  It just gets the bytes from the Global Page, unfolds them, and calls DEC.OUT to translate them to decimal numbers and display those numbers.  Again, the comments illustrate the bit manipulations involved in the unfolding process.

The final section of code is DEC.OUT, at lines 2750-2910.  In lines 2760-2810 we use the Y-register to count how many times we can subtract 10 from the number passed in the A-register.  Then lines 2830-2910 restore and save the A-register, make sure the tens count is non-zero, convert it to a character and print it.  We then recover the units value and print that out.
