

                              THE PROGRAM  

This file TOUCH.DOC covers TOUCH.COM v1.08d, dated 2003-10-05, by Charles
Dye.  At present, I can be reached as raster@highfiber.com.

This program and documentation file are Copyright 1996-2003, Charles Dye.
They are freeware, distributed under the GNU General Public License.  Please
read the section "Distribution", below, for information.


                             THE BASIC IDEA  

Use TOUCH to change the date-and-time stamps for files.  Usually the only
reasons to do this are cosmetic:  to give a directory listing a 'clean'
appearance, or to use a file's time stamp to indicate its revision.

Here's an example.  Suppose I wanted to change the time stamp of MYFILE.TXT
to 2:01, perhaps to indicate that it's version 2.01 of something:

C:\STUFF> touch myfile.txt /t:2:01

C:\STUFF\
  myfile.txt    Mon  9-02-1996   6:33:22 pm  -->  Mon  9-02-1996   2:01:00 am

Files found: 1, touched: 1 in C:\STUFF\

Total found: 1, touched: 1

TOUCH has found and changed one file, named MYFILE.TXT.  The information
before the --> arrow indicates the file's date and time stamps and attributes
before TOUCH modified it; the info after the arrow shows that the time stamp
has been changed to 2:01 a.m.  (The date was not changed.)

               
                             PROGRAM SYNTAX 

TOUCH [filespecs] [options]

You should always separate filespecs and options with spaces.  TOUCH allows
the use of either slashes or minus signs as option characters.  Both slashes
and minus signs are legal characters within filespecs, too!  (Slashes within
a filename are converted to backslashes for the benefit of Unix folks.)

You may have zero or more filespecs.  If you do not specify any filespecs,
TOUCH will supply a default of *.* -- all files in the current directory.

You may have zero or more options.  If you don't specify any options, TOUCH
will not change any files; it will act like a DIR command, just displaying
information about files.

It's a very good idea, though not absolutely required, to always type the
filespecs before the options on the command line.  TOUCH /D *.TXT /T *.DOC
and TOUCH *.TXT *.DOC /D /T both do the exact same thing; but the second
is easier to read, and makes it clear that the same operation is being
performed on .TXT files and .DOC files.

It's also a very good idea to always put a space after every parameter on the
command line!  Otherwise, what you intended as an option might be interpreted
as part of a filename, or vice versa.  TOUCH \DOS /T will change the time
stamp of all files in the DOS directory, but TOUCH \DOS/T will list all files
named T.* in the DOS directory!  The space makes the difference.
                           
                           
                             THE FILESPECS  

A filespec never begins with a slash or minus sign.  If it did, it would be
interpreted as an option.

A filespec may be a simple filename:  LETTER.TXT (since no drive or directory
is specified, LETTER.TXT is assumed to be in the current directory.)

A filespec may contain wildcards:  *.TXT (all .TXT files in the current
directory.)

If a filespec does not have an extension, TOUCH will automatically append a
.*   For example, TOUCH MYFILE will find MYFILE, MYFILE.TXT, and MYFILE.EXE.
If you only want to touch files with no extension, add a period after the
filename.  For instance, TOUCH MYFILE. will match MYFILE, but not MYFILE.TXT
or MYFILE.EXE.

A filespec may contain a drive or directory name:  C:\DOS\*.COM (will match
all .COM files in the C:\DOS directory.)

A filespec may be a directory name:  C:\WINDOWS or C:\WINDOWS\ (either way,
will match all files in the C:\WINDOWS directory.)  The DOS shortcut
directory names . and .. are also supported.

The filespec may simply be a drive letter:  D: (will match all files in the
current directory on drive D:.)

A filespec will not normally contain spaces.  If you type TOUCH FOO BAR,
TOUCH will look for a files matching FOO.* and files matching BAR.* in the
current directory.  In other words, a space usually ends a filespec.

You may use double quotes around a filespec to "trap" troublesome characters.
For example, TOUCH "-D" /T to change the time stamp of a file named "-D"
(with a leading minus sign), or TOUCH "FOO BAR" to find a file named
"FOO BAR" (with an embedded space.)

