home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 April / PCWorld_1999-04_cd.bin / Software / Servis / Jar102en / jar102x.exe / REARJ.DOC < prev    next >
Text File  |  1997-09-18  |  21KB  |  508 lines
  1.  
  2.     USER'S MANUAL FOR THE REARJ ARCHIVE CONVERSION PROGRAM  September 1996
  3.  
  4.  
  5.        REARJ software and manual copyright (c) 1991-96 by ARJ Software.
  6.        All rights reserved.
  7.  
  8.        REARJ version 2.25 release
  9.  
  10.     *********************************************************************
  11.  
  12.     REARJ originally was been designed to provide conversion to the ARJ
  13.     format.  However, it may be used to convert into the JAR format, too.
  14.     In this package, the REARJ.CFG file is modified to convert into the
  15.     JAR format by default using the DOS archiver version.
  16.  
  17.     REARJ does not support long filenames.
  18.  
  19.     *********************************************************************
  20.  
  21.  
  22.     INTRODUCTION:
  23.  
  24.     REARJ is an archive conversion program designed to facilitate the
  25.     conversion between LZH, ZIP, PAK, ARC, DWC, HYP, LZS, ZOO, ARJ, JAR
  26.     archives.
  27.  
  28.  
  29.     MAJOR FEATURES:
  30.  
  31.     Supports all major archiver programs (PAK, LHARC, PKZIP, ZOO, ARJ,
  32.     PKPAK, DWC, HYPER, LARC, LHA, JAR).
  33.  
  34.     Supports file attributes within archives.
  35.  
  36.     Supports directories within archives.
  37.  
  38.     Supports converting archives within archives (ZIPs in a ZIP).
  39.  
  40.     Ensures reliable archive conversion with a file count and total size
  41.     check.
  42.  
  43.     Supports the use of virus checkers and BBS ad removers.
  44.  
  45.     Supports recursive scanning through subdirectories.
  46.  
  47.     Optional logging of conversions.
  48.  
  49.  
  50.     ********************
  51.     * WORDS OF CAUTION:*
  52.     ********************
  53.  
  54.     If you plan to convert many archives at one time, it is STRONGLY
  55.     suggested that you make a backup of your hard disk.  This is a wise
  56.     precaution to take any time that you make major modifications to data
  57.     on your hard disk drive.
  58.  
  59.     The standard REARJ conversion DOES NOT convert any archive comments
  60.     and volume labels.  They will be lost.
  61.  
  62.     Some of the other archivers have significant bugs which can cause data
  63.     loss that REARJ cannot detect.  It is not the purpose of this document
  64.     to point out other program's shortcomings.  I suggest logging the
  65.     conversion output to a printer to facilitate checking for errors.
  66.  
  67.     If the archives you are converting will ONLY extract to absolute
  68.     paths, you must use the /w option to set the working directory to an
  69.     empty root directory such as a RAMDRIVE.  This will allow extraction
  70.     to the root.
  71.  
  72.     REARJ and the archiver executables must be located in the DOS PATH
  73.     directories.  This is due to REARJ creating and using a temporary
  74.     directory.
  75.  
  76.     If you have changed the MS-DOS switch character from "/" to another
  77.     character via an undocumented MS-DOS interrupt or the TurboC
  78.     setswitchar() function, REARJ may not work properly with the default
  79.     REARJ.CFG configuration file.
  80.  
  81.     The most thorough testing was done with ARJ as the target format and
  82.     ZIP as the original format.  In any case, you should verify that the
  83.     extract commands of your favorite archive formats in the configuration
  84.     file are correct.  The extract commands are the most important to get
  85.     right because REARJ has a built-in verification procedure to ensure
  86.     that the ADD commands executed properly.
  87.  
  88.     You should NOT set the "-t1" option for ARJ in ARJ_SW or in the
  89.     REARJ.CFG configuration file.  This may cause file size mismatches.
  90.  
  91.     Be sure you have enough disk space on your working directory to
  92.     extract the largest archive that you want to convert!!!
  93.  
  94.  
  95.     The versions of archivers tested:
  96.  
  97.     ARJ   1.00, 1.10, 2.00, 2.10, 2.20, 2.21, 2.30, 2.41a, current release
  98.     LHA   2.12, 2.13
  99.     PAK   2.51
  100.     PKZIP 1.10
  101.     PKPAK 3.61
  102.     ZOO   2.01, 2.10
  103.     DWC   A5.01
  104.     LARC  3.33
  105.     HYPER 2.5
  106.     JAR   1.02
  107.  
  108.  
  109.     INSTALLATION:
  110.  
  111.     Copy REARJ.EXE and REARJ.CFG to one of the DOS PATH directories.  They
  112.     do not have to be placed in the same directory.  The PATH directories
  113.     are usually set by the PATH command in your AUTOEXEC.BAT file.  At
  114.     this version of REARJ, changing its name to something else will cause
  115.     operation difficulties.
  116.  
  117.     Be sure the archiver programs (ARJ, PAK, PKZIP, PKUNZIP, etc.) and
  118.     virus scanner are installed in a DOS PATH directory!  It is STRONGLY
  119.     recommended that the REARJ.CFG be modified to use FULL PATHNAMES to
  120.     specify all archiver executables.
  121.  
  122.     This version assumes that you have the new SCAN version 80 and use
  123.     the new option /sub to scan subdirectories.  This version's
  124.     configuration file also assumes that SCAN.EXE is installed in
  125.     the directory C:\BIN.
  126.  
  127.  
  128.     OPERATION OF REARJ:
  129.  
  130.     REARJ will build a temporary directory in the current directory and
  131.     extract the archive(s) to this directory.  REARJ will then build the
  132.     target archive(s) with the files in this directory.  If the target
  133.     archiver does not support reading of hidden or system files, REARJ
  134.     will reset those bits and then re-archive the files without those
  135.     attributes.  If the original archive has directories in it, REARJ will
  136.     extract it with full paths and re-archive it with full paths if the
  137.     target archiver supports directories.  In this case, if the archiver
  138.     does not support directories, REARJ will skip converting this archive.
  139.  
  140.     If the "/a" option has been selected, REARJ will execute REARJ to
  141.     convert any internal archives of the same type to the target format.
  142.     Any "/s" option will be carried over to the recursive REARJ command.
  143.  
  144.     As an extra test, REARJ will count the files extracted from the
  145.     original archive and total their sizes.  Then REARJ will extract the
  146.     new archive and count the files and total the sizes.  If the count and
  147.     size do not match, REARJ will skip converting the archive.
  148.  
  149.     REARJ assumes that the supported archivers will pass a non-zero error
  150.     code when there is an operation failure.
  151.  
  152.  
  153.     COMMAND SYNTAX:
  154.  
  155.     REARJ [switch options] filespec(s) or wildspec(s)
  156.  
  157.     You can specify one or more filespecs on the command line.  These
  158.     filespecs can have paths and wildcards.  Up to 100 filespecs can be
  159.     accepted by REARJ.  If you specify *.* as a wildspec, REARJ will look
  160.     at all filenames, but will skip those filenames not ending in standard
  161.     archive suffixes.  If you specify the /r switch, REARJ will look for
  162.     filenames matching the filespec(s) in the current directory and all
  163.     subdirectories of the current directory.
  164.  
  165.     The switch options and filespecs can be entered in any order.  REARJ
  166.     uses the default MS-DOS switch character "/".  REARJ uses the Turbo
  167.     C++ function getswitchar() to determine the MS-DOS switch character.
  168.     If the switch character is "-", REARJ will translate any UNIX style
  169.     pathnames to MS-DOS syntax ("dir/file" to "dir\file").
  170.  
  171.  
  172.     SWITCH OPTIONS:
  173.  
  174.     /a - convert archives within archives
  175.  
  176.          This option causes REARJ to recursively execute REARJ to convert
  177.          any archives of the original type found within the original
  178.          archive (ex. ZIPs within a ZIP).  This option requires additional
  179.          memory to execute successfully.
  180.  
  181.          You may specify the type of internal archive to convert with the
  182.          "/a" option.
  183.  
  184.          Examples:  REARJ *.zip /aLZH  convert only internal LZH archives.
  185.                     REARJ *.zip /a*    convert any internal archive.
  186.  
  187.          If you use the "/a*" option, you may need to also specify "/u"
  188.          because of nested archives of the target type.
  189.  
  190.     /b - execute command before extracting files
  191.  
  192.          This option is used to specify a DOS command to be executed before
  193.          extracting the original archive.
  194.  
  195.          In addition, REARJ passes the name of the original archive to
  196.          this command as a command line argument when executing it.  This
  197.          may cause a problem with DOS commands that expect no arguments.
  198.          A workaround would be to install the DOS command in a batch file.
  199.  
  200.  
  201.          This feature is to allow the user to prep the environment before
  202.          extracting the archive.  This can be used to prep for archive
  203.          comments or volume labels, etc.
  204.  
  205.     /c - execute command on extracted files before counting them
  206.  
  207.          This option is used to specify a DOS command to be executed upon
  208.          the extracted files before REARJ counts them for later
  209.          verification.  This is to allow executing a DOS or batch command
  210.          to clean up the extracted files (remove BBS advertisements, etc).
  211.          REARJ does not check for any returned error code from the
  212.          executed command.
  213.  
  214.          In addition, REARJ passes the name of the original archive to
  215.          this command as a command line argument when executing it.  This
  216.          may cause a problem with DOS commands that expect no arguments.
  217.          A workaround would be to install the DOS command in a batch file.
  218.  
  219.     /d - delete the original archive
  220.  
  221.          This option causes REARJ to delete the original archive after a
  222.          successful conversion to the target format.  This option will NOT
  223.          delete read-only archives.
  224.  
  225.     /e - do not return error if no archives were found
  226.  
  227.          This option is used by the internal recursive REARJ.  This option
  228.          will cause REARJ to return a zero exit code if no matching
  229.          archives were found.  Usually, REARJ returns a non-zero exit
  230.          code for this condition.
  231.  
  232.     /f - convert diskette archives
  233.  
  234.          This option is used to facilitate the conversion of archives on a
  235.          diskette.  If you do not have sufficient space on the diskette to
  236.          keep the original archives, you MUST specify the "/d" option as
  237.          in "REARJ A:*.zip /f /d".
  238.  
  239.          This option causes REARJ to build the target archive in the
  240.          CURRENT directory (not the working temporary directory).  After
  241.          verification, REARJ will, if specified, delete the original
  242.          archive and then copy the new archive to the diskette.  You
  243.          should make sure that the current directory does not contain any
  244.          archives before executing REARJ.
  245.  
  246.     /i - check program integrity
  247.  
  248.          This option causes REARJ to validate the REARJ program on disk.
  249.          If you are using a pre-3.0 MS-DOS revision, you will have to
  250.          specify the full program name as in "REARJ /i\util\rearj.exe".
  251.  
  252.     /l - write conversion data to log file
  253.  
  254.          This option causes REARJ to open a log file and record each
  255.          successful conversion in the log file.  The default log filename
  256.          is REARJ.LOG.  You can specify the log filename as in
  257.          "REARJ /lfilename *.ZIP".  If the log file already exists, REARJ
  258.          will append logging data to it.
  259.  
  260.     /o - overwrite existing target archive
  261.  
  262.          This switch is used to delete already existing target archives.
  263.          This is not used for updating archives.  Use the /u option for
  264.          updating an archive.
  265.  
  266.     /q - query for each archive to convert
  267.  
  268.          This switch causes REARJ to pause and prompt the user for
  269.          permission to convert individual archives.  Note that REARJ will
  270.          not prompt when skipping archives.
  271.  
  272.     /r - recurse through subdirectories
  273.  
  274.          This switch causes REARJ to look for archives in all included
  275.          subdirectories as well as in the current directory.  This switch
  276.          allows the user to convert all archives on a hard disk with one
  277.          command.
  278.  
  279.     /s - skip verify of file count and total size
  280.  
  281.          Skip the overhead of the file count and total size verification
  282.          process.  This verification costs an extra extraction, but this
  283.          check is worth the time, especially when converting a large
  284.          number of archives.
  285.  
  286.     /t - specify the target archive type
  287.  
  288.          The default target archive format is normally JAR.  This can be
  289.          changed by building an external REARJ.CFG file.  The first
  290.          archive type is always the default format.  To override the
  291.          default format, the user can specify the /t switch as in
  292.          "REARJ *.ZIP /tlzh".  The previous example has specified that LZH
  293.          is the target format.
  294.  
  295.     /u - allow update of archive with backup
  296.  
  297.          This switch is used to re-archive an archive, possibly to take
  298.          advantage of improved compression.  The original archive is
  299.          backed up by renaming it with the backup suffix which by default
  300.          is "BAK".  You may specify another backup suffix with the /u
  301.          option as in "REARJ *.ARJ /uar$" where the backup suffix is
  302.          "ar$".  Since this option creates a brand new archive, archive
  303.          comments will be lost.  Do NOT specify a "." in the suffix.
  304.  
  305.     /v - execute configured command on extracted files
  306.  
  307.          This switch is used to execute a configure command on the files
  308.          extracted from the original archive.  The intent is to allow
  309.          virus scanning of the archive contents.  The command must be
  310.          specified in the REARJ.CFG file.
  311.  
  312.          The command may be placed in the REARJ.CFG file by inserting one
  313.          line ahead of the archive commands.  The line must start with the
  314.          word "VIRUS" followed by a blank and the external command.
  315.  
  316.          Example:  VIRUS scan /nomem *.*
  317.  
  318.          If the invoked command returns a non-zero error code, REARJ will
  319.          skip the conversion of that archive and log the error as code 13.
  320.  
  321.          REARJ *.* /v
  322.  
  323.     /w - set working directory
  324.  
  325.          By default, REARJ creates a temporary working directory in the
  326.          current directory.  This option allows you to specify the working
  327.          directory.  The working directory must be EMPTY when invoking
  328.          REARJ.  This directory is used to hold the extracted files.
  329.          This is NOT considered the current directory for /f use.
  330.  
  331.          Example:  REARJ *.* /wd:\
  332.  
  333.          This option helps solve the absolute pathname extraction problem
  334.          that some archivers have.  If you set the working directory to an
  335.          empty root directory, the archiver can extract to the root and
  336.          REARJ will be able to find all of the files to re-archive them.
  337.          However, this option will NOT work for internal archives that
  338.          extract to absolute paths.
  339.  
  340.     /x - exclude filenames or wildnames from the conversion process
  341.  
  342.          You can exclude one or more files from the conversion process.
  343.          The filenames can contain wildcards.
  344.  
  345.          REARJ *.ZIP /xONE.ZIP /xTWO.ZIP
  346.  
  347.     /z - simulate conversion process
  348.  
  349.          This switch causes REARJ to simulate the conversion process.  No
  350.          archives will be extracted, built, or deleted.
  351.  
  352.  
  353.     EXAMPLES:
  354.  
  355.     REARJ *.ZIP             this converts all ZIP files in the current
  356.                             directory to JAR files.
  357.  
  358.     REARJ *.ZIP *.ARC       this converts ZIP and ARC files to JAR
  359.                             files.
  360.  
  361.     REARJ SOFT.ZIP          this converts only SOFT.ZIP to SOFT.J.
  362.  
  363.     REARJ A:*.ZIP /f /d     convert ZIPs on A drive with deletion of
  364.                             each original archive upon successful
  365.                             conversion.
  366.  
  367.     REARJ *.ARC /r          this converts all ARC files in the current
  368.                             directory and in subdirectories of the
  369.                             current directory to JAR files.
  370.  
  371.     REARJ SOFT.ARJ /tZIP    this converts SOFT.ARJ to SOFT.ZIP.
  372.  
  373.     REARJ *.J /u            re-archive all JAR archives.
  374.  
  375.     REARJ *.* /v /wd:\      re-archive all archives and execute
  376.                             configured command on extracted files
  377.                             using d:\ as the temp directory.
  378.  
  379.  
  380.     EXTERNAL CONFIGURATION FILE
  381.  
  382.     REARJ comes with a configuration file, REARJ.CFG, which supports
  383.     conversion between the ARJ, ARC, LZH, PAK, ZIP, DWC, LZS, HYP, ZOO,
  384.     JAR formats.  The commands PKPAK and PKUNPAK are used for ARC files.
  385.     The command LHA is used for LZH files.  You can change these defaults
  386.     by editing the configuration file.
  387.  
  388.     The format of the configuration file is fairly simple.
  389.  
  390.     The first line can optionally specify an external command to be
  391.     executed by REARJ when the "/v" option is selected.  This line must
  392.     start with the word "VIRUS" minus the quotes, followed by a space,
  393.     followed by the external command.  The external command MUST contain
  394.     a fully specified pathname for security reasons.
  395.  
  396.     Example:  VIRUS C:\BIN\SCAN /nomem *.*
  397.  
  398.     If you do not want to configure this item, DO NOT insert a blank line.
  399.  
  400.     Each archive format requires four lines in the file.
  401.  
  402.     The first line is the format suffix.
  403.  
  404.     The second line is the archive ADD command with a %s in the place of
  405.     the archive name.  Any other percent signs in the command must be
  406.     preceded by "\" as in "\%".  The ADD command should support directory
  407.     inclusion and reading of hidden and/or system files.  REARJ will parse
  408.     this command line using the space character as the token separator.
  409.  
  410.     If your ADD command requires DOS piping as the ZOO archiver requires,
  411.     you must precede the ADD command with the text "COMMAND /C ".
  412.  
  413.     Example:  ARJ a -a -r -jt %s
  414.               COMMAND /C STUFF *.* | ZOO aI %s
  415.  
  416.     The third line is the archive EXTRACT command with a %s in the
  417.     place of the archive name.  Any other percent signs in the command
  418.     must be preceded by "\" as in "\%".  The EXTRACT command should
  419.     support directory recreation if the archive contains directories.
  420.     The extraction of directories must be to child directories within the
  421.     current directory.  REARJ will parse this command line using the space
  422.     character as the token separator.
  423.  
  424.     If your EXTRACT command requires DOS piping, you must precede the
  425.     EXTRACT command with the text "COMMAND /C ".  Beware that command exit
  426.     codes are not passed back to REARJ when using COMMAND /C.
  427.  
  428.     The fourth line contains the letters "A" and/or "D" or no letters.
  429.     The "A" stands for the ability to process files with the hidden and/or
  430.     system attribute.  The "D" stands for full support of directory trees
  431.     within archives.  No letters (blank line) stands for no support for
  432.     hidden or system files or for archive containing directories.
  433.  
  434.     There must be NO EXTRA blank lines or comments in the file.  You may
  435.     use leading blanks for clarity.
  436.  
  437.     See the supplied REARJ.CFG for the current configuration.
  438.  
  439.     If you use a different archiver program, you will need to either
  440.     rename the program to one of the supported ones or you will need to
  441.     modify the installed REARJ.CFG file.
  442.  
  443.     If your original archive format supports extraction to absolute
  444.     directory paths as opposed to relative directory paths and you have
  445.     such archives containing absolute paths, you should not put directory
  446.     extraction in the REARJ.CFG file unless you use the /w option to set
  447.     the working directory to an empty root directory.
  448.  
  449.     You can add comment handling to the ARJ command by adding the
  450.     "-zcomment.txt" option.  This is supported at ARJ 2.20 and above.
  451.  
  452.  
  453.     LOG FILE DATA
  454.  
  455.     When logging is enabled, REARJ will log the action on each selected
  456.     file.  For successful conversions, REARJ logs the date-time, target
  457.     archive type, original archive size, new archive size, bytes saved,
  458.     and original archive name.
  459.  
  460.     When selected files are skipped for any reason, REARJ will log an
  461.     entry in the log file (when logging is enabled) which specifies the
  462.     reason code for skipping the file.  The following are the codes:
  463.  
  464.     1  = File not found
  465.     2  = File is not a configured archive type
  466.     3  = Target archive already exists
  467.     4  = Not enough disk space
  468.     5  = User skipped or user did not select update option
  469.     6  = UNPACK error
  470.     7  = PACK error
  471.     8  = Target cannot support directories
  472.     9  = Wrong file count
  473.     10 = Wrong total size
  474.     11 = Internal archive REARJ error
  475.     12 = Rename archive error
  476.     13 = Invoked /v command error (found a virus?)
  477.  
  478.  
  479.     LICENSE POLICY:
  480.  
  481.     For personal (not at the office) use, the shareware version of REARJ
  482.     may be freely used only by JAR or ARJ users.  An user is one who uses
  483.     ARJ or JAR on a regular basis.  Others who wish to use REARJ must
  484.     purchase a registration or site license for the ARJ or JAR package.
  485.  
  486.     Please refer to the LICENSE.DOC for more license information.
  487.  
  488.  
  489.     TECHNICAL SUPPORT:
  490.  
  491.     Please report any bugs.  I will TRY to fix them.  See JAR.DOC for
  492.     details on how to contact me.
  493.  
  494.  
  495.     HISTORY:
  496.  
  497.     2.30 - Created registered version of REARJ.
  498.  
  499.     2.25 - Added pathname requirement for VIRUS configuration option.
  500.  
  501.     2.24 - Fixed /f /d /u processing when updating an archive.
  502.  
  503.     2.23 - Fixed /z processing with /f option.
  504.            Added -jg+ to ARJ in REARJ.CFG
  505.  
  506.  
  507.     end document
  508.