Standard Input Routines:
Character Input Routines
------------------------


	The character input routines take input from either a standard
device (keyboard, etc.) or a standard library.  After the character input
routines receive the characters they either place the characters on the stack
and/or return.  The character input routines work similar to the "C" character
input routines.



Routine:  Getc
--------------


Category:             Character Input Routine


Registers on Entry:   None


Registers on Return:  AL- Character from input device.
                      AH- 0 if eof, 1 if not eof.


Flags Affected:       Carry- 0 if no error, 1 if error.  If error occurs, AX
                             contains DOS error code.


Example of Usage:  
                      getc
                      mov     KbdChar, al
                      putc


Description:  This routine reads a character from the standard input device.
              This call is synchronous, that is, it does not return until a
              character is available.  The Default input device is DOS
              standard input.

              Getc returns two types of values: extended ASCII (codes 1-255)
              and IBM keyboard scan codes.  If Getc returns a non-zero value,
              you may interpret this value as an ASCII character.  If Getc
              returns zero, you must call Getc again to get the actual
              keypress.

              The second call returns an IBM PC keyboard scan code.

              Since the user may redirect input from the DOS command line,
              there is the possibility of encountering end-of-file (eof)
              when calling getc.  Getc uses the AH register to return eof
              status.  AH contains the number of characters actually read
              from the standard input device.  If it returns one, then
              you've got a valid character.  If it returns zero, you've
              reached end of file.  Note that pressing control-z forces an
              end of file condition when reading data from the keyboard.

              This routine returns the carry flag clear if the operation
              was successful.  It returns the carry flag set if some sort
	      of error occurred while reading the character.  Note that eof
              is not an error condition.  Upon reaching the end of file,
              Getc returns with the carry flag clear.  If getc is seen from
              a file the control-z is not seen as an end-of-file marker,
              but just read in as a character of the file.

              Control-c if read from a keyboard device aborts the program.
              However if when reading something other than a keyboard
	      (files, serial ports), control-c from the input source
              returns control-c.  However when pressing control-break
              the program will abort regardless of the input source.

              Regarding CR/LF, if the input is from a device, (eg. keyboard
              serial port) getc returns whatever that device driver returns,
              (generally CR without a LF).  However if the input is from
              a file, getc stripes a single LF if it immediately follows
              the CR.

              When using getc files operate in "cooked" mode.  While
              devices operate in "pseudo-cooked" mode, which means no
	      buffering, no CR -> CR/LF, but it handles control-c, and
              control-z.

	      See the sources for more information about GETC's internal
	      operation.

Include:	stdlib.a or stdin.a




Routine:   GetcStdIn
--------------------


Category:             Character Input Routine

Register on entry:    None.

Register on return:   AL- Character from input device.

Flags affected:       AH- 0 if eof, 1 if not eof.
                      Carry- 0 if no error, 1 if error
                      (AX contains DOS error code if error occurs).


Example of Usage:
                      GetcStdIn
                      mov     InputChr, al
                      putc


Description:    This routine reads a character from the DOS standard input
                device.  This call is synchronous, that is, it does not return
                until a character is available.  See the description of Getc
                above for more details.

		The difference between Getc and GetcStdIn is that your
		program can redirect Getc using other calls in this library.
		GetcStdIn calls DOS directly without going through this
		redirection mechanism.


Include:		stdlib.a or stdin.a






Routine:   GetcBIOS
-------------------


Category:             Character Input Routine

Register on entry:    None

Register on return:   AL- Character from the keyboard.

Flags affected:       AH- 1 (always).  Carry- 0 (always).

Example of Usage:   
		      GetcBIOS
                      mov     CharRead, al
                      putc


Description:   This routine reads a character from the keyboard.  This call is
               synchronous, that is it does not return until a character is
               available.

		Note that there is no special character processing.  This
		code does *not* check for EOF, control-C, or anything
		else like that.



Include:		stdlib.a or stdin.a



Routine:  SetInAdrs
-------------------

Category:               Character Input Routine

Registers on Entry:     ES:DI - address of new input routine

Registers on return:    None 

Flags affected:

Examples of Usage:

                        mov     es, seg NewInputRoutine
                        mov     di, offset NewInputRoutine
                        SetInAdrs



                        les     di, RoutinePtr
                        SetInAdrs


Description:    This routine redirects the stdlib standard input so that it 
                calls the routine who's address you pass in es:di.  The
		routine (whose address appears in es:di) should be a "getc"
		routine which reads a character from somewhere and returns
		that character in AL.  It should also return EOF status in
		the AH register and error status in the carry flag (see
		the description of GETC for more details).


Include:                stdlib.a or stdin.a





Routine:   GetInAdrs
--------------------

Category:             Character Input Routine

Register on entry:    None

Register on return:   ES:DI - address of current input routine (called by Getc).

Flags affected:       None


Example of Usage:   
                      GetInAdrs
		      mov     word ptr SaveInAdrs, di
		      mov     word ptr SaveInAdrs+2, es


Description:   You can use this function to get the address of the current
	       input routine, perhaps so you can save it or see if it is
	       currently pointing at some particular piece of code.
	       If you want to temporarily redirect the input and then restore
	       the original input or outline, consider using
	       PushInAdrs/PopInAdrs described later.


Include:		stdlib.a or stdin.a



Routine:   PushInAdrs
---------------------