The filespec may name an DR DOS-style file list.  TOUCH @OUTPUT will open
the file named OUTPUT and use it as a file list.  OUTPUT is assumed to be a
text file containing valid DOS filespecs, one per line.  You can create a
file list using any text editor.  You can also use the MS-DOS 5+ DIR /B
command, redirecting its output into a file list; or you can create a file
list using many file-finder programs, like Keith Ledbetter's SST or my own
LOCATE.

Filespecs read from a file list are treated almost exactly like filespecs
read from the command line.  They may be enclosed in quote marks, may contain
wildcards, may name drives or directories, and so forth.  There are two
differences:  names read from a file list do not receive the automatic
extension of .* , and names read from a file list may not open another file
list.  File lists may not be nested.

A file list may also contain comment lines beginning with a semicolon or
colon.  Lines beginning with a semicolon are "remarks" and will be ignored.
Lines beginning with a colon are "notices" which TOUCH will print to the
screen.  Remarks and notices are not standard file-list syntax, but
extensions which I have added.  Don't use either one if you want your file
list to be compatible with the DR DOS utilities.

Examples of using double quotes with file list names:  TOUCH "@OUTPUT" /T
will change the time stamp of a file named "@OUTPUT" (with a leading at-
sign.)  TOUCH @"OUTPUT" /T will instead open the file named OUTPUT and read
filespecs from it, changing the time stamp of each file named.
TOUCH @"FOO BAR" will open the file named "FOO BAR" (with an embedded space),
and use it as a file list.


                              THE OPTIONS  

An option always begins with either a slash or a minus sign.  The option
letter is not case sensitive:  /D -D /d -d all work alike.


/D     Change Date stamps.  This is one of two options which can be used to
       modify files' date stamps; the other one is /C.  If you do not use
       either /D or /C on the command line, TOUCH will not alter any date
stamps.  /D can be used in one of three ways.  With no argument, /D will
set all date stamps to today's date.  With a colon and a date, /D:date will
change all date stamps to that specific date.  Finally, /D:N will mark all
files with the 'null' date stamp.

The format in which you specify the date varies according to the COUNTRY=
setting in your CONFIG.SYS file.  In the United States, a date is MM/DD/YYYY.
In Europe, it will usually be DD/MM/YYYY, and in Japan YYYY/MM/DD.  You can
use /F to override the COUNTRY= default.

If you do not specify a year, the current year will be used.  You may
separate the month, day and year with slashes, minus signs, or periods.

TOUCH *.DOC /D                         Set all .DOC files to today's date.

TOUCH FINNEGAN. /D:5-23-98             Change file FINNEGAN to May 23, 1998.
                                       (But not FINNEGAN.LTR, etcetera)

TOUCH /D:1/1                           Change all files in the current
                                       directory to January 1 of this year.

TOUCH FUNNY.TXT /D:N                   Give FUNNY.TXT the null date stamp.

The null date stamp is a little-known peculiarity of DOS.  Files marked this
way will have no date or time shown in a DIR listing.  You can get the same
effect using /D:0-0-1980 /W.


/T     Change Time stamps.  This is one of two options which can be used to
       modify files' time stamps; the other one is /C.  If you do not use
       either /T or /C on the command line, TOUCH will not alter any time
stamps.  /T can be used in one of two ways.  With no argument, /T will set
all time stamps to the current time.  With a colon and a time, /T:time will
change all time stamps to that specific time.

You may use either 12-hour or 24-hour notation for the time.  If you specify
an hour between 1 and 12, you may use an AM or PM suffix to modify the hour.
(If the hour is zero or greater than 12, the AM or PM cannot modify the time
and will be interpreted as a filespec instead -- probably not what you
intended!)  The minutes and seconds values are optional; if you don't specify
them, they will default to zero.  You may separate the hour, minute and
second with colons, periods, or commas.

TOUCH A:*.WP /T                        Set all .WP files in the current
                                       directory on drive A: to the current
                                       time.

TOUCH TOUCH /D /T:1:06                 Sets all files TOUCH.* to today's
                                       date, with a time of 1:06 A.M.


/C=template     Copy time and date stamps from a "template" file.  This is
                the only option other than /T and /D which will modify date
                or time stamps.  If you don't use /D /T or /C, no date or
                time stamps will be changed.  /C has three variants:  /CD
