                  Multics ARCHIVE command for OS/2 
                      Version 1.0 - April, 2002
                - Peter Flass <Peter_Flass@Yahoo.com>
                                                     25 March, 2003 
      
The Multics 'archive'(ac) command is perhaps the "mother of all" file
packaging systems, such as unix 'ar' and 'tar', and OS/2's 'zip'.

An archive file consists of a series of named components separated 
by headers.  Data in an archive is not compressed.  

This program is an OS/2 re-implementation of the archive command, 
allowing Multics archives to be created and maintained, and archive 
components to be extracted.  This is not a direct port for three reasons:
  1. The Multics source code is still copyrighted.
  2. No current operating system can provide all of the
     Multics functionality that commands expect to have available.
  3. No current PL/I compiler will compile Multics source code
     without substantial modifications.


Installation:
  Copy 'archive.exe' to a directory in your PATH.  The PL/I
  version 1.1 DLLs should be somewhere in your LIBPATH.
  I'm told that the version 2.x DLLs, if you have them,
  are not compatible.  The DLLs are available from:
    http://hobbes.nmsu.edu/pub/os2/dev/misc/pli11dll.zip


Command format:

      archive <key> <archive_pathname> [ <component_pathnames...> ]

  for example: 
      archive t my.archive  
  will list all components of the archive "my.archive".
      archive x my.archive source.pl1
  will extract the component "source.pl1" from "my.archive".
  Note that the command keys are not preceeded by '-' as in unix.
  Only specific keys are valid, identified below.
  
  Component pathnames are required for some keys, ignored for others.
  They represent a list of the components of the archive to be
  extracted, listed, replaced. etc.  The "path" portion of the
  name is used to access the file for extraction, appending, etc.;
  Unlike, e.g. 'zip', the paths are not stored with the filenames
  in the archive.


