home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / arc_lbr / arcstamp.arc / ARCSTAMP.DOC next >
Text File  |  1988-06-20  |  12KB  |  284 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                              ARCSTAMP
  11.  
  12.                  Date/time stamp for archived files
  13.  
  14.                         by David Peyton
  15.  
  16.  
  17.                      Version 1.00 (June 1988)
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                   Copyright (c) 1988 by David Peyton
  28.                   All Rights Reserved
  29.  
  30.  
  31.  
  32.          ARC is a trademark of System Enhancement Associates
  33.          for its file archive utility.
  34.  
  35.  
  36.                               INTRODUCTION
  37.  
  38.  
  39.         ARCSTAMP is a utility that will allow you to change the date/time
  40. stamp and, optionally, rename files that are stored within an archive.  This
  41. represents considerable savings in time and disk space over having to extract
  42. the files, changing their date/time stamps through the operating system,
  43. renaming them, and adding them back into the archive.
  44.  
  45.         ARCSTAMP also allows the user to specify how the date/time stamp on
  46. the .ARC file itself should be updated, choosing from the two methods in
  47. common use.  In addition, it does not maintian a backup copy of the archive
  48. it is processing, so it has the added advantage that even floppy disk users
  49. need not worry about setting aside sufficient free space on disk for ARCSTAMP
  50. to operate.
  51.  
  52.  
  53.                           DISTRIBUTION POLICY
  54.  
  55.         This program is distributed under the shareware concept.  All users
  56. of this program are encouraged to make copies for online distribution and for
  57. trial use by others.  However, if you find this program of value, you are
  58. asked to register it with the author.
  59.  
  60.         No user may make any monetary charge for the distribution of this
  61. program, or distribute the program and/or its documentation with ANY
  62. modifications without the express written permission of the author.  Users'
  63. groups, and distributors of public domain or user supported software
  64. libraries, if they qualify as legitimate, non-profit organizations, are
  65. hereby granted permission to charge their typical handling fee, provided that
  66. this fee does not exceed the cost of media, postage, or other expenses
  67. directly involved in the distribution of this software.
  68.  
  69.         Registration requires a one-time fee of $12 for individuals, or $12
  70. per on-site computer used to run ARCSTAMP in a commercial environment or
  71. governmental organization.  Registered users are entitled to receive all
  72. future updates of this program as they become available, either through
  73. normal channels of shareware distribution or directly from the author.  All
  74. registration requests should be sent to:
  75.  
  76.                           David Peyton
  77.                           Platt Campus Center
  78.                           Harvey Mudd College
  79.                           Claremont, CA 91711
  80.  
  81. Any questions, comments, suggestions, and/or bug reports are most welcome,
  82. and should also be sent to this address.  Registered users will receive first
  83. priority in answering correspondence.
  84.  
  85.  
  86. WARRANTY:  This program is supplied "as-is."  The author makes no warranty of
  87.            any kind, express or implied, including without limitation, any
  88.            warranties of merchantibilty and/or fitness of this program for a
  89.            particular purpose.  The author assumes no liability for any
  90.            damages, whether direct, indirect, special, or consequential
  91.            arising from the use of or inability to use this program or any
  92.            modified version thereof, or for any claim by any other party.
  93.  
  94.  
  95.                    COMMAND LINE SYNTAX AND OPTIONS
  96.  
  97.  
  98. The format for invoking ARCSTAMP is:
  99.  
  100.         ARCSTAMP [/option] ... [d:][path]archive  [filespec] ...
  101.  
  102. Where:
  103.  
  104.         "/option" is one of two available command switches (see below) used
  105.         to control renaming of files within an archive, and how the .ARC file
  106.         is to be updated on program termination.  Both options may be used at
  107.         once, if desired.
  108.  
  109.         "d:" and "path" are the drive and path specifiers for the .ARC file.
  110.         If these are omitted, the default drive and path is assumed.
  111.  
  112.         "archive" is the name of the archive file.  If no filename extension
  113.         is given, an extension of ".ARC" is assumed.
  114.  
  115.         "filespec" is the name of a file contained within the archive.  It is
  116.         permissible to use more than one such argument.  If this argument is
  117.         omitted, ARCSTAMP will process all the files contained in "archive."
  118.  
  119. Invoking ARCSTAMP with no arguments will cause it to display a brief summary
  120. of the command line format.
  121.  
  122. For every file that it is directed to process, ARCSTAMP will display the
  123. following message:
  124.  
  125.         File [FILENAME] in archive [ARCHIVE]
  126.         is dated [Day of week], [dy] [Month] [year]
  127.         Enter new date (mm-dd-yy):
  128.  
  129. The user may enter any date acceptable to DOS in the typical format:  mm
  130. being the month number from 1 to 12, dd the day of the month from 1 to 31,
  131. and yy a two-digit number from 80 to 99 (the 19 is assumed) or a four-digit
  132. number from 1980 to 2099 representing the year.  The hyphen (-), period (.),
  133. and forward slash (/) are all acceptable separators between the numbers.
  134. Instead of entering a date in full, the following keys may be used as
  135. shortcuts:
  136.  
  137.         F1 - stamps the file with the current date
  138.  
  139.         F2 - stamps the file with the date of the newest file found in the
  140.              archive
  141.  
  142.         F3 - stamps the file with the date of the archive file when it was
  143.              opened by the program
  144.  
  145.         F4 - ends the program.  This provides a much cleaner exit than
  146.              Control-C.
  147.  
  148.         Esc - does not stamp the file, but causes the program to continue
  149.               processing.
  150.  
  151.  
  152.         If the date supplied is not valid, or a function key is used that
  153. ARCSTAMP does not recognize, an error message is displayed and the user is
  154. prompted for the date again.
  155.  
  156.         When the date of the file has been stamped, a message will be
  157. displayed indicating the current file time, and prompting for the new time as
  158. (hh:mm:ss). The format for entering times is the same one used by DOS
  159. (identical to military time), where hh represents the hour, mm the minutes,
  160. and ss the seconds.  The hour may be one digit if desired, but minutes and
  161. seconds must be two digits each.  If seconds are not supplied, "zero seconds"
  162. is assumed.  Note that the colon (:) is the only allowable separator between
  163. the digits.
  164.  
  165.         As before, it is possible to use certain keys as shortcuts instead of
  166. entering the time manually, as follows:
  167.  
  168.         F1 - stamps the file with the current time
  169.  
  170.         F2 - stamps the file with the time that is, at that point, the latest
  171.              time found in the archive (see below)
  172.  
  173.         F3 - stamps the file with the time of the archive file when it was
  174.              opened by the program
  175.  
  176.         F4 - ends the program.  Note that if the date has been changed, using
  177.              this key will cause the date just stamped not to be saved.
  178.  
  179.         Esc - does not change the file's time, but continues processing the
  180.               next file, if there is one, or else ends the program.  Using
  181.               this key instead of F4 will cause the stamped date to be saved.
  182.  
  183. If the time is not valid, or a key is used that ARCSTAMP does not recognize,
  184. an error message is displayed and the user is prompted for the time again.
  185.  
  186.         The "latest time" in the archive is defined as the time with the
  187. highest numerical value (on the 24 hour clock) associated with the file with
  188. the latest date.  For example, the time 8:25 for a file dated January 16th is
  189. considered to be later than 11:15 for a file dated January 15th.  Thus, the
  190. latest time may change as soon as the file dates change.
  191.  
  192.  
  193.  
  194. The two options recognized by ARCSTAMP work as follows:
  195.  
  196.         /R (rename)  When this option is specified, the user will be asked
  197.                      whether the file just stamped is to be renamed.  If a
  198.                      'Y' is entered, the user is then prompted for the new
  199.                      filename.  As in DOS, a filename is 1 to 8 characters
  200.                      long, plus an optional period (.) and 1 to 3 characters
  201.                      for an extension.  ARCSTAMP accepts only alphanumeric
  202.                      characters for filenames, and will not allow the user to
  203.                      give a file the same name as any other file in the
  204.                      archive.
  205.  
  206.         /U (update)  This option will stamp the archive file itself with the
  207.                      latest date and time found among the files in the
  208.                      archive when the program terminates.  If this option is
  209.                      not specified, the archive file will be stamped with the
  210.                      current date and time.  (Note: stamping the archive with
  211.                      the latest date/time of the archive files is the method
  212.                      used by System Enhancement Associates' ARC program;
  213.                      stamping the current date and time is used by Phil
  214.                      Katz's PKARC program.)
  215.  
  216. WARNING!
  217.  
  218.         The rename option should be used with caution!  The ARC program
  219. always stores files in alphabetical order by filename when it creates an
  220. archive, and it assumes that all such archives obey this convention.  Thus,
  221. if you have an archive containing the two files ALPHA.TXT and BRAVO.TXT,
  222. renaming ALPHA.TXT to COCO.TXT is asking for trouble.  If you later use ARC
  223. to add BRAVO.TXT to this file, ARC will not know any better than to do so
  224. once it sees COCO.TXT as the first file in the archive.  The result is an
  225. archive with duplicate files, or at the very least one with duplicate
  226. filenames.  Although lack of alphabetical order is not a problem for
  227. extraction, listing, or other ARC functions, if you plan to add files to your
  228. archives in the future, you should take care that the alphabetical order is
  229. preserved.
  230.  
  231.  
  232.                               ACKNOWLEDGEMENTS
  233.  
  234.  
  235.         The design, coding, testing, and debugging of this program were all
  236. done by me.  However, producing a working program is rarely a single-handed
  237. effort, particularly when the program is to work with a specialized kind of
  238. data whose format was designed by someone else.  I owe a debt of gratitude to
  239. several others, without whose efforts this program would probably never have
  240. left my computer.
  241.  
  242.         First and foremost, I would like to extend my thanks to System
  243. Enhancement Associates, creators of the original ARC program, for having made
  244. their source code available.  I found it to be very helpful in my efforts to
  245. adjust to the C language as I was developing ARCSTAMP.
  246.  
  247.         I also am grateful to Phil Katz, creator of PKARC and PKXARC, for his
  248. technical essay on archive file formats, and for his assistance in helping me
  249. over the worst pitfalls involved in making a program compatible with this
  250. format.  Without him, I would undoubtedly have banged my head against the
  251. wall much longer than I did.
  252.  
  253.         Finally, I must single out the anonymous voices at the other end of
  254. Microsoft's language support line for special recognition.  I appreciate the
  255. patience of these people as they explained to me some of the idiosyncracies
  256. of C.  Their efforts have done a great deal to convince me that their C
  257. compiler was a worthwhile investment in software.
  258.  
  259.  
  260.  
  261.                                                 ----Dave Peyton
  262.                                                     June 1988
  263.  
  264.  
  265.                             AFTERWORD
  266.  
  267.  
  268.         For those users who would prefer to contact me via E-mail rather than
  269. spending a quarter for postage, the most likely place at which I will find
  270. your message is the Public Domain Software Exchange bulletin board, the
  271. system I log into most often.
  272.  
  273.         Located in Sunnyvale, California, PDSE has two numbers:
  274.  
  275.         408-735-7190            or
  276.         408-745-0880
  277.  
  278. Both these numbers are accessible with PC Pursuit.  You should leave your
  279. message in the General section or the Programmers' SIG to ensure that I will
  280. find it.
  281.  
  282.  
  283.  
  284.