Category:             Character Input Routine

Register on entry:    ES:DI - Address of new input routine.

Register on return:   Carry=0 if operation successful.
                      Carry=1 if there were already 16 items on the stack.
                         
Example of Usage:
                      mov     es, seg NewInputRoutine
                      mov     di, offset NewInputRoutine
                      PushInAdrs
                        .
                        .
                        .
                      les     di, RoutinePtr
                      PushInAdrs


Description:   This routine "pushes" the current input address onto an
               internal stack and then copies the value in es:di into the
               current input routine pointer.  The PushInAdrs and PopInAdrs
               routines let you easily save and redirect the standard output
               and then restore the original output routine address later on.
               If you attempt to push more than 16 items on the stack,
               PushInAdrs will ignore your request and return with the
               carry flag set.  If PushInAdrs is successful, it will
               return with the carry flag clear.


Include:	stdlib.a or stdin.a





Routine:   PopInAdrs
--------------------

Category:             Character Input Routine

Register on entry:    None

Register on return:   ES:DI - Points at the previous stdout routine before
                      the pop.

Example of Usage:   
                      mov     es, seg NewInRoutine
		      mov     di, offset NewInputRoutine
                      PushInAdrs
                        .
                        .
                        .
                      PopInAdrs


Description:   PopInAdrs undoes the effects of PushInAdrs.  It pops an item
               off the internal stack and stores it into the input routine
               pointer.  The previous value in the output pointer is returned
               in es:di.

Include:	stdlib.a or stdin.a





Routine:  Gets, Getsm
---------------------

Category:             Character Input Routine

Register on entry:    ES:DI- Pointer to input buffer (gets only).

Register on return:   ES:DI - address of input of text.
                      carry-  0 if no error, 1 if error.
                      If error, AX contains: 0- End of
                      file encountered in middle of
                      string.  1- Memory allocation error (getsm only).
                      Other- DOS error code.


Flags affected:       None

Example of usage:    
                      getsm           ;Read a string from the
                                      ;keyboard
                      puts            ;Print it
		      putcr           ;Print a new line
                      free            ;Deallocate storage for
                                      ;string.

		      mov	di, seg buffer
		      mov	es, di
		      lea	di, buffer
		      gets
		      puts
		      putcr


Description:   	Reads a line of text from the stdlib standard input device.
		You must pass a pointer to the recipient buffer in es:di to
		the GETS routine.  GETSM automatically allocates storage for
		the string on the heap (up to 256 bytes) and returns a pointer
		to this block in es:di.

		Gets(m) returns all characters typed by the user except for the
		carriage return (ENTER) key code.  These routines return a
		zero-terminated string (with es:di pointing at the string).
		Exactly how Gets(m) treats the incoming data depends upon
		the source device, however, you can usually count on Gets(m)
		properly handling backspace (erases previous character),
		escape (erase entire line), and ENTER (accept current line).

		Other keys may affect Gets(m) as well.  For example, Gets(m),
		by default, calls Getc which, in turn, usually calls DOS'
		standard input routine.  If you type control-C or break while
		read from DOS' standard input it may abort the program.

		If an error occurs during input (e.g., EOF encountered in
		the middle of a line) Gets(m) returns the error code in
		AX.  If no error occurs, Gets(m) preserves AX.

Include:              	stdlib.a or stdin.a





Routine:  Scanf
---------------

Category:             Character Input Routine

Register on entry:    None

Register on return:   None

Flags affected:       None

Example of usage:   
                      scanf
                      db      "%i  %h  %^s",0
                      dd      i, x, sptr

Description:   * Formatted input from stdlib standard input.
               * Similar to C's scanf routine.
               * Converts ASCII to integer, unsigned, character, string, hex,
		 and long values of the above.
               Scanf provides formatted input in a fashion analogous to
               printf's output facilities.  Actually, it turns out that scanf
               is considerably less useful than printf because it doesn't
               provide reasonable error checking facilities (neither does C's
               version of this routine).  But for quick and dirty programs 
               whose input can be controlled in a rigid fashion (or if you're
               willing to live by "garbage in, garbage out")  scanf provides 
               a convenient way to get input from the user.  Like printf, the
               scanf routine expects you to follow the call with a format 
               string and then a list of (far pointer) memory addresses.  The
               items in the scanf format string take the following form: %^f,
               where f represents d, i, x, h, u, c, x, ld, li, lx, or lu.  
               Like printf, the "^" symbol tells scanf that the address
               following the format string is the address of a (far) pointer
               to the data rather than the address of the data location itself.
               By default, scanf automatically skips any leading whitespace 
               before attempting to read a numeric value.  You can instruct
               scanf to skip other characters by placing that character in the
               format string.  For example, the following call instructs scanf
	       to read three integers separated by commas (and/or whitespace):

                       	      scanf  
			      db                "%i,%i,%i",0
                              dd                 i1,i2,i3

               Whenever scanf encounters a non-blank character in the format
               string, it will skip that character (including multiple
               occurrences of that character) if it appears next in the input
               stream.  Scanf always calls gets to read a new line of text 
               from stdlib's standard input.  If scanf exhausts the format 
               list, it ignores any remaining characters on the line.  If
               scanf exhausts the input line before processing all of the
               format items, it leaves the remaining variables unchanged.
               Scanf always deallocates the storage allocated by gets.


Include:                stdlib.a or stdin.a


