ex13_1.in

ART OF Assembly Language Programming, 很不错

	File I/O
	Miscellaneous Routines
	Time & Date Routines
	Smart List Routines
	Serial Port I/O
	Pattern Matching Package
	Process Package



IF YOU WANT TO PLAY WITH THE SOURCE LISTINGS
********************************************

Most users will probably use the standard library routines in object form
and never worry about the actual implementation.  If you, on the other hand,
want to get "under the hood" and take a look at how this code was written
(perhaps to fix a bug), all the source listings are provided with this
release.

We assemble the library for final distribution using TASM 3.0 with the
"/M3",  "/jjumps", and "/ic:\stdlib\include" command line options.  If you
do not specify these options you will probably get an assembly error.

All initial development of these routines was done with MASM.  By writing the
code with MASM and then assembling the final release version with TASM we
could verify that the code worked with both assemblers.

That is, at least, until MASM 6.0 came along.  All new routines written since
the introduction of MASM 6.0 were developed with MASM 6.0 and assembled with
TASM 3.0.  They should compile with MASM 5.1 as well (though we haven't
verified this).  HOWEVER, older routines written before the release of MASM 6
will probably not assemble properly under MASM 6.0 unless you specify the
MASM 5.1 compatibility options.  Furthermore, routines written after the
release of MASM 6.0 take advantage of MASM/TASM's "branch out of range"
automatic correction and may produce errors when assembled under MASM 5.1.

Moral of the story-- If you're still using MASM 5.1 (or earlier) or TASM 2.0
(or earlier), *upgrade*!

Given the divergent paths that MASM 6.0 and TASM 3.0 are taking, it is
unlikely that we will continue to provide all future code in a form which
compiles under both assemblers.  The windowing package we've created (but
have not released), for example, will only assemble under MASM 6.0.  We will
always make sure that the object code works with any assembler/linker out
there, but it's unlikely we will continue to support both MASM and TASM
at the source level for TASM indefinitely (unless BORLAND gives us good
reason to do otherwise, like having a MASM 6.x compatibility mode).  Sorry,
it's just too much work for so little return.

Of course, if you would volunteer to translate our MASM 6 code to TASM,
we'd be more than happy to give you full credit for your work.

Currently (6/93), MASM 6.0 and MASM 6.1 have some severe bugs which create
some major problems.  As soon as a stable release appears we will convert
specifically to MASM 6.x.

Acknowledgements
================

There are far too many people who have their fingers in this package to
give full credit to everyone involved.  Futhermore, this section was
added long after many hard-working people's efforts were forgotten.
If you are one of these people, send me (rhyde) email and I will
certainly rectify this situation.

Most of the routines in the library were written by Randy Hyde.
Those routines authored by someone else contain appropriate notes in the
comments found in the source listing.

Many thanks to those who have found problems in routines in the library.
This includes the students in CS 191x, CS 185, CS 162ABC, and CS 13 at
UC Riverside.  They have made important contributions to this library
and their efforts are not forgotten.

Special thanks to the CS 191x class at UC Riverside who reorganized the
documentation from its original sorry state.  Special thanks to Steve
Shah for his quick reference guide.

Last, but certainly not least, praise and glory to our Lord for giving us
all the talent to achieve this...

In the future, I will endeavor to keep this section up to date and provide
personal acknowledgements to those who have contributed to the success of
this library.
Conversion Routines
-------------------


The stdlib conversion routines follow a uniform format of storing the data
to be converted and returned.  Most routines accept input and return data
of either an ASCII string of characters, stored in the ES:DI register, or
integers, stored in the DX:AX register.  If a value is just a 16 or 8-bit
value then it will be stored in AX or AL.

Since there is a possibility of an error in the input values to be converted,
such as it does not contain a proper value to convert, we use the
carry flag to show error status.  If the error flag is set then an error has
occured and things are okay if the carry flag is clear.





Routine:  ATOL (2)
------------------


Category:             Conversion Routine

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

Registers on Return:  DX:AX- Long integer converted from string
		      ES:DI- Points at first non-digit (ATOL2 only)

