1IZREADME_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 5Info-ZIP Programs 6================= 7 8Zip 9UnZip 10UnZipSFX 11fUnZip 12 13Introduction 14------------ 15 16This archive is a result of frustrations with contemporary (August 95) 17versions of Zip and UnZip. While they use the same compression 18algorithms as the Info-ZIP programs, there the compatibility ends. If 19you just use Zip/UnZip only on SMS/QDOS, then perhaps this is not a 20problem (but I know for some users it still is); if you use Zip/UnZip 21to transport source code and data between diverse systems, then the 22disregard for Info-ZIP standards is inconvenient, particularly the 23fact that directories are not supported and files are always stored 24underscored. 25 26This 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 51Info-ZIP Standards 52------------------ 53 54This (rather long-winded and waffling) section discusses the 55conventions and standards used by Info-ZIP-compatible archivers and how 56"Info-ZIP for SMS/QDOS" achieves compatibility. 57 58Info-ZIP Zip/UnZip on all supported platforms (Unix, DOS, OS/2, NT, 59VAX/VMS, Amiga etc etc), works in a specific way. (Until now SMS/QDOS 60was 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 73Basically, the listing and stored format of a file is that of the 74destination. 75 76So, 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 88Then 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 97This is also how the zipfile directory appears. 98 99And in DOS/OS2/NT 100 101 Makefile 102 src\afile.c 103 src\docs\prog.txt 104 hdr\cfile.h .. etc 105 106And 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 114And 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 121The main problem regarding SMS/QDOS is not that of extensions - (after 122all, only VMS and DOS _really_ have extensions; Unix, AmigaDOS, NT and 123OS/2 (and Win95) allow multiple '.' in.long.file.names. 124 125The SMS/QDOS problem is that '_' is both a legal file name character 126and a directory separator. This creates the difficulties, as 127directories and files are somewhat different objects. 128 129It is the intention that these versions of SMS/QDOS Zip/UnZip will 130follow the Info-ZIP rules, thus providing compatibility with the other 131platforms. It is possible to zip the file structure described above on 132SMS/QDOS and unpack it on VMS and get the VMS structure as shown in the 133example (and vice-versa). [We only choose the most obtuse file 134systems for the examples]. 135 136In order to achieve this, SMS/QDOS names are mapped into Unix-style 137ones when the zipfile is created and un-mapped when it is unpacked. 138There is an option to unpack in 'zipfile' format (i.e. with '.' rather 139than '_'), but there will be no option to pack to all '_'. That would 140contravene the standard. However, a file 141 142 src_split_name_c (which is src->split_name_c !) 143 src/split_name.c) 144 145where src is a hard directory, would be stored in the zip directory as 146 147 src/split_name.c 148 149It does handle '_' with a little intelligence. 150 151The default UnZip option will be to translate '.' to '_'; this is 152because there are still many QDOS/Minerva users that cannot handle '.' 153without quotes, which is immensely inconvenient. For many SMS users 154'_' is also the most natural and convenient option. It also means that 155SMS/QDOS <-> SMS/QDOS Zip - UnZip sequences are transparent. 156 157There 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 165Examples: 166 167Given 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 176Then 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 184In both cases the file lists as above (left). 185 186To 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 192i.e. in both cases using the 'zipfile' format. As a concession to 193SMS/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 199Both 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 204DOS/NT/OS2 etc). 205 206Options & SMS/QDOS Features 207--------------------------- 208 209The options supported by Zip/UnZip are basically those documented in 210the Info-ZIP documents and shown in on-line 'usage'. In particular, -r 211and -j work as intended. 212 213PLEASE NOTE: Previous SMS/QDOS zip/unzips have NOT followed these 214conventions, for example -r was not implemented and -j was reversed. 215 216A number of -Q (SMS/QDOS-specific) options (not yet in the current 217documents or usage screens) are implemented. 218 219The Zip 2.0.1 (and later) default is to add SMS/QDOS headers where 220file type = 1 (exe) or 2 (rel) or (type > 0 && != 255 and (filesize % 22164) != 0). Directories are included anyway, unless you zip -D. 222 223Where a header is added for an 'exe' file a '*' is displayed after the 224name in the zip display (and '#' for 'rel' files). 225 226The -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 237Zip has rationalised the file header storage in zipfiles. The 238previous Zip used to store a QDOS header for each file. This was very 239wasteful, for example compressing a SMS/QDOS release of PGP in this 240way came to 730Kb, too large for a DD disk. Changing the Zip program 241just to add a header record for the single PGP exe and the zipfile 242size went down to around 690Kb. 243 244And for UnZip 245 246 -Q1 Toggle unpack format status ('.' <-> '_') 247 -Q2 Toggle listing format 248 -Q4 Don't wait for key press 249 250Files Types 251----------- 252 253The history of QDOS suffers from incompatible feature 254implementations. For example, Thor directories have file type 3, CST 255have type 4 and Level 2 have type 255. Some software writers (both 256amateur and otherwise) have used type 3 or 4 for other purposes 257(backward compatibility ?? who cares ??). 258 259In order to bypass problems cause by incompatible (inconsiderate ?) 260usage of file types, the file type denoting a directory is a 261Config'urable item. The default is set to -1 (65535 in Config terms), 262which means "determine directory type from the file header of the root 263directory". If this is appears unsuccessful on your system, the value 264can be Config'ed in the range 3-255. 265 266Zip assumes a file is a directory if: 267 268 ((type == CONFIGed_type) && (file_size % 64) == 0) 269 270If you are unfortunate enough have files of that pass this test but 271are not directories, then Zip will loop endless, as SMS/QDOS opens the 272root directory again !!! (recursion: see recursion etc). 273 274I suggest you refrain from zipping such files and contact the software 275supplier and point out the error of their ways. 276 277File Naming Issues 278------------------ 279 280Zip will append a '_zip' suffix to the archive filename when the 281supplied name (i.e. excluding device/directory parts) does not 282contain a '_' or a '.'. This is broadly compatible with Info-ZIP, 283taking into account the '_' aberation. 284 285So 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 296This implies that if a file ram2_test.zip exists, and you do: 297 298 ex zip;'ram2_test ...' 299 300Then a new file (test_zip) is created, rather than 'test.zip' being 301updated. 302 303Zip supports extensive recursive wild-carding, again the fact that '_' 304can be a directory separator as well as part of a file name makes this 305a 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 318You might think that 319 320 ex zip;'-r ram2_test *_*_bas' 321 322would just find the files in the subdirectories--well yes, but it will 323also find very other sub-dir'ed _bas file on the disk too. This is 324a feature. 325 326The 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 333UnZip has now got a fixed -d option. This is used to specify the 334directory to unpack the zipfile into, it must follow immediately 335after the zip name. 336 337 ex unzip;'ram2_test_zip -d ram3_ *_txt' 338 339would unpack all *_txt files to ram3_ . 340 341It is not necessary to set the default directory to pack files, Zip 342will remove any device names (and store any hard directory names, 343unless 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 354Due to the way the file-mapping is implemented, it is not supported 355over the nX_ type network device. 356 357Config Options 358-------------- 359 360A limited number of SMS/QDOS specific functions can be set using the 361QJump 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 389When the 'Press a key' text is displayed, if you press ESC, then it 390waits until you press any other key, infinite timeout. This may be 391useful if you want (much) more time to study a listing etc. 392 393Defaults for timeout and directory type are 250 and -1 respectively. 394 395More Goodies 396------------ 397 398Part of the Zip compression code is now in assembler; it runs 399noticably faster than the previous version. Compressing some arbitrary 400files with the previous Zip it took 251 seconds, with Zip 2.0.1 it 401took (a mere) 170 seconds (68008 QL). 402 403More good news is that SMS/QDOS is just another system option on top 404of standard Info-ZIP, unlike the previous ports that were much more 405SMS/QDOS specific. For example, compiling the standard source with c68 406(i.e. #define QDOS), then you get an SMS/QDOS version. 407 408Compile with Linux/gcc and get the standard Linux version. Now, here's 409the cool bit; compile with Linux/gcc and "-DQLZIP", and get a standard 410Linux Zip/UnZip with SMS/QDOS (header) extensions. 411 412so, on Linux: 413 414 zip -Q stuff.zip qtpi zip unzip 415 416the -Q tells Zip to look for XTc68/Lux68 cross-compiler data size 417blocks and produce a zipfile with SMS/QDOS headers in it (for exec 418type programs). This works for exec files produced by the XTc68/Lux68 419cross compilers and ANY SMS/QDOS files copied to a Unix or MS-DOS disk 420from an SMS/QDOS floppy using 'qltools v2.2' (or later). 421 422Self Extracting Archives 423------------------------ 424 425Info-ZIP self-extracting archives (_sfx) are created in a rather 426'brute-force' way. The UnZipSFX program is prepended to a zipfile. 427 428i.e. file_sfx = unzipsfx + file_zip 429 ex file_sfx 430 431Although the UnZipSFX program is a cut-down UnZip, it is still around 43230Kb - 50Kb, depending on platform. 433 434The success of this approach depends on how the operating system 435loader loads executable files. On most systems where the loader only 436loads the actual program part (Unix, VMS, DOS et al), the this is 437quite efficient; if you make, say, a 4Mb zipfile and prepend a 30Kb 438UnZipSFX image, then the system only loads the 30Kb program and the 439process is efficient as the zipped data part is still unpacked from 440disk. These systems also supply the running UnZipSFX program stub with 441the path name of the file it was loaded from, so the program knows 442what 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 449Unfortunately, the more simplistic nature of SMS/QDOS makes this much 450more 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 466If anyone is still interested, then the following support for UnZipSFX 467is 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 475The makesfx program concatenates the supplied files to standard 476output. 477 478So, 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 488ex makesfx;'-o test_sfx -x win1_bin_unzipsfx -s win1_bin_callstub -z ram1_test_zip' 489 490The arguments to makesfx are: 491 492 -s stubfile 493 -x UnZipSFX_program 494 -z Zip_file 495 -o Output_file 496 497You can now unpack the _sfx file on any SMS/QDOS-compatible 498system. 499 500 f$ = "win2_tmp_test_sfx" 501 a = alchp(flen(\f$)) 502 lbytes f$,a 503 call a 504 rechp(a) 505 506ZipInfo 507------- 508 509Given the above note concerning SMS/QDOS programs not knowing the name 510by which the program was invoked, then the usual symbolic-link-of-unzip- 511to-zipinfo trick is unavailable (presupposing there is some some SMS/QDOS 512trick to emulate symbolic links). 513 514ZipInfo functionality is only available via 'unzip -Z'. There is no 515separate ZipInfo program. 516 517Caveat ATP Users 518---------------- 519 520ATP for SMS/QDOS users should pay particular attention to the 521Zip/UnZip options in their atprc and compare with Info-ZIP Zip/UnZip 522usage. Older versions of Zip/UnZip screwed up -j. 523 524 525 zip -jk 526 unzip -jo 527 528Distribution & Copyright 529------------------------ 530 531This software is written by and largely copyrighted by the 'Info-ZIP' 532group whose members are noted in the accompanying documentation. This 533particular SMS/QDOS port plus 'makesfx' was written by, but is not 534copyrighted by, Jonathan R Hudson. The SMS/QDOS code in this release 535is written from scratch and is not dependent on previous SMS/QDOS 536releases, but is (largely) compatible. 537 538As a courtesy to the authors of this package, please ensure that the 539documentation is supplied when it is re-distributed. 540 541In particular, if this archive is split into Zip and UnZip components, 542ensure that this document ("IZREADME_SMS") is supplied in 543each component. 544 545SMS/QDOS version by: 546Jonathan R Hudson (jrhudson@bigfoot.com) 547 548I am grateful to Graham Goodwin for finding some most imaginative 549means of breaking the beta code. 550 551I'd also like to thank Thierry Godefroy for providing the 2.1/5.2 552source code and making the initial contact with the Info-ZIP group. 553 554And of course, many, many thanks to the Info-ZIP workers for making 555this code freely available. 556 557Note 1 558------ 559 560The 'C' language FAQ ('frequently asked questions' [comp.lang.c]) 561notes on the matter of obtaining the load file name of a 'C' program: 562 56316.5: How can my program discover the complete pathname to the 564 executable file from which it was invoked? 565 566A: 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 573Note 2 574------ 575 576NUL files for SMS2. There appears to be a conflict between SMS2/LBASIC 577compiled 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 584Note 3 585------ 586 587version number incremented to 2.0.1a and 5.12a to accomodate Erling 588Jacobsen's exit message requirements 589 590version number incremented to Zip 2.0.1b to fix bug on zipping files 591starting with leading underscore. 592 593version number incremented to UnZip 5.12b to fix UnZip problem on 594files zipped with leading './', and linked with revised (fixed) c68 595'utime' function (could corrupt level 1 files). (source code _only_ as 596IZQ004.zip). 597 598Ported Zip 2.1 and UnZip 5.2 (July 1996). Released as INZIP005.zip 599 600All later versions --- see Info-ZIP release notes and documentation. 601