NEW.DOC

Scott R. Houck

6/9/90


NEW (version 2.7) is a utility that locates "new" files, that is,
files created as of a certain number of days ago. It can also find
"old" files if the number of days is a negative number. It can search
the entire disk (or disks) if desired and can accept wildcards.

The syntax is: NEW [filespec(s)] [options]

If filespec is omitted, *.* is assumed. Also, a "day" in this program
starts at 6:00 am and ends at 5:59 am the following day. Options and
filespecs can be in any order. Valid options are:

/n Show files SINCE the number of "days" specified by n
/-n Show files BEFORE the number of "days" specified by n
/A Include ALL files, regardless of timestamp
/C cmd Invoke command "cmd" for each file found.
/D Include directories in listing
/DO Include directories ONLY in listing
/E Search entire disk
/Fn Use format n (default is n = 1)
/G Guru mode -- use simple prompt when pausing (/P)
/H or /? Show help screen
/I Ignore the environment variable NEW if it is defined
/J Junk option -- include files with corrupted dates
/Kn Use output option n (0-3) if /C or /V is used
/NP Force No Pause
/NQ Force No Quiet mode on /C or /V
/O... Sort order /O{U|N|E|D|S}[-] (Default = /OD-)
/P Pause when screen display is full
/Q Quiet mode -- don't ask for confirmation on /C or /V
/S Search specified directory and its subdirectories
/[-]T... Use a specific timestamp
/V [batfile] Invoke Polytron VCS PUT for each file found
/X Suppress opening


Details on /n
-------------

Besides just specifying a simple number of "days" ago (6 am to
5:59 am), time periods may also be specified as follows:

/[n1D][n2H][n3M][n4S] means show files as of n1 days, n2 hours,
n3 minutes, and/or n4 seconds ago
Examples:

/3h = as of 3 hours ago
/3h30m = as of 3 hours and 30 minutes ago
/5d5s = as of 5 days and 5 seconds ago
/10d10h10m10s = as of 10 days, 10 hrs, 10 mins, and 10 secs ago

NOTE: /3d is NOT equivalent to /3 since /3 takes into account
the 6:00 am start time for a "day." /3d means EXACTLY
3 days ago from the current time.


Details on /T
-------------

Another alternative is to use a specific timestamp:

/[-]T{date|time}[,{time|date}]

date is of the format mm-dd[-yy]

mm-dd-yy = month, day, and year
If yy is omitted, it defaults to the current year.

time is of the format hh:mm[:ss][{a|p}[m]]

hh:mm:ss = hours, minutes, and seconds
If ss is omitted, it defaults to 00.
24-hour notation may be used, and you may specify
am or pm (or just a or p). E.g., /T9:00p, /T9:00pm,
and /T21:00 are equivalent. If p[m] or a[m] are
specified, and mm = 0, you may omit mm. That is,
/T9:00pm can be expressed at /T9pm or even /T9p.
If mm or ss is specified, they must each be two digits
long. E.g. /T9:05, not /T9:5.

If BOTH mm-dd-yy and hh:mm:ss are given, they must be separated
by a comma. For example, /T10-15,9:00. You may also express this as
/T9:00,10-15. Alternatively, they may be expressed as separate /T
options: /T10-15 /T9:00.

If the minus sign is used (/-T...), it means search for files that
are BEFORE the specified time (analogous to /-n).


Details on /Fn
--------------

The /Fn switch specifies the format of NEW's output. The default
output (/F1) looks like this:

Directory since 6 am Sunday, 9-10-89

9-10-89 9:24:48 pm 11789 c:\msc\prog\NEW.DOC
9-10-89 2:59:42 pm 35717 c:\msc\prog\NEW.EXE
9-10-89 2:59:34 pm 22444 c:\msc\prog\NEW.OBJ
9-10-89 2:58:04 pm 48067 c:\msc\prog\NEW.C

4 files found

The /F0 switch removes the drive and path specifiers:

Directory since 6 am Sunday, 9-10-89

