Zodiac Super OZ/MEDIADEPOT.ISO/FILES/16/FREEDOS.ZIP/FD_A4PRE.ZIP/HELP/TOUCH

Text File | 1995-06-28 | 9KB | 212 lines

    Program usage documentation for the Free-DOS TOUCH program

    (c) Copyright 1995 by K. Heidenstrom.

    Modified:

    KH.19950605.001  (TOUCH 1.4.0)    First version

1.  LEGAL

    This program is Copyright 1989-1995 by K. Heidenstrom.    The author
    may be reached at [e-mail] on the Internet or by snail
    mail: K. Heidenstrom c/- P.O. Box 27-103, Wellington, New Zealand.

    This program is free software.    You may redistribute the source and
    executable and/or modify the program under the terms of the GNU
    General Public License as published by the Free Software Foundation;
    either version 2 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but is provided "as-is", without any warranty of any kind, including
    the implied warranty of merchantability or fitness for a particular
    purpose.  In no event will the author be liable for any damages of
    any kind related to the use of this program.  See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

2.  FUNCTION AND USAGE SYNTAX

    The TOUCH program modifies the date and/or time of files on disk.
    TOUCH is originally from the Unix operating system, and there are
    many other DOS ports of this utility.  This implementation has the
    following features.

    TOUCH allows the date, time, or both date and time of the file to be
    modified.  TOUCH can set the date and time to the current date and
    time, or to any date and time specified by the user.  The date and time
    can also be set to zero, which causes the values to be displayed as
    blank in the directory listing under some versions of DOS.

    TOUCH can also scan the file for a textual version string and set the
    file time according to the value of the string.  I find this useful as
    the version number of the program can be seen at a glance from the
    directory listing.  I first noticed this convention of setting the file
    time according to the version number on PKWARE products, and it has
    been adopted by many software companies.

    The program usage syntax is:

    TOUCH [-?] [-C] [-F] [Date] [Time] Pathspec [...]

    Parameters may be specified in any order.  More than one Date is not
    allowed.  More than one Time is also not allowed.  The 'Pathspec' may
    be repeated as needed.    Each Pathspec specifies a file or group of
    files to be touched, and may contain an initial drive specification,
    a directory path specification, and/or a file specification, and may
    specify a group of files (using the '?' and '*' wildcard characters)
    or a single file (an unambiguous specification).

    If a directory is specified, with no file specification, the default
    file mask of '*.*' is appended.  This can also be forced by specifying
    a trailing backslash.

    All parameters are case-insensitive.  Switches may begin with '-' or
    with the currently active DOS switch character (switchar) which is
    normally '/'.  TOUCH does not support the forward slash as a directory
    separator character, regardless of the setting of the switchar.  The -C
    and -F option switches may be run together into -CF or -FC.

    If no parameters are specified, or the -? parameter is specified, or if
    an illegal number is specified, the program issues a usage summary
    message and terminates, returning errorlevel 255.

2.1.  DATE PARAMETER

    The Date and Time parameters are distinguished from Pathspecs according
    to the characters they contain.  A date must be formatted as:

        nn-nn-nn

    where each 'nn' is a one or more digit number, and the '-' character
    may alternatively be a '/' or the date separator character provided
    by DOS according to the country number specified in your CONFIG.SYS
    file.  Usually this will be a '-' though it may be a '.' in Japan.
    Whatever the two date separator characters are, they must be the same.

    The order in which the numbers are interpreted depends on the country
    number.  There are three standard date orders:

        mm-dd-yy    (American)
        dd-mm-yy    (European)
        yy.mm.dd    (Japanese)

    The year may be specified in full (e.g. 1995) in which case it must be
    in the range 1980 to 2099 inclusive.  It may be specified in shorthand
    form as two digits in the range 80 to 99, in which case it is assumed
    to be 19xx where xx are the two digits supplied, or as two digits in
    the range 00 to 79, in which case it is assumed to be 20xx where xx are
    the two digits supplied.

    A date value of 0-0-0 may be specified.  With some versions of DOS
    (3.30, I believe, and possibly others), this will result in the date
    column in the directory listing being blank.

2.2.  TIME PARAMETER

    A time parameter must be formatted as:

        hh:mm[:ss]

    where each value is a one or more digit number.  The second colon and
    the 'ss' value are optional.  If they are not given, a seconds value
    of zero will be used.

    A time value of 0:0 may be specified.  With some versions of DOS (as
    noted earlier), this will result in the time column in the directory
    listing being blank.

2.3.  TOUCH DATE AND TIME SETTING BEHAVIOUR

    If date and time values are both present, each file will be touched to
    that date and time.  If only one value is present, each file will be
    touched to that value but the other will be unchanged; in other words,
    if only a date is specified, each file will have its date set to the
    specified date but its time will be unchanged, or if only a time is
    specified, each file will have its time set to the specified time but
    its date will be unchanged.  For files created by TOUCH, values that
    are not specified will be the current value at the date and time when
    TOUCH was started.

    If neither date nor time are specified, the current date and time are
    used (unless the -F switch is present).  TOUCH reads the current date
    and time once when it starts up, so regardless of how many files are
    touched, they will all be touched to the same date and time.

2.4.  THE -C OPTION

    TOUCH will (by default) create files specified unambiguously (i.e.
    named explicitly, without wildcards) if they don't already exist.
    This is apparently the behaviour of the Unix 'touch', though it is
    not usual in DOS implementations.  This feature can be overridden
    by the -C command line switch, which tells TOUCH not to create the
    specified file if it does not already exist.

    For example, the command TOUCH NOSUCH.FIL (if NOSUCH.FIL does not
    already exist), will create an empty (zero bytes long) file called
    NOSUCH.FIL.  The command TOUCH -C NOSUCH.FIL will report an error
    and will not create the file.

2.5.  THE -F OPTION

    The -F option specifies touching the file(s) according to the version
    strings within each file.  If this option is specified, the Date and
    Time parameters must not be specified.    TOUCH will scan the contents
    of each file for a string indicating the file's version number.  It
    scans only the first 48K (approximately) of the file.  The version
    string is taken in two parts - the 'version' string, and the version
    number.  The 'version' string is matched using a case-insensitive
    comparison.  Recognised strings are:

        "version "
        "vers "
        "vers. "
        "ver "
        "ver. "
        "v "
        "v."
        "v"

    Immediately following the 'version' string is the version number, which
    may be in any of the following forms (where 'x', 'y', and 'z' are
    single digits):

        "x"
        "x.y"
        "x.yz"
        "x.y.z"

    The 'x' and 'z' values must both be in the range 0 to 9.  The 'y' value
    must be in the range 0 to 5.

    The file will be touched with a time value created from the values
    given, so that the time stamp indicates the version number.  For
    example, if the ; version number in the file is 2.12, it will be
    touched to 2:12 a.m.  Its date will be unchanged.

    If TOUCH cannot locate a version string in the file, it will issue an
    error message, leave the file date and time unmodified, and continue
    processing.

    If the file was created by TOUCH (i.e. the file specified was an
    unambiguous pathname that did not already exist), TOUCH will not scan
    the file for a version string if -F is specified; TOUCH will just touch
    the file with the current date and time.  No error message is issued.

2.6.  ERRORLEVELS

    TOUCH always reports an errorlevel when it terminates.    This may be
    useful when TOUCH is used within batch files.  A message will be also
    issued if an error occurs.  The errorlevels that may be returned by
    TOUCH are as follows:

    0    Normal completion; no errors
    2    One or more errors occurred during processing
    162    Insufficient memory (approx. 64K of memory is required)
    255    Incorrect usage syntax

                   ----//----