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