home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / msdos / asmutl / bluebook.arc / FILES.DOC < prev    next >
Text File  |  1986-05-08  |  8KB  |  355 lines
  1. FILES.DOC -- File Manipulation Procedures
  2.  
  3.  
  4.   From `BLUEBOOK of ASSEMBLY ROUTINES for the IBM PC & XT'
  5.         by Christopher L. Morgan
  6.         Copyright (C) 1984 by The Waite Group, Inc.
  7.  
  8.   Purpose: These routines aid file manipulation.  Routines are included to
  9.     transfer files from serial communications to disk, and to filter files.
  10.  
  11.    Contents:
  12.    ---------
  13.    CBUF_CLR    --  Clear the circular buffer
  14.    CBUF_IN    --  Input to circular buffer 
  15.    CBUF_INIT    --  Initialize a circular buffer
  16.    CBUF_OUT    --  Output to a circular buffer
  17.    CBUF_PUT    --  Put a byte into a circular buffer
  18.    CLOS_FIL    --  Close a file
  19.    EMSG_OUT    --  Exception message output
  20.    GET_SPEC    --  Get a file specifier
  21.    MAKE_FIL    --  Create a file
  22.    READ_FIL    --  Read bytes from a file
  23.    SAVE        --  Save a file from communications line to disk
  24.    WRIT_FIL    --  Write bytes to a file
  25.  _____________________________________________________________________________
  26.  
  27.   Overview: These routines require MS/PCDOS 2.+, because they use file handles
  28.     & filters.
  29.     EMSG_OUT reports exceptions to the user.  These codes are extended
  30.     from standard DOS (0,14,19,20,21,&22).
  31.     GET_SPEC gets parameters from the command line, and places
  32.     them where you specify.
  33.     The xxxx_FIL routines are standard and self-explanatory.
  34.     The CBUF_xxxx routines handle input/output for a circular buffer.
  35.     There are four variables and three constants associated with CBUF_xxxx.
  36.     The variables are CBUF & GUAGE (memory variables), an input pointer held
  37.     in DI, and an output pointer held in SI. CBUF is the base address of the
  38.     buffer and GUAGE is the number of items currently in the buffer. As items
  39.     are added to the buffer, they are placed according to DI, and DI is
  40.     incremented to account for them. As items are removed from the buffer,
  41.     they are taken according to SI, and SI is incremented accordingly. The
  42.     CBUF_xxxx constants are BUF_SIZ, NEAREMPTY, & NEARFULL.  BUF_SIZ is the
  43.     total # of bytes allotted to the buffer. NEARFULL & NEAREMPTY are limits
  44.     to how few or many items should be in the buffer at one time. NEARFULL
  45.     helps to prevent buffer overflow. When the buffer hits NEARFULL, the
  46.     routines call a routine to stop the input.  Programmer must adjust NEARFULL
  47.     according to input speed. NEAREMPTY is the trigger to start input again
  48.     after a NEARFULL condition.
  49.      The SAVE routine saves files from one of the two communications lines
  50.     to the disk.  It uses the CBUFF routines.
  51.     COUNT, FILT_WS, & FILT_CR are filters. COUNT counts the number of 
  52.      characters and words in a file. FILT_WS replaces any single CR/LF with a
  53.      `soft' CR/LF, and any double CR/LF with a `soft' and `hard' CR/LF pair.
  54.      FILT_CR strips bit 7 from each byte, adds LF's to CR's, and expands TAB's.
  55.      All these filter programs can serve as models for new filter programs. 
  56.     
  57. ____________________________ FILE ROUTINES ___________________________________
  58.           
  59. EMSG_OUT -- Exception Message Output
  60.  
  61.   Function: This routine sends a specified exception message out through the
  62.     standard output device.
  63.  
  64.   Input: Upon entry, AX contains the exception message number as listed in
  65.     the table below.  This table is an extension of the Error Return Table
  66.     in the DOS 2 Disk Operating System manual.
  67.  
  68.   Output: The output is sent to the standard output device.
  69.  
  70.   Register used: AX is used for input; SI & AX are saved and restored.
  71.  
  72.   Segments referenced: Upon entry, the data segment must contain the text of
  73.     the exception messages as in the following table:
  74.  
  75.     EMSG    DW    EMSG1
  76.         DW    EMSG2
  77.         DW    EMSG3
  78.         DW    EMSG4
  79.         DW    EMSG5
  80.         DW    EMSG6
  81.         DW    EMSG7
  82.         DW    EMSG8
  83.         DW    EMSG9
  84.         DW    EMSG10
  85.         DW    EMSG11
  86.         DW    EMSG12
  87.         DW    EMSG13
  88.         DW    EMSG14
  89.         DW    EMSG15
  90.         DW    EMSG16
  91.         DW    EMSG17
  92.         DW    EMSG18
  93.     EMSG1    DB    CR,LF,'Invalid function number',CR,LF,0 
  94.     EMSG2    DB    CR,LF,'File not found',CR,LF,0
  95.     EMSG3    DB    CR,LF,'Path not found',CR,LF,0
  96.     EMSG4    DB    CR,LF,'Too many open files',CR,LF,0 
  97.     EMSG5    DB    CR,LF,'Access denied',CR,LF,0
  98.     EMSG6    DB    CR,LF,'Invalid handle',CR,LF,0
  99.     EMSG7    DB    CR,LF,'Memory control blocks destroyed',CR,LF,0
  100.     EMSG8    DB    CR,LF,'Insufficient memory',CR,LF,0
  101.     EMSG9    DB    CR,LF,'Invalid memory block address',CR,LF,0
  102.     EMSG10  DB    CR,LF,'Invalid environment',CR,LF,0
  103.     EMSG11    DB    CR,LF,'Invalid format',CR,LF,0
  104.     EMSG12    DB    CR,LF,'Invalid access code',CR,LF,0
  105.     EMSG13    DB    CR,LF,'Invalid data',CR,LF,0
  106.     EMSG14    DB    CR,LF,'Message not in use',CR,LF,0
  107.     EMSG15    DB    CR,LF,'Invalid drive was specified',CR,LF,0
  108.     EMSG16    DB    CR,LF,'Attempted to remove the current directory',CR,LF,0
  109.     EMSG17    DB    CR,LF,'Not same device',CR,LF,0
  110.     EMSG18    DB    CR,LF,'No more files',CR,LF,0
  111.   
  112.   The first part of the table consists of addresses of the messages and the
  113.   second part consists of the actual messages as ASCIIZ strings.
  114.  
  115.   Routines called:  MSG_OUT.
  116. ______________________________________________________________________________
  117. DLP PAGE 216
  118. GET_SPEC
  119.   Function:
  120.  
  121.   Input:
  122.  
  123.   Output:
  124.  
  125.   Registers used:
  126.  
  127.   Segments referenced:
  128.  
  129.   Routines called:
  130.  
  131.   Note:
  132. ______________________________________________________________________________
  133.  
  134. MAKE_FIL
  135.   Function:
  136.  
  137.   Input:
  138.  
  139.   Output:
  140.  
  141.   Registers used:
  142.  
  143.   Segments referenced:
  144.  
  145.   Routines called:
  146.  
  147.   Note:
  148. ______________________________________________________________________________
  149.  
  150. CLOS_FIL
  151.  
  152.   Function:
  153.  
  154.   Input:
  155.  
  156.   Output:
  157.  
  158.   Registers used:
  159.  
  160.   Segments referenced:
  161.  
  162.   Routines called:
  163.  
  164.   Note:
  165. ______________________________________________________________________________
  166.  
  167. WRIT_FIL
  168.  
  169.   Function:
  170.  
  171.   Input:
  172.  
  173.   Output:
  174.  
  175.   Registers used:
  176.  
  177.   Segments referenced:
  178.  
  179.   Routines called:
  180.  
  181.   Note:
  182. ______________________________________________________________________________
  183.  
  184. READ_FIL
  185.  
  186.   Function:
  187.  
  188.   Input:
  189.  
  190.   Output:
  191.  
  192.   Registers used:
  193.  
  194.   Segments referenced:
  195.  
  196.   Routines called:
  197.  
  198.   Note:
  199. ______________________________________________________________________________
  200.  
  201. CBUF_INIT
  202.  
  203.   Function:
  204.  
  205.   Input:
  206.  
  207.   Output:
  208.  
  209.   Registers used:
  210.  
  211.   Segments referenced:
  212.  
  213.   Routines called:
  214.  
  215.   Note:
  216. ______________________________________________________________________________
  217.  
  218. CBUF_PUT
  219.  
  220.   Function:
  221.  
  222.   Input:
  223.  
  224.   Output:
  225.  
  226.   Registers used:
  227.  
  228.   Segments referenced:
  229.  
  230.   Routines called:
  231.  
  232.   Note:
  233. ______________________________________________________________________________
  234.  
  235. CBUF_IN    
  236.  
  237.   Function:
  238.  
  239.   Input:
  240.  
  241.   Output:
  242.  
  243.   Registers used:
  244.  
  245.   Segments referenced:
  246.  
  247.   Routines called:
  248.  
  249.   Note:
  250. ______________________________________________________________________________
  251.  
  252. CBUF_CLR
  253.  
  254.   Function:
  255.  
  256.   Input:
  257.  
  258.   Output:
  259.  
  260.   Registers used:
  261.  
  262.   Segments referenced:
  263.  
  264.   Routines called:
  265.  
  266.   Note:
  267. ______________________________________________________________________________
  268.  
  269. CBUF_OUT
  270.  
  271.   Function:
  272.  
  273.   Input:
  274.  
  275.   Output:
  276.  
  277.   Registers used:
  278.  
  279.   Segments referenced:
  280.  
  281.   Routines called:
  282.  
  283.   Note:
  284. ______________________________________________________________________________
  285.  
  286. SAVE
  287.  
  288.   Function:
  289.  
  290.   Input:
  291.  
  292.   Output:
  293.  
  294.   Registers used:
  295.  
  296.   Segments referenced:
  297.  
  298.   Routines called:
  299.  
  300.   Note:
  301. ______________________________________________________________________________
  302.  
  303. FILT_CR
  304.  
  305.   Function:
  306.  
  307.   Input:
  308.  
  309.   Output:
  310.  
  311.   Registers used:
  312.  
  313.   Segments referenced:
  314.  
  315.   Routines called:
  316.  
  317.   Note:
  318. ______________________________________________________________________________
  319.  
  320. FILT_WS
  321.  
  322.   Function:
  323.  
  324.   Input:
  325.  
  326.   Output:
  327.  
  328.   Registers used:
  329.  
  330.   Segments referenced:
  331.  
  332.   Routines called:
  333.  
  334.   Note:
  335.  
  336. ______________________________________________________________________________
  337.  
  338. COUNT
  339.  
  340.   Function:
  341.  
  342.   Input:
  343.  
  344.   Output:
  345.  
  346.   Registers used:
  347.  
  348.   Segments referenced:
  349.  
  350.   Routines called:
  351.  
  352.   Note:
  353. ______________________________________________________________________________
  354. >>>>> Physical EOF FILES.DOC <<<<<
  355.