Pathnames:

  Multics uses the characters '<' and '>' to represent the equivalent
  of OS/2's '..\' and '\' (unix '../' and '/').  Unfortunately 
  COMMAND.COM reserves these characters for redirection.  Archive
  will accept any of the variations as equivalent.  In order to
  prevent COMMAND.COM from munging '>' and '<', enclose the entire
  command or just the pathname in double quotes (").
  For example "archive t <my.archive" or archive t "<my.archive"
  are both equivalent to archive t ..\my.archive, which is also
  acceptable.

  All archives end with the suffix ".archive".  If an archive name
  is entered without this suffix ".archive" will be appended.

  Entry names (filenames) are limited to 32 characters.  This is
  a restriction of the archive format.
  Path names are limited to 168 characters.  This is the Multics
  limitation, but can be changed in this version of archive
  by changing the constant "MAX_PATH" and recompiling.

  Component sizes are limited to approximately 2.7MB each.  This is
  a restriction of the archive format.


Drive letters:

  Multics had a file system with a single root ('>', like unix '/'),
  unlike OS/2, DOS, etc. which have a root per logical drive.
  Accordingly (as far as I know) Multics had no way of specifying
  a "drive letter", but relied on mounting a drive onto the
  filesystem, like unix.  Archive version 1.0 has no way of 
  specifying drive letters, though I expect to add this later.
  Currently all files accessed must be on the current drive or
  accessed thru a filesystem that accesses multiple drives 
  transparently, such as TVFS.


Starnames ("wildcards"):

  Multics, like OS/2 and unlike unix leaves wildcard expansion
  in commands [called "starnames" in Multics] (e.g. 'command *.x') 
  to the application rather than the shell.  Archive version 1.0 
  does not do starname expansion.  This is a planned future 
  enhancement.


Archive Component Formats:

  Most OS/2 text files use carriage-return + line feed ('0D0A'x) as
  a line terminator; Multics files use only a line feed.  Archive
  stores and extracts files exactly as they are.
  A possible future enhancement would be to strip the carriage
  returns out of files appended to or replaced in an archive, but
  this leaves open the question of how to restore files.  If
  you want files stored without carriage-returns, use a program
  such as "os22unix" which deletes them before storing these files
  in an archive.


Dates, Times, and Access Modes:

  OS/2 stores file dates as unsigned 7-bit offsets from 1980,
  allowing dates between 1980 and 2107 inclusive.  Multics 
  development started in the mid 1960s and ended in 2000,
  it is theoretically possible that archives might contain 
  components dated in the 1960s, and dates in the 1970s should
  be common.  In order to attempt to remain true to the archive
  dates files dated between 1960 and 1979 will be extracted with 
  dates above 2060.  DIR, which shows only two-digit years will 
  show the correct date.  When Archive checks dates for replacement
  dates above 2060 will be interpreted as 1960 and above.  Of course
  this allows only a 58-year lifespan for Archive, but I expect
  not to have to worry about it then. ['ls -l' shows four-digit 
  years and thus will show 2060-2079]. 

  Archive dates are stored with only two-digit years [Y2K, what Y2K??].
  Years less than 60 are interpreted as 2000-2059.

  Multics stores times in tenths of minutes (6 sec), OS/2 stores times
  in units of two-seconds.  Archive times will be rounded _up_ to the
  nearest tenth of a minute when components are stored.

  OS/2 does not use file access modes in the same was as Multics.
  Components stored in an archive will be assigned "r w" (read/write),
  Extracted files will be assigned "normal" attributes (not hidden,
  system, or read-only).  "F" in archive keys (e.g. "rdf") will be
  ignored.
  
  

Archive 'command keys':

     +-----------------------------------------------------------+
     |                                                           | 
     |    key    function   valid options...                     | 
     |    ---    --------   --------------------------------     |
     |    r      replace    empty+norig+zarg                     | 
     |    rd                del+empty+norig+zarg                 | 
     |    rdf               del+force+empty+norig+zarg           | 
     |    cr                copy+empty+norig+zarg                | 
     |    crd               copy+del+empty+norig+zarg            | 
     |    crdf              copy+del+force+empty+norig+zarg      | 
     |                                                           | 
     |    u                 update+zarg                          | 
     |    ud                update+zarg+del                      | 
     |    udf               update+zarg+del+force                | 
     |                                                           | 
     |    cu                copy+update+zarg                     | 
     |    cud               copy+update+zarg+del                 | 
     |    cudf              copy+update+zarg+del+force           | 
     |                                                           | 
     |    a                 append+empty+norig                   | 
     |    ad                append+empty+norig+del               | 
     |    adf               append+empty+norig+del+force         | 
     |    ca                copy+append+empty+norig              | 
     |    cad               copy+append+empty+norig+del          | 
     |    cadf              copy+append+empty+norig+del+force    | 
     |                                                           | 
     |    d      delete                                          | 
     |    cd                copy                                 | 
     |                                                           | 
     |    x      extract    zarg+star                            | 
     |    xd                zarg+star+del                        | 
     |    xdf               zarg+star+del+force                  | 
     |    xf                zarg+star+force                      | 
     |                                                           | 
     |    t      table*     star+zarg                            | 
     |    tl                long+star+zarg                       | 
     |    tb                star+zarg+brief                      | 
     |    tlb               long+star+zarg+brief                 | 
     |                                                           |
     | *table = list archive headers                             |
     |                                                           | 
     +-----------------------------------------------------------+


Files for archive:

  archive.archive    - Sample archive containing all source files.
  archive.exe        - executable for 'archive'. (not in source-only distribution).
  readme.txt         - this file.

-in directory 'source':
  archive.pli        - Source for the main procedure of the archive command.
  archive_header.cpy - %include file for the archive header description.
  key.pli            - Source for the table of keys for the archive command.
  key.pp             - **MVS PL/I 1.1 program** which was run through the 
                       preprocessor on the mainframe to generate 'key.pl1'.
                       This program is not required to rebuild 'archive',
                       but is included for reference only.
  makefile           - Gnu make makefile for archive command.
  osdep.pli          - OS/2 dependent code for archive command.
  word.cpy 
  wordpos.cpy        - Two %included procedures.
  ac.txt             - The archive command description from the Multics
                       Programmer's Manual (MPM).


Recompiling, Porting:

  This program was compiled with IBM's VisualAge PL/I for OS/2 1.1.
  Version 2.x provides some BIFs for OS-dependent functions that
  had to be coded directly in version 1.1.  Anyone porting archive
  to PL/I 2.x on other OS's might want to take advantage of the new BIFs.
  The OS/2 dependent code is isolated in the module 'osdep.pli', the 
  remainder of the program should be OS independent.  

  To rebuild the program from source just cd to the source directory
  and type 'make'.

  If you port Archive, please e-mail me <Peter_Flass@Yahoo.com>.
  I would like to maintain a consolidated source version using
  %if logic for compiler differences.


Note on archive format:

  Multics ran on hardware that stored four 9-bit bytes in a 36-bit word.
  Fortunately the character set was ASCII, so conversion to 32-bits
  preserved character data.  Any binary components that may have been stored
  would have been destroyed by the conversion.  The archive header stores
  the length of the component _IN BITS_.  Most (all?) components seem to have
  been a multiple of whole words so conversion to lengths in bytes is
  a matter of dividing the stored length by 36 to get number of words and
  multiplying the result by 4 to get bytes.  Conversion of bytes to bits
  for append or replace operations is the reverse.

  Archive headers contain lots of unused bytes of spaces.  It should be 
  possible to define a "version 2" header by grabbing an unused byte to
  hold a version number and storing lengths in bytes.  With this method it
  would be possible to transparently store components in both old and new
  formats in a single archive.  


Corrupted archives:

  Should you happen to be in possession of any Multics archive files,
  rumor has it that some corruption may have occurred during transmission.
  The "bit count" in the archive headers may not be exactly correct, either
  a few bytes too big or too small.  The program RDARCH.PLI is provided
  which will scan an archive and identify the bad components. No automated
  correction is provided at present, although there is no reason why this
  couldn't be added.  The easiest way to fix corrupted archives might be 
  to use an editor to add or subtract blanks at the end of the bad components
  to adjust them to a four-byte boundary.


More on Multics:

  Tom Van Vleck maintains an excellent web site on Multics at:
  http://www.multicians.org


Copyright:

  Use of this program is governed by the terms of the Gnu General Public 
  License (GPL). 

