home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / z.lbr / ZSDOS2.HZP / ZSDOS2.HLP
Encoding:
Text File  |  1991-11-18  |  11.3 KB  |  236 lines
  1.  Function 15: Open File      -- File I/O Functions --
  2.  Function 16: Close File
  3.  Function 20: Read Sequential 
  4.  Function 21: Write Sequential
  5.  Function 22: Make File
  6.  Function 33: Read Random
  7.  Function 34: Write Random
  8.  Function 36: Set Random Record
  9.  Function 40: Write Random Zero Fill
  10.  Extended Error Codes
  11.  Directory Codes
  12.  Read/Write Codes
  13. :
  14.  
  15.      +---------------------------------------------------------------+
  16.      |                   FUNCTION 15 -- OPEN FILE                    |
  17.      +--------------------------------+------------------------------+
  18.      | Entry:  C = 15 (0Fh)           | Exit:  A = Directory code    |
  19.      |        DE = Address of FCB     |                              |
  20.      |                                |                              |
  21.      +--------------------------------+------------------------------+
  22.  
  23. Opens the file specified in the file control block (FCB).  ZSDOS can use 
  24. the public attribute of the filename and the path to locate the file.  On 
  25. return, if the open is successful, the user number at FCB+13 will be set to 
  26. the user in which the file was found.  The user number is OR'd with 80h, 
  27. which sets its high bit.
  28.  
  29. Bytes in the file control block through FCB+14 should be initialized.  To 
  30. get ZSDOS to use the user number byte at FCB+13 set this byte to the user 
  31. number OR'd with 80h and set the error mode to non-zero using Function 45.
  32.  
  33. If the path or public attribute was used to find the file, the seventh 
  34. character of the filename (F7) will have its high bit set on return.
  35. :
  36.  
  37.      +---------------------------------------------------------------+
  38.      |                   FUNCTION 16 -- CLOSE FILE                   |
  39.      +--------------------------------+------------------------------+
  40.      | Entry:  C = 16 (10h)           | Exit:  A = Directory code    |
  41.      |        DE = Address of FCB     |                              |
  42.      |                                |                              |
  43.      +--------------------------------+------------------------------+
  44.  
  45. Closes the file specified in the file control block (FCB), if it exists.
  46.  
  47. Internal buffers are flushed to the disk and the directory entry of the 
  48. file is updated, if it was written to.  It is good practice to close a 
  49. file, even it was only open for reading.
  50. :
  51.  
  52.      +---------------------------------------------------------------+
  53.      |                FUNCTION 20 -- READ SEQUENTIAL                 |
  54.      +--------------------------------+------------------------------+
  55.      | Entry:  C = 20 (14h)           | Exit:  A = Read/Write code   |
  56.      |        DE = Address of FCB     |                              |
  57.      |                                |                              |
  58.      +--------------------------------+------------------------------+
  59.  
  60. Reads from the next record of a file opened with Function 15, transferring 
  61. 128 bytes to the current DMA buffer.
  62.  
  63. Repeated calls will read successive records from the file sequentially.
  64. :
  65.  
  66.      +---------------------------------------------------------------+
  67.      |                FUNCTION 21 -- WRITE SEQUENTIAL                |
  68.      +--------------------------------+------------------------------+
  69.      | Entry:  C = 21 (15h)           | Exit:  A = Read/Write code   |
  70.      |        DE = Address of FCB     |                              |
  71.      |                                |                              |
  72.      +--------------------------------+------------------------------+
  73.  
  74. Writes to the next record of a file opened with Function 15, transferring 
  75. 128 bytes from the current DMA buffer.
  76.  
  77. Repeated call will write to successive records of the file sequentially.  
  78. New allocation blocks are allocated and new file extents are opened or 
  79. created as necessary.
  80.  
  81. The archive attribute  of the first directory extent of a file will be 
  82. reset if it is written to by this function.
  83.  
  84. Incomplete files should always be closed via Function 16 before they are 
  85. deleted via Function 19, to prevent unused blocks for remaining allocated.
  86. :
  87.  
  88.      +---------------------------------------------------------------+
  89.      |                   FUNCTION 22 -- MAKE FILE                    |
  90.      +--------------------------------+------------------------------+
  91.      | Entry:  C = 22 (16h)           | Exit:  A = Directory code    |
  92.      |        DE = Address of FCB     |                              |
  93.      |                                |                              |
  94.      +--------------------------------+------------------------------+
  95.  
  96. Create a file with the filename specified in the file control block (FCB).  
  97. No disk data space is allocated, but a directory entry is written and the 
  98. file is open for writing after this call.
  99.  
  100. The program should check for a pre-existing file before calling this 
  101. function; otherwise, a duplicate directory entry could be created.
  102. :
  103.  
  104.      +---------------------------------------------------------------+
  105.      |                  FUNCTION 33 -- READ RANDOM                   |
  106.      +--------------------------------+------------------------------+
  107.      | Entry:  C = 33 (21h)           | Exit:  A = Read/Write code   |
  108.      |        DE = Address of FCB     |                              |
  109.      |                                |                              |
  110.      +--------------------------------+------------------------------+
  111.  
  112. Reads a random record from the file in the file control block (FCB).
  113.  
  114. Before each call initialize the FCB for the record to read by placing the 
  115. three-byte record number in FCB+33, FCB+34, and FCB+35, with the least 
  116. significant byte in FCB+33 and the most significant byte in FCB+35.
  117.  
  118. Unlike a sequential read, the record number is not advanced after each 
  119. read.  The random record number must be set before each call.  Since each 
  120. random read operation automatically sets the extent and record values into 
  121. the specified FCB, however, the file can then be sequentially read or 
  122. written, starting from the currently accessed position.
  123. :
  124.  
  125.      +---------------------------------------------------------------+
  126.      |                  FUNCTION 34 -- WRITE RANDOM                  |
  127.      +--------------------------------+------------------------------+
  128.      | Entry:  C = 34 (22h)           | Exit:  A = Read/Write code   |
  129.      |        DE = Address of FCB     |                              |
  130.      |                                |                              |
  131.      +--------------------------------+------------------------------+
  132.  
  133. Writes a random record to the file in the file control block (FCB).
  134.  
  135. Before each call initialize the FCB for the record to write by placing the 
  136. three-byte record number in FCB+33, FCB+34, and FCB+35, with the least 
  137. significant byte in FCB+33 and the most significant byte in FCB+35.
  138.  
  139. Unlike a sequential write, the record number is not advanced after each 
  140. write.  The random record number must be set before each call.  Since each 
  141. random write operation automatically sets the extent and record values into 
  142. the specified FCB, however, the file can then be sequentially read or 
  143. written, starting from the currently accessed position.
  144. :
  145.  
  146.      +---------------------------------------------------------------+
  147.      |               FUNCTION 36 -- SET RANDOM RECORD                |
  148.      +--------------------------------+------------------------------+
  149.      | Entry:  C = 36 (24h)           | Exit:  A = 00h               |
  150.      |        DE = Address of FCB     |                              |
  151.      |                                |                              |
  152.      +--------------------------------+------------------------------+
  153.  
  154. Sets random record number in the file control block (FCB) to the current 
  155. position in a file after it has been read or written sequentially.
  156.  
  157. Repeatedly calling this function while writing sequentially allows the 
  158. building of an index of the file's records for later random access.
  159. :
  160.  
  161.      +---------------------------------------------------------------+
  162.      |          FUNCTION 40 -- WRITE RANDOM WITH ZERO FILL           |
  163.      +--------------------------------+------------------------------+
  164.      | Entry:  C = 40 (28h)           | Exit:  A = Read/Write code   |
  165.      |        DE = Address of FCB     |                              |
  166.      |                                |                              |
  167.      +--------------------------------+------------------------------+
  168.  
  169. Writes a random record to the file in the file control block (FCB), like 
  170. Function 34, but unwritten records are filled with zeros, instead of 
  171. remaining as missing extents or "holes" filled with garbage.
  172.  
  173. Before each call initialize the FCB for the record to write by placing the 
  174. three-byte record number in FCB+33, FCB+34, and FCB+35, with the least 
  175. significant byte in FCB+33 and the most significant byte in FCB+35.
  176.  
  177. The record number is not advanced after each write, so the random record 
  178. number must be set before each call.  Each random write operation 
  179. automatically sets the extent and record values into the specified FCB, 
  180. however, so the file can be sequentially read or written, starting from the 
  181. currently accessed position.
  182. :
  183.  
  184.                            EXTENDED ERROR CODES
  185.  
  186. These codes are returned by disk and file functions when Return Error mode 
  187. is set using Function 45.  If FFh is returned in A, then H contains an 
  188. extended error code.  These codes are not compatible with the extended 
  189. codes returned by CP/M Plus.
  190.  
  191.                    A = FFh   extended error flag
  192.                    H = 0     no error
  193.                    H = 1     disk I/O error (bad sector)
  194.                    H = 2     read-only disk
  195.                    H = 3     write-protected file
  196.                    H = 4     invalid drive (Select)
  197. :
  198.  
  199.                               DIRECTORY CODES
  200.  
  201.               (Returned by Functions 15, 16, 17, 18, and 22)
  202.  
  203.                             A = 0-3   no error
  204.                             A = FFh   error
  205.  
  206. Directory codes 0 to 3 are actually multipliers used to find the directory 
  207. entry of the desired file in the current DMA buffer.  The buffer will 
  208. contain a sector (128 bytes) of four 32-byte directory entries.  The return 
  209. code points to one of the entries, which can be found by multiplying the 
  210. code by 32 and adding the resulting offset to the buffer address:
  211.           rrca                ; multiply return code by 32
  212.           rrca
  213.           rrca
  214.           ld   l,a            ; put offset in HL
  215.           ld   h,0
  216.           ld   de,buffaddr    ; add offset to DMA buffer address
  217.           add  hl,de
  218. Now HL contains the address of the directory record for the desired file.
  219. :
  220.  
  221.                              READ/WRITE CODES
  222.  
  223.               (Returned by Functions 20, 21, 33, 34, and 40)
  224.  
  225.        A = 0     no error
  226.  
  227.        A = 1     for read:  end of file
  228.                  for write:  directory full
  229.  
  230.        A = 2     disk full
  231.  
  232.        A = 3     for random read or write:  close error
  233.        A = 4     for random read:  reading empty record
  234.        A = 5     for random write:  directory full
  235.        A = 6     for random read or write:  random record too large
  236.