home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / assembler / thesource / volume1 / source / system / dostools.lha / WarLib.DOC < prev   
Encoding:
Text File  |  1990-12-19  |  8.6 KB  |  231 lines
  1. ; WARLIB.DOC   Library routines by Warren A. Ring
  2.  
  3. OpenDOSLibrary  :    This routine opens the DOS liibrary
  4.  
  5. CloseDOSLibrary :    This routine closes the DOS library
  6.  
  7. OpenFile :           This routine opens an already-existing file
  8.  
  9.                      In:  A0 => a string buffer containing the filename
  10.                      Out: A1 => the file handle (0 = file doesn't exist)
  11.                      Zero Flag = Clear if the file exists,
  12.                      Set if the file doesn't exist
  13.  
  14. CreateFile :         This routine creates a new file
  15.  
  16.                      In:  A0 => a string buffer containing the filename
  17.                      Out: A1 => the file handle (0 = file could not be created)
  18.                      Zero Flag = Clear if the file was created,
  19.                      Set if the file wasn't created
  20.  
  21. Notes: This routine deletes any already-existing file of the same name.
  22.        A create operation may fail because an already-existing file under
  23.        the same name has its protection attribute set, or there is
  24.        insufficient disk space to create the new file.
  25.  
  26. DeleteFile :         This routine deletes a file
  27.  
  28.                      In:  A0 => a string buffer containing the filename
  29.                      Out: D0 = the status (0 = file could not be deleted)
  30.  
  31. Note:  A delete operation may fail because the existing file has its
  32.        protection attribute set.
  33.  
  34. ReadFile :           This routine reads a record from a file
  35.  
  36.                      In:  A0 => the file handle
  37.                      A1 => a string buffer to receive the data from the file
  38.                      Out: D0 = the number of characters read from the file
  39.  
  40. Note: This routine overwrites any data already in the string buffer
  41.  
  42. WriteFile :          This routine writes a record to a file
  43.  
  44.                      In:  A0 => the file handle
  45.                      A1 => a string buffer containing the data for the file
  46.                      Out: D0 = the number of characters written to the file
  47.                      (-1 = write error, possibly disk full)
  48.  
  49. SeekFile :           This routine moves the position in a file at which the
  50.                      next read or write is to take place.
  51.  
  52.                      In:  A0 => the file handle
  53.                      D0 = the offset
  54.                      D1 = the mode:
  55.                      -1 = the offset is from the beginning of the file
  56.                       0 = the offset is from the current position in the file
  57.                       1 = the offset is from the end of file
  58.                      Out: D0 = the previous position
  59.                      (-1 = seek error)
  60.  
  61. Notes: When a file is opened, the position at which the next read or write
  62.        is to take place is the beginning of file.  This position advances
  63.        to the byte just beyond the end of each record as that record is
  64.        read, so that if you read a file sequentially, you need never use the
  65.        Seek system call.
  66.  
  67.        If you wish to append data to the end of a file, you seek with an
  68.        offset of zero, and a mode of 1.
  69.  
  70. CloseFile :          This routine closes a previously-opened file.
  71.  
  72.                      In: A0 => the file handle
  73.  
  74. RenameFile :         This routine renames a file
  75.  
  76.                      In:  A0 => a string buffer containing the current filename
  77.                      A1 => a string buffer containing the new filename
  78.                      Out: D0 = the status (0 = file could not be renamed)
  79.  
  80. Notes: Directory names may be included in the filenames.  Thus, this
  81.        function can serve as a move function within a volume.
  82.  
  83.        A delete operation may fail because the destination file already
  84.        exists, or because a named directory doesn't exist.
  85.  
  86.  
  87. DisplayCrlf :         Outputs a carriage ret and line feed
  88.  
  89. DisplaySpace :        Outputs a space
  90.  
  91. Left_                 BASIC Fn: B$ = Left$(A$, I)
  92.                                <A1>       <A0> D0
  93.  
  94.                       In: A0 => source buffer
  95.                       A1 => dest buffer
  96.                       D0 = Number of bytes to copy
  97.  
  98. Mid_                  BASIC Fn: B$ = Mid$(A$, I, J)
  99.                                <A1>      <A0> D0 D1
  100.  
  101.                       In: A0 => source buffer
  102.                       A1 => dest buffer
  103.                       D0 = The position in A$ to start copying
  104.                       D1 = Number of bytes to copy
  105.  
  106. Right_                BASIC Fn: B$ = Right$(A$, I)
  107.                                <A1>        <A0> D0
  108.  
  109.                       In: A0 => source buffer
  110.                       A1 => dest buffer
  111.                       D0 = The number of bytes in A$, from the right end,
  112.                            to start copying
  113.  
  114. StrCpy_               BASIC Fn: B$ = A$
  115.                                <A1> <A0>
  116.  
  117.                       In: A0 => source buffer (A$)
  118.                       A1 => dest buffer (B$)
  119.  
  120. StrCat_               BASIC Fn: B$ = B$ + A$
  121.  
  122.                       In: A0 => source buffer (A$)
  123.                       A1 => dest buffer (B$)
  124.  
  125.  
  126. StrCmp_               C fn: I = (A$==B$);
  127.  
  128.                       This routine indicates whether or not A$ = B$
  129.  
  130.                       In: A0 => source buffer (A$)
  131.                       A1 => dest buffer (B$)
  132.                       Out: <Zero flag> = Set if the strings are equal,
  133.                       = Clear if the strings are unequal
  134.  
  135. StrLen_               BASIC Fn: I = LEN(A$)
  136.  
  137.                       This routine indicates the current length of a string
  138.  
  139.                       In:  A0 => the buffer (A$)
  140.                       Out: D0 = the current useage of A$
  141.  
  142.  
  143. Scanw_                This routine scans a string for the next visible word
  144.  
  145.                       In:  ScanPointer => the next byte in the string to be
  146.                                           scanned
  147.                       ScanCounter = the number of bytes in the string remaining
  148.                       to be scanned
  149.                       A0 => the dest buffer
  150.                       Out: ScanPointer, ScanCounter are updated
  151.  
  152. Note: This routine skips over spaces, tabs, and other invisible characters
  153.  
  154. Scana_                This routine scans a string for the next alphanumeric word
  155.  
  156.                       In:  ScanPointer => the next byte in the string to be
  157.                                           scanned
  158.                       ScanCounter = the number of bytes in the string remaining
  159.                       to be scanned
  160.                       A0 => the dest buffer
  161.                       Out: ScanPointer, ScanCounter are updated
  162.  
  163. Note: This routine skips over spaces, tabs, and invisible characters
  164.       including non-alphanumeric characters
  165.  
  166.  
  167. Scanc_                This routine scans a string for the next character
  168.  
  169.                       In:  ScanPointer => the next byte in the string to be
  170.                                           scanned
  171.                       ScanCounter = the number of bytes in the string remaining
  172.                       to be scanned
  173.                       A0 => the dest buffer
  174.                       Out: ScanPointer, ScanCounter are updated
  175.  
  176. ItoA_                 BASIC Fn: A$ = STR$(I)
  177.                                (A0)      (D0)
  178.  
  179.                       This routine converts a signed integer from binary to a
  180.                       decimal ASCII string.
  181.    
  182.  
  183. AtoI_                 BASIC Fn: I = VAL(A$)
  184.                                (D0)    (A0)
  185.  
  186.                       This routine converts a decimal ASCII string to a signed
  187.                       binary integer. 
  188.  
  189.  
  190. HAtoI_                BASIC Fn: I = HEX(A$)
  191.                                (D0)    (A0)
  192.  
  193.                       This routine converts a hex-ASCII string to a binary
  194.                       integer.
  195.  
  196. Note: Conversion stops if a non-hex-ASCII character is encountered in
  197.       the string.
  198.  
  199.  
  200. ItoHA8_               BASIC Fn: A$ = STR8HEX$(I)
  201.                                (A0)          (D0)
  202.  
  203. ItoHA4_               BASIC Fn: A$ = STR4HEX$(I)
  204.                                (A0)          (D0)
  205.  
  206. ItoHA2_               BASIC Fn: A$ = STR2HEX$(I)
  207.                                (A0)          (D0)
  208.  
  209.  
  210. ItoHA1_               BASIC Fn: A$ = STR1HEX$(I)
  211.                                (A0)          (D0)
  212.  
  213.  
  214. ItoHA_                BASIC Fn: A$ = STRHEX$(I)
  215.                                (A0)         (D0)
  216.  
  217.                       In: D1 = the number of hex-ASCII characters to convert
  218.  
  219.  
  220. IsHexASCII             Is hex-ASCII routine
  221.  
  222.                        This routine determines whether or not a character
  223.                         is a valid hex-ASCII character
  224.  
  225.                        In: <D0.B> = the character
  226.  
  227.                        Out: <Zero> = Clear if the character is a hex-ASCII
  228.                                      character,
  229.                                    = Set if the character is not a hex-
  230.                                      ASCII character
  231.