Flags Affected:       Carry flag- Error status

Examples of Usage:
		      gets         ;Get a string from user
		      ATOL         ;Convert to a value in DX:AX


Description:  ATOL converts the string of digits that ES:DI points at to a
	      long (signed) integer value and returns this value in DX:AX.
	      Note that the routine stops on the first non-digit.
	      If the string does not begin with a digit, this routine returns
	      zero.  The only exception to the "string of digits" only rule is
	      that the number can have a preceding minus sign to denote a
	      negative number.  Note that this routine does not allow leading
	      spaces.  ATOL2 works in a similar fashion except it doesn't
	      preserve the DI register.  That is, ATOL2 leaves DI pointing at
	      the first character beyond the string of digits.  ATOL/ATOL2 both
	      return the carry flag clear if it  translated the string of
	      digits without error.  It returns the carry flag set if overflow
	      occurred.


Include:              	stdlib.a or conv.a



Routine:  AtoUL (2)
-------------------

Category:            Conversion Routine

Register on entry:   ES:DI- address of the string to be converted

Register on return:  DX:AX- 32-bit unsigned integer
		     ES:DI- Points at first character beyond digits (ATOUL2
			    only)

Flags affected:      Carry flag- Set if error, clear if okay.

Examples of Usage:
		     les InputString
		     AtoUL


Description:  AtoUL converts the string pointed by ES:DI to a 32-bit unsigned
	      integer.  It places the 32-bit unsigned integer into the memory
	      address pointed by DX:AX. If there is an error in conversion,
	      the carry flag will set to one. If there is not an error, the
	      carry flag will be set to zero.

	      ATOUL2 does not preserve DI.  It returns with DI pointing at
	      the first non-digit character in the string.

Include:        stdlib.a or conv.a



Routine:    ATOU (2)
--------------------

Category:            Conversion Routine

Register on entry:   ES:DI points at string to convert

Register on return:  AX-    unsigned 16-bit integer
		     ES:DI- points at first non-digit (ATOU2 only)

Flags affected:      carry flag - error status

Example of Usage:

Description:    ATOU converts an ASCII string of digits, pointed to by ES:DI,
		to unsigned integer format. It places the unsigned 16-bit
		integer, converted from the string, into the AX register.
		ATOI works the same, except it handle unsigned 16-bit integers
		in the range 0..65535.

		ATOU2 leaves DI pointing at the first non-digit in the string.

Include:        stdlib.a or conv.a



Routine: ATOH (2)
-----------------

Category:             Conversion Routine

Registers on Entry:   ES:DI- Points to string to convert

Registers on Return:  AX- Unsigned 16-bit integer converted from hex string
		      DI (ATOH2)- First character beyond string of hex digits

Flags Affected:       Carry = Error status

Example of Usage:
		      les  DI, Str2Convrt
		      atoh                  ;Convert to value in AX.
		      putw                  ;Print word in AX.


Description:  ATOH converts a string of hexadecimal digits, pointed to by
	      ES:DI, into unsigned 16-bit numeric form. It returns the value in
	      the AX register.  If there is an error in conversion, the carry
	      flag will set to one.  If there is not an error, the carry flag
	      will be clear.  ATOH2 works the same except it leaves DI
	      pointing at the first character beyond the string of hex digits.

Include:        stdlib.a or conv.a


Routine: ATOLH (2)
------------------

Category:             Conversion Routine

Registers on Entry:   ES:DI- Points to string to convert

Registers on Return:  DX:AX- Unsigned 32-bit integer converted from hex string
		      DI (ATOLH2)- First character beyond string of hex digits

Flags Affected:       Carry = Error status

Example of Usage:
		      les  DI, Str2Convrt
		      atolh                 ;Convert to value in DX:AX

Description:  ATOLH converts a string of hexadecimal digits, pointed to by
	      ES:DI, into unsigned 32-bit numeric form. It returns the value in
	      the DX:AX register.  If there is an error in conversion, the carry
	      flag will set to one.  If there is not an error, the carry flag
	      will be clear.  ATOLH2 works the same except it leaves the DI
	      register pointing at the first non-hex digit.


