home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / hd / b192_1 / !Help < prev    next >
Text File  |  1994-03-13  |  13KB  |  334 lines
  1. > !Help file for MapManager v0.50 13 Mar 1994
  2. —————————————————————————————————————————————
  3.  
  4. (Please note: MapManager needs RISC OS 3 to run.)
  5.  
  6. Before giving this software to anybody else, please read the section called
  7. 'Distribution' below.
  8.  
  9.  
  10. The MapManager Module
  11. −————————————————————
  12. This module was written to help examining or even repairing harddiscs which
  13. maps do not correspond completely to the directory tree. Such HDs will
  14. respond to a *CheckMap command with the error message 
  15.  
  16.         'Map inconsistent with directory tree'
  17.  
  18. or alternatively hang the machine, depending on the nature of the fault.
  19. CheckMap only does a simple integrity check and can't tell which files are
  20. affected. The command *MapCheck supplied by the MapManager module lists the
  21. offending fragments so you can assess the severity of the error.
  22. Alternatively, it is possible for *CheckMap to hang, when it can't find all
  23. the fragments for a file.
  24.  
  25. What can MapManager do? Well, in most cases it can't relieve you from the
  26. need to reformat the disc and restore its contents from a backup. However, it
  27. gives you the chance to see which files are endangered and could contain
  28. garbage. Later versions might include commands to modify the map or directory
  29. tree to restore a harddisc without reformatting.
  30.  
  31.  
  32. FileCore E-Format
  33. —————————————————
  34. The FileCore E format is a very advanced file storage system. Most other
  35. filing systems are FileCore based and effectively pass all calls through to
  36. FileCore. MapManager only works on FileCore based filing systems.
  37.  
  38. (This is only a short description of FileCore's E-Format. For more detailed
  39. information see Acorn's Programmer's Reference Manuals for RISC OS 3.)
  40.  
  41. Under FileCore files are a stream of bytes, identified by their system
  42. internal number SIN. Filename, SIN, length, access attributes etc. are stored
  43. in the directory tree. The SIN acts as the filenumber, except in the special
  44. case where a fragment is shared between files.
  45.  
  46. The directory tree consists of the root directory (file number 2) and its
  47. subdirectories, which on this level are ordinary files (i.e.., they have a
  48. file number).
  49.  
  50. The map consists of several zones, with each map zone block the size of a
  51. sector. Depending on the BitSize and sector size each zone represents roughly
  52. a few megabytes of disc space.
  53.  
  54. Each bit in the map represents a fixed number of bytes of disc space, the
  55. BitSize. This BitSize - often called something else (Acorn calls it bpmb -
  56. bytes per map bit) - can (or rather should) be set when formatting the disc.
  57. Large values speed up disc access somewhat and reduce the size of the map
  58. (because more disc space is mapped into each map bit). However, as there is a
  59. minimum length of some 15 bits for each fragment the minimum space allocated
  60. for a file may be rather large; a bitsize of 2K translates to a minimum
  61. allocation unit of 26 Kbytes. If you want to store a number of big files this
  62. is not important, but for highly structured discs (with lots of Impression
  63. documents, say) losing dozens of kilobytes for each subdirectory is something
  64. to avoid.
  65.  
  66. To partly overcome the problem of minimal size fragments sharing as allowed.
  67. Directories can share fragments with their sub files and files in the same
  68. directory can share a fragment. Thus several files can have the same file
  69. number (aka fragment ID), but they have different offsets into the fragment.
  70. The SIN, which contains both file ID and offset (if applicable), is unique
  71. for each object. 
  72.  
  73.  
  74. Repairing the Map
  75. —————————————————
  76. As yet no commands to write the map to disc are implemented.
  77. Actually I'm not sure whether such a command is needed at all (except when
  78. MapCheckSums reports errors) as RISC OS is sturdy enough to cope with
  79. slightly inconsistent maps - so don't panic!
  80.  
  81.  
  82. Commands provided
  83. —————————————————
  84. (Note: <disc spec.> below must contain the drive number rather than the disc
  85.        name, i.e. scsi::4, adfs::0 etc..)
  86.  
  87. *MapCheck [<options>]
  88.  
  89. MapCheck compares a disc map against the directory tree of that disc.
  90. Options:
  91. A(ll)           Also print files that check out OK {off}
  92. V(erbose)       Print information on each file {off}
  93. C(onfirm)       Prompt for confirmation of each write operation; only useful
  94.                 in conjunction with the remove option {on}
  95. reM(ove)        Try to remove excess space allocated to a file {off}
  96.  
  97. The reMove options tries to remove excess fragments RISC OS seems to tack at
  98. the end of certain files. It only uses OS routines (it's playing with the
  99. file extent), but nevertheless MapManager asks you before it modifies
  100. anything (this can be switched off with the ~C option).
  101.  
  102. All causes MapCheck to print all files (ordinarily only 'faulty' files would
  103. get printed).
  104.  
  105. Verbose lists the allocated fragments for each printed file.
  106.  
  107. Some possibly useful 'AV' combinations:
  108.  
  109. <none>  This is the fastest way to check the disc. Please note that this
  110.         might still take several minutes, and only lists the offending files.
  111.  
  112. V       Probably the most useful of the set. It lists all faulty files and
  113.         their allocated fragments, thus you can spot immediately double
  114.         allocated files etc.
  115.  
  116. A       Lists all files (with their system internal number only), with an
  117.         additional message if any should be faulty. Also when MapCheck
  118.         finally looks for lost fragments it lists unused parts of shared
  119.         fragments. These are NOT error; it just means that some disc space
  120.         could not be used due to FileCore's minimum allocation size.
  121.  
  122. AV      For those who want to know everything.
  123.  
  124. For medium and large harddiscs the output generated by the A option might be
  125. larger than 1Mbyte; keep this in mind if you spool it to a floppy.
  126.  
  127.  
  128. *MapCheckSums [<disc spec.>]
  129.  
  130. MapCheckSums re-calculates the checksum bytes of the map. If any bytes are
  131. incorrect it allows you to correct them. Currently this only works if the
  132. disc is recognized by FileCore, i.e. if all checks turn out OK in the first
  133. place, which makes this command rather useless for now.
  134.  
  135.  
  136. *MapFindID [<disc spec.>] <ID number>
  137.  
  138. MapFindID scans the specified map for the given ID (hexadecimal). Free space
  139. fragments are ignored.
  140.  
  141.  
  142. *MapFree [<disc spec.>]
  143.  
  144. MapFree checks the free space chain. It lists two 'bytes free' counts: the
  145. first is the real amount of disc space unallocated, the second figure is the
  146. same as returned by *Free; don't be alarmed if this numbers differ. The *Free
  147. value doesn't seem to be calculated in any way but instead is updated
  148. whenever you save/delete a file, and adjusts automatically if it would become
  149. negative or on a *CheckMap command.
  150.  
  151.  
  152. *MapInfo [<disc spec.>]
  153.  
  154. MapInfo gives more detailed information about the loaded disc map. The
  155. allocation unit is probably the most interesting bit.
  156.  
  157.  
  158. *MapZone [[<disc spec.>] <zone number>]
  159.  
  160. MapZone lists all fragments in the given zone. Free space fragments are
  161. displayed as 'free space', so you should never see ID 0 etc.
  162.  
  163.  
  164. *FindID [<disc spec.>] <file ID>
  165.  
  166. FindID scans the directory tree for the given file number. It reports name
  167. and size of the object(s) that match the file number.
  168.  
  169.  
  170.  
  171.  
  172. Example MapManager Session
  173. ——————————————————————————
  174.  
  175.                 *MapManager     | load the module
  176.  
  177.                 *MapInfo scsi::4| not strictly necessary, but do it the first time
  178.                                 | to ensure the correct map has been loaded
  179.  
  180. Disc name: LPS120S      size: 117 Mbytes
  181. ID:95EF                 density: harddisc
  182. sector size: 512 bytes  bit size: 256 bytes             cluster size: 512 bytes
  183. Number of zones: 118    zone size: 1040384 bytes        zone 0 size: 917504 bytes
  184. Map size: 60416 bytes   disc address: &83A6C000         memory address: &018CC000
  185. IDfield length: 15 bits allocation unit: 4096 bytes     unused map bits: 0
  186.  
  187.                                 | looks good so far, so continue
  188.                 *spool ram:MapLog
  189.                 *MapFree
  190.  
  191. Disc name: LPS120S      density: harddisc       size: 117 Mbytes
  192. Zone 0 :        (full)
  193. Zone 1 :        (full)
  194. Zone 2 :        (   1A400,   54200)
  195. Zone 3 :        (   12E00,   6C200)
  196. Zone 4 :        (   6E400,   2F400)
  197. Zone 5 :        (    D600,   15C00)
  198. Zone 6 :        (   61400,   9EC00)
  199. Zone 7 :        (   62A00,   1A800)   (   D7400,    6600)
  200. Zone 8 :        (full)
  201. ...
  202. Zone 117 :      (full)
  203. Total free space: &01025A00, stored in disc record: &01025A00
  204.  
  205.                                 | free space chain is OK (no error msgs)
  206.                                 | now test the directory tree - map integrity
  207.  
  208.                 *MapCheck       | this may take a while (several minutes)
  209.  
  210.  *** Fragment(s) too short or missing / too long or too many ***
  211. $.Apps.Graphics.!Graphs.Examples.spiral
  212.  --- allocated in map: &00000800, needed: &00000400
  213.  
  214.                                 | too bad; perhaps re-run with V option
  215.  
  216. Looking for bad fragments ...  
  217. Lost fragment: (  2F4200,    BE00); ID=&00741B
  218. Lost fragment: ( 5DF9200,    6E00); ID=&0037EB
  219. Lost fragment: ( 5E2AA00,    2E00); ID=&0037EB
  220. Lost fragment: ( 5EB2600,    3200); ID=&0037EB
  221. Lost fragment: ( 72C5A00,   1E600); ID=&006D38
  222. Total number of bytes lost: &00037200 = 225792
  223.                                 | OK, I can live with that
  224. Total number of over-allocated bytes: &0000000 = 0
  225.                                 | If this return non-zero it's time to panic...
  226.                                 | ...after you calmed down, do the following:
  227.                                 | a) Make a complete backup
  228.                                 | b) Use a spooled MapCheck output to determine
  229.                                 |    which files are damaged & check them
  230.                                 | c) Format your HD; simply writing an empty
  231.                                 |    directory structure (as offered by some
  232.                                 |    formatting programs) is sufficient.
  233.  
  234.  
  235. If it doesn't work...
  236. —————————————————————
  237. • did you load the correct map? (try *MapInfo)
  238.  
  239. • is it an E format disc (*Map should say 'new map, new directories' on top)
  240.  
  241.  
  242.  
  243. Bugs
  244. ————
  245. • Should be able to recognise non-E-Format (indeed, non-FileCore) discs.
  246.  
  247. • MapFree checks the free fragment chain more thoroughly than MapCheck, so
  248. use it!
  249.  
  250. • MapCheck only list fragment clashes, it doesn't list the files affected.
  251.  
  252. • Apart from the rather trivial file extent correction mentioned above,
  253.   MapManager still can't repair the disc map or the directory tree. I really
  254.   hope to implement it in a future release.
  255.  
  256. Glossary
  257. ————————
  258. • File ID
  259. • Fragment ID
  260. • Filenumber
  261. I use these interchangeably; normally fragment ID is used when talking about
  262. different fragments, while file ID or filenumber refers to the object.
  263.  
  264. • Object
  265. In RISC OS, an object is either a file or directory. Note that 'file ID'
  266. should be really called 'object ID' because directories have an ID as well.
  267.  
  268. (Acorn has changed the terminology in the new PRMs. So far I had no time to
  269. make this text conform to them - sorry.)
  270.  
  271.  
  272. Acknowledgments
  273. ———————————————
  274. Dominic Symes for the best ever text editor Zap - highly recommended.
  275.  
  276. Walter Meyer for providing his map progs and daring to test the alpha
  277. versions.
  278.  
  279. Chris Poole for his fsfschk program, some ideas of his code were incorporated
  280. into MapManager. (the modifying disc bits haven't made it yet - sorry.)
  281.  
  282. Acorn for building one of the best computer platforms, and supplying one of
  283. the best operating systems with it. Parts of this help file and a few bytes
  284. of code were take from Acorn's documents.
  285.  
  286.  
  287. Distribution
  288. ————————————
  289. The module MapManager and its source code are copyright Holger Klingspohr
  290. 1993 & 1994. I offer no guarantees as to the reliability or stability of
  291. MapManager or the correctness of the technical details outlined in this
  292. document.
  293.  
  294. You may copy the program freely provided that the whole application remains
  295. unaltered. You may not sell the program without my written permission. You
  296. must not distribute this software for commercial gain. However, Public Domain
  297. libraries may distribute the program provided they charge at most 3 pounds
  298. sterling per disc. If anyone one else would like to distribute MapManager
  299. then please [e-]mail me first to get my permission.
  300.  
  301. MapManager is distributed complete with source code. Feel free to use chunks
  302. of code in your own freeware programs, but please acknowledge me somewhere in
  303. your documentation. To re-assemble the complete module you will obviously need
  304. the relevant header files. Again, if you want to use parts of MapManager in
  305. commercial code please get in touch with me.
  306.  
  307. Please send any bug fixes or other improvements to me so I can modify the
  308. master copy. If this includes some code fragments - so much better, but
  309. please do not distribute a modified ('hacked') version.
  310.  
  311.  
  312.  
  313. Holger Klingspohr
  314. Ebelingstr. 1 / 6.3.2.e
  315. D-21073 Hamburg
  316. Germany
  317. email: klingspohr@tu-harburg.d400.de
  318.  
  319.  
  320.  
  321. Change Log:
  322. ———————————
  323. 0.26    23 May 1993 first alpha release, didn't even work correctly on my setup
  324. 0.30    13 Jun 1993 second alpha release, first try to handle bitsizes greater
  325.                     than than the sector size correctly; seems to work
  326. 0.32    22 Jun 1993 first beta release. MapZone & FindID tools added
  327. 0.33    26 Jun 1993 now reports clashing fragments & floppy density correctly;
  328.                     also spellchecked this help file
  329. 0.34    28 Jun 1993 second beta release. cleaned up things generally
  330. 0.35    02 Jul 1993 
  331. 0.40    11 Jul 1993 started to speed up MapCheck
  332. 0.48    12 Dec 1993 third beta release
  333. 0.49    13 Mar 1994 [release] speeded & tidied up a bit
  334.