M-Doc

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.