home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 8: Compilations 2 / nf_archive_eight_v1.0.iso / TOOLS / WIN32 / MSATOST.ZIP / msatost.txt < prev   
Text File  |  1997-08-31  |  8KB  |  194 lines
  1.                             MSA-to-ST version 1.3
  2.  
  3.                             =====================
  4.  
  5.                          Copyright 1997 Damien Burke 
  6.  
  7.                         email: st@jetman.demon.co.uk
  8.                WWW: http://www.jetman.demon.co.uk/st/index.html
  9.         
  10.   DESCRIPTION
  11. --===========-----------------------------------------------------------------
  12.  
  13. MSA-to-ST converts Magic Shadow Archiver (MSA) files to .ST disk images for
  14. use with the Atari ST emulator, PacifiST. Both compressed and uncompressed
  15. archives are supported, as are disks that have been split into more than
  16. one MSA file.
  17.  
  18.   WHAT'S NEW IN VERSION 1.3?
  19. --==========================--------------------------------------------------
  20.  
  21. Wildcards and filename completion - i.e. you need no longer supply an output
  22. filename (it'll guess it based on the input filename). This has the handy
  23. side-effect that you can now use drag and drop in Win95! Just drag the MSA
  24. file to convert onto the MSATOST.EXE icon (or a shortcut to it) and the file
  25. is automatically converted. An icon is supplied if you want to use it; I also
  26. recommend you set the properties of the EXE file so that the DOS box is
  27. closed after execution.
  28.  
  29. You can now convert multiple files using wildcard characters in the input
  30. filename. In this case, you *cannot* supply an output filename - no point
  31. overwriting the same filename over and over again, is there?
  32.  
  33. Also fixed one small bug - if converting an MSA file of precisely 80 tracks
  34. it would give a spurious 'not a full image' message. This never actually
  35. caused a problem, it was just a message!
  36.  
  37.   DISTRIBUTION
  38. --============----------------------------------------------------------------
  39. MSA-to-ST is freeware and unsupported. I take no responsibility for any data
  40. loss you may suffer (e.g. if you type the wrong filename in and overwrite
  41. something important). If you find bugs, mail me and I'll fix them. You may do
  42. what you want with the program provided you include this documentation
  43. unaltered, and do not alter the program itself.
  44.  
  45.   USAGE
  46. --=====-----------------------------------------------------------------------
  47.  
  48. To use MSA-to-ST, type:
  49.  
  50. MSATOST <name of MSA input file> [name of ST output file] [/Q] [/O]
  51.         
  52. /Q - quiet mode - no screen output and no pauses for keyboard input
  53. /O - overwrite - if output file exists, overwrite without prompting
  54.         
  55. If /Q is used without /O and an output file exists, it will *not* be
  56. overwritten and the program will *not* extract the archive at all. Both /Q and
  57. /O, if used, must be *after* the input/output filenames, for example:
  58.  
  59. MSATOST INFILE.MSA OUTFILE.ST /Q /O
  60.  
  61. ...extracts the disk in INFILE.MSA to the disk image OUTFILE.ST without
  62. any onscreen messages and overwriting the existing OUTFILE.ST file (if it
  63. exists).
  64.  
  65. MSATOST INFILE.MSA
  66.  
  67. ...extracts INFILE.MSA to INFILE.ST - the output filename is based on the
  68. input filename if you don't supply a specific output filename.
  69.  
  70. MSATOST *.MSA
  71.  
  72. ...extracts every MSA file in the current directory, using output filenames
  73. based on the input filenames as described above.
  74.  
  75. While extracting, a progress bar is displayed. Each block in the bar indicates
  76. one track converted. Large blocks indicate compressed tracks and smaller
  77. blocks indicate uncompressed tracks.
  78.  
  79.   NOTES
  80. --=====-----------------------------------------------------------------------
  81.  
  82. MSA-to-ST will return status codes of 0 for success or 1 for failure; you can
  83. check for these in a batch file by testing ERRORLEVEL or if you are running
  84. MSA-to-ST from within another program you can check by testing the return code
  85. you get from the execution.
  86.  
  87.   MULTI-MSA DISKS
  88. --===============-------------------------------------------------------------
  89.  
  90. Disks that have been split into more than one MSA file (e.g. an 800Kb disk
  91. split into tracks 1 to 40 and 41 to 80 in order to keep two small MSA files
  92. that can fit onto 720Kb disks) should be handled correctly by MSA-to-ST, but
  93. if you find any problems please mail me. It doesn't matter what order you
  94. convert the MSA files, just make sure you use the same output file, e.g.:
  95.  
  96. MSATOST 01_TO_40.MSA OUTFILE.ST
  97. MSATOST 41_TO_80.MSA OUTFILE.ST
  98.  
  99. Any areas in the image not filled with data from an MSA file will be full of 0
  100. bytes and such an incomplete image will no doubt not be of any use until you
  101. complete it by converting all the appropriate MSA files. Also note that if you
  102. convert only the first part of a disk, the image file will be too short and
  103. PaCifiST may be unable to use it. I doubt this will be a problem but if it is
  104. mail me and I'll make the next version add blank bits to the end of the image
  105. in such a situation.
  106.  
  107.   .MSA FILE FORMAT
  108. --================------------------------------------------------------------
  109.  
  110. For those interested, an MSA file is made up as follows:
  111.  
  112. Header:
  113.  
  114. Word    ID marker, should be $0E0F
  115. Word    Sectors per track
  116. Word    Sides (0 or 1; add 1 to this to get correct number of sides)
  117. Word    Starting track (0-based)
  118. Word    Ending track (0-based)
  119.  
  120. Individual tracks follow the header in alternating side order, e.g. a double
  121. sided disk is stored as:
  122.  
  123. TRACK 0, SIDE 0
  124. TRACK 0, SIDE 1
  125. TRACK 1, SIDE 0
  126. TRACK 1, SIDE 1
  127. TRACK 2, SIDE 0
  128. TRACK 2, SIDE 1
  129.  
  130. ...and so on. Track blocks are made up as follows:
  131.  
  132. Word    Data length
  133. Bytes    Data
  134.  
  135. If the data length is equal to 512 x the sectors per track value, it is an
  136. uncompressed track and you can merely copy the data to the appropriate track
  137. of the disk. However, if the data length value is less than 512 x the sectors
  138. per track value it is a compressed track.
  139.  
  140. Compressed tracks use simple a Run Length Encoding (RLE) compression method.
  141. You can directly copy any data bytes until you find an $E5 byte. This signals
  142. a compressed run, and is made up as follows:
  143.  
  144. Byte    Marker - $E5
  145. Byte    Data byte
  146. Word    Run length
  147.  
  148. So, if MSA found six $AA bytes in a row it would encode it as:
  149.  
  150. $E5AA0006
  151.  
  152. What happens if there's an actual $E5 byte on the disk? Well, logically
  153. enough, it is encoded as:
  154.  
  155. $E5E50001
  156.  
  157. This is obviously bad news if a disk consists of lots of data like
  158. $E500E500E500E500... but if MSA makes a track bigger when attempting to
  159. compress it, it just stores the uncompressed version instead.
  160.  
  161. MSA only compresses runs of at least 4 identical bytes (after all, it would be
  162. wasteful to store 4 bytes for a run of only 3 identical bytes!). There is one
  163. exception to this rule: if a run of 2 or 3 $E5 bytes is found, that is stored
  164. appropriately enough as a run. Again, it would be wasteful to store 4 bytes
  165. for every single $E5 byte.
  166.  
  167. The hacked release of MSA that enables the user to turn off compression
  168. completely simply stops MSA from trying this compression and produces MSA
  169. images that are completely uncompressed. This is okay because it is possible
  170. for MSA to produce such an image anyway, and such images are therefore 100%
  171. compatible with normal MSA versions (and MSA-to-ST of course).
  172.  
  173.   .ST FILE FORMAT
  174. --===============-------------------------------------------------------------
  175.  
  176. The file format of the .ST image files used by PaCifiST is simplicity itself;
  177. they are just straight images of the disk in question, with sectors stored in
  178. the expected logical order. So, on a sector basis the images run from sector
  179. 0 (bootsector) to however many sectors are on the disk. On a track basis the
  180. layout is the same as for MSA files but obviously the data is raw, no track
  181. header or compression or anything like that.
  182.  
  183. .ST files can be written to real disks using DKC's STImage program for the PC,
  184. available from my web site (see top of this document). If you have .ST files
  185. on your real ST you can write them to a disk using ArghBlarg's STTODSK.TTP
  186. program, also available from my web site.
  187.  
  188. You can also use MSAtoST's companion program, STtoMSA, to convert .ST files to
  189. MSA files. That is also available from my web site.
  190.  
  191. -- 
  192. Damien Burke
  193. 31st August 1997
  194.