Debian Codegraph @

qdos/IZREADME.SMS

raw
1 IZREADME_SMS (IZREADME.SMS): Info-ZIP for SMS/QDOS, last revised: 15-Jun-1998
2 ===============================================================================
3 [was "InfoZIP_SMSQDOS_ReadMe" in J. Hudson's original ports, ca. 08/1995]
4
5 Info-ZIP Programs
6 =================
7
8 Zip
9 UnZip
10 UnZipSFX
11 fUnZip
12
13 Introduction
14 ------------
15
16 This archive is a result of frustrations with contemporary (August 95)
17 versions of Zip and UnZip. While they use the same compression
18 algorithms as the Info-ZIP programs, there the compatibility ends. If
19 you just use Zip/UnZip only on SMS/QDOS, then perhaps this is not a
20 problem (but I know for some users it still is); if you use Zip/UnZip
21 to transport source code and data between diverse systems, then the
22 disregard for Info-ZIP standards is inconvenient, particularly the
23 fact that directories are not supported and files are always stored
24 underscored.
25
26 This release of Zip/UnZip offers:
27
28 o zipfile/directory compatibility with all other supported
29 platforms
30
31 o SMS/QDOS compatibility and back-compatible with earlier
32 versions.
33
34 o Improved performance (Zip is typically 50% faster)
35
36 o Command-line compatibility with Info-ZIP
37
38 o Self-extracting archives (but not very elegantly)
39
40 o Archives are marked as 'created by SMS/QDOS'.
41
42 o Optional recursion into directories
43
44 o Directory structure restored on unzip of Info-ZIP/PKZIP-
45 compatible archives.
46
47 o Config'urable for listing and unpack formats (Info-ZIP (.) or
48 SMS/QDOS (_) and 'Press any key' timeouts. Override options
49 from command line.
50
51 Info-ZIP Standards
52 ------------------
53
54 This (rather long-winded and waffling) section discusses the
55 conventions and standards used by Info-ZIP-compatible archivers and how
56 "Info-ZIP for SMS/QDOS" achieves compatibility.
57
58 Info-ZIP Zip/UnZip on all supported platforms (Unix, DOS, OS/2, NT,
59 VAX/VMS, Amiga etc etc), works in a specific way. (Until now SMS/QDOS
60 was neither 'supported' nor Info-ZIP-compliant.)
61
62 a. The zipfile directory is in (/.) (Unix) format.
63
64 b. When zips are listed, it is in 'zipfile' (Unix) format.
65
66 c. When files are added, they are defined in native format.
67
68 d. When files are added, this is shown in 'zipfile' format.
69
70 e. When files are unpacked, this is done to native format, but
71 selection is done in 'zipfile' format.
72
73 Basically, the listing and stored format of a file is that of the
74 destination.
75
76 So, given a file structure at some arbitrary 'root' level.
77
78 Makefile
79 src (Dir)
80 afile.c
81 bfile.c
82 docs (Dir)
83 prog.txt
84 hdr (Dir)
85 cfile.h
86 dfile.h
87
88 Then these would be in Unix (and Amiga) as
89
90 Makefile
91 src/afile.c
92 src/bfile.c
93 src/docs/prog.txt
94 hdr/cfile.h
95 hdr/dfile.h
96
97 This is also how the zipfile directory appears.
98
99 And in DOS/OS2/NT
100
101 Makefile
102 src\afile.c
103 src\docs\prog.txt
104 hdr\cfile.h .. etc
105
106 And in VMS (we SHOUT in VMS and have a silly file system)
107
108 MAKEFILE
109 [SRC]AFILE.C
110 [SRC.DOC]PROG.TXT
111 [HDR]CFILE.H .. etc
112 (OK VMS purist, [.SRC] etc. Only an example)
113
114 And in SMS/QDOS (quiet again, but slightly ludicrous !)
115
116 Makefile
117 src_afile_c
118 src_doc_prog_txt
119 hdr_cfile_h .. etc
120
121 The main problem regarding SMS/QDOS is not that of extensions - (after
122 all, only VMS and DOS _really_ have extensions; Unix, AmigaDOS, NT and
123 OS/2 (and Win95) allow multiple '.' in.long.file.names.
124
125 The SMS/QDOS problem is that '_' is both a legal file name character
126 and a directory separator. This creates the difficulties, as
127 directories and files are somewhat different objects.
128
129 It is the intention that these versions of SMS/QDOS Zip/UnZip will
130 follow the Info-ZIP rules, thus providing compatibility with the other
131 platforms. It is possible to zip the file structure described above on
132 SMS/QDOS and unpack it on VMS and get the VMS structure as shown in the
133 example (and vice-versa). [We only choose the most obtuse file
134 systems for the examples].
135
136 In order to achieve this, SMS/QDOS names are mapped into Unix-style
137 ones when the zipfile is created and un-mapped when it is unpacked.
138 There is an option to unpack in 'zipfile' format (i.e. with '.' rather
139 than '_'), but there will be no option to pack to all '_'. That would
140 contravene the standard. However, a file
141
142 src_split_name_c (which is src->split_name_c !)
143 src/split_name.c)
144
145 where src is a hard directory, would be stored in the zip directory as
146
147 src/split_name.c
148
149 It does handle '_' with a little intelligence.
150
151 The default UnZip option will be to translate '.' to '_'; this is
152 because there are still many QDOS/Minerva users that cannot handle '.'
153 without quotes, which is immensely inconvenient. For many SMS users
154 '_' is also the most natural and convenient option. It also means that
155 SMS/QDOS <-> SMS/QDOS Zip - UnZip sequences are transparent.
156
157 There will, however, be two ways around this in UnZip.
158
159 1. It is possible to Config the UnZip default to be '.'
160 translations (or not).
161
162 2. The UnZip -Q1 option will toggle the default (Config'ed)
163 state.
164
165 Examples:
166
167 Given that we want/have
168
169 Makefile (Makefile)
170 src/afile.c (src_afile_c)
171 src/bfile.c (src_bfile_c)
172 src/docs/prog.txt (src_docs_prog_txt)
173 hdr/cfile.h (hdr_cfile_h)
174 hdr/dfile.h (hdr_dfile_h)
175
176 Then on SMS/QDOS we might have added the *.c files as
177
178 ex zip;'-r test *_c'
179
180 (or VMS, just to do something different)
181
182 zip -r test [.src]*.c
183
184 In both cases the file lists as above (left).
185
186 To unpack on SMS/QDOS (just the _c/.c files)
187
188 ex unzip;'test src/*.c'
189
190 (and VMS, unzip test src/*.c)
191
192 i.e. in both cases using the 'zipfile' format. As a concession to
193 SMS/QDOS, you could also have:
194
195 ex unzip;'test src_*_c'
196
197 but not unzip test [.src]*.c on VMS !!!!! Sorry, dinosaurs.
198
199 Both SMS/QDOS commands unpack to
200
201 src_afile_c etc, where src_ is a hard sub-directory.
202
203 (and the VMS example would unpack to [.src]afile.c, (or to src\afile.c on
204 DOS/NT/OS2 etc).
205
206 Options & SMS/QDOS Features
207 ---------------------------
208
209 The options supported by Zip/UnZip are basically those documented in
210 the Info-ZIP documents and shown in on-line 'usage'. In particular, -r
211 and -j work as intended.
212
213 PLEASE NOTE: Previous SMS/QDOS zip/unzips have NOT followed these
214 conventions, for example -r was not implemented and -j was reversed.
215
216 A number of -Q (SMS/QDOS-specific) options (not yet in the current
217 documents or usage screens) are implemented.
218
219 The Zip 2.0.1 (and later) default is to add SMS/QDOS headers where
220 file type = 1 (exe) or 2 (rel) or (type > 0 && != 255 and (filesize %
221 64) != 0). Directories are included anyway, unless you zip -D.
222
223 Where a header is added for an 'exe' file a '*' is displayed after the
224 name in the zip display (and '#' for 'rel' files).
225
226 The -Q options for Zip are:
227
228 -Q1 Don't add headers for ANY files
229 -Q2 Add headers for all files
230 -Q4 Don't wait for interactive key press
231
232 (additive, so -Q5 => no headers, no wait, -Q6 all headers,
233 no wait etc)
234
235 (the default is exec/rel headers, 5 sec wait)
236
237 Zip has rationalised the file header storage in zipfiles. The
238 previous Zip used to store a QDOS header for each file. This was very
239 wasteful, for example compressing a SMS/QDOS release of PGP in this
240 way came to 730Kb, too large for a DD disk. Changing the Zip program
241 just to add a header record for the single PGP exe and the zipfile
242 size went down to around 690Kb.
243
244 And for UnZip
245
246 -Q1 Toggle unpack format status ('.' <-> '_')
247 -Q2 Toggle listing format
248 -Q4 Don't wait for key press
249
250 Files Types
251 -----------
252
253 The history of QDOS suffers from incompatible feature
254 implementations. For example, Thor directories have file type 3, CST
255 have type 4 and Level 2 have type 255. Some software writers (both
256 amateur and otherwise) have used type 3 or 4 for other purposes
257 (backward compatibility ?? who cares ??).
258
259 In order to bypass problems cause by incompatible (inconsiderate ?)
260 usage of file types, the file type denoting a directory is a
261 Config'urable item. The default is set to -1 (65535 in Config terms),
262 which means "determine directory type from the file header of the root
263 directory". If this is appears unsuccessful on your system, the value
264 can be Config'ed in the range 3-255.
265
266 Zip assumes a file is a directory if:
267
268 ((type == CONFIGed_type) && (file_size % 64) == 0)
269
270 If you are unfortunate enough have files of that pass this test but
271 are not directories, then Zip will loop endless, as SMS/QDOS opens the
272 root directory again !!! (recursion: see recursion etc).
273
274 I suggest you refrain from zipping such files and contact the software
275 supplier and point out the error of their ways.
276
277 File Naming Issues
278 ------------------
279
280 Zip will append a '_zip' suffix to the archive filename when the
281 supplied name (i.e. excluding device/directory parts) does not
282 contain a '_' or a '.'. This is broadly compatible with Info-ZIP,
283 taking into account the '_' aberation.
284
285 So
286 ex zip;'ram2_test ...' >> ram2_test_zip
287
288 ex zip;'ram2_test.zip ...' >> ram2_test.zip
289
290 ex zip;'ram2_test_rep ... ' >> ram2_test_rep
291
292 ex zip;'ram2_fdbbs.rep ... ' >> ram2_fdbbs.rep
293
294 ex zip;'ram2_test_rep.zip ...' >> ram2_test_rep.zip
295
296 This implies that if a file ram2_test.zip exists, and you do:
297
298 ex zip;'ram2_test ...'
299
300 Then a new file (test_zip) is created, rather than 'test.zip' being
301 updated.
302
303 Zip supports extensive recursive wild-carding, again the fact that '_'
304 can be a directory separator as well as part of a file name makes this
305 a bit tricky, but given the example:
306
307 test1_bas
308 test2_bas
309 dir1->demo1_bas where -> indicates a sub dir
310 dir2->demo2_bas
311
312 ex zip;'ram2_test *_bas'
313 just finds test1_bas, test2_bas
314
315 ex zip;'-r ram2_test *_bas'
316 recurses and finds all the files
317
318 You might think that
319
320 ex zip;'-r ram2_test *_*_bas'
321
322 would just find the files in the subdirectories--well yes, but it will
323 also find very other sub-dir'ed _bas file on the disk too. This is
324 a feature.
325
326 The pattern matching supports Unix-style 'regex' so you could:
327
328 ex zip;'ram2_test dir?_*_bas'
329 or
330 ex zip;'ram2_test dir[12]_*_bas
331
332
333 UnZip has now got a fixed -d option. This is used to specify the
334 directory to unpack the zipfile into, it must follow immediately
335 after the zip name.
336
337 ex unzip;'ram2_test_zip -d ram3_ *_txt'
338
339 would unpack all *_txt files to ram3_ .
340
341 It is not necessary to set the default directory to pack files, Zip
342 will remove any device names (and store any hard directory names,
343 unless you zip -j).
344
345 ex zip;'ram1_test flp1_*'
346
347 ----->
348 adding: file.dat (deflated 50%)
349 adding: menu.rext # (deflated xx%)
350 adding: zip * (deflated yy%)
351 adding: hard_one (stored 0%)
352 adding: hard_one/stuff.bas (deflated ...)
353
354 Due to the way the file-mapping is implemented, it is not supported
355 over the nX_ type network device.
356
357 Config Options
358 --------------
359
360 A limited number of SMS/QDOS specific functions can be set using the
361 QJump Config program.
362
363 For Zip:
364
365 Timeout for interactive 'Press any key' prompt
366
367 65535 Wait forever (aka -1)
368 0 No wait
369 n (1-32767) Wait for 'n' clocks (1/50 sec)
370
371 Other values are unsupported. Note Config works on 'unsigned'
372 integer values (at least according to my manual).
373
374 Directory file type key.
375
376 Config will accept any value in the range 3-255, known useful
377 values are 3 (Thor), 4 (CST) and 255 (Level 2 devices). A value
378 of 65535 (aka -1) means "determine from device info".
379
380 For UnZip:
381
382 Timeout as above
383
384 Unpack mode (SMS/QOS ('_') or Info-ZIP ('.')
385
386 List format (Info-ZIP ('.') or SMS/QDOS ('_')
387
388
389 When the 'Press a key' text is displayed, if you press ESC, then it
390 waits until you press any other key, infinite timeout. This may be
391 useful if you want (much) more time to study a listing etc.
392
393 Defaults for timeout and directory type are 250 and -1 respectively.
394
395 More Goodies
396 ------------
397
398 Part of the Zip compression code is now in assembler; it runs
399 noticably faster than the previous version. Compressing some arbitrary
400 files with the previous Zip it took 251 seconds, with Zip 2.0.1 it
401 took (a mere) 170 seconds (68008 QL).
402
403 More good news is that SMS/QDOS is just another system option on top
404 of standard Info-ZIP, unlike the previous ports that were much more
405 SMS/QDOS specific. For example, compiling the standard source with c68
406 (i.e. #define QDOS), then you get an SMS/QDOS version.
407
408 Compile with Linux/gcc and get the standard Linux version. Now, here's
409 the cool bit; compile with Linux/gcc and "-DQLZIP", and get a standard
410 Linux Zip/UnZip with SMS/QDOS (header) extensions.
411
412 so, on Linux:
413
414 zip -Q stuff.zip qtpi zip unzip
415
416 the -Q tells Zip to look for XTc68/Lux68 cross-compiler data size
417 blocks and produce a zipfile with SMS/QDOS headers in it (for exec
418 type programs). This works for exec files produced by the XTc68/Lux68
419 cross compilers and ANY SMS/QDOS files copied to a Unix or MS-DOS disk
420 from an SMS/QDOS floppy using 'qltools v2.2' (or later).
421
422 Self Extracting Archives
423 ------------------------
424
425 Info-ZIP self-extracting archives (_sfx) are created in a rather
426 'brute-force' way. The UnZipSFX program is prepended to a zipfile.
427
428 i.e. file_sfx = unzipsfx + file_zip
429 ex file_sfx
430
431 Although the UnZipSFX program is a cut-down UnZip, it is still around
432 30Kb - 50Kb, depending on platform.
433
434 The success of this approach depends on how the operating system
435 loader loads executable files. On most systems where the loader only
436 loads the actual program part (Unix, VMS, DOS et al), the this is
437 quite efficient; if you make, say, a 4Mb zipfile and prepend a 30Kb
438 UnZipSFX image, then the system only loads the 30Kb program and the
439 process is efficient as the zipped data part is still unpacked from
440 disk. These systems also supply the running UnZipSFX program stub with
441 the path name of the file it was loaded from, so the program knows
442 what it has to unpack (so on Linux, for example):
443
444 cat /usr/bin/unzipsfx test.zip > test.sfx # concatenate the files
445 chmod 755 test.sfx # make executable
446 test.sfx # to extract, it
447 # 'knows' it is "test.sfx"
448
449 Unfortunately, the more simplistic nature of SMS/QDOS makes this much
450 more difficult and rather less efficient as: (see note 1)
451
452 a. The SMS/QDOS 'loader' loads the whole file into memory.
453
454 b. The SMS/DOS 'loader'/c68 run-time system does not return the
455 name of the file from which it was loaded.
456
457 c. You cannot so easily create a image file by concatenating two
458 files, it is also necessary to ensure the executable file
459 header is set correctly.
460
461 d. The show stopper. The data space required for the
462 self-extracting archive is required, as not easily maintained
463 during electronic transfer.
464
465
466 If anyone is still interested, then the following support for UnZipSFX
467 is provided.
468
469 o A program 'makesfx' will combine a stub (callstub), UnZipSFX image
470 and a zipfile to produce a sfx (self-extracting zip) file.
471
472 o A callable interface is supplied. The user calls the SFX file,
473 which creates the files necessary to do the extraction.
474
475 The makesfx program concatenates the supplied files to standard
476 output.
477
478 So, to create a sfx of all the _c files in the default directory.
479
480 # 1st create a zipfile of the required files
481
482 ex zip;'ram1_test_zip *_c'
483
484 # Now create the sfx file (ram2_test_sfx)
485 # our UnZipSFX image is in 'win1_bin'
486 # as is the call stub.
487
488 ex makesfx;'-o test_sfx -x win1_bin_unzipsfx -s win1_bin_callstub -z ram1_test_zip'
489
490 The arguments to makesfx are:
491
492 -s stubfile
493 -x UnZipSFX_program
494 -z Zip_file
495 -o Output_file
496
497 You can now unpack the _sfx file on any SMS/QDOS-compatible
498 system.
499
500 f$ = "win2_tmp_test_sfx"
501 a = alchp(flen(\f$))
502 lbytes f$,a
503 call a
504 rechp(a)
505
506 ZipInfo
507 -------
508
509 Given the above note concerning SMS/QDOS programs not knowing the name
510 by which the program was invoked, then the usual symbolic-link-of-unzip-
511 to-zipinfo trick is unavailable (presupposing there is some some SMS/QDOS
512 trick to emulate symbolic links).
513
514 ZipInfo functionality is only available via 'unzip -Z'. There is no
515 separate ZipInfo program.
516
517 Caveat ATP Users
518 ----------------
519
520 ATP for SMS/QDOS users should pay particular attention to the
521 Zip/UnZip options in their atprc and compare with Info-ZIP Zip/UnZip
522 usage. Older versions of Zip/UnZip screwed up -j.
523
524
525 zip -jk
526 unzip -jo
527
528 Distribution & Copyright
529 ------------------------
530
531 This software is written by and largely copyrighted by the 'Info-ZIP'
532 group whose members are noted in the accompanying documentation. This
533 particular SMS/QDOS port plus 'makesfx' was written by, but is not
534 copyrighted by, Jonathan R Hudson. The SMS/QDOS code in this release
535 is written from scratch and is not dependent on previous SMS/QDOS
536 releases, but is (largely) compatible.
537
538 As a courtesy to the authors of this package, please ensure that the
539 documentation is supplied when it is re-distributed.
540
541 In particular, if this archive is split into Zip and UnZip components,
542 ensure that this document ("IZREADME_SMS") is supplied in
543 each component.
544
545 SMS/QDOS version by:
546 Jonathan R Hudson ([email protected])
547
548 I am grateful to Graham Goodwin for finding some most imaginative
549 means of breaking the beta code.
550
551 I'd also like to thank Thierry Godefroy for providing the 2.1/5.2
552 source code and making the initial contact with the Info-ZIP group.
553
554 And of course, many, many thanks to the Info-ZIP workers for making
555 this code freely available.
556
557 Note 1
558 ------
559
560 The 'C' language FAQ ('frequently asked questions' [comp.lang.c])
561 notes on the matter of obtaining the load file name of a 'C' program:
562
563 16.5: How can my program discover the complete pathname to the
564 executable file from which it was invoked?
565
566 A: argv[0] may contain all or part of the pathname, or it may
567 contain nothing. You may be able to duplicate the command
568 language interpreter's search path logic to locate the
569 executable if the name in argv[0] is present but incomplete.
570 However, there is no guaranteed or portable solution.
571 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
572
573 Note 2
574 ------
575
576 NUL files for SMS2. There appears to be a conflict between SMS2/LBASIC
577 compiled programs and c68 programs using nul as stdin.
578
579 EW zip,nul;'ram1_test *_bas' # will not work
580
581 # This does work !
582 EW zip,#FOP_IN('nul');'ram2_test *_bas' : CLOSE
583
584 Note 3
585 ------
586
587 version number incremented to 2.0.1a and 5.12a to accomodate Erling
588 Jacobsen's exit message requirements
589
590 version number incremented to Zip 2.0.1b to fix bug on zipping files
591 starting with leading underscore.
592
593 version number incremented to UnZip 5.12b to fix UnZip problem on
594 files zipped with leading './', and linked with revised (fixed) c68
595 'utime' function (could corrupt level 1 files). (source code _only_ as
596 IZQ004.zip).
597
598 Ported Zip 2.1 and UnZip 5.2 (July 1996). Released as INZIP005.zip
599
600 All later versions --- see Info-ZIP release notes and documentation.