9-10-89 9:24:48 pm 11789 NEW DOC
9-10-89 2:59:42 pm 35717 NEW EXE
9-10-89 2:59:34 pm 22444 NEW OBJ
9-10-89 2:58:04 pm 48067 NEW C

4 files found

Other formats may be added in future releases.


Details on /C cmd
-----------------

If /C is used, then the command "cmd" will be executed for each
file NEW finds. This is a powerful feature! /C must be the last NEW
option, as anything after /C is interpreted as the string to pass to
COMMAND.COM. (This also allows "cmd" to have its own options beginning
with a slash.) The command may reference the filename or its separate
parts by using the special symbols defined below.

For example, if the filename NEW finds is "c:\sub1\sub2\FNAME.DAT",
the following symbols will be interpreted as:

%P = full pathname (c:\sub1\sub2\FNAME.DAT)
%D = drive letter (c)
%S = subdirectory path (\sub1\sub2)
%F = filename (FNAME)
%E = extension (DAT)
%N = filename.extension (FNAME.DAT)

Note that %D:%S\%F.%E and %D:%S\%N are equivalent to %P.

For example, to copy new files to drive B:, use

NEW /C COPY %P B:

NEW will ask for confirmation for each file that is to be processed.
You may circumvent this by using the /Q option.

NOTE: If the /C option is used in a batch file, you must double
the percent signs in the symbols above. For example, if
the previous example was in a batch file, it should be typed
in as:

NEW /C COPY %%P B:


Details on /V [batfile]
-----------------------

The /V option will invoke the Polytron Version Control System command
PUT using the flags -U and -N for each file processed by NEW for which a
logfile exists. The environment variable VCSCFG must be defined for the
VCS configuration file. In addition, the configuration file must contain
a valid VCSDIR directive so that NEW can find the logfiles.

As with the /C option, NEW will ask for confirmation for each file to
be processed. Use /Q to bypass the confirmation.

If a filename (default extension .BAT) is specified after /V, a batch
file will be created instead of invoking PUT. For example,

NEW /V runput will create RUNPUT.BAT.


Details on /Kn
--------------

For /Kn, as the /C or /V command is executing for each file found:

If n = 0: suppress NEW output AND do not print command
If n = 1: show NEW output AND print command (default)
If n = 2: print command only
If n = 3: print NEW output only

For example, to backup to drive B: while suppressing NEW output, use

NEW /K2 /C COPY %P B:

NOTE: Even if /K0 is chosen, the command will still be printed as
NEW asks for confirmation to execute each command. This may
be avoided by using /Q:

NEW /Q /K0 /C COPY %P B:


Details on /NP and /NQ
----------------------

These options can be used to override /P and /Q if the latter are
defined as options in the NEW environment variable. /NP and /NQ may
only be used on the command line. They may not be specified in the
NEW environment variable. Remember that /I will cause NEW to ignore
ALL options set in the NEW environment variable.


Details on /O{U|N|E|D|S}[-]
---------------------------

The /O option allows you to control how the files are sorted for
display. Choose one of the sort options, optionally followed by
a dash (to reverse the sort order).

U = unsorted
N = sort by file name
E = sort by file name within extension
D = sort by file date
S = sort by file size

The default sort option is /OD- (by descending date).


More Examples
-------------

C>NEW List files in the current directory created
or modified as of 6 am

C>NEW *.C List files as of 6 am with the extension .C

C>NEW /7 List files as of one week ago

C>NEW /E Search entire disk for files as of 6 am

C>NEW C: D: /E Search all of drives C: and D:

C>NEW \MSC\*.C /7 /S Search for .C files as of one week ago
starting from the \MSC directory and
searching all subdirectories of \MSC

C>NEW /7/S \MSC\*.C Same as previous example above (options and
filespec can be in any order)

C>NEW D:/E/365/P Search all of drive D: for files created up
to a year ago and pause when the screen is
full

C>NEW /-365 Search for files older than one year

C>NEW /D Search for today's files, including any
directories that were created

C>NEW /DO /7 /E Display any new directories created in the
last 7 days over the entire disk

C>NEW /J Display new files, including any "junk" files
that is, files that have corrupted time
stamps

C>NEW C: D: /A/E/D >ALLFILES.TXT

