Displaying graphics when a disc directory is listed

There are two instructions to display a directory of a disc:

• CAT
• |DIR

The differences between these two commands are listed below.

CAT

Example output using CAT command:

cat

Drive A: user  0

CATALOG .ASM   4K   SCROLL  .BAK   2K
HWSPRITE.ASM*  4K   SPLTSCRN.ASM   3K
SCROLL  .ASM   2K

163K free

Ready

Notes:

• File names are sorted into increasing alphabetical order before display
• The file-size is displayed
• The file names are printed using firmware "TXT OUTPUT" (&BB5A) function which will execute control characters.
• A "*" character is displayed after the extension if the file is read-only. If the file is read-write then a " " (space) character is displayed.
• Hidden/system files are not displayed
• Free space remaining on disc is displayed

|DIR

Example output using |DIR command:

|dir

Drive A: user  0

HWSPRITE.ASM   CATALOG .ASM
SPLTSCRN.ASM   SCROLL  .ASM

163K free

Ready

Notes:

• File names are listed in the order stored in the directory
• File size is not displayed.
• The file names are printed using firmware "TXT OUTPUT" (&BB5A) function which will execute control characters
• read-only/read-write state is not displayed
• Hidden/system files are not displayed
• Free space remaining on disc is displayed

Displaying text and graphics using CAT and/or |DIR

The standard DATA and SYSTEM formats have 64 directory entries.

The following procedure is used to display a directory listing:

1. Display blank line
2. Display "Drive " followed by drive letter ("A" or "B")
3. Display ":" character
4. Display " user " followed by user number (the user number is displayed padded with spaces) e.g. " 0", " 15"
5. Display blank line
6. if CAT:
   • Perform directory operation and sort filenames into increasing alphabetical order
7. if |DIR:
   • Perform directory operation and do not sort
8. The following procedure is repeated for each filename:
   • Display the 8 characters of the name part of the filename
   • Display a "." character
   • Display the 3 characters of the extension part of the filename
   • If |DIR
     • display 3 spaces
   • if CAT
     • If file is read-only, display a "*" character, otherwise if file is read-write display a " " (space) character.
     • display 2 spaces
     • display file size in K, followed by "K" character

If you want the output to look identical with CAT and |DIR, follow these rules:

• List the directory entries in the order that they are "executed"
• Do not use the extra characters ("*" and file size) displayed by CAT, or the 3 spaces displayed by |DIR

Offset	Count	Description
0	1	User number (note 1)
1	1	NAK (note 2)
2	1	Sort key (note 3)
3	1	ACK (note 4)
4..8	5	(note 5)
9	1	BS (note 6)
10	1	(note 5)
11	1	NAK (note 7)
12..31	19	file clusters (note 8)

This setup will work with DIR and CAT and gives 6 useable bytes per directory entry. Each printable char uses 1 byte. Some control codes will use more than 1 byte. Be careful when using control codes that use parameters are are close to the last byte or byte 8. It is best to put them into the next directory entry to ensure they are executed correctly.

1. Set user number to 0 so that this directory entry will be visible in the directory listing and processed.
2. This NAK control code is used to prevent display of the sort key character
3. Use the characters with ASCII codes 32-127 in ascending order for the sort key. Codes below 32 are control codes and often require a parameter which we can't use here.
4. This ACK control code enables printing for the bytes following.
5. This gives 6 useable bytes per directory entry. 5 hear and 1 in the extension part.
6. This BS control code is used to erase the "." character)
7. This NAK is used to disable printing again. Note the use of ACK and NAK to enable and disable character printing so you have ultimate control on how the characters are drawn.
8. These can be set to "0". However if you are loading using sector by sector and you want to stop AMSDOS from saving to these sectors, then set valid cluster numbers here to map over the sectors.
9. Ensure bit 7 of bytes 9,10,11 are 0. Normally these are used to indicate file status (e.g. system, readonly).

   The ASCII codes for the control codes used here:

   • ACK is 6 (&06)
   • NAK is 21 (&15)
   • BS is 8 (&08)