Firmware function CAS CATALOG in disc mode

This article originally came from Kevin Thackers' archive at http://www.cpctech.org.uk.

The "CAS CATALOG" firmware function is designed to catalogue a cassette or disc.

If disc operations are enabled, e.g. after a |DISC command, this function will get the directory of a disc.

This function performs the same as the BASIC "CAT" instruction.

The function has the following description:

CAS CATALOG (&BC9B)

Entry conditions:

• DE = address of a 2k buffer

Exit conditions:

• If the catalog succeeded:
  • carry true. zero false. A corrupt
• If the catalog failed:
  • carry false. zero false. V1.0: A corrupt, V1.1: A = &0E
• BC,DE,HL,IX and other flags corrupt.

In disc mode the 2K buffer is used and contains a list of 14-byte records. Each record identifies a single file on the disc. The records are listed in increasing alphabetical order.

In disc mode, if the catalog succeeded, DE contains the free space remaining on the disc in K.

Each record has the following format:

(Multi-byte values are stored in little endian format)

Offset from start of record	Count	Description
0	1	Marker (note 1)
1	8	Name part of filename (note 2)
9	3	Extension part of filename (note 3)
12	2	Size of file in Kilobytes

Notes:

1. This will be &FF to indicate a record exists and has valid data. If &00, the record is not used and this is the end of the file list.
2. The filename is taken from the disc and is in upper-case and is padded with spaces if it is less than 8 characters. AMSDOS can't use file's with lower-case letters in the name.
3. The extension is taken from the disc and is in upper-case. It is padded with spaces if it is less than 3 characters.
   • Bit 7 of byte 0 of the extension is "1" if the file is hidden/system, otherwise the file is listed,
   • Bit 7 of byte 1 of the extension is "1" if the file is read-only, otherwise the file is read/write,
   • Bit 7 of byte 2 of the extension isn't used.
4. Any hidden files will not be listed.
5. The list will only contain files from the current user. (defined with |USER command)
6. The buffer can hold up to 146 file-names, which is plenty for the standard DATA, SYSTEM and IBM formats. However, some DOS's allow more directory entries, in this case, the buffer should be made larger. The maximum number of directory entries I have seen used is 256, therefore a buffer of 3.6K should be large enough.
7. This function will print the filenames to the screen. If we don't want this to happen then we should disable text output. This can be done with "TXT VDU DISABLE" firmware function. (We can use "TXT VDU ENABLE" after to enable text output again). If text output is disabled, then disc error messages will not be displayed, but AMSDOS will still wait for a key to be pressed. Use "BIOS SET MESSAGE" function to disable this.

After execution, we can go through the buffer and extract the filenames and their sizes. (Each character of the name or extension should be logically ANDed with &7F to remove the flag bits).

The following example source shows how this can be done: Media:catalog.asm