home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / vol179 / carchive.lbr / CARCHIVE.DQC / CARCHIVE.DOC
Text File  |  1985-02-09  |  6KB  |  151 lines
  1. ARCHIVE.DOC
  2. ----------------------------------------------------------------
  3.  
  4.  
  5.        Chris Kern
  6.        201 I St., S.W., Apt. 839
  7.        Washington, D.C. 20024
  8.  
  9.  
  10.  
  11. This file accompanies ARCHIVE.C, my CP/M implementation of the
  12. archive program from "Software Tools," by Brian W. Kernighan and
  13. P.J. Plauger (also available as "Software Tools in Pascal,"
  14. which, like the original FORTRAN version, is published by
  15. Addison-Wesley).
  16.  
  17. For those who don't have one or the other of the books, the
  18. syntax is:
  19.  
  20.     archive -[option] archive_name filename1 filename2 ...
  21.  
  22. and the legal options are:
  23.  
  24.     -c  create an archive containing the named files
  25.     -u  update the archive with the named files
  26.     -d  delete the named files from an existing archive
  27.     -p  print the named files on the console
  28.     -x  extract the named files from the archive
  29.     -t  print the table of contents
  30.     -s  print an alphabetically sorted table of contents
  31.  
  32. The -s option is an addition to those documented in Kernighan
  33. and Plauger.  If no file names are given, the specified
  34. operation (except -d) is performed on all the files in the
  35. archive.
  36.  
  37. ARCHIVE combines a number of files into one big file and
  38. provides facilities for accessing, updating, deleting and adding
  39. to the components.  This method of archival storage saves disk
  40. space since CP/M allocates a minimum increment of disk storage
  41. for even the smallest files.  This increment, and the
  42. corresponding savings, vary with the disk capacity and the size
  43. of the files in the archive.  In general, the amount of space
  44. saved will be greater if the archive is composed of a lot of
  45. small files instead of a few big ones and if the disk storage
  46. devices are relatively high capacity.  On my double-sided,
  47. double-density 8" disks, for example, the minumum unit of
  48. storage is 2K.    ARCHIVE, by contrast, can allocate as little as
  49. one 128-byte sector of disk storage.
  50.  
  51. But the real purpose of ARCHIVE is not to pack them in (other
  52. public domain programs, e.g. the SQUEEZER programs used on so
  53. many remote CP/M systems, are far more effective in that
  54. regard).  ARCHIVE's real strength is that it simplifies archival
  55. storage by collecting lots of files into a few general
  56. categories.  It helps hide the details of a database until they
  57. are really needed.
  58.  
  59. The version of ARCHIVE that I am distributing contains some
  60. conditionally-compiled portions that support date and time
  61. stamping of files.  I have left these sections in the program
  62. for illustrative purposes only.  The program will compile
  63. without them unless you set the CLOCK define at the beginning of
  64. the source file to TRUE.  Users who have real-time system clocks
  65. can use them with ARCHIVE by providing four simple support
  66. routines:
  67.  
  68.     rdtime()    reads the time into a data structure
  69.             (_time) of the user's own design;
  70.  
  71.     rddate()    reads the date into a similar structure
  72.             (_date);
  73.  
  74.     timestr()   converts the contents of the _time
  75.             structure to an ASCII string;
  76.  
  77.     datestr()   converts the _date to a string.
  78.  
  79. The details of these routines, and the associated data
  80. structures, will of course be dependent on the precise clock
  81. facilities available on the host system.
  82.  
  83. Together, ARCHIVE and the ubiquitous SQUEEZER programs provide a
  84. very convenient way to transfer a group of related files
  85. among CP/M systems.  First, squeeze the files.    Then combine
  86. them in an archive.  The archive of related files can be
  87. transmitted to another machine in a single file transfer.  This
  88. not only saves time; it also guarantees that all the files
  89. needed for a given purpose (e.g., all the source files making up
  90. a single program) will actually reach the recipient.  This will
  91. only work, however, if everyone is using the same archive
  92. program (or if the appropriate version of ARCHIVE.COM is
  93. transmitted along with a given archive).  For anyone who wants
  94. to use this procedure, I suggest keeping the header format just
  95. as it appears in my source code.  Date and time stamps obviously
  96. should not be present in any public access archive.
  97.  
  98.  
  99.  
  100. ----------------------------------------------------------------
  101.  
  102.  
  103. Dependencies:
  104.  
  105.  
  106. (1) ARCHIVE requires CP/M version 2.X, since it uses the random
  107.     file I/O system calls that are not available in earlier
  108.     versions.
  109.  
  110. (2) ARCHIVE was compiled with version 2.6 of the BDS C Compiler
  111.     and linked to library routines that were included with that
  112.     release.
  113.  
  114. (3) There is a bug in the rread() function in the standard
  115.     library distributed with BDS C version 2.6 which must be
  116.     fixed before ARCHIVE will work reliably.  Briefly, rread()
  117.     checks only for an error #1 condition (reading unwritten
  118.     data) after calling the system read-random-sector
  119.     primitive.    But if reading ends on an extent boundary,
  120.     error #4 (seek to unwritten extent) may be returned.  Both
  121.     must be trapped, since both indicate only that an end-of-
  122.     file condition has occurred.  The following change in the
  123.     file DEFF2A.CSM, which is included with the compiler, does
  124.     the trick:
  125.  
  126.     r2a:    lhld    arg2
  127.         xchg
  128.         ...
  129.         ...
  130.         mvi    c,readr ;code for BDOS random read
  131.         push    d    ;save so we can fudge, etc.
  132.         call    bdos    ;we stop reading, etc.
  133.         pop    d    ; obscure technical jargon
  134.         ora    a
  135.         jz    r4    ;go to r4 if no problem
  136.         cpi    1
  137.         jz    r2b    ;EOF
  138.     --------------------------------------------------------
  139.     |    cpi    4    ;check for error 4, too        |
  140.     |    jz    r2b    ;treat it the same as error 1  |
  141.     --------------------------------------------------------
  142.         mov    c,a    ; put return error code, etc.
  143.         mvi    b,0
  144.         ...
  145.         ...
  146.  
  147. (4) Note that the storage allocation globals in bdscio.h -- the
  148.     standard header file -- must be compiled since the program
  149.     uses alloc() to create a file I/O buffer.
  150.     But if reading ends on an extent boundary,
  151.     error #4 (seek to unwritten extent) may