List ALL files and directories on drives C:
and D:, sorted by date, time, and filename,
and put them in a file called ALLFILES.TXT

C>NEW /-T1-1-84/A/E List all files on the current drive with dates
before 1-1-84.

And now for a ridiculous example...

C>NEW C:\MSC\PROG\*.C D:\DBASE\*.DBF E: /30/D/I/J/P/S/OS-

Display files up to a month old that match
the three filespecs listed and their
subdirectories, ignore the environment
variable NEW if it is defined, include
directories and "junk" files, pause when
the screen is full, and sort by descending
file size!


NEW Environment Variable
------------------------

If you find that you would like certain options or filespecs as
defaults, you may set up an environment variable called NEW that includes
the options or filespecs. For example, if you always want NEW to pause,
put the following command in your AUTOEXEC.BAT file:

SET NEW=/P

Other good candidates for the environment variable are the "config-
uration" type options, /Fn, /Kn, /G, and /Q.

If you've set up the NEW environment variable, but want to override
it temporarily, use the /I option on the command line. For example, if
you have issued SET NEW=C: D:/E but just want to use NEW on the current
directory, type in NEW/I. Any other options may be added as well. For
example, NEW/I/P/7.

The following options may not be specified in the NEW environment
variable: /H, /?, /I, /NP, or /NQ.

NEW first processes the command line options/filespecs. If /I is
not issued on the command line and the NEW environment variable is defined,
the environment variable is then processed. If /Kn and /Fn are used on
the command line, they take precedence over the environment variable.
To override /P or /Q, specify on the command line /NP or /NQ, respectively.


NOTES
-----

1. The file display is sorted by descending date and time. If
two or more files have the same date and time, they are then
sorted by ascending filename.

2. If /E or /S is chosen, the directories are displayed as they
are traversed.

3. If the full path name of the file is very long, the first
directory is shown, followed by an ellipsis (...), followed
by the ending portion of the path name. I did this because I
am using NEW on a network drive sometimes, and we tend to get
carried away with subdirectories! The /S option comes in handy
here. For example, if I want to see only my data area on the
network, I'll type in NEW \DATA\USERS\SCOTT /S. Doing a /E on
our network drive can take 2-3 minutes. However, the /E option
is interesting on a network as it shows the current day's
activities for multiple users (assuming you have supervisory
rights).

4. The "junk" option (/J) was added to include files with corrupted
dates. Such files defeat the purpose of NEW in that they appear
to be new files when they really aren't. However, if you really
want to see them, use /J. In fact, if you are trying to locate
such files, use /J in conjunction with /E to search the entire
disk.

5. Normally, I'm not interested in when directories were created,
but if you really want to include them, use /D. If you want
to see ONLY directories (no regular files), use /DO. Note that
the /D and /DO options are mutually exclusive.

6. The /P option has been enhanced to take into account the number
of text lines being used. That is, if you are using 43-line mode
with an EGA or 40- or 50-line mode with a VGA, NEW will pause
after the appropriate number of lines have been displayed.

7. Since I am allowing multiple filespecs, it is necessary to show
the complete path for filenames, even if /E is not being used.
For example, if you type in NEW C: D:, the current directories
on C: and D: will be checked. You need to know just where those
files really are. Consequently, if you are just using NEW on
your current directory, the full path will also appear. This
may seem a bit annoying. To compensate, I am displaying the
drive and directory path in lower case and the filename in upper
case. You may circumvent this by specifying /F0. In the future,
I may add other format specifications.

8. If you have Vern Buerg's LIST program, you can also view NEW's
help by typing in: NEW/H | LIST/S.

9. This program can be considered as dedicated to the public domain.
I will, however, accept small contributions ($2 to $15) if you
find the program to be useful and wish to encourage me. I would
also like feedback from users. Most of the new options have been
incorporated because of requests I've received from my loyal public!
If you would like to contact me about bugs, enhancements, or
contributions that could inspire me to create ever more ingenious
utilities, I can be reached at the following address.

Scott R. Houck
1880 Riggs Place, N.W.
Washington, D.C. 20009