 Function 17: Search for First   -- Miscellaneous File Functions --
 Function 18: Search for Next
 Function 19: Delete File
 Function 23: Rename File
 Function 26: Set DMA Address
 Function 30: Set File Attributes
 Function 35: Compute File Size
 Function 47: Get Current DMA Address
 Error Codes and Extended Error Codes
 Directory Codes
:

     +---------------------------------------------------------------+
     |                FUNCTION 17 -- SEARCH FOR FIRST                |
     +--------------------------------+------------------------------+
     | Entry:  C = 17 (11h)           | Exit:  A = Directory code    |
     |        DE = Address of FCB     |                              |
     |                                |                              |
     +--------------------------------+------------------------------+

Returns the first occurrence of a filename matching the one in the file 
control block (FCB), hich can be ambiguous.  The match is based on the 
first 13 bytes of the FCB (drive, name, extent, and, if given, user number. 
Question marks may be used in any or all of these first 13 bytes and in the 
data module byte (FCB+14).  The data module byte is only considered it is a 
"?".

If the Extent byte (FCB+12) and the data module byte (FCB+14) contain 
question marks, all given extents of files matching the filename will be 
found.  If the drive byte (FCB+0) contains a question mark, all directory 
entries on the current drive matching the filename, including erased 
entries, will be found.
:

     +---------------------------------------------------------------+
     |                FUNCTION 18 -- SEARCH FOR NEXT                 |
     +--------------------------------+------------------------------+
     | Entry:  C = 18 (12h)           | Exit:  A = Directory code    |
     |        DE = Address of FCB     |                              |
     |                                |                              |
     +---------------------------------------------------------------+

Called following a call to Function 17, returns the next occurrence of a 
filename matching that in the file control block (FCB), which can be 
ambiguous.  No intervening ZSDOS disk functions are permitted between 
search calls.
:

     +---------------------------------------------------------------+
     |                  FUNCTION 19 -- DELETE FILE                   |
     +--------------------------------+------------------------------+
     | Entry:  C = 19 (13h)           | Exit:  A = Error code        |
     |        DE = Address of FCB     |                              |
     |                                |                              |
     +--------------------------------+------------------------------+

Deletes all files match that in the file control block (FCB), which can be 
ambiguous.

If the drive is read-only, the operation is aborted.  If a matching read- 
only file is encountered or if a wheel-protected file is encountered and 
the wheel byte is not set, the operation is aborted at that point.
:

     +---------------------------------------------------------------+
     |                  FUNCTION 23 -- RENAME FILE                   |
     +--------------------------------+------------------------------+
     | Entry:  C = 23 (17h)           | Exit:  A = Error code        |
     |        DE = Address of FCB     |                              |
     |                                |                              |
     +--------------------------------+------------------------------+

Renames the file specified in the file control block at FCB+1 to the name 
specified at FCB+17.

If a question mark is substituted for any character in the old filename in 
the FCB, the character will not be changed by this function.  File 
attributes, except the Public attribute, are preserved after renaming.

The program should check for a pre-existing file with the new name before 
calling this function; otherwise, a duplicate entry could be created.

FUNCTION 23 (continued)



                         RENAME FILE CONTROL BLOCK


offset:   0 1               9      13      17              25    28    31
          | |               |       |       |               |     |     |
          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
          | \_____________/ \___/   |       \_____________/ \___/
          |  old filename    type   |        new filename    type
          |                         |
        drive (0-16)               user (0-31)

:

     +---------------------------------------------------------------+
     |                FUNCTION 26 -- SET DMA ADDRESS                 |
     +--------------------------------+------------------------------+
     | Entry:  C = 26 (1Ah)           | Exit:  None                  |
     |        DE = DMA address        |        (A = 00h)             |
     |                                |                              |
     +--------------------------------+------------------------------+

Sets the starting address of a 128-byte direct memory access buffer used 
for disk reads and writes and file stamp transfers.  The default DMA 
address is 80h, if this function is not used to change it.
:

     +---------------------------------------------------------------+
     |              FUNCTION 30 -- SET FILE ATTRIBUTES               |
     +--------------------------------+------------------------------+
     | Entry:  C = 30 (1Eh)           | Exit:  A = Error code        |
     |        DE = Address of FCB     |                              |
     |                                |                              |
     +--------------------------------+------------------------------+

Sets file attributes from the specified file control block (FCB).  Before 
calling this function set or reset the high bits of the filename (FCB+1 to 
FCB+8) and filetype (FCB+9 to FCB+11) which correspond to the attributes to 
be set or reset.  The filename may be ambiguous.

The attributes associated with the filename are usually referred to as F1 
to F8 (FCB+1 to FCB+8), while those associated with the filetype are 
usually referred to as T1 to T3 (FCB+9 to FCB+11).

Attributes F5, F6, and F7 are reserved and should never be set.

FUNCTION 30 (continued)

                        ATTRIBUTES THAT MAY BE SET

     F1   no meaning to ZSDOS, but available to user.
     F2   public attribute, allows file to be accessed by an unambiguous 
          filespec from any user area on the same drive.
     F3   no datestamp attribute, suppresses access date stamping.
     F4   no meaning to ZSDOS, but available to user.
     F8   wheel protect attribute, under ZCPR prevents erasing, renaming, 
          writing to, or change attributes of file unless wheel byte is 
          set.
     T1   read-only attributes, prevents erasing, renaming, or writing to 
          file.
     T2   system attribute, causes many programs to ignore the file and 
          allows the file to be found along the path in path access mode.
     T3   archive attribute, indicates the file is not changed since the 
          attribute was set.

FUNCTION 30 (continued)


                            FILE ATTRIBUTES MAP

               user defined     user defined
                        |           |
                        |no datestmp|                 read-only
                        |       |   |                   | system
                        |public |   |   reserved  wheel |   | archive
                        |   |   |   |   ____|_____  |   |   |   |
                        f1  f2  f3  f4  f5  f6  f7  f8  t1  t2  t3
                    0   F   I   L   E   N   A   M   E   T   Y   P 
                    |   \___________________________/   \_______/
                    |             filename                type
                  drive
:

     +---------------------------------------------------------------+
     |               FUNCTION 35 -- COMPUTE FILE SIZE                |
     +--------------------------------+------------------------------+
     | Entry:  C = 35 (23h)           | Exit:  A = Error code        |
     |        DE = Address of FCB     |    (FCB+33 to FCB+35 =       |
     |                                |        last record + 1)      |
     +--------------------------------+------------------------------+

Computes the size of a file based on its last random record.  After this 
call the file control block random record bytes (FCB+33, FCB+34, and 
FCB+35) will contain the number of the last record plus one.

While accurate for sequential files, this method is not accurate for random 
files with missing extents ("holes").

This function is commonly used for appending to an existing file by 
positioning the pointer past the file's last record.
:

     +---------------------------------------------------------------+
     |           FUNCTION 47 -- RETURN CURRENT DMA ADDRESS           |
     +-------------------------------+-------------------------------+
     | Entry:  C = 47 (2Fh)          | Exit: HL = DMA address        |
     |                               |                               |
     |                               |                               |
     +-------------------------------+-------------------------------+

Returns the address of the current DMA buffer.  The direct memory access 
address is used for all file transfers and file stamp functions.
:

                                ERROR CODES

                (Returned by Functions 19, 23, 30, and 35)

                            A = 0      no error
                            A = FFh    error

                           EXTENDED ERROR CODES

These codes are returned by disk and file functions when Return Error mode 
is set using Function 45.  If FFh is returned in A, then H contains an 
extended error code.  These codes are not compatible with the extended 
codes returned by CP/M Plus.

                   A = FFh   extended error flag
                   H = 0     no error
                   H = 1     disk I/O error (bad sector)
                   H = 2     read-only disk
                   H = 3     write-protected file
                   H = 4     invalid drive (Select)
:

                              DIRECTORY CODES

              (Returned by Functions 15, 16, 17, 18, and 22)

                            A = 0-3   no error
                            A = FFh   error

Directory codes 0 to 3 are actually multipliers used to find the directory 
entry of the desired file in the current DMA buffer.  The buffer will 
contain a sector (128 bytes) of four 32-byte directory entries.  The return 
code points to one of the entries, which can be found by multiplying the 
code by 32 and adding the resulting offset to the buffer address:
          rrca                ; multiply return code by 32
          rrca
          rrca
          ld   l,a            ; put offset in HL
          ld   h,0
          ld   de,buffaddr    ; add offset to DMA buffer address
          add  hl,de
Now HL contains the address of the directory record for the desired file.
