home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / z.lbr / ZSDOS3.HZP / ZSDOS3.HLP
Encoding:
Text File  |  1991-11-18  |  11.3 KB  |  242 lines
  1.  Function 17: Search for First   -- Miscellaneous File Functions --
  2.  Function 18: Search for Next
  3.  Function 19: Delete File
  4.  Function 23: Rename File
  5.  Function 26: Set DMA Address
  6.  Function 30: Set File Attributes
  7.  Function 35: Compute File Size
  8.  Function 47: Get Current DMA Address
  9.  Error Codes and Extended Error Codes
  10.  Directory Codes
  11. :
  12.  
  13.      +---------------------------------------------------------------+
  14.      |                FUNCTION 17 -- SEARCH FOR FIRST                |
  15.      +--------------------------------+------------------------------+
  16.      | Entry:  C = 17 (11h)           | Exit:  A = Directory code    |
  17.      |        DE = Address of FCB     |                              |
  18.      |                                |                              |
  19.      +--------------------------------+------------------------------+
  20.  
  21. Returns the first occurrence of a filename matching the one in the file 
  22. control block (FCB), hich can be ambiguous.  The match is based on the 
  23. first 13 bytes of the FCB (drive, name, extent, and, if given, user number. 
  24. Question marks may be used in any or all of these first 13 bytes and in the 
  25. data module byte (FCB+14).  The data module byte is only considered it is a 
  26. "?".
  27.  
  28. If the Extent byte (FCB+12) and the data module byte (FCB+14) contain 
  29. question marks, all given extents of files matching the filename will be 
  30. found.  If the drive byte (FCB+0) contains a question mark, all directory 
  31. entries on the current drive matching the filename, including erased 
  32. entries, will be found.
  33. :
  34.  
  35.      +---------------------------------------------------------------+
  36.      |                FUNCTION 18 -- SEARCH FOR NEXT                 |
  37.      +--------------------------------+------------------------------+
  38.      | Entry:  C = 18 (12h)           | Exit:  A = Directory code    |
  39.      |        DE = Address of FCB     |                              |
  40.      |                                |                              |
  41.      +---------------------------------------------------------------+
  42.  
  43. Called following a call to Function 17, returns the next occurrence of a 
  44. filename matching that in the file control block (FCB), which can be 
  45. ambiguous.  No intervening ZSDOS disk functions are permitted between 
  46. search calls.
  47. :
  48.  
  49.      +---------------------------------------------------------------+
  50.      |                  FUNCTION 19 -- DELETE FILE                   |
  51.      +--------------------------------+------------------------------+
  52.      | Entry:  C = 19 (13h)           | Exit:  A = Error code        |
  53.      |        DE = Address of FCB     |                              |
  54.      |                                |                              |
  55.      +--------------------------------+------------------------------+
  56.  
  57. Deletes all files match that in the file control block (FCB), which can be 
  58. ambiguous.
  59.  
  60. If the drive is read-only, the operation is aborted.  If a matching read- 
  61. only file is encountered or if a wheel-protected file is encountered and 
  62. the wheel byte is not set, the operation is aborted at that point.
  63. :
  64.  
  65.      +---------------------------------------------------------------+
  66.      |                  FUNCTION 23 -- RENAME FILE                   |
  67.      +--------------------------------+------------------------------+
  68.      | Entry:  C = 23 (17h)           | Exit:  A = Error code        |
  69.      |        DE = Address of FCB     |                              |
  70.      |                                |                              |
  71.      +--------------------------------+------------------------------+
  72.  
  73. Renames the file specified in the file control block at FCB+1 to the name 
  74. specified at FCB+17.
  75.  
  76. If a question mark is substituted for any character in the old filename in 
  77. the FCB, the character will not be changed by this function.  File 
  78. attributes, except the Public attribute, are preserved after renaming.
  79.  
  80. The program should check for a pre-existing file with the new name before 
  81. calling this function; otherwise, a duplicate entry could be created.
  82.  
  83. FUNCTION 23 (continued)
  84.  
  85.  
  86.  
  87.                          RENAME FILE CONTROL BLOCK
  88.  
  89.  
  90. offset:   0 1               9      13      17              25    28    31
  91.           | |               |       |       |               |     |     |
  92.           0 O L D F N A M E T Y P 0 0 0 0 0 N E W F N A M E T Y P 0 0 0 0
  93.           | \_____________/ \___/   |       \_____________/ \___/
  94.           |  old filename    type   |        new filename    type
  95.           |                         |
  96.         drive (0-16)               user (0-31)
  97.  
  98. :
  99.  
  100.      +---------------------------------------------------------------+
  101.      |                FUNCTION 26 -- SET DMA ADDRESS                 |
  102.      +--------------------------------+------------------------------+
  103.      | Entry:  C = 26 (1Ah)           | Exit:  None                  |
  104.      |        DE = DMA address        |        (A = 00h)             |
  105.      |                                |                              |
  106.      +--------------------------------+------------------------------+
  107.  
  108. Sets the starting address of a 128-byte direct memory access buffer used 
  109. for disk reads and writes and file stamp transfers.  The default DMA 
  110. address is 80h, if this function is not used to change it.
  111. :
  112.  
  113.      +---------------------------------------------------------------+
  114.      |              FUNCTION 30 -- SET FILE ATTRIBUTES               |
  115.      +--------------------------------+------------------------------+
  116.      | Entry:  C = 30 (1Eh)           | Exit:  A = Error code        |
  117.      |        DE = Address of FCB     |                              |
  118.      |                                |                              |
  119.      +--------------------------------+------------------------------+
  120.  
  121. Sets file attributes from the specified file control block (FCB).  Before 
  122. calling this function set or reset the high bits of the filename (FCB+1 to 
  123. FCB+8) and filetype (FCB+9 to FCB+11) which correspond to the attributes to 
  124. be set or reset.  The filename may be ambiguous.
  125.  
  126. The attributes associated with the filename are usually referred to as F1 
  127. to F8 (FCB+1 to FCB+8), while those associated with the filetype are 
  128. usually referred to as T1 to T3 (FCB+9 to FCB+11).
  129.  
  130. Attributes F5, F6, and F7 are reserved and should never be set.
  131.  
  132. FUNCTION 30 (continued)
  133.  
  134.                         ATTRIBUTES THAT MAY BE SET
  135.  
  136.      F1   no meaning to ZSDOS, but available to user.
  137.      F2   public attribute, allows file to be accessed by an unambiguous 
  138.           filespec from any user area on the same drive.
  139.      F3   no datestamp attribute, suppresses access date stamping.
  140.      F4   no meaning to ZSDOS, but available to user.
  141.      F8   wheel protect attribute, under ZCPR prevents erasing, renaming, 
  142.           writing to, or change attributes of file unless wheel byte is 
  143.           set.
  144.      T1   read-only attributes, prevents erasing, renaming, or writing to 
  145.           file.
  146.      T2   system attribute, causes many programs to ignore the file and 
  147.           allows the file to be found along the path in path access mode.
  148.      T3   archive attribute, indicates the file is not changed since the 
  149.           attribute was set.
  150.  
  151. FUNCTION 30 (continued)
  152.  
  153.  
  154.                             FILE ATTRIBUTES MAP
  155.  
  156.                user defined     user defined
  157.                         |           |
  158.                         |no datestmp|                 read-only
  159.                         |       |   |                   | system
  160.                         |public |   |   reserved  wheel |   | archive
  161.                         |   |   |   |   ____|_____  |   |   |   |
  162.                         f1  f2  f3  f4  f5  f6  f7  f8  t1  t2  t3
  163.                     0   F   I   L   E   N   A   M   E   T   Y   P 
  164.                     |   \___________________________/   \_______/
  165.                     |             filename                type
  166.                   drive
  167. :
  168.  
  169.      +---------------------------------------------------------------+
  170.      |               FUNCTION 35 -- COMPUTE FILE SIZE                |
  171.      +--------------------------------+------------------------------+
  172.      | Entry:  C = 35 (23h)           | Exit:  A = Error code        |
  173.      |        DE = Address of FCB     |    (FCB+33 to FCB+35 =       |
  174.      |                                |        last record + 1)      |
  175.      +--------------------------------+------------------------------+
  176.  
  177. Computes the size of a file based on its last random record.  After this 
  178. call the file control block random record bytes (FCB+33, FCB+34, and 
  179. FCB+35) will contain the number of the last record plus one.
  180.  
  181. While accurate for sequential files, this method is not accurate for random 
  182. files with missing extents ("holes").
  183.  
  184. This function is commonly used for appending to an existing file by 
  185. positioning the pointer past the file's last record.
  186. :
  187.  
  188.      +---------------------------------------------------------------+
  189.      |           FUNCTION 47 -- RETURN CURRENT DMA ADDRESS           |
  190.      +-------------------------------+-------------------------------+
  191.      | Entry:  C = 47 (2Fh)          | Exit: HL = DMA address        |
  192.      |                               |                               |
  193.      |                               |                               |
  194.      +-------------------------------+-------------------------------+
  195.  
  196. Returns the address of the current DMA buffer.  The direct memory access 
  197. address is used for all file transfers and file stamp functions.
  198. :
  199.  
  200.                                 ERROR CODES
  201.  
  202.                 (Returned by Functions 19, 23, 30, and 35)
  203.  
  204.                             A = 0      no error
  205.                             A = FFh    error
  206.  
  207.                            EXTENDED ERROR CODES
  208.  
  209. These codes are returned by disk and file functions when Return Error mode 
  210. is set using Function 45.  If FFh is returned in A, then H contains an 
  211. extended error code.  These codes are not compatible with the extended 
  212. codes returned by CP/M Plus.
  213.  
  214.                    A = FFh   extended error flag
  215.                    H = 0     no error
  216.                    H = 1     disk I/O error (bad sector)
  217.                    H = 2     read-only disk
  218.                    H = 3     write-protected file
  219.                    H = 4     invalid drive (Select)
  220. :
  221.  
  222.                               DIRECTORY CODES
  223.  
  224.               (Returned by Functions 15, 16, 17, 18, and 22)
  225.  
  226.                             A = 0-3   no error
  227.                             A = FFh   error
  228.  
  229. Directory codes 0 to 3 are actually multipliers used to find the directory 
  230. entry of the desired file in the current DMA buffer.  The buffer will 
  231. contain a sector (128 bytes) of four 32-byte directory entries.  The return 
  232. code points to one of the entries, which can be found by multiplying the 
  233. code by 32 and adding the resulting offset to the buffer address:
  234.           rrca                ; multiply return code by 32
  235.           rrca
  236.           rrca
  237.           ld   l,a            ; put offset in HL
  238.           ld   h,0
  239.           ld   de,buffaddr    ; add offset to DMA buffer address
  240.           add  hl,de
  241. Now HL contains the address of the directory record for the desired file.
  242.