home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / arj2_275.exe / arj / readme.txt < prev    next >
Text File  |  2000-12-31  |  18KB  |  402 lines

  1.  
  2.    ARJ for OS/2, version 2.75                           December, 31, 2000
  3.  
  4.  
  5.    LEGAL NOTICE
  6.  
  7.       No warranties of any kind are made. In no  event should ARJ Software
  8.       Russia be liable for any damage resulting from use or misuse of this
  9.       product.
  10.  
  11.       You  have a royalty-free  right to distribute  this  product  in any
  12.       form.  Commercial  use of  this  product  must be  approved  by  ARJ
  13.       Software, Inc.
  14.  
  15.       The  information in  this document is  a subject  to change  without
  16.       notice.
  17.  
  18.  
  19.    INTRODUCTION
  20.  
  21.       To meet  the data  archiving  needs, ARJ Software  Russia delivers a
  22.       range of its own  products based  on the code of  original ARJ. From
  23.       the  beginning,  our  goal  was  to  retain  the  functionality  and
  24.       compatibility with  the  original ARJ  for DOS, but we  also provide
  25.       features  and  enhancements  that  are a  must for certain  tasks or
  26.       certain platforms where no ARJ has been before.
  27.  
  28.  
  29.    NEW FEATURES AND DIFFERENCES FROM THE ORIGINAL ARJ
  30.  
  31.       ("-" indicates a  missing feature, "*" - a different  operation and
  32.        "+" stands for a feature unique for our implementation)
  33.  
  34.       -  There may be a  significant  performance drawback  when accessing
  35.          files on volumes with no write-back cache.
  36.  
  37.       *  The "-hm" options  are  compatible  with their ARJ implementation
  38.          hence  a  temporary  swap  file  is  created  if  the  file  list
  39.          exceeds  3000  files.  To keep  the  entire list  in  memory, use
  40.          -hm65000. This  is  useful if you are running  a non-DOS version,
  41.          have  an   adequate  amount  of   RAM  and   therefore   are  not
  42.          constrained with RAM occupied by file lists.
  43.  
  44.       +  The "-ha" has been improved. Now, when  used  in conjuction  with
  45.          an archiving  command, it does  not mark read-only  files as such
  46.          in archive.  This simplifies  archiving from  CD-ROM media  where
  47.          virtualized read-only  attribute  is  forced  by  respective IFS
  48.          driver.
  49.  
  50.       +  The "-h#" option  has been  improved to  allow  custom  date/time
  51.          formats.  A  custom  format  is  specified  by  putting a  format
  52.          sequence   right   after  the "-h#".  The  following   characters
  53.          represent date/time macros:
  54.  
  55.           Y = year,       M = month,      D = day
  56.           h = hour,       m = minute,     s = second
  57.           N = day of year
  58.  
  59.           (note that these are case-sensitive)
  60.  
  61.          All  other  characters,  as  well as  those going  beyond  format
  62.          limits (4  digits for year, 2 digits for all  other fields),  are
  63.          treated as delimiters. Examples:
  64.  
  65.          ARJ a project- -h#YYYYMMDD              (project-19991022.arj)
  66.          ARJ a backup- -h#MM-DD_hh-mm-ss    (backup-10-22_23-57-16.arj)
  67.          ARJ a specs -h#YY                                (specs99.arj)
  68.          ARJ a logs_ -h#NNN                              (logs_295.arj)
  69.          ARJ a test -h#YYYYYYYY                      (testYYYY1999.arj)
  70.  
  71.       +  "-2k" option forces 2-digit display of year in lists. This can be
  72.          be helpful  if the  3-digit year  format  used for  dates  beyond
  73.          2100 is confusing.
  74.  
  75.          Alternatively, "-2k1" uses a non-ambigous  format  that  is  both
  76.          easy to read and  information-packed.  The dates are  represented
  77.          by two digits if  the year  is 1970 to 2069, and in three  digits
  78.          if it's 2070 or beyond.
  79.  
  80.       +  The  "-2a"  option  is  implemented  in  ARJ  due  to  a  popular
  81.          demand from  FidoNet system  operators.  Basically it  acts  like
  82.          "-jo",  with   the   exception  that  file  names,  and  not  the
  83.          extensions,  are  "serialized". Consider  having  a  file  called
  84.          "FILE995N.TXT" and  an archive that contains  the  same  file. If
  85.          extracted  with  the "-2a"  option,  the  file  will  be  written
  86.          to  "FILE9950.TXT", if  you extract it  again,  it'll  be  called
  87.          "FILE9951.TXT",  and   so   on   up   to   "FILE9959.TXT",   then
  88.          "FILE9960.TXT". And  after  "FILE9999.TXT" ARJ  will  start  with
  89.          "FIL00000.TXT". This option allows you  to extract  one  file  to
  90.          100000000  unique  names.  It's  essential  to  system  operators
  91.          since multiple mail  packets with  the same  name may  come  from
  92.          different systems.
  93.  
  94.          NOTES:
  95.            1. It'll be wise to  include  this  option in the  script  that
  96.               unpacks the ARCmail  packets and  NOT  in ARJ_SW environment
  97.               variable. This  option is  a  security  measure  for systems
  98.               running in  unattended  mode, and  will  only confuse you if
  99.               enabled by default.
  100.            2. There's a security  hole: a file  called  "9999.XXX" or  so,
  101.               will not  be  overwritten.  However, all  subsequent  writes
  102.               will be  redirected  into  file  "0000.XXX". So, files  with
  103.               9s in the beginning have  less  chances of being  preserved.
  104.               Hopefully such situation is unlikely for FidoNet systems.
  105.            3. There is  another  option, "-jo1", to  serialize  filenames,
  106.               however  its   operation   is  different.  The  volume  must
  107.               support  long  filenames  in   order  to  use  this  option,
  108.               moreover,  it's  not   suitable  for  dealing  with  FidoNet
  109.               ARCmail.
  110.  
  111.       +  With no ARJ_SW  specified, ARJ  looks for  a file  named  ARJ.CFG
  112.          in its home  directory. If found, this file  will  be parsed  and
  113.          used  as  a  standard  ARJ  configuration  file (see  manual  for
  114.          details).
  115.  
  116.  
  117.    EXTENDED ATTRIBUTES HANDLING
  118.  
  119.       Beginning  with  version  2.62.10,  the  extended  attributes  (also
  120.       referenced to  as  EAs) can  be  backed  up  and   restored  without
  121.       needing  any external  utilities. This is  achieved  by  compressing
  122.       and storing EAs as a part of file header.
  123.  
  124.       Restrictions on EA support:
  125.  
  126.       *  The multivolume restart  feature (-jn) will not  work  if EAs are
  127.          enabled. You'll  have to  disable EAs  with -2d  prior  to  using
  128.          -jn, or to recreate the archive if the EAs are precious.
  129.  
  130.       *  Hollow mode archives do not support EAs.
  131.  
  132.       A set of new options has been introduced to let  the user control EA
  133.       handling:
  134.  
  135.       *  "-2c" restricts  EA  handling  to  critical  EAs  only.  Archived
  136.          non-critical  EAs  will not  be  restored.  When  an  archive  is
  137.          created, only critical EAs will be saved.
  138.  
  139.       *  "-2e" specifies EA inclusion  filter. With no  parameters  given,
  140.          it disables EA  handling at  all. Otherwise, an  expression  that
  141.          follows  it  is  interpreted  as  a   wildcard  that   limits  EA
  142.          inclusion to a  particular EAs. Multiple  options can be  entered
  143.          to represent a set of EA names but list files are not allowed.
  144.          Examples:
  145.  
  146.          ARJ a test
  147.  
  148.          In this example, all EAs will be preserved.
  149.  
  150.          ARJ a no_eas -2e
  151.          ARJ x no_eas -2e
  152.  
  153.          EAs will neither be packed nor restored.
  154.  
  155.          ARJ a documents -2e.LONGNAME
  156.  
  157.          In this case, only .LONGNAME EAs will be handled.
  158.  
  159.          ARJ a test -2e.CLASSINFO -2e.ICON*
  160.  
  161.          .CLASSINFO and .ICON* (i.e. .ICON, .ICON1, .ICONPOS) EAs  will be
  162.          be packed and restored.
  163.  
  164.          It's wise  to specify "-2e.*" when backing up  your OS/2  desktop
  165.          or  configuration  files.  The system  EAs  start with  dot (".")
  166.          while application EAs start with application name.
  167.  
  168.       *  "-2l" allows to  convert  .LONGNAME  extended  attributes  (these
  169.          represent icon titles used in  WPS) to file names, when possible.
  170.          This feature  simplifies moving document  files away from an OS/2
  171.          system installed on a FAT volume.
  172.  
  173.          If  the icon  title (and  so  the  extended  attribute)  contains
  174.          line breaks, wildcard characters  or other symbols, real filename
  175.          will be used instead and the .LONGNAME EA will be preserved.
  176.  
  177.          This option is ignored during extraction. "-2e" and "-2x" have no
  178.          effect  on  this  option  (but  .LONGNAME EAs are  not  saved  if
  179.          .LONGNAME EA handling is implicitly or explicitly disabled).
  180.  
  181.       *  "-2x" specifies an  exclusion  filter. It must be followed  by an
  182.          exclusion  EA name  specification. The  rules  are  the  same  as
  183.          with "-2e". Also, the  two options  may  work together, providing
  184.          both an inclusion and an exclusion rule. For example:
  185.  
  186.          ARJ a backup_ -r -p1 -h#2 -2e.* -2x.FED* c:\projects
  187.  
  188.          may be used to  create  regular back-ups of your  work directory,
  189.          including all system EAs  but  excluding  EAs  created  with FED
  190.          (Fast Editor  Lite, an  editor written  by Sergey I. Yevtushenko,
  191.          evsi@naverex.kiev.ua) - that program  does not follow traditional
  192.          EA naming  conventions  and  uses  system-alike  EAs  for  anchor
  193.          position marks.
  194.  
  195.       Extended  attributes are  also  supported in ARJSFXV self-extractors
  196.       where they are stored using the  same  technology as with  usual ARJ
  197.       archives.
  198.  
  199.       The presence of EAs  is  indicated  by a "(EA: ...)" message when  a
  200.       file is packed. Note that this size  may differ from  the one  given
  201.       when the file  is unpacked - the  former is  the EA  structure  size
  202.       and the latter is the space allocated  for EA storage. The number of
  203.       EAs and the size of EA structure is  also displayed when the archive
  204.       is listed with "ARJ v" command.
  205.  
  206.  
  207.    FREQUENTLY ASKED QUESTIONS
  208.  
  209.       Q: Third-party applications fail to handle ARJ/2 archives!
  210.       A: Try to disable extended attributes (-2e) and HPFS DTA/DTC storage
  211.          (-j$). Many applications  are incapable  of handling new  archive
  212.          format (although  this format is fully compliant with  documented
  213.          guidelines). Known  examples  of such  applications  include File
  214.          Commander v 2.11, Norton Commander v 5.00 and WinRAR v 2.60.
  215.  
  216.       Q: Extended  attribute  sizes  reported  by InfoZIP  and  ARJ/2  are
  217.          different. What's the cause?
  218.       A: As  we  have  stated  earlier,  ARJ/2  reports  the  size of  its
  219.          internal EA  storage structure  as EA  size  when  packing files.
  220.          This may mismatch with  space allocated for EAs  by  the  system,
  221.          and it may  also  mismatch  with  values  reported by other  OS/2
  222.          native archivers.
  223.  
  224.       Q: How can I back up my OS/2 Workplace Shell folders, preserving the
  225.          icons?
  226.       A: Since  folders are  represented  with directories, you'll have to
  227.          enable directory storage with -a1 or -hbfd.
  228.  
  229.       Q: What is ARJLX?
  230.       A: It's the same program as  ARJ/2, compressed  with LXLITE utility.
  231.          It requires  OS/2  v 3.0 or  higher  to  run. You  may  encounter
  232.          some  compatibility problems  with  it (it's unable  to  register
  233.          ARJLX with REGISTER.EXE, and so on...)
  234.  
  235.       Q: The EAs have vanished after I used ARJ/DOS to update an archive.
  236.       A: Current versions  of ARJ/DOS and ARJ32, as well as ARJ/2 prior to
  237.          2.62.10, strip  the  extended  headers when  any kind  of archive
  238.          update occurs.
  239.  
  240.       Q: I want  to  create  single-volume  self-extracting  archive  that
  241.          supports EAs but ARJ/2 uses ARJSFX instead of ARJSFXV.
  242.       A: You need to  force  use of  ARJSFXV/2. The best way for  it is to
  243.          specify an arbitrary large value for volume size, e.g. -va.
  244.  
  245.       Q: How can I create an installer for my OS/2 product with ARJ?
  246.       A: ARJSFX/2 is  able  to run OS/2  commands after unpacking archive.
  247.          Try this: create a  script you want  to to be  invoked  after the
  248.          installation completes.
  249.  
  250.          e.g., INSTALL2.CMD:
  251.          =======
  252.           /* REXX */
  253.  
  254.           if RxFuncQuery('SysLoadFuncs') then do
  255.            call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
  256.            call SysLoadFuncs
  257.           end
  258.  
  259.           say "Installation has completed, creating desktop object..."
  260.           call SysCreateObject ....
  261.          ========
  262.          and so on...
  263.  
  264.          Now create an archive comment with the first line as follows:
  265.          )) \InstallDir\ -b -x -y -!INSTALL2.CMD
  266.  
  267.          Call it, for example, CMT.ANS. Now create an ARJSFX archive:
  268.  
  269.          ARJ a PACKAGE.EXE -je -r -a -jm -zCMT.ANS -xCMT.ANS
  270.  
  271.          You'll make  a  self-extracting  archive  with  an  automatically
  272.          invoked installation program.
  273.  
  274.          You may not commercially distribute these packages.
  275.  
  276.       Q: How can I distinguish ARJ/2 archives from ARJ/ARJZ ones?
  277.       A: Use the ARJ V  command. The "Host OS" field contains  the type of
  278.          host OS. The  "Revision"  field  may  be used  to  determine  the
  279.          archiver version that added the file:
  280.  
  281.                  1 = ARJ versions earlier than 0.14,
  282.                      ARJZ compatibility mode (-md is less than 26624)
  283.                  2 = ARJ v 0.14...0.20
  284.                  3 = ARJ v 1.00...2.22
  285.                  4 = ARJ v 2.30, X1
  286.                  5 = ARJ v 2.39a, 2.39b
  287.                  6 = ARJ v 2.39c...2.41
  288.                  7 = ARJ v 2.42a...2.50a
  289.                  8 = ARJ v 2.55...2.61, ARJ/2 v 2.61
  290.                  9 = ARJ v 2.62, ARJ/2 v 2.62, ARJ32 v 3.00
  291.                 10 = ARJ v 2.70 and higher, ARJ/2 v 2.62.10 and higher
  292.                 50 = ARJZ with maximum distance up to 32K
  293.                 51 = ARJZ with maximum distance up to 64K
  294.                100 = ARJ32 v 3.00b...3.01
  295.                101 = ARJ32 v 3.02 and higher
  296.  
  297.          Note: ARJ versions  that  created  the  Revision 1  header used a
  298.          different method 4  compression. Support for  it  was dropped  in
  299.          versions 1.xx. Such  archives  may  be  incorrectly  processed by
  300.          ARJ/2.
  301.  
  302.  
  303.    INFORMATION FOR DEVELOPERS
  304.  
  305.       The header format  is 100% compatible  with standard  ARJ format but
  306.       we  were the first to  make  use  of extended  header fields. Here's
  307.       a brief  summary of  the EA storage  technology. First, the extended
  308.       header layout is as follows (all values are little-endian):
  309.  
  310.       Bytes  Description
  311.       -----  -----------
  312.           1  Extended header  ID (0x45, the  character  'E'). Indicates
  313.              a EA information header. This is only valid if the arj_nbr
  314.              (header revision number) is 10 or greater.
  315.           1  Continuation  flag. If set to  0, marks the  end of  block
  316.              chain so the  EA data  can be concatenated  and  unpacked.
  317.              Also it provides a way of checking for trashed EA blocks.
  318.           ?  Packed EA block.
  319.  
  320.       A standard CRC32 of the whole header, including the ID but excluding
  321.       header size field,  is  appended to  it. It is strongly  recommended
  322.       that the CRC is verified when any compressed EA processing occurs.
  323.  
  324.       The packed  EA  block is a  complex  structure  that  can span  over
  325.       multiple  volumes. In  case of  such  spanning,  separate  parts  of
  326.       the block  are stored  in  separate extended  headers  on  different
  327.       volumes and they must be joined together when the last block is read
  328.       (it's recognized   by  EXTFILE_FLAG being clear). The layout of  the
  329.       packed block follows:
  330.  
  331.       Bytes  Description
  332.       -----  -----------
  333.           1  Compression method (0...4, may differ from the  one found  in
  334.              the file header)
  335.           2  Unpacked EA data size in bytes
  336.           4  CRC32 of unpacked EA data
  337.           ?  Raw packed EA data
  338.  
  339.       The raw  packed data  may  be decompressed  using the  original  ARJ
  340.       algorithms. In the case when the file is encrypted, the packed block
  341.       is also  encrypted (but the  garble  routine is  reinitialized  when
  342.       compression  of the EA occurs). The password modifier is the same as
  343.       for the  first file section. After  decompression, the  following EA
  344.       structure will exist:
  345.  
  346.       Bytes  Description
  347.       -----  -----------
  348.           2  Total number of EA records
  349.           ?  Extended attribute records
  350.  
  351.       The extended attribute records are merged altogether. They should be
  352.       processed  sequentally. A single record  represents a single EA, and
  353.       no EA can be represented twice. The layout is as follows:
  354.  
  355.       Bytes  Description
  356.       -----  -----------
  357.           1  fEA byte (may indicate a critical EA)
  358.           1  Size of extended attribute name
  359.           2  Size of extended attribute value
  360.           ?  Extended attribute name (not ASCIIZ)
  361.           ?  Extended attribute value (binary data)
  362.  
  363.       Even if the file is  a text  one, the EAs must be  handled as binary
  364.       data during  compression and  extraction. When EAs are spanned  over
  365.       multiple volumes, neither  the packed  block header  is repeated nor
  366.       the compression  is  restarted (actually, the whole block  including
  367.       its header is created in memory and later split to volumes).
  368.  
  369.  
  370.    PRODUCT INFORMATION
  371.  
  372.       This program has been developed by ARJ Software Russia with the most
  373.       of original ARJ code left intact. It has been briefly tested  on the
  374.       following systems:
  375.  
  376.       DOS:
  377.  
  378.         MS-DOS v 2.11, 3.20, 3.21, 4.01, 5.00, 6.00, 6.20, 6.22
  379.         PC DOS v 6.30, 7.00
  380.         Windows 95, 98
  381.         Windows NT Workstation v 3.51, 4.00
  382.  
  383.       OS/2:
  384.  
  385.         IBM OS/2 v 1.30, 2.00, 2.10, 3.00, 4.00, 4.50
  386.         OS/2 subsystem in Windows NT Workstation v 3.51, 4.00.
  387.  
  388.       The following file systems have been chosen for testing:
  389.  
  390.         FAT, HPFS, Ext2FS and NTFS.
  391.  
  392.  
  393.       The development team:
  394.  
  395.                       Programmed  by  Andrew Belov
  396.                     Testing lead  by  Viatcheslav Odintsov
  397.  
  398.       Source code is not available for public use.
  399.  
  400.  
  401.       End of document
  402.