M-DOC OPERATING MANUAL M-Doc is a utility program for the Spectrum 48k/Plus which allows you to inspect files on a Microdrive cartridge and see where any faults lie. If an unloadable file can still be listed in a CAT, you should in most cases be able to repair the faulty part, at least enough to ensure the whole file loads again. We recommend that you read these instructions right through before commencing to use M-Doc. CARTRIDGE FILES Unlike cassette tape files, which consist of a single header and then a continuous block of data, cartridge files are split into a number of records, each containing up to 512 bytes of data, which are stored in areas of the tape called sectors. Each sector consists of a header and a data block. The header is established when the cartridge is formatted, and is unchanged by any Microdrive operations. The data block consists of two sections. The first is a list of details about the record, eg whether or not that sector is used or free, the filename and record number and so on. The second section is the data itself. The number of sectors present on a cartridge varies; sector 0 is always missing, as are the sectors over about 190. The formatting routines also will mark any that are unreliable - usually the couple of sectors over the Join in the tape loop. The exact format of each sector is shown in Appendix 3 of the Sinclair "Microdrive and Interface 1 Manual", which shows a Microdrive channel. The sector header starts at location 28 in the channel, and consists of 12 bytes of preamble (10 zeros and two FF hex bytes), followed by HDFLAG-HDCHK inclusive. The data block starts at location 55 and consists of 12 bytes of preamble, followed by RECFLG-DCHK inclusive. Note that bit 1 of RECFLG, if set, indicates that the record is the end-of-file (EOF). A sector which is unused will have this bit reset and RECLEN set to zero. The first nine bytes of data in record 0 of a non-PRINT file (ie a program, array or bytes) are used to store its attributes; these are similar to the system variables HD_00 to HD_11 as listed in Appendix 2 of the "Manual". Note that the first byte contains a code denoting the type of file: 0 = program, 1 = number array, 2 = character array, 3 = bytes. Serious users of M-Doc are recommended to obtain one of the various books on Microdrives, eg "Master Your ZX Microdrive" by Andrew Pennell (Sunshine Books), for more details. LOADING M-DOC Use LOAD "". This loads a short BASIC program which puts up the title screen, and then loads and runs the machine code (which occupies from 55000 to 63794). It also issues a CLEAR 54999 command so that RAMTOP (which represents the highest address that BASIC can use) is safely below the machine code. NEW will thus not affect M-Doc. After loading, the screen will clear and the main options will be displayed. SCREEN DISPLAY AND KEYBOARD INPUT All the display takes place in the main part of the screen, with a maximum of 42 characters per line. Character codes below 31 and above 127 (including keywords) are represented by dots. The keyboard input routine is much simpler than that used with BASIC, and the various modes (including keywords) are not available. The Cursor does not flash and simply shows the position of the next character to be entered. The cursor left and cursor right keys operate in the normal way, but characters typed in the middle of an existing line do not insert as they do in BASIC. CAPS SHIFT and SYMBOL SHIFT work in the usual way but; since E mode isn't available, the characters printed in red below the keys, eg "[", cannot be accessed at all. The maximum line length is only 24 characters; however, this will be found to be more than adequate. Whenever a numeric input is requested, either decimal or hex numbers (0-65535) are allowed. Hex should be preceded by a "#" sign, eg #A4. Numeric output is always three or five digits for decimal and two or four digits for hex. M-Doc's error messages are shown in inverse characters and return you to the main menu; Microdrive error messages will leave you in BASIC. MAIN OPTIONS Pressing STOP (SYMBOL SHIFT/A) while an option is waiting for a key press abandons the option and returns to the main menu. 1. Read cartridge This scans the whole cartridge, reading details about every sector into a buffer area within M-Doc. Each sector is only read once, So the results are on the pessimistic side (Interface 1 normally tries several times to get a perfect result). The process takes about a minute as several passes are made through the tape loop. Options 2-5 are only possible if this option has been first carried out. 2. List all sectors All sectors are listed in sector number order. The sector number, filename and record number (if any) are shown, together with the status. as follows: BAD - the data block may have been corrupted; it will however be possible to read that sector in using options 6 or 7. GOOD - header and data block are in good order. MISSING - the sector does not exist or has a corrupted header; it will be impossible to read it in using options 6 or 7. UNRELIABLE - the sector was marked as such during formatting and should not be used. UNUSED - the sector does not contain a record. If a cartridge is in poor condition the sectors marked BAD in this list may vary considerably the first time option 1 is performed. In this case the files should be removed and it should be reformatted. 3. List bad records This is option 2 confined to bad records. 4. List unused sectors This is option 2 confined to unused sectors. 5. Give file report A named file (do not enclose it in quotes) is listed in record number order, showing the sector number and status. Note that the last record should be marked "EOF". If this is not the case, it means that further records with higher numbers are missing. 6. Read record and give report This reads a record in from a file and gives a full report on the sector, including the checksums (HDCHK, DESCHK and DCHK). Up to five attempts are made and the best is selected. After this has been done, the whole Microdrive channel (595 bytes) is transferred to a buffer area in M-Doc, so that it can be examined and altered, and the channel is closed. (The buffer is located at addresses 63200-63794, eg location 82 is at 63282.) Note that options 8-12 are only possible if this option or option 7 has first been carried out. 7. Read sector and give report This is like option 6 but searches by sector number instead of record number. 8. Examine channel The channel which has been loaded into the buffer can be examined using this option, which gives a hex/ASCII dump, commencing at a given location. Each line gives the location within the channel in decimal, then eight bytes in hex, then the same eight bytes in ASCII characters (bit 7 reset). Non-printable characters are shown as dots. The scrolling display can be paused (and restarted) by pressing any key. 9. Modify channel This allows you to modify the channel buffer, commencing at a given location. Each line displays the current location in decimal, then its contents in both hex and decimal. If no change is required, Just press ENTER and the next byte will be shown. To modify the byte, type in one or more numbers in decimal, hex (precede with "#" as usual), or as an ASCII character string (enclose in quotes). When the line is ready, press ENTER to write it to the buffer. You can go back a byte by entering ":" at the beginning of a line. To quit this option, enter "." at the beginning of a line. 10. Filter data In some cases it may be desirable to filter the data before writing it back to the cartridge, to ensure for example that non-text characters are not present in a text file. This option allows you to specify an upper and lower limit for the data, and bytes outside this range in locations 82-593 will be given the default value. It is also possible to use this option to fill this data area with any code if both limits and the default are set to the code. The first nine data bytes of record 0 of a non-PRINT file will not be affected by this option. 11. Redisplay record/sector report After modifying the channel buffer, you can redisplay the report using this option, as a final check before writing it to cartridge. The check sums are rechecked so that you can see if your corrections have restored the original sector. However, if you are making changes rather than corrections, ignore the integrity reports - the checksums will be recalculated in any case when the sector is written to cartridge. 12. Write sector This option opens a Microdrive channel and then partially overwrites it with the modified channel in the buffer (which is retained). The data block (RECFLG-DCHK) is written to the specified sector, and then this rewritten sector is verified. Finally, the Microdrive channel is closed. Note that an attempt to write to a missing sector will give a "File not found" error. 13.Hex-dec-hex converter This displays the decimal and hex equivalents of any decimal or hex number. 14. Set printer mode This option allows you to print the screen displays in options 2-8 and 11 on a "full size" or ZX printer. The current mode is shown on the main menu. In "fullsize" mode, characters are sent via stream #3. M-Doc does not contain printer interface software so, if your interface requires software to be loaded from tape, ensure this is done and the interface is ready first. Some interfaces require their software to loaded at the top of memory and sufficient space has been allowed for this. For Interface 1's RS232 output, do FORMAT "t";n (n = baud rate) and OPEN #3;"t". In "ZX" mode, a special routine is used to send the 42-column display to a ZX or similar printer. Note that if either printer mode is enabled, the screen displays will scroll right through to the end of an option without a pause (however, the BREAK key is operative). 15. Return to BASIC A straightforward return to BASIC. If you wish to re-enter M-Doc, use RANDOMIZE USR 55000. CHECKING FILES Always check the cartridge after any Microdrive malfunction. Use options 1 then 3 to find any bad records. If any file ever fails to load, use options 1 then 5 to give a file report indicating any missing or possibly bad records. However, a record may be shown as missing simply because its filename has got corrupted, so check all bad records using option 3 and see if any have that filename corrupted. Sometimes a perfectly good file may fail to load if one of its sectors precedes a damaged sector. Note that if the EOF record is missing, then several records with higher numbers may be missing; if it is a non-PRINT file you can work out how many from the attributes of record 0 and the formula given later. REPLACING BAD RECORDS First use option 6 to confirm that the record really is bad - you may find it loads correctly using this option because multiple attempts are made. The report will show which parts, if any, are corrupted. If the first part of the data block giving the record details (filename, record number etc) is bad, carefully check these details. If the error cannot be seen, then use option 8 with a start location of 55 to inspect it byte by byte. Correct any errors using option 9. Once this is done, you can use option 11 to check it has been restored. If the second part of the data block (ie the actual data) is corrupted, you can inspect it using option 8, starting at location 82. You need only correct it to the extent that it can be edited using the program that created it in the first place. If it is part of a BASIC program, leave it alone at this stage. (Once you can load the whole program, you can use B-Doc to make it editable again.) Ensure the program does not auto-run by amending the record 0 attributes if necessary (see below). If the data is from a text file, such as a Tasword Two file, it need only be filtered using option 10 so that spurious characters which may upset editing are replaced by valid ones. (For Tasword Two, set a lower limit of 32, an upper limit of 143, and a default code of 42. Corrupted characters will be replaced by asterisks, which can be deleted using Tasword.) Other data types can be corrected using option 9, though this will be difficult for machine code, numeric arrays and SCREEN$. Once the record has been repaired. it should be written to an unused sector using option 12. (When rewriting several records with ascending numbers, choose unused sectors in descending number order.) The original bad record must now be deleted (see below). If it fails to verify, mark the sector "unreliable". REPLACING MISSING RECORDS Any missing records should be replaced with dummy records bearing the correct record numbers. The easiest way to do this is to read in a good record (not the EOF) from the file, using option 6. Then change its record number to the missing one using option 9. Finally, fill its data area with, say, question marks (code 63) using option 10 so you can see where where the missing record was when you reload the complete file. If record 0 of a non-PRINT file is missing, there is a complication: the first nine bytes of its data are attributes and must be recreated. For a program, set the first byte (location 82) to 0 and locations 83/84 and 87/88 to the length of the program and any variables in hex, most significant byte last. This is given by: (Number of records-1)*512+Length of EOF record-9 Use option 13 to work out the hex once you have calculated it in decimal. Ideally, 87/88 should be set to the length of the program without its variables, otherwise these will appear as rubbish at the end of the program listing. Set locations 89/90 (auto-run line number) to FFFF hex to prevent auto-run. For a number or character array, set location 82 to 1 or 2 respectively. Set locations 83/84 to the length of the file, determined as above. Set location 87 to the variable name of the array in upper-case ASCII. Then add to this number 64 if it is a numeric array or 128 if it is a character array, eg b$ = 194. For bytes set location 82 to 3, locations 83/84 to the length of the file (see above), and H5/H6 to the start address. Finally, check the attributes are OK using option 11. Once the dummy record is ready, it may be written to cartridge in the same way as for bad records (see above). DELETING A BAD RECORD Set locations 67-81 inclusive to zero and rewrite to cartridge using option 12. MARKING A SECTOR "UNRELIABLE" Any sector which fails to verify after being written to is probably physically damaged and should be marked "unreliable" so the Microdrives will ignore it. Set location 67 to 2 and 68-81 inclusive to zero, and rewrite to cartridge using option 12. Check that the sector now lists as "unreliable" in option 7. MAKING BASIC PROGRAMS EDITABLE Once you have used M-Doc to get your corrupted BASIC program to load again, the next step is to ensure that it's in an editable state. A separate program, B-Doc, is supplied for this purpose, thus giving maximum room for your program. B-Doc does several things. First, it goes through the program ensuring that line numbers ascend and are in the range 1-9999, that the line length bytes are correct, that the line text commences with a keyword, and that the line is properly terminated with an ENTER byte. Faulty line numbers are changed to 9999; lines with other faults are turned into REM statements. B-Doc then goes through the program again, and re-enters each line, Just as if you had done this at the keyboard. This ensures the hidden floating-point forms match the visible numbers, and shows up syntax errors caused by corruption. To use B-Doc, proceed as follows. First load it, using LOAD "". This loads a short BASIC program, which puts up a title screen and then loads the code (which occupies 65000-65535). It also issues a CLEAR 64999 command but does not of course run the code. Now load the BASIC program to be repaired (don't try to run it yet!). Run B-Doc using RANDOMIZE USR 65000. The screen will clear and show the title "B-DOC" but nothing else may happen for a short while if the program is a long one or is heavily corrupted. Eventually, one of the following messages will be displayed and you will be returned to BASIC. Bad line number means a 9999 line number was found in B-Doc's second pass. Press ENTER to see the listing showing the offending line and EDIT to bring it down for editing. Correct its line number and then delete the original 9999 line (if there are several 9999 lines only the first one will be affected by this process). It is often worthwhile checking the preceding line in case its number was corrupted and is now too high. This could have caused B-Doc to assume the following line was out of sequence, hence making it a 9999 line. Nonsense in BASIC means a syntax error was found. Press ENTER to see the offending line and EDIT to bring it down for correction. Always run B-Doc again after correcting faulty lines until you get the Ready to edit message: you should now be able to edit the program without any trouble. You must go through it carefully, checking each statement, particularly REMs which may contain the debris of corrupted lines. Note that any variables which were originally stored with the program may also have been corrupted by the Microdrive malfunction - these can be removed using a CLEAR command. SAVING M-DOC TO MICRODRIVE Load the BASIC program. Press BREAK as soon as it is loaded and immediately stop the tape. Then load the machine code using LOAD "" CODE. Delete line 40 of the BASIC and change line 30 to: LOAD *"m";n;"m-doc-code"CODE where n is the drive number. Now save the BASIC with: SAVE *"m";n;"m-doc" LINE 10 Finally, save the machine code with: SAVE *"m";n;"m-doc-code"CODE 55000,5128 B-Doc can be saved in a similar way; the machine code should be saved with: SAVE *"m";n;"b-doc-code"CODE 65000,536 SEVEN STARS Seven Stars Publishing, 34 Squirrel Rise, Marlow, Bucks SL7 3PN Copyright (c) R.J. Eckersley, 1985. All rights reserved. Made in UK. Every effort has been made to ensure there are no errors in this product but the publisher can accept no responsibility for any that may remain or for their consequences.