
                       Documentation for cbmconvert 2.0
                                       
cbmconvert 2.0 - extract and convert different Commodore binary archives

   Copyright  1996-1998 [1]Marko Mkel
   
     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2 of the
     License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
     General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
     
1 Introduction

   There are many archiving programs for the Commodore 64, all of which
   are incompatible with archiving programs on other systems. This
   cbmconvert utility tries to address this problem. It extracts files
   from most known file formats and writes them to several different
   formats, including some formats used by some Commodore 64 emulators.
   
   This release of cbmconvert does not contain LHARC support any more,
   since 1541 disk images (either plain or ZipCoded) and Lynx archives
   are much easier to handle. If you need LHARC support, get the older
   release, cbmconvert 1.1.
   
   All code has been cleaned up. The file type management in cbmconvert
   2.0 is very flexible, and it is very easy to add file types later.
   Currently cbmconvert reads the following file types: Arkive, Lynx,
   ARC64/128, PC64, disk images (1541, 1571, 1581, both native and C128
   CP/M format), and raw files. Conversions between 1541 disk images and
   ZipCoded files can be made with the two supplied utilities disk2zip
   and zip2disk.
   
2 Getting Started

   Compile cbmconvert by entering make. If you do not have GNU C compiler
   (gcc) installed on your system, you will need to edit the Makefile.
   
   The compilation should leave you with three executables: cbmconvert,
   zip2disk and disk2zip. Install these to your binaries directory, and
   you are ready to go. Ask your system administrator and/or a local guru
   if you do not know where to install the binaries. Or just use them
   from the current directory.
   
3 Using cbmconvert

   As of version 2.0, cbmconvert consists of three programs:
   
   cbmconvert
          The main program that makes most conversions.
          
   disk2zip
          ZipCode creator. Encodes a 35-track 1541 disk image to four
          ZipCode files (1!filename..4!filename).
          
   zip2disk
          ZipCode dissolver. Decodes a 35-track 1541 disk image from four
          ZipCode files.
          
  3.1 cbmconvert
  
   Starting with version 2.0, cbmconvert consists of independent file
   reader and writer modules that are controlled through a main program.
   There only a command-line interface, but adding an interactive user
   interface should be easy (any volunteers?).
   
   cbmconvert reads all files in all input files you specify on the
   command line and writes them in the format you specify. If you want to
   copy only some files from a set of archive files to an archive file or
   disk image, you will have to extract all the files to a single-file
   format such as the PC64 format, and to copy the wanted individual
   files to the output archive with another invocation of cbmconvert.
   
   You can get a list of cbmconvert options by invoking the program
   without any arguments. cbmconvert supports following file formats:
   
   Raw files
          Files with just the raw data. Written with the -I and -N
          options, read with the -n option.
          
   PC64 files
          Also known as "P00" files. Written with the -P option, read
          with the -p option.
          
   Lynx archives
          Written with -L, read with -l.
          
   C128 CP/M disk images
          Written with -C[478], read with -c.
          
   CBM DOS disk images
          Written with -D[478], read with -d. 1571 and 1581 support have
          not been tested properly, and not all 1581 features are
          implemented.
          
   ARC/SDA
          Read with -a. No write support.
          
   Arkive
          Read with -k. No write support.
          
   T64
          Read with -t. No write support.
          
    3.1.1 CP/M disk images
    
   Since cbmconvert has been written exclusively with Commodore file
   names in mind, the support for CP/M disk images is a bit clumsy. You
   may want to rename the files after extracting them from the disks. For
   instance, if you have downloaded the CP/M disk images from
   http://www.funet.fi/pub/cbm/demodisks/c128/, you can use the following
   commands in bash to extract the files from the disk images:
   
gunzip *.d64.gz

for i in *.d64; do mkdir ${i%.d64}; cd ${i%.d64}; cbmconvert -c ../$i; cd ..; d
one

for i in */*.prg; do mv $i "`echo ${i%.prg}|tr A-Z a-z`"; done

   CP/M does not store the exact length of the files anywhere. That is
   why many CP/M programs create files whose length is a multiple of 128
   bytes. Text files in CP/M commonly use ^Z as an end-of-file delimiter,
   and many programs fill the extra bytes in the last 128-byte block of
   the file with this character. The CP/M routines in cbmconvert does so
   as well, and it removes the padding when reading the files. So, you
   could use cbmconvert to remove the padding. But you may prefer the
   following bash command (requires Perl 5):
   
for i in *; do perl -i -e 'undef $/; $_=; while(/\032$/){chop} print' $i; done

    3.1.2 Flaws of cbmconvert
    
   The conversion may lose some file name or attribute information. In
   some cases, the filenames will be converted from PETSCII to ASCII or
   vice versa, and some PETSCII or ASCII specific characters will be lost
   in the conversions. Non-standard directory information available in
   some formats will be lost as well.
   
   Lynx, Arkive and ARC allow duplicate filenames. But cbmconvert detects
   them and refuses to write multiple files with identical names to
   archives or to disk images. These duplicates are often used as
   directory separators, to separate groups of filenames. If you really
   need such separators, use 1-block-long PRG or SEQ files with different
   names. For example, the first separator can be a string of 16 dashes,
   the second one can be 15 dashes, and so on.
   
   Arkive also works on illegal filetypes that cannot be created without
   directly modifying the directory blocks. Such files will be converted
   to a supported file type. Files with unknown types on disk images will
   be skipped.
   
   Handling the errors on disk images could be more robust. Not all
   (typically BAM-related) errors on CBM DOS disk images are detected.
   For erroneous 1541 disk images that do not work with the new
   cbmconvert, you may want to try the disk2files program of the previous
   release.
   
  3.2 disk2zip
  
   This program converts a standard 35-track, 683-block 1541 disk image
   to ZipCode format. Because the ZipCode format stores the disk
   identifier, this conversion adds information. You can use the -i
   option to specify the disk identifier.
   
  3.3 zip2disk
  
   ZipCoded archives consist of four files prefixed with a number from 1
   to 4, and a exclamation point. To extract an archive having the files
   "1!disk", "2!disk", "3!disk" and "4!disk", command "zip2disk disk".
   You may then delete the original files with "rm [1-4]\!disk" or
   similar. But note that some software (demos and copy-protected
   software) may rely on the disk identifier, which will not be stored in
   the 1541 disk image file.
   
   Support for ZipCode SixPacks ("1!!disk", "2!!disk", ..., "6!!disk")
   could be added easily, but this format is used mainly for really
   custom 1541 disks with abnormal low-level format, for which there
   doesn't exist any commonly agreed representation format.
   
4 Credits

   The zip2disk module was originally programmed by [2]Paul David
   Doherty. The ISO 9660 compliant filename truncation algorithm was
   taken from the T64TOP00 utility created by Wolfgang Lorenz as a part
   of his now discontinued PC64 emulator.
   
   Support for 1581 CBM DOS disk images was programmed by Pasi Ojala.
   
   The ARC/SDA dissolving code was originally written by Chris Smeets.

References

   1. mailto:Marko.Makela@ftp.funet.fi
   2. mailto:h0142kdd@rz.hu-berlin.de