will copy only the date stamp from a template file, /CT will copy only the
time stamp, and /CA will copy the attributes from a template file.

TOUCH *.WPT /C=FIRST.WPT               Change all .WPT files to the date and
                                       time stamp from FIRST.WPT.

TOUCH *.DOC /CD=VORTEX                 Give all .DOC files the date stamp 
                                       from VORTEX; leave times unchanged.

TOUCH *.DOC /CD=VORTEX /T:13           Give all .DOC files the date stamp
                                       from VORTEX and a time of 1 P.M.

TOUCH *.DOC /CT=C:\TEMP\FOO.DOC /D     Give all .DOC files the time stamp
                                       from C:\TEMP\FOO.DOC and today's date.

TOUCH *.PIF /CD=DT /CT=TT /CA=AT       Copy date stamp from one file, time
                                       from another, attributes from a third.

You may combine /CD with /T, /CT with /D, or /CD with /CT, but /C may not be
combined with any of /CD /CT /D /T.  /CA may not be combined with /A.

Template filenames may also contain wildcards or name subdirectories.  If the
template name contains wildcards, the first matching file (not subdirectory!)
will be used.  If the template name exactly matches a subdirectory with no
wildcards, the date and/or time stamps or attributes from the subdirectory
entry will be used.  Wildcarding is by the usual DOS rules; there is no
implied .* extension.


/S     Find and touch files in Subdirectories.  This is a powerful and
       potentially dangerous feature; it turns TOUCH into a small but potent
       file-finder.  If you use /S, TOUCH will search for files matching the
filespec in subdirectories.  /S even applies to filespecs read in from a file
list!  Use caution when combining /S with file lists.

TOUCH *.DOC /T /S                      Finds all .DOC files in the current
                                       directory or below, and changes their
                                       time stamps to the current time

TOUCH C:\*.8 /S                        Finds all files with the extension .8
                                       on the C: drive, anywhere!

TOUCH D:\ /C:C:\AUTOEXEC.BAT           Stamps all files in the root directory
                                       of drive D: with date and time from
                                       C:\AUTOEXEC.BAT

TOUCH D:\ /C:C:\AUTOEXEC.BAT /S        Stamps ALL files on drive D: ANYWHERE
                                       with the date and time from
                                       C:\AUTOEXEC.BAT

TOUCH /S @LISTFILE /T /D               If LISTFILE contains only two lines, 
                                       "D:\*.TXT" and "C:\DOS", TOUCH will
          stamp all .TXT files on drive D:, and all files in the \DOS
          directory (or below) on drive C:, with the current date and time.

TOUCH /S will even find files which many shareware file-finder programs miss.
Hidden or System files, files inside Hidden or System directories, and files
in subdirectories with extensions will all be correctly located.


/A:change     Change file Attributes.  Use a plus sign followed by attribute
              letters to set attributes, or a minus sign to clear them.  You
              may not use spaces in the change string.

TOUCH C:\JUNK\*.TXT /A:-A /T           Find all .TXT files in the C:\JUNK
                                       directory; clear their "Archive
          needed" attributes and set their time stamps to the current time.

TOUCH C:\*.DB /S /T:5:00P /A:+R-SH     Find all .DB files on drive C:,
                                       anywhere.  Set their time stamps to
          five P.M., make them Read-only, and clear their System and Hidden
          attributes.

Note that /A is the only option other than /D /T and /C which can make any
change to files.  If you do not use /D /T /C or /A, TOUCH will not change
anything.


/P     Prompt user.  This gives you the opportunity to decide, on a file-by-
/Q     file basis, whether or not to allow TOUCH to do its thing.  For each
       file that TOUCH finds, you will be given a prompt like this:
       [Yes No All Quit]    Press Y to allow TOUCH to change the file.  Press
N to prevent TOUCH from changing the file.  Press A, and TOUCH will change
this and all subsequent files without prompting you again.  Press Q, and
TOUCH will abort without changing the current file.  (/Q is a synonym for /P;
it stands for Query.)

If you do not specify any options which would cause changes to be made, then
/P will have no effect and will be ignored.


