FILES.DOC -- File Manipulation Procedures


  From `BLUEBOOK of ASSEMBLY ROUTINES for the IBM PC & XT'
        by Christopher L. Morgan
        Copyright (C) 1984 by The Waite Group, Inc.

  Purpose: These routines aid file manipulation.  Routines are included to
    transfer files from serial communications to disk, and to filter files.

   Contents:
   ---------
   CBUF_CLR	--  Clear the circular buffer
   CBUF_IN	--  Input to circular buffer 
   CBUF_INIT	--  Initialize a circular buffer
   CBUF_OUT	--  Output to a circular buffer
   CBUF_PUT	--  Put a byte into a circular buffer
   CLOS_FIL	--  Close a file
   EMSG_OUT	--  Exception message output
   GET_SPEC	--  Get a file specifier
   MAKE_FIL	--  Create a file
   READ_FIL	--  Read bytes from a file
   SAVE		--  Save a file from communications line to disk
   WRIT_FIL	--  Write bytes to a file
 _____________________________________________________________________________

  Overview: These routines require MS/PCDOS 2.+, because they use file handles
    & filters.
	EMSG_OUT reports exceptions to the user.  These codes are extended
    from standard DOS (0,14,19,20,21,&22).
	GET_SPEC gets parameters from the command line, and places
    them where you specify.
	The xxxx_FIL routines are standard and self-explanatory.
	The CBUF_xxxx routines handle input/output for a circular buffer.
    There are four variables and three constants associated with CBUF_xxxx.
    The variables are CBUF & GUAGE (memory variables), an input pointer held
    in DI, and an output pointer held in SI. CBUF is the base address of the
    buffer and GUAGE is the number of items currently in the buffer. As items
    are added to the buffer, they are placed according to DI, and DI is
    incremented to account for them. As items are removed from the buffer,
    they are taken according to SI, and SI is incremented accordingly. The
    CBUF_xxxx constants are BUF_SIZ, NEAREMPTY, & NEARFULL.  BUF_SIZ is the
    total # of bytes allotted to the buffer. NEARFULL & NEAREMPTY are limits
    to how few or many items should be in the buffer at one time. NEARFULL
    helps to prevent buffer overflow. When the buffer hits NEARFULL, the
    routines call a routine to stop the input.  Programmer must adjust NEARFULL
    according to input speed. NEAREMPTY is the trigger to start input again
    after a NEARFULL condition.
 	The SAVE routine saves files from one of the two communications lines
    to the disk.  It uses the CBUFF routines.
	COUNT, FILT_WS, & FILT_CR are filters. COUNT counts the number of 
     characters and words in a file. FILT_WS replaces any single CR/LF with a
     `soft' CR/LF, and any double CR/LF with a `soft' and `hard' CR/LF pair.
     FILT_CR strips bit 7 from each byte, adds LF's to CR's, and expands TAB's.
     All these filter programs can serve as models for new filter programs. 
    
____________________________ FILE ROUTINES ___________________________________
          
EMSG_OUT -- Exception Message Output

  Function: This routine sends a specified exception message out through the
    standard output device.

  Input: Upon entry, AX contains the exception message number as listed in
    the table below.  This table is an extension of the Error Return Table
    in the DOS 2 Disk Operating System manual.

  Output: The output is sent to the standard output device.

  Register used: AX is used for input; SI & AX are saved and restored.

  Segments referenced: Upon entry, the data segment must contain the text of
    the exception messages as in the following table:

	EMSG	DW	EMSG1
		DW	EMSG2
		DW	EMSG3
		DW	EMSG4
		DW	EMSG5
		DW	EMSG6
		DW	EMSG7
		DW	EMSG8
		DW	EMSG9
		DW	EMSG10
		DW	EMSG11
		DW	EMSG12
		DW	EMSG13
		DW	EMSG14
		DW	EMSG15
		DW	EMSG16
		DW	EMSG17
		DW	EMSG18
	EMSG1	DB	CR,LF,'Invalid function number',CR,LF,0 
	EMSG2	DB	CR,LF,'File not found',CR,LF,0
	EMSG3	DB	CR,LF,'Path not found',CR,LF,0
	EMSG4	DB	CR,LF,'Too many open files',CR,LF,0 
	EMSG5	DB	CR,LF,'Access denied',CR,LF,0
	EMSG6	DB	CR,LF,'Invalid handle',CR,LF,0
	EMSG7	DB	CR,LF,'Memory control blocks destroyed',CR,LF,0
	EMSG8	DB	CR,LF,'Insufficient memory',CR,LF,0
	EMSG9	DB	CR,LF,'Invalid memory block address',CR,LF,0
	EMSG10  DB	CR,LF,'Invalid environment',CR,LF,0
	EMSG11	DB	CR,LF,'Invalid format',CR,LF,0
	EMSG12	DB	CR,LF,'Invalid access code',CR,LF,0
	EMSG13	DB	CR,LF,'Invalid data',CR,LF,0
	EMSG14	DB	CR,LF,'Message not in use',CR,LF,0
	EMSG15	DB	CR,LF,'Invalid drive was specified',CR,LF,0
	EMSG16	DB	CR,LF,'Attempted to remove the current directory',CR,LF,0
	EMSG17	DB	CR,LF,'Not same device',CR,LF,0
	EMSG18	DB	CR,LF,'No more files',CR,LF,0
  
  The first part of the table consists of addresses of the messages and the
  second part consists of the actual messages as ASCIIZ strings.

  Routines called:  MSG_OUT.
______________________________________________________________________________
DLP PAGE 216
GET_SPEC
  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

MAKE_FIL
  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CLOS_FIL

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

WRIT_FIL

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

READ_FIL

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CBUF_INIT

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CBUF_PUT

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CBUF_IN	

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CBUF_CLR

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

CBUF_OUT

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

SAVE

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

FILT_CR

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________

FILT_WS

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:

______________________________________________________________________________

COUNT

  Function:

  Input:

  Output:

  Registers used:

  Segments referenced:

  Routines called:

  Note:
______________________________________________________________________________
>>>>> Physical EOF FILES.DOC <<<<<