home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / tdate140.zip / truedate.doc < prev    next >
Text File  |  1994-05-18  |  17KB  |  412 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                       TrueDate
  16.  
  17.             OS/2 Archive "True Date" Stamp Utility, version 1.40 Manual
  18.  
  19.             Copyright 1993-94 by David G. Fisher.  All rights reserved.
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.        Introduction
  27.             What is TrueDate?.....................................3
  28.             Registering TrueDate..................................4
  29.             Disclaimer............................................5
  30.             Documentation.........................................6
  31.  
  32.        Using TrueDate
  33.             Description of Syntax.................................7
  34.             Using TrueDate........................................9
  35.             Configuration File Options............................9
  36.             Using TrueDate for Sysops.............................9
  37.                  Maximus - Last Write Date vs. Creation Date.....11
  38.  
  39.  
  40.  
  41.        TrueDate Users Manual                                          Page 3
  42.        ----------------------------------------------------------------------
  43.  
  44.        What is TrueDate?
  45.  
  46.        TrueDate is a utility that will reset the dates for archive files to a
  47.        more appropriate "true" date.  Many times, the files within an archive
  48.        are much older than the actual date of the archive itself.  The true
  49.        date of the archive may be changed to a newer date for a variety of
  50.        reasons.  System BBS operators may set the date of an archive to the
  51.        current date so users know that the file is new to their BBS.  Or, the
  52.        archive may be manually re-packed using a different archival method.
  53.        In short, there are a plethora of reasons that the true date of the
  54.        archive can change.
  55.  
  56.        I could not find a program to reset the date of archives under OS/2.
  57.        Therefore, I wrote this program.  While it is primarily intended as a
  58.        tool for my BBS, it may also be useful to the end user who wants to
  59.        set the dates on their archives to something more appropriate so they
  60.        can determine it's true age at a glance in the directory.
  61.  
  62.        TrueDate uses a simple method to determine the true date of an
  63.        archive.  TrueDate creates a listing of the archive, and then finds
  64.        the date of the newest or oldest file (depending on DateSelection)
  65.        within the archive.  It then sets the date of the archive to this
  66.        date.
  67.  
  68.        Archivers can be defined in the TrueDate configuration file.
  69.  
  70.        Currently, TrueDate is only available for OS/2 2.x.
  71.  
  72.  
  73.  
  74.        TrueDate Users Manual                                          Page 4
  75.        ----------------------------------------------------------------------
  76.  
  77.        Registering TrueDate
  78.  
  79.        TrueDate is shareware.  If you find TrueDate useful and use it on a
  80.        consistent basis, please be sure to send in your payment.  I
  81.        distribute TrueDate in an uncrippled form and rely on your
  82.        conscientiousness to support the shareware concept.
  83.  
  84.        Simply print and send the form REGISTER.DOC.
  85.  
  86.        The most recent TrueDate release is always available here with the
  87.        magic File Request name of TRUEDATE.  The archive name is distributed
  88.        as TDATE???.ZIP where '???' is the version number of TrueDate.
  89.  
  90.        Network Addresses:
  91.  
  92.             FidoNet: 1:170/110@fidonet.org
  93.             ibmNET : 40:4372/0
  94.             OS2NET : 81:202/201
  95.  
  96.             BBS: (918) 481-5779 (LiveNet OS/2 BBS)
  97.  
  98.        Paper mail address:
  99.  
  100.             Dave Fisher
  101.             5131 East 88th Court
  102.             Tulsa, Oklahoma  74137
  103.             USA
  104.  
  105.        Please don't hesitate to send suggestions.  Find a bug and I'll
  106.        promptly try to make a new version, or at least a temporary work-
  107.        around, available to you.
  108.  
  109.  
  110.  
  111.        TrueDate Users Manual                                          Page 5
  112.        ----------------------------------------------------------------------
  113.  
  114.        Disclaimer
  115.  
  116.        This program is shareware.  There is absolutely no warranty for this
  117.        program or guarantee it will work.  The user of this program assumes
  118.        all risk.  While I feel confident this program will not harm your
  119.        system in any way, by using this program, you agree to assume full
  120.        responsibility for any adverse effect to your system.
  121.  
  122.        Where applicable, all trademarks referred to here are the property of
  123.        their owners.
  124.  
  125.  
  126.  
  127.        TrueDate Users Manual                                          Page 6
  128.        ----------------------------------------------------------------------
  129.  
  130.        Documentation
  131.  
  132.        There are three document files that describe TrueDate.
  133.  
  134.        TRUEDATE.DOC
  135.  
  136.             The file you are reading is a basic description and
  137.             introduction to TRUEDATE.
  138.  
  139.        HISTORY.DOC
  140.  
  141.             History of changes to TrueDate should serve as a good
  142.             reference to track new TrueDate enhancements as they are
  143.             added.
  144.  
  145.        TRUEDATE.CFG
  146.  
  147.             The accompanying TRUEDATE.CFG configuration file is heavily
  148.             documented and demonstrates how I use TrueDate on my system.
  149.             It is a companion to this document, included to illustrate how
  150.             TrueDate's default settings are modified and how new Archiver
  151.             programs are defined.
  152.  
  153.  
  154.  
  155.        TrueDate Users Manual                                          Page 7
  156.        ----------------------------------------------------------------------
  157.  
  158.        Description of Syntax
  159.  
  160.        TrueDate ArcFileName [, ArcFileName, ...]
  161.  
  162.             /Config = <path+file name>         default: TRUEDATE.CFG
  163.             /[no]Log                           default: NoLog
  164.             /LogFile = <path+file name>        default: None
  165.             /LogLevel = <1..4>                 default: 4
  166.             /[no]Quiet                         default: NoQuiet
  167.             /[no]LastWriteDate                 default: LastWriteDate
  168.             /[no]CreationDate                  default: NoCreationDate
  169.             /[no]TestOnly                      default: NoTestOnly
  170.             /Debug = <0..5>                    default: 0
  171.  
  172.        Notes on the syntax:
  173.  
  174.             Qualifiers can appear in any order, in any case, and are only
  175.             significant to four characters.  /LogFile, for instance, is
  176.             the same as /logf.
  177.  
  178.        Qualifiers
  179.  
  180.        Config = <path+file name>
  181.  
  182.             This is the name of the configuration file.  The default is
  183.             TRUEDATE.CFG in the current directory.  If you prefer, you can
  184.             define an environment variable using the DOS SET command
  185.             instead, with the following syntax:
  186.  
  187.             Set TRUEDATE_CONFIG=<path+filename>
  188.  
  189.        /[no]Log
  190.  
  191.             This qualifier will turn the logging function on and off.
  192.             Default is NoLog.
  193.  
  194.        /LogFile = <path+file name>
  195.  
  196.             This qualifier defines the name of the log file.
  197.  
  198.        /LogLevel = <1..4>
  199.  
  200.             This qualifier defines the level of log file detail.  Level 1
  201.             is the least detailed, while Level 4 is the most verbose.  The
  202.             levels indicate the 'importance' of a message, where Level 1
  203.             is the most important (usually error messages).
  204.  
  205.        /[no]Quiet
  206.  
  207.             This qualifier controls whether TrueDate should print detailed
  208.             output to the "standard output device", which is normally the
  209.             screen.  Set it to /Quiet and all you see are the program
  210.             copyright line and any error messages.  The default is
  211.             /NoQuiet.
  212.  
  213.  
  214.  
  215.        TrueDate Users Manual                                          Page 8
  216.        ----------------------------------------------------------------------
  217.  
  218.  
  219.        /[no]LastWriteDate
  220.  
  221.             This qualifier controls whether TrueDate will reset the "Last
  222.             Write" date under OS/2.  This is the default action of
  223.             TrueDate.  Most programs, including the basic "dir" command,
  224.             will use and display this date.
  225.  
  226.        /[no]CreationDate
  227.  
  228.             This qualifier controls whether TrueDate will reset the
  229.             "Creation" date under OS/2.  The default action of TrueDate
  230.             will NOT set the creation date of the archive.  Many times, it
  231.             is beneficial to leave the Creation date alone, so it will
  232.             reflect the true date the archive was actually created, and
  233.             set the Last Write to the "true" date of the archive.
  234.             However, this default action of TrueDate can be overridden by
  235.             specifying /CreationDate on the command line.
  236.  
  237.        /[no]TestOnly
  238.  
  239.             If this qualifier is specified as /TestOnly (or /Test), then
  240.             TrueDate will analyze the indicated archives and report the
  241.             changes it would have made if not run in test mode.
  242.  
  243.        /Debug = <0..5>
  244.  
  245.             This qualifier is primarily used by me when testing TrueDate.
  246.             However, if TrueDate does not perform as expected, this
  247.             qualifier will instruct TrueDate to display quite a bit of
  248.             information concerning the internal processing of the program.
  249.             This information may be instructive as to why TrueDate is not
  250.             performing as expected.
  251.  
  252.  
  253.  
  254.        TrueDate Users Manual                                          Page 9
  255.        ----------------------------------------------------------------------
  256.  
  257.        Using TrueDate
  258.  
  259.        TrueDate is simple to use.  The most basic form is as follows:
  260.  
  261.             TrueDate [ArcFileName]
  262.  
  263.        where 'ArcFileName' is the name of the archive which is to have its
  264.        date reset.  'ArcFileName' can include wildcard matches such as
  265.        "*.ZIP", or even "*.*" which will reset the time stamp on every
  266.        archive defined in the current directory.  Multiple archive file
  267.        matches can be included, also.  However, all 'ArcFileName's MUST be
  268.        separated by commas on the command line, not spaces.  For example, if
  269.        you want to time stamp all *.ARJ and *.LZH files and one specific ZIP
  270.        file called "XYZ.ZIP", you would execute the following:
  271.  
  272.             TrueDate *.ARJ, *.LZH, XYZ.ZIP
  273.  
  274.        Full paths can also be specified such as:
  275.  
  276.             TrueDate f:\max\files\os2\newup\*.*
  277.  
  278.        Configuration File Options
  279.  
  280.        TrueDate's behavior can be changed by modifying the configuration file
  281.        included with TrueDate (TRUEDATE.CFG).  This is a text file and can be
  282.        edited using any text editor which saves a file in text (ASCII)
  283.        format.
  284.  
  285.        Each option is fully documented in TRUEDATE.CFG itself.
  286.        Using TrueDate for Sysops
  287.  
  288.        I invoke TrueDate each time I detect *.TIC files in my inbound
  289.        directory.  The following is an OS/2 REXX procedure I use:
  290.  
  291.             isfile "c:\binkley\inbound\*.tic"
  292.  
  293.             if ( rc <= 0 ) then
  294.                 return              /* No *.TIC files received */
  295.  
  296.             call bbslog "Tick", "Initiating TICK Processing"
  297.  
  298.             /*
  299.              * Set the archive dates to the "True" archive date.
  300.              */
  301.  
  302.             truedate "c:\binkley\inbound\* /Quiet"
  303.  
  304.  
  305.  
  306.        TrueDate Users Manual                                          Page 10
  307.        ----------------------------------------------------------------------
  308.  
  309.             /*
  310.              * Now call TICK to do the actual distribution
  311.              */
  312.  
  313.             "c:"
  314.  
  315.             cd "\bbs\tick"
  316.  
  317.             TICP ">> c:\bbs\logs\tick.log"
  318.  
  319.             .... [and so on.]
  320.  
  321.        If there are *.TIC files found in the inbound directory, I run
  322.        TrueDate BEFORE I run Tick.  After TrueDate has reset the dates on any
  323.        archives found within the inbound directory, I run Tick and any other
  324.        appropriate post-Tick processing.
  325.  
  326.        Also, after I wrote TrueDate, I ran the program on every directory of
  327.        downloadable files.  Thus, every archive on the system now reflected
  328.        an accurate, true date of the archive.  This is not only helpful to
  329.        you, the Sysop, but also to your users calling in.  They also will now
  330.        know the true "age" of an archive without having to look inside the
  331.        archive itself.
  332.  
  333.  
  334.  
  335.        TrueDate Users Manual                                          Page 11
  336.        ----------------------------------------------------------------------
  337.  
  338.        :Maximus - Last Write Date vs. Creation Date
  339.  
  340.        Since Maximus was originally written under DOS, support for the
  341.        multiple dates associated with a file under OS/2 is minimal.  Searches
  342.        for "new" files by users on the BBS becomes a problem.  How do you
  343.        define "new?"  What date do you display (the "last write" date or
  344.        "creation" date) when it is found?  Under Maximus 2.00, this is
  345.        controlled by the program FB.EXE (the Filebase Build command).
  346.  
  347.        There are two version of FB.EXE which are important to note since they
  348.        handle the dates of files differently.
  349.  
  350.        FB.EXE bundled with Maximus 2.00:
  351.  
  352.             The version of FB which comes with the initial release will
  353.             build a database of all downloadable file sections using the
  354.             "creation" date of the file.  Thus, any file searches based on
  355.             date (especially using the "NewFiles" MECCA token) will search
  356.             for files based on the "creation" date and display this date
  357.             to the caller.
  358.  
  359.        FB.EXE bundled with Maximus 2.01/wb:
  360.  
  361.             This version of FB which comes bundled in the 2.01/wide beta
  362.             version of Maximus will build a database of all downloadable
  363.             file sections using the "last write" date of the file.  Thus,
  364.             any file searches based on date will search for files based on
  365.             the "last write" dat and display this date to the caller.
  366.  
  367.        The change in the wide beta version has caused quite a bit of
  368.        consternation among OS/2 Maximus Sysops.  In order to announce new
  369.        file arrivals, the Sysop must actually change the "last write" date of
  370.        the archive to the CURRENT date it was received on the system.  Many
  371.        systems use a Unix-like Touch program to accomplish this.
  372.        Unfortunately, the true date of that archive is now lost, and actually
  373.        misrepresents that actual age of the archive.
  374.  
  375.        In my opinion, setting the "last write" date to the date the archive
  376.        was received on a particular BBS clouds the issue of the true age of
  377.        an archive for both Sysops and users alike.
  378.  
  379.        The more appropriate way of dealing with this is to set the "last
  380.        write" date to the true date of the archive and display this date to
  381.        users when the scan for new files.  However, the scan itself should be
  382.        based on the CREATION DATE of the archive.  Thus, users will quickly
  383.        identify new files that have arrived on the BBS system, but will be
  384.        presented with the "true age" of the archive when it is displayed to
  385.        them.
  386.  
  387.        Currently, OS/2 Maximus sysops can only partially achieve this
  388.        behavior.  If you are running Maximus 2.01/wb, then you will have to
  389.        acquire FB.EXE version 2.00.  (This is available from my system as
  390.        FB200.ZIP.)  This version of FB will create a database using the
  391.        "creation" date of the file.  However, it also displays this date to
  392.  
  393.  
  394.  
  395.        TrueDate Users Manual                                          Page 12
  396.        ----------------------------------------------------------------------
  397.  
  398.        the user on file title/list displays.  Thus, while the true date of
  399.        the archive can be maintained in the "last write" date of the file,
  400.        users will still be somewhat mislead by the date they see in the
  401.        display list.
  402.  
  403.        HOWEVER, if you use Downsort to create your downloadable file lists,
  404.        the correct dates are used.  Downsort marks new files with an asterisk
  405.        and/or plus sign depending upon age.  Downsort uses the "creation"
  406.        date to do this.  However, the dates actually printed in the list is
  407.        the "last write" date.  Thus the actual age of the archive is
  408.        correctly represented.
  409.  
  410.        Therefore, I encourage Maximus Sysops to leave the "last write" date
  411.        intact, and use the "creation" date to indicate arrival/"newness" of
  412.        an archive on your system.