/F:x     Set date Format.  Use /F:x in combination with /D:date to specify
         the way the date is arranged.  This might be useful in batch files
         which need to work the same way in different countries.

/F:U selects United States format:  MM/DD/YYYY or just MM/DD.
/F:E selects European date format:  DD/MM/YYYY or just DD/MM.
/F:J selects Japanese date format:  YYYY/MM/DD or just MM/DD.
/F:I selects the ISO date  format:  YYYY-MM-DD or just MM-DD.

This option affects the way dates are displayed, and the way that user-
specified dates in /D are interpreted.  /F:I also causes dates to be shown
using dashes and times to be displayed in 24-hour format, regardless of the
local date and time format.  (/F:U /F:E and /F:J do not affect the date
separator or time format.)


/W     Permit Weird values in date and time stamps.  Normally, TOUCH only
       allows reasonable values.  If you use /W, you may specify any value
       that will fit in the number of bits assigned by DOS.

  Value   Normal range  /W weird range  Notes:
  ------  ------------  --------------  ----------------------------------
  Year    1980 to 2099  1980 to 2107    2-digit years 00-99 are accepted
  Month      1 to 12       0 to 15
  Day        1 to n        0 to 31      n varies by month, 28 to 31
  Hour       0 to 23       0 to 31
  Minute     0 to 59       0 to 63
  Second     0 to 59       0 to 63      Truncated to an even value by DOS

Needless to say, this option has no normal use.  It might be useful for
simulating the effects of certain viruses which mark infected files with
illegal time stamps.


/M     Controls paging.  Use /M to cause TOUCH to pause after each screen, or
       /M:x to cause TOUCH to pause every x lines.  X is between 0 and 255;
       a value of 0 will disable paging (the default behavior.)  /M has no
effect if /P is used, or if the output from TOUCH is redirected into a file.
You can remember /M as standing for More.

If you do not use /M or redirect output, it is possible to pause a scrolling
display by holding down the Alt key.


/E     Disable the automatic .* extension.  Might be useful for forcing TOUCH
       to behave more like many common DOS utilities.


/H     Do not hook INT 24, the critical-error handler.


/R     Do-nothing option.  Ignored.


               DIFFERENCES FROM THE DR DOS TOUCH COMMAND  

I have deliberately tried to keep the syntax for my TOUCH similar to the
DR DOS TOUCH command.  However, there are some major differences in
operation which you should know about if you're familiar with the DR DOS
command.

DR DOS TOUCH will, by default, change date and time stamps to the current
date and time.  There is no way to make it change only time stamps, or only
date stamps.  My TOUCH will not change either time or date stamps unless you
tell it to.  (In other words, my TOUCH with no options acts like a glorified
DIR command.)  If you only tell it to change time stamps, it will not change
date stamps, and vice versa.

DR DOS TOUCH will not accept directory names.  It must be passed at least
one filename, or it will abort with an error message.  My TOUCH, by contrast,
will accept directory names, and will touch all files in the specified
directories.  (It will never touch the subdirectories themselves; neither
will the DR DOS command.)  If you do not specify a filespec, my TOUCH will
default to *.* (all files in the current directory.)

My TOUCH adds a default extension of .* if the filespec has no extension.
DR DOS TOUCH does not do this.  I provide an option /E to disable this
behavior.

DR DOS TOUCH will not touch Read-only files, unless you pass it the /R
option.  My TOUCH will change files regardless of their attributes.  (/R is
accepted as a legal option, but does nothing.)

The "remark" and "notice" lines supported by my TOUCH are not standard.  No
DR DOS utility will handle them correctly.  Also, my TOUCH permits more than
one filename per line in a file list, separated by spaces or tabs.  This is
nonstandard, and I can't think of any good reason to format a file list this
way!  Just a useless feature / side effect of the way I implemented it.


                            WHY THE CHANGES?  

There are two reasons for requiring an option to make any change.  First of
all, it lets you preview the operation to see exactly which files would be
affected before actually making the changes.  Type your TOUCH command line
without any /D /T /C or /A and see which files TOUCH lists.  If you are
satisfied that TOUCH is interpreting your command line as you intended, hit
F3 to recall the last command, then type a space and append your options.
Second, this method avoids nasty circumlocutions like /T:NOCHANGE or
/D:OLD_DATE -- complicated syntax to do nothing bothers me.

