ex13_1.in

ART OF Assembly Language Programming, 很不错

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


Example of Usage:

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

			mov	ah, 2ah
			int	21h
			lesi	TodaysDate2
			LDTOA2

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

Description:

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

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

Category:       Date/Time Routines

Author:		Randall Hyde

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


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

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

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


Example of Usage:

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

			lesi	TodaysDate2
			xLDTOA2

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

Description:

Similar to xDTOA, xDTOA2, and xDTOAM 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:  TTOA (2,m)
--------------------

Category:       Date/Time Routines

Author:		Randall Hyde

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


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

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

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


Example of Usage:

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

			mov	ah, 2ch
			int	21h
			lesi	CurTime2
			TTOA2

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

Description:

TTOA 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).

TTOA2 works like TTOA 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 TTOA is one component.

TTOAM is like TTOA except it automatically allocates storage for the string
on the heap.

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

Category:       Date/Time Routines

Author:		Randall Hyde

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


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

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

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


Example of Usage:

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

			lesi	CurTime2
			xTTOA2

			xTTOAM			;ES:DI is allocated on heap.

Description:

These routines work just like TTOA, TTOA2, and TTOAM 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

File I/O Routines
-----------------

Although MS-DOS provides some fairly decent file I/O facilities, the MS-DOS
file routines are all block oriented.  That is, there is no simple routine
you can call to read a single character from a file (the most common case).
Although you can create a buffer consisting of a single byte and call MS-DOS
to read a single character into that buffer, this is very slow.  The standard
library file I/O routines provide a set of buffered I/O routines for sequent-
ially accessed files.  These routines are suitable only for files which you
sequentially read or sequentially write.  They do not work with random access
files nor can you alternately read and write to the file.  However, most file
accesses fall into the category of sequential read or write so the Standard
Library routines will work fine in most cases.  In other cases, MS-DOS
provides a reasonable API so there really isn't a need for augmentation in
the Standard Library.

The Standard Library provides routines to OPEN a file (for reading or writing
only), CREATE a new file and open it for writing, CLOSE a file, FLUSH the file
buffers associated with a file, GET a character from a file, READ a block of
bytes from a file, PUT a single character to a file, or write a block of chars
to a file.

Note that you can use the standard I/O redirection operations to redirect the
standard input and output to routines which read and write bytes through a
file.  Consider the following short routine:

Redir2File	proc	far
		push	ds
		push	es
		push	di
		mov	di, seg MyFileVar
		mov	ds, di

		les	di, ds:MyFileVar
		fputc

		pop	di
		pop	es
		pop	ds
		ret
Redir2File	endp

This routine, when called, writes the character in AL to the file specified
by the file variable "MyFileVar" (see an explanation of the FPUTC routine
for more details).  You can selectively redirect all of the standard output
routines through this procedure (hence sending all standard output to the
file) using the Standard Library SetOutAdrs routine:

		lesi	Redir2File
		SetOutAdrs

		<use print, printf, puts, puti, etc. here, all output
		 goes to the file rather than to the screen.>

		lesi	PutcStdOut	;Default DOS output
		SetOutAdrs

		<Now all output goes back to the DOS standard output>

You can also preserve the previous output address using the code:

		lesi	Redir2File
		PushOutAdrs

		<use print, printf, puts, puti, etc. here, all output
		 goes to the file rather than to the screen.>

		PopOutAdrs

		<Now all output goes back to the previous handler.>


You can do the same thing with the standard input routines when redirecting
input from a file, though this is less useful.


All file I/O routines in the library use a "File Variable" to keep track of
the specified file.  *THIS IS NOT THE SAME THING AS A DOS FILE HANDLE!*
"FileVar" is a structure defined in the "file.a" include file.  For each file
you open/close, you must create a unique file variable.


Routine:  FOPEN
---------------

Category:             File I/O

Registers on Entry:	AX contains file open mode
				(0=open for read, 1=open for write)
			ES:DI points at a file variable.
			DX:SI points at a file name.

Registers on return:	Carry is set/clear for error/no error.
			AX contains (DOS) error code if carry is set.

Flags affected:
			Carry denotes error.

Example of Usage:

MyFileVar		FileVar	<>
MyFileName		db	"file.nam"
			.
			.
			.
			mov	ax, 0			;Open for reading
			lesi	MyFileVar		;Ptr to file variable.
			ldxi	MyFileName		;Ptr to file name.
			fopen
			jc	Error

Description:

fopen opens a sequential file for reading or writing.  It calls DOS to 
actually open the file and then sets up appropriate internal variables (in
the FileVar variable) to provide efficient blocked I/O.

Include:              stdlib.a or file.a

Routine:  FCREATE
-----------------

Category:             File I/O

Registers on Entry:	
			ES:DI points at a file variable.
			DX:SI points at a file name.

Registers on return:	Carry is set/clear for error/no error.
			AX contains (DOS) error code if carry is set.

Flags affected:
			Carry denotes error.

Example of Usage:

MyFileVar		FileVar	<>
MyFileName		db	"file.nam"
			.
			.
			.