In the same way that MasterBasic was Dr Wrights improvement to Sam Basic, MasterDOS was the improvement to the original SamDOS.
MasterDOS contains many features missing from the original, such as file directorys, date and time stamps using the real-time clock in the SamBus.
Another feature that was highly prized was the ability to set up Ram Discs which was especially useful with the One Meg extension that could be formattted into a complete 800k virtual disc.
Directory entry format
The first tracks on side 1 of a disk are used for the directory, starting at track 0, sector 1. Each sector holds two 256-byte directory entries. The format of each entry is as follows:
|0||Status/File type, as returned by the FSTAT function with a parameter of 4. Zero if entry unused or ERASEd.|
|1-10||(10 bytes) File name. If the first byte is zero, the entry is assumed to have never been used and directory reading will not proceed further.|
|11||MSB of number of sectors used in the file.|
|12||LSB of number of sectors used in the file.|
|13||Track number of start of file.|
|14||Sector number of start of file.|
|15-209||(195 bytes) Sector usage map for the file. Bit 0 of the first byte represents track 4, sector 1, bit 1 represents sector 2, etc. If a bit is set the sector is used by the file.|
|210||(10 bytes) In all entries except the first one on the disk, these bytes hold Plus D/Disciple-form information. In the first entry, the disk name is stored here. Bit 7 of byte 210 can be set or reset without altering the disk name.|
|221-231||(10 bytes) File-type specific information. If the file type is SCREEN$ then byte 221 is the screen MODE, minus 1.|
|232-235||(4 bytes) Reserved.|
|236||Start page number in bits 4-0, bits 7-5 are undefined.|
|237-238||(2 bytes) Start offset in the range 32768-49151.|
|239||Number of pages in length.|
|240-241||(2 bytes) Length MOD 16384. Bits 15 and 14 are undefined.|
|242||Execution page for CODE files, or 255|
|243-244||(2 bytes) Execution offset (32768-49151) for CODE files, or auto-run line for a Basic program.|
|245||Day of SAVE, or 255|
|246||Month of SAVE|
|247||Year of SAVE|
|248||Hour of SAVE|
|249||Minute of SAVE|
|250||For a DIR file, code number tagging files in that subdirectory.|
|252-253||(2 bytes) In the first directory entry only, Random word identifying the disk.|
|254||Subdirectory code number of this file.|
|255||In first entry only, number of directory tracks, minus 4.|
MasterDOS provides hook (command) codes which enable the machinecode programmer to use the DOS’s facilities without having to return to or call SAM BASIC.
If an error occurs, MasterDOS puts an error number into the A register; otherwise the A register will be zero.
The Hook Codes currently available are:
- INIT 128 (80H)
Look for an AUTO file on the current disk. No action (or error) occurs if there is no AUTO file, otherwise it is loaded (and executed if it is an auto-running Basic or CODE file). This Hook can only be used in sections B and C of the memory map.
- HGTHD 129 (81H)
Get file header. This routine should be called with IX pointing to the UIFA, which should hold the file type required(at IX+0) and the file name (at IX+1 to IX+10). The routine looks for the file in the current directory on the current drive and either returns with an error code, or transfers the data from the file directory entry to IX+80 dec, in UIFA form. The calling code and the UIFA can be in sections B, C or D of the memory map. (Note: this hook works correctly in SAMDOS, provided IX=4BOOH.)
- HLOAD 130 (82H)
Load data from the file you have just got the header of using HGTHD above. HL must point to the destination address, paged in between 8000H and BFFFH, i.e. in section C of the memory map. The C register should hold the number of 16K pages in the file, and DE should hold the length MOD 16K. These values can be read from the header loaded by HGTHD. See also Hook 143.
- HVERY 131 (83H)
Like HLOAD, but verify the data on the disk against the data in memory. Error code 93 dec if verify failed.
- HSAVE 132 (84H)
Save the file whose UIFA is pointed to by IX. All relevant data in the UIFA must be complete - for a CODE file, type, name, start, length and execute address. If in doubt, try a SAVE from BASIC and then look at 4500H-4B47H to find the required values.
- HSKSF 133 (85H)
Seek Safe. On some machines, pressing the Reset button can corrupt the disk sector under the drive head. This is often on the track containing the last sector of the last file loaded. MasterDOS tries to minimise the problem by parking the drive head on the last track in the directory, after a LOAD or a SAVE. This track will be unused unless the directory is fairly full. Using the HSKSF hook will move the head of the current drive to the last track in the directory, unless this would be track 4 (which contains the first sector of DOS) in which case track 3 is used instead.
- HAUTO 136 (88H)
Like Hook 128, but an error code of 101 dec is returned if there is no AUTO file.
- HSKTD 137 (89H)
Seek Track D. Move the drive head of the current drive to the track specified in the D register.
- HFMTK 138 (8AH)
Format Track. Format the track under the drive head, using the D register to supply the track number and the E register as the number of the first sector (1-10). Later sectors will be numbered 1 higher till 10 is reached and numbering goes back to1. [Does not exist?]
- HVAR 139 (8BH)
Supply the address of a DVAR by putting it on the floating point calculator stack. On entry, the FPCS should hold the desired DVAR number. Note: it is probably easier to page in DOS(the DOS page is held at 5BC2H) and read the disk variables directly. DVAR 0 is at an offset of 0220H within the page - this will not change.
- HEOF 140 (8CH)
Supply the End-Of-File status (1 or 0) of a specified stream. The stream number should be on the FPCS. It will be replaced by the EOF status.
- HPTR 141 (8DHl)
Supply the PTR value for a specified stream. The stream number on the FPCS is replaced by the PTR value.
- HPATH 142 (8EH)
Supply the current PATH$ on the FPCS Use CALL0124H (JSTKFETCH) to get page (A) offset (DE) and length (BC) of the string.
- HLUPG 143 (8FH)
As Hook 130, but on entry the A register should hold the page number of the destination address. This need not be paged in.
- HVEPG 144 (90H)
As Hook 131, but on entry the A register holds the page to verify against.
- HSDIR 145 (9lH)
Select Directory. Similar to DIR=”name” in Basic. On entry, the registers hold details of the location and length of the desired subdirectory name. DE is the offset, A is the page of the name start, and BC is the name length.
- HOFSM 146 (92H)
Open a File Sector Map for an OPENTYPE file. IX must point to the UIFA. The routine will create the map and clear the disk buffer.
- HOFLE 147 (93H)
Open a file on the disk. IX must point to the UIFA. The routine will create a sector address map, and save a 9-byte header to the disk buffer.
- HSBYT 148 (94H)
Save the byte in the A register to the disk file (If the buffer is full it will be written to the disk and the byte will go into the start of the next buffer.)
- HWSAD 149 (95H)
Write Single Sector. On entry, the A register is the drive number (1-7) which is used to access the table at DVAR111 to get the actual drive to use. D holds the destination track, and E the sector. HL points to the source in memory, which must be in sections B, C or D of the memory map. 512 bytes will be written to disk.
- HKSB 150 (96H)
Save a block of data to the disk file. The A register holds the length to save in pages, and DE holds the length MOD 16K. HL points to the start of the data to save, paged into section C of the memory map.
- HDBOP 151 (97H)
Save BC bytes to the disk file. DE points to the start of the data to save, paged into section C of the memory map. Used by DOS to write strings to OPENTYPE files.
- HCFSM 152 (98H)
Close a file. This routine writes the last buffer to a disk file and creates a directory entry for it. IX should point to the UIFA.
- HORDER 153 (99H)
Sort list into ASCII order. HL should point to the start of the list in sections B, C or D of the memory map. The BC register should hold the length of each item in the list, and the DE register the number of items. The A register specifies the number of characters to sort on. No paging is performed so the entire list must be paged in by the user before this hook is called.
- HGFLE 158 (9EH)
Get a file from the disk. The IX register must point to the UIFA. The return is made with the first sector of the file loaded into the disk buffer and RPT pointing to the first byte.
- HRSAD 160 (A0H)
Read Single Sector. On entry, the A register is the drive number (1-7) which is used to access the table at DVAR 111to get the actual drive to use. D holds the source track, and E the sector. HL points to the destination in memory, which must be in sections B, C or D of the memory map. 512 bytes will be read from the disk.
- HLDBK 161 (A1H)
Load a block of data from the current disk file. HL points to the destination of the data in memory, paged into section C of the memory map. The A register is the length to load, in pages, and DE holds the length MOD 16K.
- HMRSAD 162 (A2H)
Read Multiple Sectors. Equivalent to READ AT in Basic. The A register is the drive to use (1-7, using DVAR 111table), D holds the track, E the sector, C the page and HL the offset (8000H-BFFFH) of the destination. IX holds the number of sectors to load.
- HMWSAD 163 (A3H)
Write Multiple Sectors. Equivalent to WRITE AT in Basic. As above, but C and HL hold the source address, rather than the destination.
- HREST 164 (A4H)
Restore. Move drive head to track 0. The disk need not be formatted.
- HP2IR 165 (A5H)
Print directory. If the A register holds 2,print a simple directory. If it holds 4, print a detailed directory. Neither option does a CLS first. The current stream is used to output.
- HERAZ 166 (A6H)
ERASE a file from disk. The file name should beat IX+1 to IX+10.
- HCHRD 168 (A8H)
Read character from the disk file whose UIFA is pointed to by IX. The character and flags are passed out in the alternate BC register: EXX, PUSH BC, EXX, POP AF gives the character in A, and the carry flag set if the read was OK, else we hit end of file.
PDF Manual Scan at www.samcoupe-pro-dos.co.uk
|Sinclair & SAM Computing #1||95%|
Review by Tim Paveley from the Sam Coupé Scrapbook
Urm, I got SamDOS free with my Sam, why do I need another one?
Because it’s just packed full of useful new features, that are of use to even a total beginner. I’ll tell you the 3 most useful features it has.
- The most useful thing is that you can now have subdirectories, which makes file management far more easier. Each Subdirectory uses a free directory slot, but that’s it. They are incredibly useful, since they allow you to ie store all your word processing files in one directory, and all your pictures in another. Subdirectories can contain furthur subdirectories, and so on, allowinf nice tree like structures of files.
- Another useful thing, is that it allows you to set aside areas of memory to use as a RAMDisk. This Basically acts as another (faster) disk drive, that you can carry out normal operations on. If you have a load of files to copy, copying them all to a RAMDisk, and then to the target disk, is a lot easier than 20 or 30 disk swaps. The RAMDisk is limited by the amount of free memory you have, and can be as large as a normal disk (800k), very useful if you have a 1meg expansion!
- The 3rd “useful for anyone” feature, is that you can now reserve extra tracks on the disk for directory information. Basically this means that you can have more than 80 files on a disk, upto a maximum of 778, useful if you have a lot of small files, and subdirectories, since you could sometimes have about 1/2 your disk space free. Every additional 20 slots uses up 5k of disk space, a small price to pay.
So is that it then?
Not at all, there are plently more features available to those who would use them. For a start, MasterDOS keeps track of the time (if you have the SamBUS with the clock in it), and allows you to date stamp files. You can have a confirm option when using wildcards (ie ERASE “*.txt”). There are some useful new Keywords, to find the current subdirectory name, to count the amount of free memory pages, to give information about the disk, and files. MasterDOS also finally has opentype files, allowing you to open a stream to a file (ie you can use PRINT, INPUT, and the like on disk files).