home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / varc10b3.zip / VArc.txt < prev   
Text File  |  1993-01-07  |  11KB  |  256 lines
  1. VArc v1.0b3 - An Archive Management Interface for OS/2 v2.0
  2. ===========================================================
  3. (c) Paul Gallagher 1992
  4. This REXX/VREXX script is copywrite, but freely distributable.
  5.  
  6. Contents of this file:
  7.   * Version History
  8.   * Contacting the author
  9.   * System Requirements
  10.   * About VREXX
  11.   * About VArc
  12.   * Performance
  13.   * Supported Archive Utilities
  14.   * Starting VArc
  15.   * VArc Options
  16.   * Current Archiving Capabilities
  17.   * Adding Support for New/Other Archive Utilities
  18.  
  19. Version History
  20. ===============
  21. VArc is currently in "beta" release (which basically means I haven't had
  22. a lot of time to test it). Please do your best to report all problems so that
  23. I can generate the appropriate fixes. Suggestions for improvements are most
  24. welcome, as are criticisms of my REXX code! 
  25.  
  26. 93.01.07 : v1.0b3
  27.   Pros:
  28.     * Added option to show output of last archive operation.
  29.     * Fixed bug that triggered endless loop when first archive file used is
  30.       corrupt (or otherwise unsupported).
  31.     * Clarified some error messages.
  32.  
  33. 92.12.24 : v1.0b2
  34.    Pros:
  35.      * Now officially "beta".
  36.      * "Another archive" problem rectified.
  37.      * Added support for ARC format.
  38.      * Generalised the parsing of archive listings somewhat by adding start/end
  39.        delimiter variables.
  40.   Cons:
  41.      * There is no validation on new directory specified with "Change work directory"
  42.        option.
  43.  
  44. 92.12.23 : v1.0
  45.   Pros: 
  46.     * Supports most ZIP,ZOO,LZH formats.
  47.   Cons:
  48.     * woops! slipped out with a bug in the "Another archive" option.
  49.  
  50. Contacting the Author
  51. =====================
  52. I (that is: me, i.e. Paul Gallagher) welcome comments, discussion, criticism
  53. even ;-) about VArc.
  54.  
  55. Contact me by mail at <paulg@a1.resmel.bhp.com.au>, snail mail at:
  56. PO Box 731 Mt Waverley 3149 Australia, or tel: +61-3-560-7066 (BH),
  57. +61-3-803-9543 (AH)
  58.  
  59. System Requirements
  60. ===================
  61. VArc requires REXX and VREXX to be properly installed on your system. VArc is
  62. written for VREXX2 which requires IBM OS/2 v2.0.
  63.  
  64. About VREXX
  65. ===========
  66. I'm sure that Richard B. Lam from IBM's T.J. Watson Research Center won't mind
  67. me plugging VREXX (c) Copyright IBM Corp.  1992
  68. I highly recommended the product - it adds the flair that makes REXX just that
  69. more than a superb job control language.
  70.  
  71. I picked VREXX up by anonymous ftp from <ftp-os2.nmsu.edu> under the filename
  72. VREXX2.ZIP, though it's surely available elsewhere (anywhere that archives or
  73. mirrors an archive of comp.binaries.os2 for example).
  74.  
  75. About VArc
  76. ==========
  77. I started writing VArc one night because I couldn't figure out how to force
  78. PMZIP (an never-the-less excellent product by Nico Mak) to handle archives other than
  79. ZIPs. At first I thought that writing an archive management front end with REXX
  80. was sheer madness, but after pondering it for a while, I decided it could
  81. be done reasonably well. I might note here that if it hadn't been for VREXX, the
  82. project would have ended up in the circular file pronto!
  83.  
  84. Performance
  85. ===========
  86. I was surprised how well VArc works. However, you will notice an appreciable
  87. delay in getting a contents listing of larger archives. Not much I can do about
  88. that though. 
  89.  
  90. Supported Archive Utilities
  91. ===========================
  92. Currently VArc is setup for and has been tested (sort of) with the following
  93. archive systems (in order of preference where extensions are the same):
  94.  
  95. No.  filename       archive programs
  96. ---  --------       -------------------
  97. -1-   *.LZH         LH.EXE v2.0 by Peter Fitzsimmons
  98. -2-   *.ZIP         ZIP.EXE 1.9 (C) 1990-1992 Mark Adler, Richard B. Wales,
  99.                     Jean-loup Gailly and Kai Uwe Rommel. UNZIP.EXE v5.0 (c) 1989 S.H.Smith
  100. -3-   *.ZIP         PKZIP2.EXE/PKUNZIP2.EXE v1.01-OS/2 Prot Mode 7-21-89 by PKWARE 
  101.                     (used if -2- not available)
  102. -4-   *.ZOO         ZOO.EXE v2.1 by Rahul Dhesi
  103. -5-   *.ARC         ARC.EXE v5.21 by ???
  104.  
  105. Starting VArc
  106. =============
  107. From the command line:
  108.    VArc [filemask]    .... starts VArc and tries to interpret 'filemask' as an archive file
  109.    VArc /h            .... starts VArc and displays an info screen (very brief!)
  110.  
  111. From the WPS:
  112.    double click VArc.cmd  .... starts VArc, display dialog for selecting archive file
  113.    drop archive file onto VArc.cmd  .... uses VArc to open the archive file
  114.  
  115. VArc Options
  116. ============
  117. Once an archive file has been specified, a radio box menu is displayed with the following options:
  118.   'Show contents'
  119.       - displays the contents of the selected archive
  120.   'Add/update a file'
  121.       - allows you to select a new file to add to an archive
  122.   'Add/update some files'
  123.       - provide a filemask for adding more than one file to archive
  124.   'Extract all files'
  125.       - explodes the archive into the working directory
  126.   'Extract some files'
  127.       - allows you to provide a filemask to control file extraction
  128.   'Delete a file'
  129.       - select a file to delete from archive
  130.   'Set working directory'
  131.       - change the 'home' directory used for adding/extracting files
  132.   'Set options'
  133.       - current options
  134.       (1) Include subdirectories - when set will try to include subdirectories when
  135.           adding/extracting files if supported by archive utility
  136.       (2) Display archive utility output - after each archive operation will display
  137.           a log file using the system editor
  138.   'Another archive'
  139.        - select a new archive
  140.  
  141. Current Archiving Capabilities
  142. ==============================
  143. Many of the archive utilities supported have quite complex capabilities. VArc brings
  144. them all down to (at least) the lowest common denominator! Basic operations supported
  145. are:
  146.   * list archive contents
  147.   * add (update where appropriate)
  148.   * extract (over-write by default)
  149.   * delete file(s) from archive
  150.  
  151. The "Include subdirectories" option combines the concept of storing relative pathnames
  152. in an archive file, and extracting files to their original path relative to the
  153. current working directory. Absolute pathnames are not supported.
  154.  
  155. When the "include subdirectories" option is not set:
  156.   Only filenames (not paths) are stored when adding files to an archive. 
  157.   Files will be extracted into the current working directory.
  158.  
  159. When the "include subdirectories" option is set:
  160.   File paths relative to the working directory are stored in the archive. Additionally,
  161.   VArc will try to get the archive utility to recurse through all sub-directories and
  162.   archive matching files. NB: most archive utilities will only do this properly if "*"
  163.   or "*.*" is the file specification.
  164.   Files will be extracted with pathnames relative to the working directory. Directories
  165.   will be created as required.
  166.  
  167. Adding Support for New/Other Archive Utilities
  168. ==============================================
  169. I've tried to make VArc as independant of the archive utility used as I can.
  170. All the settings regarding archive utilities are stored in a stem variable
  171. as (what I call) archive utility prototypes. To add a new archive utility
  172. or to modify/update existing utilities, it should simply be a matter of
  173. tweeking the archive prototypes (which are stored in a stem variable and
  174. all set in a procedure called "SetArcParams" in the VArc source).
  175.  
  176. The one big assumption I've made is that when getting a listing of archive
  177. contents, the output from the archive utility separates header and footer
  178. info from the meat of the output with lines that contain at least 3 consecutive
  179. hyphens (i.e. "---"). If this no longer remains true, then the procedure 
  180. "LogArchive" will need updating.
  181.  
  182. Let's have a look at the archive prototype to see how archive utilities are
  183. incorporated into the script. (All that follows can be found in the procedure
  184. "SetArcParams").
  185.  
  186.   arcmask='*.*z*'    -this defines the file mask used in the file selection
  187.                       box. Luckily all the supported archive utilities make
  188.                       archives with the letter "z" in the extention
  189.   arcselect=1        -this is a global variable used to indicated the current
  190.                       archive type
  191. All the details of archive utilities are contained in a stem variable called
  192. "arcproto" 
  193.  
  194.   arcproto.number=4  -tells us how many different utility configs are present
  195.  
  196. Each config is contained in a "sub-"stem identified by its config number. Let's
  197. look at the config for Zoo (which is utility #4)
  198.  
  199.   arcproto.4.ext='.ZOO'
  200.     -this is the file extention associated with the archive files. Must be uppercase.
  201.  
  202.   arcproto.4.arcexe='ZOO.EXE'
  203.     -the filename of the executable used for archiving. No pathnames please!
  204.      The utility *must* be on the PATH.
  205.  
  206.   arcproto.4.unarcexe='ZOO.EXE'
  207.     -the filename of the executable used for unarchiving. No pathnames please!
  208.      The utility *must* be on the PATH.
  209.  
  210.   arcproto.4.arc='zoo a ~archive~ ~filemask~'
  211.     -the command line used to archive files. Relative paths are stored in the
  212.      archive, and subdirectories are recursed if possible. "Variables" are defined:
  213.      ~archive~ is the name of the current archive file
  214.      ~filemask~ is the specification of files to be archived
  215.  
  216.   arcproto.4.arcnosub='zoo a: ~archive~ ~filemask~'
  217.     -the command line used to archive files without paths or recursion.
  218.      "Variables" are defined as for arcproto.x.arc
  219.  
  220.   arcproto.4.unarc='zoo x.O ~archive~ ~filemask~'
  221.     -the command line used to unarchive files with path info. Paths stored in
  222.      the archive are created relative to the current working directory. 
  223.      Subdirectories are extracted if possible.
  224.  
  225.   arcproto.4.unarcnosub='zoo x:O ~archive~ ~filemask~'
  226.     -the command line used to extract files into the current directory without
  227.      paths.
  228.  
  229.   arcproto.4.list='zoo -l ~archive~ ~filemask~'
  230.     -the command line used to list the contents of an archive file.
  231.  
  232.   arcproto.4.del='zoo DP ~archive~ ~filemask~'
  233.     -the command line used to delete files matching the filemask from an archive.
  234.  
  235.   arcproto.4.parse="fsize d.1 d.2 fdd fmm fyy d.3 d.4 fname"
  236.     -tells the program how to interpret the output of a file list. This string
  237.      is actually as a prototype for a Parse statement. Key variables are:
  238.        fsize        -file size (actual)
  239.        fyy,fmm,fdd  -file date (year, month and day)
  240.        fname        -file name
  241.        d.           -stem variable to hold any rubbish in the output
  242.  
  243.   arcproto.4.startdelim='---'
  244.     -the starting delimiter used when interpreting "list" output. This is the unique
  245.      string appearing in the line immediately prior to the actual file details.
  246.  
  247.   arcproto.4.enddelim='---'
  248.     -the ending delimiter used when interpreting "list" output. This is the unique
  249.      string appearing in the line immediately after the actual file details. It may be
  250.      the same as the "startdelim", since the program only starts looking for an ending
  251.      delimiter after finding a starting delimiter.
  252.  
  253. Adding a new archive utility should be as simple as incrementing the
  254. "arcproto.number" counter, and adding a new arcproto.(new number) stem
  255.  
  256.