-
Notifications
You must be signed in to change notification settings - Fork 2
/
cbmconvert.html
406 lines (343 loc) · 17 KB
/
cbmconvert.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
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
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en"><head>
<title>cbmconvert release notes</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css"><!--
body {
color: black;
background: white;
font-family: helvetica, sans-serif;
}
h1 { text-align: center; }
h2, h3, h4 { text-align: left; }
A:link, A:visited, A:active, A:hover {
display: inline;
color: red;
font-weight: normal;
}
A:link, A:visited { text-decoration: none; }
A:hover, A:active { text-decoration: underline; }
A:link.ext, A:visited.ext, A:active.ext, A:hover.ext {
color: blue;
text-decoration: underline;
}
td, th { text-align: left; }
td.c { text-align: center; }
--></style>
</head>
<h1><code>cbmconvert</code> release notes</h1>
<dl>
<dt><code>cbmconvert</code></dt>
<dd>create, extract and convert different Commodore binary archives</dd>
</dl>
<p>Copyright © 1993‒2006,2021‒2022 <a class="ext"
href="http:https://www.iki.fi/~msmakela/">Marko Mäkelä</a>.</p>
<blockquote>
<p>This program is free software; you can redistribute it and/or
modify it under the terms of the <a class="ext"
href="http:https://www.gnu.org/copyleft/gpl.html">GNU General Public
License</a> as published by the <a class="ext"
href="http:https://www.gnu.org/">Free Software Foundation</a>; either
version 2 of the License, or (at your option) any later version.</p>
<p>This program is distributed in the hope that it will be useful, but
<strong>without any warranty</strong>; without even the implied
warranty of <strong>merchantability</strong> or <strong>fitness for a
particular purpose</strong>. See the <a class="ext"
href="http:https://www.gnu.org/copyleft/gpl.html">GNU General Public
License</a> for more details.</p>
</blockquote>
<h2>Table of Contents</h2>
<dl>
<dd><a name="toc-intro" href="#intro">1</a> Introduction</dd>
<dd><a name="toc-start" href="#start">2</a> Getting Started</dd>
<dd><a name="toc-using" href="#using">3</a> Using <code>cbmconvert</code>
<dl>
<dd><a name="toc-using-c" href="#using-c">3.1</a> <code>cbmconvert</code>
<dl>
<dd><a name="toc-using-c-cpm" href="#using-c-cpm">3.1.1</a>
CP/M disk images</dd>
<dd><a name="toc-using-c-geos" href="#using-c-geos">3.1.2</a>
GEOS disk images</dd>
<dd><a name="toc-using-c-c2n" href="#using-c-c2n">3.1.3</a>
Commodore C2N tape archives</dd>
<dd><a name="toc-using-c-flaws" href="#using-c-flaws">3.1.4</a>
Flaws of <code>cbmconvert</code></dd>
</dl></dd>
<dd><a name="toc-using-d" href="#using-d">3.2</a> <code>disk2zip</code></dd>
<dd><a name="toc-using-z" href="#using-z">3.3</a> <code>zip2disk</code></dd>
</dl></dd>
<dd><a name="toc-credits" href="#credits">4</a> Credits</dd>
<dd><a name="toc-dist" href="#dist">5</a> Distribution
<dl>
<dd><a name="toc-dist-hist" href="#dist-hist">5.1</a> Revision History</dd>
</dl></dd>
</dl>
<h2><a name="intro" href="#toc-intro">1</a> Introduction</h2>
<p>There are many archiving programs for the Commodore 64, all of
which are incompatible with archiving programs on other systems. This
<code>cbmconvert</code> 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.</p>
<p>This release of <code>cbmconvert</code> 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, <code>cbmconvert 1.1</code>.</p>
<p>All code has been cleaned up. The file type management in
<code>cbmconvert 2.0</code> is very flexible, and it is very easy to
add file types later. Currently <code>cbmconvert</code> reads the
following file types: Arkive, Lynx, ARC64/128, PC64, tape images (T64
and native Commodore C2N), 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
<code>disk2zip</code> and <code>zip2disk</code>.
<h2><a name="start" href="#toc-start">2</a> Getting Started</h2>
<p>Compile <code>cbmconvert</code> as follows:
<pre>
mkdir build
cd build
cmake ..
cmake --build .
cmake --install .
</pre>
<p>The compilation should leave you with three executables:
<code>cbmconvert</code>, <code>zip2disk</code> and
<code>disk2zip</code>. The installation step is optional;
you may also invoke the executables from the build directory.</p>
<p>16-bit compilers will probably have trouble with
<code>cbmconvert</code>. For instance, the standard file I/O library
in Borland C uses signed 16-bit integers for <code>size_t</code>,
which is not enough.</p>
<h2><a name="using" href="#toc-using">3</a> Using <code>cbmconvert</code></h2>
<p>Starting with version 2.0.0, <code>cbmconvert</code> consists of
three programs:</p>
<dl>
<dt><code>cbmconvert</code></dt>
<dd>The main program that makes most conversions.</dd>
<dt><code>disk2zip</code></dt>
<dd>ZipCode creator. Encodes a 35-track 1541 disk image to four
ZipCode files
(<code>1!<var>filename</var></code>..<code>4!<var>filename</var></code>).</dd>
<dt><code>zip2disk</code></dt>
<dd>ZipCode dissolver. Decodes a 35-track 1541 disk image
from four ZipCode files.</dd>
</dl>
<h3><a name="using-c" href="#toc-using-c">3.1</a> <code>cbmconvert</code></h3>
<p>Since version 2.0, <code>cbmconvert</code> has independent file
reader and writer modules that are controlled through a main program.
There is only a command-line interface, but adding an interactive user
interface should be easy (any volunteers?).</p>
<p><code>cbmconvert</code> 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
<code>cbmconvert</code>.</p>
<p>You can get a list of <code>cbmconvert</code> options by invoking
the program without any arguments. <code>cbmconvert</code> supports
the following file formats:</p>
<dl>
<dt>Raw files</dt>
<dd>Files with just the raw data. Written with the <code>-I</code> and
<code>-N</code> options, read with the <code>-n</code> option.</dd>
<dt>PC64 files</dt>
<dd>Also known as "P00" files. Written with the <code>-P</code> option,
read with the <code>-p</code> option.</dd>
<dt>Lynx archives</dt>
<dd>Written with <code>-L</code>, read with <code>-l</code>.</dd>
<dt>Commodore C2N tape archives</dt>
<dd>Written with <code>-C</code>, read with <code>-c</code>. These files
are raw dumps of the data format the Commodore KERNAL routines
maintain. Block checksums and countdown leaders (0x89..0x81 for the
first copy and 9..1 for the second) are omitted, and the blocks are
not stored twice, but only once. The data consists of 192-byte tape
header blocks, 192-byte data file blocks, and arbitrary-length program
file blocks.</dd>
<dt>C128 CP/M disk images</dt>
<dd>Written with <code>-M[478]</code>, read with <code>-m</code>.</dd>
<dt>CBM DOS disk images</dt>
<dd>Written with <code>-D[478]</code>, read with <code>-d</code>.
1571 and 1581 support have not been tested properly, and not
all 1581 features have been implemented.</dd>
<dt>ARC/SDA</dt>
<dd>Read with <code>-a</code>. No write support.</dd>
<dt>Arkive</dt>
<dd>Read with <code>-k</code>. No write support.</dd>
<dt>T64</dt>
<dd>Read with <code>-t</code>. No write support.</dd>
</dl>
<h4><a name="using-c-cpm" href="#toc-using-c-cpm">3.1.1</a>
CP/M disk images</h4>
<p>Since <code>cbmconvert</code> 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 <a class="ext"
href="http:https://www.funet.fi/pub/cbm/demodisks/c128/"
>http:https://www.funet.fi/pub/cbm/demodisks/c128/</a>, you can use the
following commands in <CODE>bash</CODE> to extract the files from the
disk images:</p>
<pre>
gunzip *.d64.gz
for i in *.d64; do mkdir ${i%.d64}; cd ${i%.d64}; cbmconvert -m ../$i; cd ..; done
for i in */*.prg; do mv $i "`echo ${i%.prg}|tr A-Z a-z`"; done
</pre>
<p>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 <kbd>^Z</kbd> 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 <code>cbmconvert</code> does so as well, and it removes
the <kbd>^Z</kbd> padding when reading the files. So, you could use
<code>cbmconvert</code> to remove the padding. But you may prefer the
following Perl 5 command:</p>
<pre>
perl -i -e 'undef $/; while (<>) { s/\032+\z//gs; print }' *
</pre>
<h4><a name="using-c-geos" href="#toc-using-c-geos">3.1.2</a>
GEOS disk images</h4>
<p>GEOS files on disk images will be handled transparently by
converting them to and from the Convert format on the fly. All unused
areas in the Convert file will be zeroed out, and all possible
integrity checks will be made in both conversions. If the file is
interpreted to be in GEOS or Convert format, and it fails in any
integrity check, it will be treated as a native Commodore file.</p>
<p>You should note that Convert does not provide much safety for the
file. For sequential files, the original file length is not stored
anywhere. For VLIR files, it is, but even then there are no
checksums.</p>
<p>As a speciality, all GEOS files have a file information block. The
contents of this block can be viewed with the simple Perl script
<code>cvtinfo.pl</code> that reads files in Convert format. It was just
a quick hack; feel free to make it more robust.</p>
<p>The GEOS routines have been tested with twelve 1541 disk images and
with several megabytes of <code>*.cvt</code> files, and they are
believed to be error free now. There were problems with the VLIR
sector format; Mr. Boyce's reverse engineered information about it was
incorrect, or at least inadequate.</p>
<h4><a name="using-c-c2n" href="#toc-using-c-c2n">3.1.3</a>
Commodore C2N tape archives</h4>
<p>The Commodore C2N tape format uses 187-byte file names that are
padded with spaces. On disks, file names are 16 bytes and padded with
shifted spaces. Since <code>cbmconvert</code> was designed primarily
for disk-based archives, it truncates tape file names to 16 bytes and
changes the padding from regular spaces to shifted spaces and vice
versa.</p>
<p>End-of-tape markers on C2N tapes are not converted.</p>
<p>There are two kinds of program files on tapes: relocatable program
files (type code 1, typically written in BASIC) and absolute program
files (type code 3, typically written in machine language). There is
no such distinction among disk files. When writing program files to
C2N archives, <code>cbmconvert</code> marks the files relocatable if the
least significant byte of their start address is 1. This typically
indicates a BASIC program.</p>
<p>On output, all file types expect PRG are converted to tape data
files consisting of 191-byte fixed-length data blocks. The output to
tape data blocks tries to mimic the Commodore KERNAL behaviour: a zero
byte is written to the last data block after end-of-file, and the
bytes following the zero byte are identical with the bytes in the
preceding data or header block.</p>
<p>The data file padding in the last block is not detected or removed
on input. Also, the padding is not added on output if the file length
is an exact multiple of 191 bytes, even though the KERNAL routines
would add an extra block whose first data byte is zero. This prevents
data files from growing when they are imported from tape and exported
again, but this may cause incompatibilities when writing a data file
with exactly <var>n·191</var> bytes of payload.</p>
<h4><a name="using-c-flaws" href="#toc-using-c-flaws">3.1.4</a>
Flaws of <code>cbmconvert</code></h4>
<p>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.</p>
<p>Lynx, Arkive and ARC allow duplicate filenames. But
<code>cbmconvert</code> 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.</p>
<p>Arkive also works on illegal file types 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.</p>
<p>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
<code>cbmconvert</code>, you may want to try the <code>disk2files</code>
program of the previous release.</p>
<h3><a name="using-d" href="#toc-using-d">3.2</a> <code>disk2zip</code></h3>
<p>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
<code>-i</code> option to specify the disk identifier.</p>
<h3><a name="using-z" href="#toc-using-z">3.3</a> <code>zip2disk</code></h3>
<p>ZipCoded archives consist of four files prefixed with a number from
1 to 4, and an exclamation point. To extract an archive having the
files <code>1!disk</code>, <code>2!disk</code>, <code>3!disk</code>
and <code>4!disk</code>, type <code>zip2disk disk</code>. You may
then delete the original files with <code>rm [1-4]\!disk</code> 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.</p>
<p>Support for ZipCode SixPacks (<code>1!!<var>disk</var></code>,
<code>2!!<var>disk</var></code>, ..., <code>6!!<var>disk</var></code>)
could be added easily, but this format is used mainly for really
custom 1541 disks with abnormal low-level format, which
<code>cbmconvert</code> does not support.</p>
<h2><a name="credits" href="#toc-credits">4</a> Credits</h2>
<p>Most of the <code>cbmconvert</code> package was written by Marko
Mäkelä. The original version appeared in 1993, and a complete rewrite
was started in 1997 and finished in 1998.</p>
<p>The zip2disk module was originally programmed by <a class="ext"
href="mailto:[email protected]">Paul David Doherty</a>. 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.</p>
<p>Support for 1581 CBM DOS disk images was programmed by <a
class="ext" href="mailto:[email protected]">Pasi Ojala</a>.</p>
<p>The ARC/SDA dissolving code was originally written by Chris
Smeets.</p>
<p>The necessary information for supporting GEOS was provided by <a
class="ext" href="mailto:[email protected]">Joe Forster/STA</a>, <a
class="ext" href="mailto:[email protected]">Doug Cotton</a>,
Alexander Boyce (author of the unofficial GEOS Programmer's Reference
Guide) and by the anonymous author of the file "convertfrmt.txt".</p>
<h2><a name="dist" href="#toc-dist">5</a> Distribution</h2>
<p>The source code repository of
<code>cbmconvert</code> is available at <a class="ext"
href="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/dr-m/cbmconvert/"
>https://github.com/dr-m/cbmconvert/</a>.</p>
<h3><a name="dist-hist" href="#toc-dist-hist">5.1</a> Revision History</h3>
<dl>
<dt>Version 2.1.5:</dt>
<dd>Bug fixes, and regression tests for everything except the read-only formats
<code>-a</code>, <code>-k</code>, <code>-t</code></dd>
<dt>Version 2.1.4:</dt>
<dd>Bug fixes; public source code repository</dd>
<dt>Version 2.1.3:</dt>
<dd>Bug fixes</dd>
<dt>Version 2.1.2:</dt>
<dd>Bug fixes</dd>
<dt>Version 2.1.1:</dt>
<dd>Bug fixes</dd>
<dt>Version 2.1:</dt>
<dd>Added support for raw Commodore C2N tape archives. Renamed the
CP/M-related options to <code>-m</code> and <code>-M</code>, so that
the C2N-related options can be <code>-c</code> and <code>-C</code>.</dd>
<dt>Version 2.0.5:</dt>
<dd>Mikko Suonio
provided patches for tolerating truncated T64 and Lynx archives. His
patches also handle single-file T64 archives that have number of
entries set to zero, and Lynx archives that have file names starting
with a space.</dd>
<dt>Version 2.0.5.1:</dt>
<dd>It was brought to my attention that Lynx 17 on the Commodore 64
and some other utilities do not recognize the Lynx archives created
by <code>cbmconvert</code>. I slightly modified the magic cookie to
fix the problem.
</dl>
</body></html>