home *** CD-ROM | disk | FTP | other *** search
/ MACD 4 / MACD4.iso / Emulatory / SPConv / Docs / SPCONV.DOC < prev   
Encoding:
Text File  |  1978-03-06  |  11.9 KB  |  326 lines
  1.  
  2.  
  3. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  4.  
  5.  
  6. NAME
  7.  
  8.      spconv - Convert snapshot files (.SNA, .SP, .Z80,  .PRG,  .ACH,  .ZX,
  9.      .SNX and RAW)
  10.  
  11.  
  12. DISCLAIMER
  13.  
  14.      This program is Public Domain, and because of that I will not be liable
  15.      for any damages resulting from the use of this software.
  16.  
  17.  
  18. SYNOPSIS
  19.  
  20.      spconv <infile.EXT> <.EXT>
  21.      spconv <infile.EXT> <outfile.EXT>
  22.  
  23.  
  24. DESCRIPTION
  25.  
  26.      Spconv is a utility to convert between various snapshot formats. Snapshot
  27.      files  are created by various spectrum emulators. SPCONV converts between
  28.      .SNA, .SP, .Z80, .PRG, .ACH, .SNX and .ZX files.
  29.  
  30.      Wildcards for the infile or outfile parameters are not accepted, an error
  31.      message  is  displayed  if  either  *  or  ?  is found in one or both the
  32.      filenames. The outfile parameter is either a full filename  or  only  the
  33.      suffix .SNA, .SP, .Z80, .PRG, .ACH, .SNX or .ZX. The prefix is taken from
  34.      the first parameter in that case.
  35.  
  36.      Normaly the <infile> and <outfile> are not of the same type. If they  are
  37.      you will get a error message. This is so unless both files are of the .SP
  38.      or .Z80 type. In case of .SP format the converter  will  convert  an  old
  39.      style .SP file to a new style .SP file or from a new style .SP file to an
  40.      old style .SP file, depending on the input. The old  style  .SP  file  is
  41.      used  by VGASPEC, with seems to be an unauthorised version of the spanish
  42.      "SPECTRUM" program. The "SPECTRUM" program will use  the  new  style  .SP
  43.      files.
  44.  
  45.      In case both files are of the .Z80 format spconv will read the .Z80  file
  46.      and will output a .Z80 file in the version 1.45 .Z80 format. This enables
  47.      conversion of normal 48K Spectrum files made by Z80 version 2.01  or  3.0
  48.      to  the  older format so they can be loaded in a version 1.45 Z80 or 2.01
  49.      Z80 emulator. Of course additional information that can only be stored in
  50.      the  version  2.01  and 3.0 files is lost. Therefore spconv will check if
  51.      the .Z80 file is for a 48K Spectrum and check if the Interface-1 rom  was
  52.      not  paged  in.  If  the  check  fails  an error message is given and the
  53.      conversion is terminated - no output will be produced. Spconv  will  only
  54.      output  version  1.45  .Z80 files since these are compatible with old and
  55.      new Z80-emulator versions. If Spconv encounters a .Z80 format  file  that
  56.      seems  to  be  newer  than version 3.0, Spconv will attempt to convert it
  57.      anyway in the hope that it is upwards compatible. A warning will ge given
  58.      in that case.
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                   15th June, 1995                                1
  65.  
  66.  
  67.  
  68. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  69.  
  70.  
  71. CONVERSION NOTES
  72.  
  73.      [.SP files - Used by the Spanish "SPECTRUM" and "VGASPEC" programs.]
  74.  
  75.      Conversion to/from .SP files may not always work. It is not clear  to  me
  76.      how  IFF,  IFF2  and the interrupt mode are stored in the .SP file. Since
  77.      version 1.02 I have made some improvements to  this  type  of  conversion
  78.      however,  it  sould  work now, but I have not enough .SP samples to fully
  79.      test it. Note that crashing of a converted image may also  be  caused  by
  80.      bugs  in  the SPECTRUM emulator. Conversion to .SP will work if the image
  81.      is converted from a RAW image (see later).
  82.  
  83.      [.Z80 files - Used by the Dutch  "Z80"  programs.  This  format  is  also
  84.      usable for 128K Spectrum images.]
  85.  
  86.      [.SNA files - Used by the  Norwegian  "JPP"  PC-program;  the  "Spectrum"
  87.      program  for  the Amiga; the "XZX" X-Windows program and a lot more. This
  88.      is the most  supported  format  since  it  originated  from  the  Mirage-
  89.      Microdirver format.]
  90.  
  91.      Conversion between .SNA and .Z80 and from  .Z80  to  .SNA  should  be  no
  92.      problem,  both formats are sufficiently described in the documentation of
  93.      JPP (the norwegian emulator) and Z80 (the dutch emulator).
  94.  
  95.      [.PRG files are loaded by a PC-emulator from Ireland. This  emulator  can
  96.      not save in this format.]
  97.  
  98.      Conversion to/from .PRG files should work  fine  also.  I  don't  have  a
  99.      description  of  that format, but I think I figured it all out by looking
  100.      at some samples. I only don't know where the border colour is stored. The
  101.      specem  emulator  (an Irish emulator) doesn't show the border, so I can't
  102.      find out by trail and error.
  103.  
  104.      [.ACH files are  used  on  Archimeds  computers  by  an  emulator  called
  105.      "Speculator" or "!Speccy"]
  106.  
  107.      Since  version  1.07  Conversion  should  work  without   problems.   The
  108.      conversion  is  patterned after a program (also called Spconv) and a BBC-
  109.      Basic program from John Veness (supplied to me by Mike Borcherds). I also
  110.      got a .ACH file snapped just after startup which was most helpfull. Since
  111.      the programs I got were written independently but had  all  registers  at
  112.      the  same place (but one got her accent registers swapped with the normal
  113.      registers), I think it is pritty  save  to  assume  that  the  format  is
  114.      correct now. The previous version of this converter got register 'I' from
  115.      the wrong spot, and more important, I forgot to set  the  interrupt  mode
  116.      when converting to .ACH file format.
  117.  
  118.      It is also tested now with a fair collection of snaps. The .ACH extension
  119.      is  my  own invention to cope with the MS-DOS naming conventions. I named
  120.      them this way because the samples I had ended in ".archimedes" and use of
  121.      .ARC  as  extension  didn't  sound  like  a  good  idea.  I don't have an
  122.      archimedes computer to test it but somebody else (Adrian Jackson) did  it
  123.      for me. For proper conversion you need the spectrum rom because that is a
  124.      part of the archimedes image (don't blame me).  The  ROM  must  be  named
  125.      'spectrum.rom'  and  be  located  in the working directory or in the same
  126.      directory as spconv.exe. If no ROM is found  the  converter  will  insert
  127.  
  128.  
  129.                   15th June, 1995                                2
  130.  
  131.  
  132.  
  133. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  134.  
  135.  
  136.      NULL bytes.
  137.  
  138.      [.ZX files are used by the KGB emulator on a Commodore Amiga]
  139.  
  140.      Conversion to/from .ZX files should  work,  Peter  McGavin  send  me  the
  141.      definition  of  the format as used in the KGB emulator.  I implemented it
  142.      that way but I don't have an Amiga with a KGB emulator so it is untested!
  143.      I  previously  used  the  information about the format of the file from a
  144.      VAX-Basic program supplied to me by  Jason  Brown  and  most  information
  145.      correlated  so  I'm hopefull that it works. Please send me feetback if it
  146.      works so I can put it here in the documentation. Oh, before I forget, the
  147.      .ZX  format contains the last 132 bytes of the spectrum rom (don't ask me
  148.      why) so spconv will look for "spectrum.rom" in the working  directory  or
  149.      in the same directory as spconv.exe is located.  If absent than the first
  150.      132 bytes will be NULL bytes.
  151.  
  152.      [.SNX files are used by one of the Atari ST Spectrum emulators.]
  153.  
  154.      The .SNX format is an extended version of the SNA format.  The headers of
  155.      SNA and SNX files are nearly identical; SNX files contain a 'XSNA' marker
  156.      and have 10 extra bytes,  these being the settings  for particular things
  157.      in the emulator program.  The RAM image itself is packed using simple RLE
  158.      encoding, so file sizes are similar to .Z80 files.  Only three .SNX files
  159.      have been  tested so far,  but they all  converted to a  different format
  160.      (and back) with no problems.
  161.  
  162.      [RAW files are created by saving the whole ram on a real spectrum to  the
  163.      RS232 port of Interface-1 from basic]
  164.  
  165.      Spconv can also be used to convert a raw spectrum  image  to  a  snapshot
  166.      file.  The  image  has  to  be  captured  with via the RS232 connetion on
  167.      Interface-1.  Some tools to do this are in an archive called "SPEC232". A
  168.      program  called  "SLOAD"  will  read from the RS232 link to a file on the
  169.      MSDOS-PC. At the Spectrum side the the command
  170.  
  171.      SAVE *"b"CODE 16384,49152
  172.  
  173.      HAS to be used. Spconv will convert the file is such  way  that  it  will
  174.      continue in the basic interpreter after the snapshot is loaded. so
  175.  
  176.      SAVE *"b"CODE 16384,49152:PRINT Hello, World!
  177.  
  178.      will after conversion to a snapshot file and loading it in  the  emulator
  179.      begin  with printing "Hello, World!". A description how to wire the RS232
  180.      cable is also in the "SPEC232" package.
  181.  
  182.  
  183. EXAMPLES
  184.  
  185.      Converting a .SNA JPP file to the .Z80 Dutch emulator:   spconv  game.sna
  186.      game.z80 or spconv game.sna .z80
  187.  
  188.  
  189. DIAGNOSTICS
  190.  
  191.      0 - OK: The program finished without problems
  192.  
  193.  
  194.                   15th June, 1995                                3
  195.  
  196.  
  197.  
  198. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  199.  
  200.  
  201.      1 - USAGE:  The program was called incorrectly:
  202.  
  203.      -    Wrong number of parameters
  204.  
  205.      -    Wildcards on the command-line
  206.  
  207.      -    Input and output are of the same type (not for .SP and .Z80)
  208.  
  209.      2 - READ_ERROR:  There was a problem while reading the input file:
  210.  
  211.      -    Error while reading the input file
  212.  
  213.      -    Error while fseeking the input file
  214.  
  215.      3 - WRITE_ERROR: There was a problem while creating the output file:
  216.  
  217.      -    Error while writing the output file
  218.  
  219.      -    Error with opening/reading the spectrum.rom needed  for  the  output
  220.       file.
  221.  
  222.      4 - FILE_ERROR: There was a problem with the input or output file format:
  223.  
  224.      -    Input file does not exist
  225.  
  226.      -    Type of input or output file not known
  227.  
  228.      -    Input file is:
  229.  
  230.      +    A newer version of an existing type
  231.  
  232.      +    Corrupt
  233.  
  234.      +    Not in the expected format (RAW and new .SP types)
  235.  
  236.      +    Not a 48K spectrum file (in .Z80 files)
  237.  
  238.      -    Input file snapshot was taken while the interface-1 was paged in (in
  239.       .Z80  files).  The  other  file  formats  can  not  cope  with  this
  240.       (including the version 1.45 .Z80 files).
  241.  
  242.      -    Undocumented page number in .Z80 files (file corrupt).
  243.  
  244.      -    Decompression of .Z80 file failed (file corrupt).
  245.  
  246.  
  247. PORTABILITY
  248.  
  249.      The program should be portable. Assumptions about endian-ness are avoided
  250.      and  I  ensured  clean  compilation with Turbo-C++ 1.0 (with all warnings
  251.      enabled).  Chris Wells used this command line of GCC on this program (and
  252.      gave feetback until it gave a clean compile):
  253.  
  254.      gcc -ansi -pedantic -Wall -Wwrite-strings -Wshadow -Wformat
  255.      -Wpointer-arith -Wconversion -Wstrict-prototypes
  256.      -Wmissing-prototypes -o spconv spconv.c
  257.  
  258.  
  259.                   15th June, 1995                                4
  260.  
  261.  
  262.  
  263. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  264.  
  265.  
  266.      I also ensured that the identifiers used in the program are uniq  in  the
  267.      first  8  characters.  I  don't  expect  much problems when compiling the
  268.      program with other compilers. The code does make assumptions  about  path
  269.      names.   Using  the  program on a VAX will give problems with recognizing
  270.      directories e.t.c. especially for finding "spectrum.rom", I leave  a  fix
  271.      for this as an exercise...
  272.  
  273.  
  274. BUGS
  275.  
  276.      Conversion to/from .SP files may not always work.
  277.  
  278.  
  279. THANKS TO
  280.  
  281.      Thanks  for  suppling  information  and  for  creating   these   spectrum
  282.      emulators:
  283.      Arnt Gulbrandsen (author of JPP)
  284.      Ramco v.d. Woestijne (supplied new .SP format);
  285.      Gerton A. Lunter (author of Z80);
  286.      Pedro Gimeno (author of SPECTRUM);
  287.      Kevin J Phair (author of SPECEM);
  288.      Mike Borcherds (suppied the archimedes file format);
  289.      Jason Brown (suppied the initial KGB file format);
  290.      Peter McGavin (suppied the complete KGB file format);
  291.      John Veness (reverse engineerd the ACH file format);
  292.      Adrian Jackson (send me a near perfect .SNA to .ACH converter);
  293.      Chris Wells (ran the program through GCC in pedantic  mode  and  supplied
  294.      the UNIX man page and Makefile);
  295.      Eric March (supplied the SNX file format).
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.                   15th June, 1995                                5
  325.  
  326.