=====================
Date & Time  Routines
=====================

These routines convert DOS system times and dates to/from ASCII strings.
They appear in this section rather than conversions because we eventually
intend to add date and time arithmetic to the package.

Note the time to string conversion routines do not output the hundredths of
a second.  Most applications do not need (or want) this.  If you want
hundredths of a second you can easily write a routine (using this code) or
modify the existing code to suit your purposes.




Routine:  DATE (2,m)
--------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			CX-	Current year (in the range 1980-2099)
			DL-	Current day
			DH-	Current month
			ES:DI-	Points at buffer with room for at least
				nine bytes (DATE/DATE2 only).


Registers on Return: 	ES:DI-	DATE sticks a string of the form MM/DD/YY
				into a buffer allocated on the heap (DATEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (DATE2 only).

Flags Affected:       carry-	Set if memory allocation error (DATEM only).


Example of Usage:

			mov	ah, 2ah		;Call DOS to get the system
			int	21h		; time (also see xDATE)
			lesi	TodaysDate	;Buffer to store string.
			DATE			;Convert date to string.

			mov	ah, 2ah
			int	21h
			lesi	TodaysDate2
			DATE2

			mov	ah, 2ah
			int	21h
			DATEM			;ES:DI is allocated on heap.

Description:

DATE converts a DOS system date (in CX/DX) to an ASCII string and deposits
the characters into a buffer specified by ES:DI on input.  ES:DI must be at
least nine bytes long (eight bytes for mm/dd/yy plus the zero terminating
byte).

DATE2 converts a DOS system date to an ASCII string just like DATE above.
The only difference is that it does not preserve DI.  It leaves DI pointing
at the zero terminating byte at the end of the string.  This routine is use-
ful for building up long strings with a date somewhere in the middle.

DATEM works like DATE except you do not pass the pointer to a buffer in ES:DI.
Instead, DATEM allocates nine bytes for the string on the heap.  It returns
a pointer to this new string in ES:DI.

Include:              stdlib.a or date.a

Routine:  xDATE (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at buffer with room for at least
				nine bytes (xDATE/xDATE2 only).


Registers on Return: 	ES:DI-	DATE sticks a string of the form MM/DD/YY
				into a buffer allocated on the heap (xDATEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (xDATE2 only).

Flags Affected:       carry-	Set if memory allocation error (xDATEM only).


Example of Usage:

			lesi	TodaysDate	;Buffer to store string.
			xDATE			;Convert date to string.

			lesi	TodaysDate2
			xDATE2

			mov	ah, 2ah
			int	21h
			xDATEM			;ES:DI is allocated on heap.

Description:

These routines work just like DATE, DATE2, and DATEM except you do not pass
in the date to them, they call DOS to read the current system date and
convert that to a string.

Include:              stdlib.a or date.a


Routine:  LDATE (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			CX-	Current year (in the range 1980-2099)
			DL-	Current day
			DH-	Current month
			ES:DI-	Points at buffer with room for at least
				nine bytes (DATE/DATE2 only).


Registers on Return: 	ES:DI-	DATE sticks a string of the form "mmm dd, yyyy"
				into a buffer allocated on the heap (LDATEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (LDATE2 only).

Flags Affected:       carry-	Set if memory allocation error (LDATEM only).


Example of Usage:

			mov	ah, 2ah		;Call DOS to get the system
			int	21h		; time (also see xDATE)
			lesi	TodaysDate	;Buffer to store string.
			LDATE			;Convert date to string.

			mov	ah, 2ah
			int	21h
			lesi	TodaysDate2
			LDATE2

			mov	ah, 2ah
			int	21h
			LDATEM			;ES:DI is allocated on heap.

Description:

These routines work just like the DATE, DATE2, and DATEM routines except they
output their date in the form "mmm dd, yyyy", e.g., Jan 1, 1980.

Include:              stdlib.a or date.a

Routine:  xLDATE (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at buffer with room for at least
				nine bytes (xLDATE/xLDATE2 only).


Registers on Return: 	ES:DI-	Sticks a string of the form MMM DD, YYYY
				into a buffer allocated on the heap (xLDATEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (xLDATE2 only).

Flags Affected:       carry-	Set if memory allocation error (xLDATEM only).


Example of Usage:

			lesi	TodaysDate	;Buffer to store string.
			xLDATE			;Convert date to string.

			lesi	TodaysDate2
			xLDATE2

			mov	ah, 2ah
			int	21h
			xLDATEM			;ES:DI is allocated on heap.

Description:

Similar to xDATE, xDATE2, and xDATEM except these routines produce strings of
the form "MMM DD, YYYY".

Include:              stdlib.a or date.a

Routine:  ATOD (2)
------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at string containing date to convert.


Registers on Return: 	CX-	Year (1980-2099)
			DH-	Month (1-12)
			DL-	Day (1-31)
			ES:DI-	Points at first non-date string (ATOD2 only)

Flags Affected:       	carry-	Set if bad date format.


Example of Usage:

			lesi	TodaysDate	;Buffer containing string.
			ATOD			;Convert string to date.
			jc	Error

			lesi	TodaysDate	;Buffer containing string.
			ATOD2			;Convert string to date.
			jc	Error

Description:

ATOD converts an ASCII string of the form "mm/dd/yy" or "mm-dd-yy" to a DOS
format date.  It returns the carry flag set if there is a parse error (that
is, the string is not in one of these two forms) or if the month, date, or
year values are out of range (including specifying Feb 29th on non-leap years).

ATOD2 works just like ATOD except it does not preserve DI.  It leaves DI
pointing at the first non-date character encountered in the string.

Include:              stdlib.a or date.a

Routine:  ATOT (2)
------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at string containing time to convert.


Registers on Return: 	CH-	Hour (0..23)
			CL-	Minutes (0..59)
			DH-	Seconds (0..59)
			DL-	Seconds/100 (0..99)

			ES:DI-	Points at first character which is not a part
				of the parsed time (ATOT2 only).

Flags Affected:       	carry-	Set if bad time format.


Example of Usage:

			lesi	CurrentTime	;Buffer containing string.
			ATOT			;Convert string to time.
			jc	Error

			lesi	CurrentTime	;Buffer containing string.
			ATOT2			;Convert string to time.
			jc	Error


Description:

ATOT converts an ASCII string of the form "hh:mm:ss" or "hh:mm:ss.xxx" to a DOS
format date.  It returns the carry flag set if there is a parse error (that
is, the string is not in one of these two forms) or if the hours, minutes,
seconds, or hundredth values are out of range.  If the string does not contain
1/100ths of a second, this routine returns zero in DL.

ATOT2 works just like ATOT except it does not preserve DI.  It leaves DI
pointing at the first character beyond the time characters.

Include:              stdlib.a or time.a

Routine:  TIME (2,m)
--------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			CH-	Hour (0..23)
			CL-	Minutes (0..59)
			DH-	Seconds (0..59)
			DH-	1/100 seconds (0..99)
			ES:DI-	Points at buffer with room for at least
				nine bytes (TIME/TIME2 only).


Registers on Return: 	ES:DI-	Sticks a string of the form hh:mm:ss
				into a buffer allocated on the heap (TIMEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (TIME2 only).

Flags Affected:       carry-	Set if memory allocation error (TIMEM only).


Example of Usage:

			mov	ah, 2ch		;Call DOS to get the system
			int	21h		; time (also see xTIME)
			lesi	CurrentTime	;Buffer to store string.
			TIME			;Convert Time to string.

			mov	ah, 2ch
			int	21h
			lesi	CurTime2
			TIME2

			mov	ah, 2ch
			int	21h
			TIMEM			;ES:DI is allocated on heap.

Description:

TIME converts the DOS system time in CX/DX to a string and stores the string
at the location specified by ES:DI.  ES:DI must point at a buffer with at
least nine characters in it (for a string of the form hh:mm:ss followed by
a zero terminating byte).

TIME2 works like TIME except it does not preserve DI.  It leaves DI pointing
at the zero terminating byte in the string.  This is useful for generating
long strings in memory of which TIME is one component.

TIMEM is like TIME except it automatically allocates storage for the string
on the heap.

Include:              stdlib.a or time.a

Routine:  xTIME (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at buffer with room for at least
				nine bytes (xTIME/xTIME2 only).


Registers on Return: 	ES:DI-	Sticks a string of the form HH:MM:SS
				into a buffer allocated on the heap xTIMEM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (xTIME2 only).

Flags Affected:       carry-	Set if memory allocation error (xTIMEM only).


Example of Usage:

			lesi	CurrentTime	;Buffer to store string.
			xTIME			;Convert time to string.

			lesi	CurTime2
			xTIME2

			xTIMEM			;ES:DI is allocated on heap.

Description:

These routines work just like TIME, TIME2, and TIMEM except you do not pass
in the time to them, they call DOS to read the current system time and
convert that to a string.

Include:              stdlib.a or time.a

