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 KH.19950716.002 (TOUCH 1.4.1) Added -Dpathname command KH.19950722.003 (TOUCH 1.4.2) Bug fixed KH.19951005.004 (TOUCH 1.4.3) CREATE conditional, am/pm suffix 1. LEGAL This program is Copyright 1989-1995 by K. Heidenstrom. The author may be reached at kheidens@actrix.gen.nz 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 copy the date and time from one file to one or more other files. 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] [-Dpathname] [-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. If the -Dpathname option is used, no Date or Time may be specified, and vice versa. 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, -Dpathname, and -F option switches may be combined (e.g. -CF) but the -Dpathname switch, if combined in this way, must be the last, to ensure that the command is unambiguous. 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][a|p] 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. The 'a' and 'p' suffixes (a.m and p.m) are optional, and if neither is used, TOUCH will assume that the time is being specified in 24-hour format. 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. THE -DPATHNAME OPTION This option tells TOUCH to get the date and time values from the file specified by 'pathname'. If the file does not exist, TOUCH will exit with an error message. If the file does exist, TOUCH will request its date and time, and use this date and time to set the date and time of the other files specified in the command. 2.4. TOUCH DATE AND TIME SETTING BEHAVIOUR If the -Dpathname option is used, each file will be touched to the date and time of the specified file. 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.5. 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. I believe this is also standard in Unix implementations. 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. If you don't like this behaviour, and would rather TOUCH defaulted to not creating files that don't exist, and you have TASM and a linker, you can edit the source file, change the CREATE equate to 0 and reassemble the program. The usage message is conditional on the CREATE equate and will reflect the change. 2.6. 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 " "ver. " "vers " "v " "vers. " "v." "ver " "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.7. 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 48 Error during processing of -Dpathname option 162 Insufficient memory (approx. 64K of memory is required) 255 Incorrect usage syntax 3. EXAMPLES There aren't many examples I can suggest, but here is a useful batch file that uses the -Dpathname feature of TOUCH. Recently I archived a lot of old ZIP archive files and wanted to add archive comments to them. Adding a comment to a ZIP file causes the ZIP file's date and time to be updated to the current date and time, and I wanted to retain the original date and time of the ZIP file. The following batch file called ZIPC.BAT does this. @ECHO OFF REM REM Add a comment to a ZIP file without modifying date and time REM IF NOT .%1 == . GOTO Cont1 ECHO Usage: ZIPC Zipfilename ECHO. ECHO Note: Give the full pathname of the ZIPfile ECHO Note: The .ZIP extension is optional ECHO. GOTO Exit :Cont1 IF EXIST %1 GOTO Cont2 IF EXIST %1.ZIP GOTO Cont3 ECHO Archive file %1 or %1.ZIP does not exist GOTO Exit :Cont2 TOUCH -D%1 %TMP%\$ZIPC$.$$$ PKZIP -z %1 TOUCH -D%TMP%\$ZIPC$.$$$ %1 DEL %TMP%\$ZIPC$.$$$ GOTO Exit :Cont3 TOUCH -D%1.ZIP %TMP%\$ZIPC$.$$$ PKZIP -z %1 TOUCH -D%TMP%\$ZIPC$.$$$ %1.ZIP DEL %TMP%\$ZIPC$.$$$ :Exit This batch file assumes that the TMP environment variable is set to the drive specifier of a RAM drive or the pathname of a temporary directory, for example "E:" or "C:\MISC\TMP". It creates a temporary file in that location, called $ZIPC$.$$$, that is set to the date and time of the ZIP file before the comment update is done. It then restores the ZIP file date and time from the temporary file, and deletes the temporary file. The same technique can be used to preserve date and time information when converting a file from one format to another, for example when re-ZIPping an old ZIP file created with PKZIP version 1, or when converting an archive, picture, or data file from one format to another. 4. BUGS Versions 1.4.0 and 1.4.1 had a bug which caused them to try to touch directories, including the '.' and '..' directory entries (sometimes called "fules"). Version 1.4.2 fixes this problem. ----//----