Why do I allow directory names?  Because it's faster to type TOUCH \UPLOAD
than TOUCH \UPLOAD\*.*.

Why do I provide the automatic .* extension?  Files with the same base name
probably are related and should be treated as a group.  This way, I can type
TOUCH VORTEX /D and get the same result as TOUCH VORTEX.* /D, only without
having to type that awkward asterisk.

Why doesn't the automatic .* extension apply to filespecs from a file list?
File lists are often created by redirecting the output from DIR (or XDIR, or
a file finder) into a file.  But filenames without extensions are usually
printed without a trailing period, so adding the .* would probably be a
serious misinterpretation of what was intended.


                              WHAT'S NEW?  

In 1.08d:             2003-10-05   6,191 bytes   CRC32: B88CF8C1   XDIR: EA17

If a user-specified date has three numbers and the first is 1980 or greater,
assumes the date is in ISO format regardless of locale settings.  Also, /F:I
now sets the date separator to a dash and forces time stamps to be displayed
in 24-hour format.  (The formerly identical /F:J does not affect the date
separator or time format; nor do /F:U or /F:E.)  Tweaks to syntax messages.

In 1.08c:             2001-01-01   6,106 bytes   CRC32: 65B78941   XDIR: 7B29

Trivial change:  /C /CD /CT /CA now permit a comma instead of the equals
sign.  This is to allow for changes to filename completion in the latest
version of 4DOS.

In 1.08b:             2000-04-24   6,107 bytes   CRC32: 37534B1B   XDIR: 543B

Expanded the filespec buffers to 260 bytes to handle the super-long pathnames
permitted under Windows 95/98.

In 1.08a:             1999-12-30   6,110 bytes   CRC32: 75C0CF45   XDIR: EA34

Removed a minor (undocumented) feature which would sometimes cause a spurious
syntax error message.

In 1.08:              1999-10-04   6,116 bytes   CRC32: D8A8C220   XDIR: CF58

I have changed the license to GPL and ported the code to NASM.  Added
options /? /D? /T? /C? /A? /F? /M? which display syntax help to standard
output instead of standard error -- you can redirect the help messages to a
file.  Added /F:I as a synonym for /J (ISO date format.)  Inline error
handler and other size optimizations.  Added a check for character device
names -- clock$, nul, con, prn, and so on.  Leading zeroes are no longer
suppressed in 24-hour times.  Finally, I am now compressing the executable
using UPX.


                              ERRORLEVELS  

        00   Normal exit
        16   General syntax error, or buffer overflow
        17   Not enough memory
        18   Problem with template file
        19   Problem with list file
        20   Internal overflow of working buffer
        21   Error resolving directory name (too many dots?)
        22   Tree buffer overflow (directory structure too complex)
        23   Bad DOS version (DOS 3.0 or better required)


                             SUNDRY CREDITS  

This program is created with NASM, the Netwide Assembler, a freely available
80x86 assembler.  NASM's home page is:  http://nasm.sourceforge.net/

I compress the executable using UPX.  The UPX home page is:
http://upx.sourceforge.net/

The code was originally written for Eric Isaacson's shareware assembler A86.

MS-DOS is a trademark of Microsoft Corporation.  PC DOS is a trademark of
IBM.  DR DOS is a copyrighted product owned, at various times, by Digital
Research, Novell, Caldera, and DeviceLogics, under an assortment of names.


                              DISTRIBUTION  

This program is copyrighted, but may be freely distributed under the terms of
the Free Software Foundation's GNU General Public License v2 (or later, at
your option.)  See the file COPYING for the legalities.  If you did not
receive a copy of COPYING with this program, you may request one from the
Free Software Foundation, Inc. at:

        59 Temple Place - Suite 330
        Boston, MA  02111-1307, USA.

NO WARRANTY:  Like all things free, you get no warranty for TOUCH.  I
believe it to work substantially as documented here, and have made reasonable
efforts to test it in a variety of different situations.  However, I cannot
and will not be responsible for any unforseen consequences.  Use At Your Own
Risk.  (You're welcome to send me bug reports, of course.)

