home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 12: Textmags & Docs / nf_archive_12.iso / TOOLS / WIN32 / STTOMSA.ZIP / sttomsa.txt < prev   
Text File  |  1997-05-31  |  7KB  |  175 lines
  1.                             ST-to-MSA version 1.0
  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. ST-to-MSA converts the .ST disk images used by PaCifiST, the Atari ST
  14. emulator, into compressed Magic Shadow Archiver (MSA) files.
  15.  
  16.   DISTRIBUTION
  17. --============----------------------------------------------------------------
  18. ST-to-MSA is freeware and unsupported. I take no responsibility for any data
  19. loss you may suffer (e.g. if you type the wrong filename in and overwrite
  20. something important). If you find bugs, mail me and I'll fix them. You may do
  21. what you want with the program provided you include this documentation
  22. unaltered, and do not alter the program itself.
  23.  
  24.   USAGE
  25. --=====-----------------------------------------------------------------------
  26.  
  27. To use ST-to-MSA, type:
  28.  
  29. STTOMSA <name of ST input file> <name of MSA output file> [/Q] [/O]
  30.         
  31. /Q - quiet mode - no screen output and no pauses for keyboard input
  32. /O - overwrite - if output file exists, overwrite without prompting
  33.         
  34. If /Q is used without /O and an output file exists, it will *not* be
  35. overwritten and the program will *not* create the archive at all. Both /Q and
  36. /O, if used, must be *after* the input/output filenames, for example:
  37.  
  38. STTOMSA INFILE.ST OUTFILE.MSA /Q /O
  39.  
  40. ...creates the OUTFILE.MSA archive from the disk image INFILE.ST without
  41. any onscreen messages and overwriting the existing OUTFILE.MSA file (if it
  42. exists).
  43.  
  44. While creating, a progress bar is displayed. Each block in the bar indicates
  45. one track converted. Large blocks indicate compressed tracks and smaller
  46. blocks indicate uncompressed tracks.
  47.  
  48.   NOTES
  49. --=====-----------------------------------------------------------------------
  50.  
  51. ST-to-MSA will return status codes of 0 for success or 1 for failure; you can
  52. check for these in a batch file by testing ERRORLEVEL or if you are running
  53. ST-to-MSA from within another program you can check by testing the return code
  54. you get from the execution.
  55.  
  56.   SPLITTING DISKS INTO MORE THAN ONE MSA FILE
  57. --===========================================---------------------------------
  58.  
  59. One of ST-to-MSA's uses is to enable ST users to use some of the .ST files on
  60. the net. However, many of these files are images of disks that are quite
  61. large - it can be difficult to get a PC to format a disk to the appropriate
  62. size in order to write the .ST image to it, and if that fails, it can be even
  63. more difficult to try and copy the .ST file over to your ST as it is so large.
  64.  
  65. So, converting that .ST file to an MSA archive can give you a smaller file to
  66. deal with, which you can then de-MSA on your real ST. However, the compression
  67. routine used by MSA is very basic so many disk images will not get any smaller
  68. when converted to an MSA file. This leaves you back at square one - how do you
  69. get such a big file onto your ST so you can de-MSA it there?
  70.  
  71. Answer: split it into two MSA files. If you supply ST-to-MSA with a *second*
  72. output filename, it will create two separate MSA files - the first holding
  73. the first half of the disk and the second holding the second half (oddly
  74. enough). For example, if BIGDEMO.ST is an 800Kb disk (80 tracks, 2 sides, 10
  75. sectors per track), then the following:
  76.  
  77. STTOMSA BIGDEMO.ST BIGDEMO1.MSA BIGDEMO2.MSA
  78.  
  79. ...will create two MSA files named BIGDEMO1.MSA and BIGDEMO2.MSA. BIGDEMO1.MSA
  80. will store tracks 0 to 39 (or 1 to 40 as MSA likes to term them) and
  81. BIGDEMO2.MSA will store tracks 40 to 79 (or 41 to 80 in MSA-speak). Now it's a
  82. lot easier to get them across to your ST because you can use standard format
  83. ST disks (if you have TOS 1.04+) or standard 720Kb PC disks.
  84.  
  85.   .MSA FILE FORMAT
  86. --================------------------------------------------------------------
  87.  
  88. For those interested, an MSA file is made up as follows:
  89.  
  90. Header:
  91.  
  92. Word    ID marker, should be $0E0F
  93. Word    Sectors per track
  94. Word    Sides (0 or 1; add 1 to this to get correct number of sides)
  95. Word    Starting track (0-based)
  96. Word    Ending track (0-based)
  97.  
  98. Individual tracks follow the header in alternating side order, e.g. a double
  99. sided disk is stored as:
  100.  
  101. TRACK 0, SIDE 0
  102. TRACK 0, SIDE 1
  103. TRACK 1, SIDE 0
  104. TRACK 1, SIDE 1
  105. TRACK 2, SIDE 0
  106. TRACK 2, SIDE 1
  107.  
  108. ...and so on. Track blocks are made up as follows:
  109.  
  110. Word    Data length
  111. Bytes    Data
  112.  
  113. If the data length is equal to 512 x the sectors per track value, it is an
  114. uncompressed track and you can merely copy the data to the appropriate track
  115. of the disk. However, if the data length value is less than 512 x the sectors
  116. per track value it is a compressed track.
  117.  
  118. Compressed tracks use simple a Run Length Encoding (RLE) compression method.
  119. You can directly copy any data bytes until you find an $E5 byte. This signals
  120. a compressed run, and is made up as follows:
  121.  
  122. Byte    Marker - $E5
  123. Byte    Data byte
  124. Word    Run length
  125.  
  126. So, if MSA found six $AA bytes in a row it would encode it as:
  127.  
  128. $E5AA0006
  129.  
  130. What happens if there's an actual $E5 byte on the disk? Well, logically
  131. enough, it is encoded as:
  132.  
  133. $E5E50001
  134.  
  135. This is obviously bad news if a disk consists of lots of data like
  136. $E500E500E500E500... but if MSA makes a track bigger when attempting to
  137. compress it, it just stores the uncompressed version instead.
  138.  
  139. MSA only compresses runs of at least 4 identical bytes (after all, it would be
  140. wasteful to store 4 bytes for a run of only 3 identical bytes!). There is one
  141. exception to this rule: if a run of 2 or 3 $E5 bytes is found, that is stored
  142. appropriately enough as a run. Again, it would be wasteful to store 4 bytes
  143. for every single $E5 byte.
  144.  
  145. The hacked release of MSA that enables the user to turn off compression
  146. completely simply stops MSA from trying this compression and produces MSA
  147. images that are completely uncompressed. This is okay because it is possible
  148. for MSA to produce such an image anyway, and such images are therefore 100%
  149. compatible with normal MSA versions (and MSA-to-ST of course).
  150.  
  151. ST-to-MSA always tries to compress tracks - the time taken to try the
  152. compression is so small it wasn't worth putting in an option to turn it off.
  153.  
  154.   .ST FILE FORMAT
  155. --===============-------------------------------------------------------------
  156.  
  157. The file format of the .ST image files used by PaCifiST is simplicity itself;
  158. they are just straight images of the disk in question, with sectors stored in
  159. the expected logical order. So, on a sector basis the images run from sector
  160. 0 (bootsector) to however many sectors are on the disk. On a track basis the
  161. layout is the same as for MSA files but obviously the data is raw, no track
  162. header or compression or anything like that.
  163.  
  164. .ST files can be written to real disks using DKC's STImage program for the PC,
  165. available from my web site (see top of this document). If you have .ST files
  166. on your real ST you can write them to a disk using ArghBlarg's STTODSK.TTP
  167. program, also available from my web site.
  168.  
  169. You can also use STtoMSA's companion program, MSAtoST, to convert MSA files to
  170. .ST files. That is also available from my web site.
  171.  
  172. -- 
  173. Damien Burke
  174. 31st May 1997
  175.