Include:        stdlib.a or conv.a



Routine:   ATOI (2)
-------------------

Category:             Conversion Routine

Register on entry:    ES:DI- Points at string to convert.

Register on return:   AX- Integer converted from string.
		      DI (ATOI2)- First character beyond string of digits.

Flags affected:       Error status

Examples of Usage:
		      les  DI, Str2Convrt
		      atoi                 ;Convert to value in AX


Description:   Works just like ATOL except it translates the string to a
	       signed 16-bit integer rather than a 32-bit long integer.


Include:              stdlib.a or conv.a


Routine ITOA (2,M)
------------------

Category:             Conversion Routine

Registers on Entry:   AX- Signed 16-bit value to convert to a string
		      ES:DI- Pointer to buffer to hold result (ITOA/ITOA2
			     only).

Registers on Return:  ES:DI- Pointer to string containing converted
		      characters (ITOA/ITOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (ITOA2 only).

Flags Affected:       Carry flag is set on memory allocation error (ITOAM only)

Examples of Usage:
		      mov     ax, -1234
		      ITOAM                   ;Convert to string.
		      puts                    ;Print it.
		      free                    ;Deallocate string.

		      mov     di, seg buffer
		      mov     es, di
		      lea     di, buffer
		      mov     ax, -1234
		      ITOA		      ;Leaves string in BUFFER.

		      mov     di, seg buffer
		      mov     es, di
		      lea     di, buffer
		      mov     ax, -1234
		      ITOA2		      ;Leaves string in BUFFER and
					      ;ES:DI pointing at end of string.


Description:	These routines convert an integer value to a string of
		characters which represent that integer.  AX contains the
		signed integer you wish to convert.

		ITOAM automatically allocates storage on the heap for the
		resulting string, you do not have to pre-allocate this
		storage.  ITOAM returns a pointer to the (zero-terminated)
		string in the ES:DI registers.  It ignores the values in
		ES:DI on input.

		ITOA requires that the caller allocate the storage for the
		string (maximum you will need is seven bytes) and pass a
		pointer to this buffer in ES:DI.  ITOA returns with ES:DI
		pointing at the beginning of the converted string.

		ITOA2 also requires that you pass in the address of a buffer
		in the ES:DI register pair.  However, it returns with ES:DI
		pointing at the zero-terminating byte of the string.  This
		lets you easily build up longer strings via multiple calls
		to routines like ITOA2.

Include:        stdlib.a or conv.a



Routine:   UTOA (2,M)
---------------------

Category:            Conversion Routine

Registers on entry:   AX - unsigned 16-bit integer to convert to a string
		      ES:DI- Pointer to buffer to hold result (UTOA/UTOA2
			     only).

Registers on Return:  ES:DI- Pointer to string containing converted
		      characters (UTOA/UTOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (UTOA2 only).

Flags affected:       Carry set denotes malloc error (UTOAM only)

Example of Usage:
		      mov     ax, 65000
		      utoa
		      puts
		      free

		      mov     di, seg buffer
		      mov     es, di
		      lea     di, buffer
		      mov     ax, -1234
		      ITOA		      ;Leaves string in BUFFER.

		      mov     di, seg buffer
		      mov     es, di
		      lea     di, buffer
		      mov     ax, -1234
		      ITOA2		      ;Leaves string in BUFFER and
					      ;ES:DI pointing at end of string.


Description:    UTOAx converts a 16-bit unsigned integer value in AX to a
		string of characters which represents that value.  UTOA,
		UTOA2, and UTOAM behave in a manner analogous to ITOAx.  See
		the description of those routines for more details.


Include:       stdlib.a or conv.a



Routine:   HTOA (2,M)
---------------------

Category:            Conversion Routine

Registers on entry:   AL - 8-bit integer to convert to a string
		      ES:DI- Pointer to buffer to hold result (HTOA/HTOA2
			     only).

Registers on Return:  ES:DI- Pointer to string containing converted