NOTE: This program is offered as a "FREEBIE"
NO donations are requested or accepted. I've used enough other
people's freebies that this is offered as only a partial repayment
for their time and effort. My only request is that if you have
any suggestions, bug reports, or comments (I LOVE comments!),
please drop me a line or leave a message for me on Compuserve

ID # (72317,2751).


------------------ PURPOSE AND FUNCTION OF PROGRAM ----------------

This program was designed to help take care of some "regular" chores...
ones which I usually performed either once a day (optimizing my disk),
once a week (using TIMESET to call the Naval Observatory Clock and set the
time on my computer), or once a month (using SpinRite to renew the low-level
format of my hard disk) ... no matter how many times during that particular
day I booted my computer.

----------------------------- ENVIRONMENT --------------------------

This program was designed to run on an IBM PC/XT/AT or compatible. It should
also run on the PS/2 without difficulty. It runs under MS-DOS or PC-DOS
version 2.0 or later. It is NOT designed to run under OS/2. In terms of
hardware, it was designed to be run from a hard disk, and although it should
work on a floppy machine, the author neither claims that it will work, nor
understands why anyone would bother. Of course, a valid time and date are
expected to be on the system clock...If there is no real-time clock, then
the time and date should be entered BEFORE running DO-ONCE. Otherwise,
nothing would EVER run a second time, since as far as the machine is
concerned, it would ALWAYS be January 1, 1980. (Gee, Dad, is that when
the Universe began?)

------------------------------- SYNTAX -----------------------------

The syntax of DO-ONCE is:

DO-ONCE [@DAY] [d:\path\]FILENAME.EXT [PARAM1 PARAM2 PARAM3 ETC]

DAY is the name of the day of the week that you want it to occur
on, OR the day of the month. (i.e. TUE or SAT or 1 or 15)

FILENAME is the program you want to run.

You can PATH to the FILENAME, if it isn't in your normal PATH using the
optional d:\path\ in front of the FILENAME. Also note that the EXTension
is not necessary (unless you want to force DOS to bypass its normal
execution search priority)

Only the first three letters of the @DAY parameter matter, so
@MON or @THU would work just fine.

Versions 2.1 and later offer the possibility of running a program not only
by the proper weekday, but by the day of the month. Thus, it can execute
requested programs ONLY on the 15th of the month, if you want. You
would do this by using the @ parameter with a number, @15 for example.

If you run DO-ONCE without any parameters, it will give you a brief
synopsis of the command syntax and parameter possibilities.

Version 2.2 offers the possibility of including redirection within the
requested command line. If you need this capability, use the following
symbols in your DO-ONCE request:

`] will be replaced by the redirection symbol >
`[ will be replaced by the redirection symbol <
`^ will be replaced by the piping symbol |


Note: Versions 2.1 and later provide the option of running the program on the
first day AFTER it is due to be run, just in case you didn't turn
on the computer on the EXACT day. You may activate this option by
adding the + (plus) character immediately after the @ character.

Thus, DO-ONCE @MON VOPT -- will run VOPT on Mondays ONLY
but DO-ONCE @+MON VOPT -- will run VOPT on Monday OR on the
next day you boot the machine after
that Monday. (see examples below)

If this is confusing, try reading it this way:

The @ sign equals the word "ON"
The @+ sign equals the words "ON OR AFTER"

Therefore:

DO-ONCE @SATURDAY BACKUP reads: run BACKUP ON Saturday

DO-ONCE @+SATURDAY BACKUP reads: run BACKUP ON OR AFTER Saturday.

DO-ONCE @1 BACKUP reads: run BACKUP ON the first of the
month

DO-ONCE @+1 BACKUP reads: run BACKUP ON OR AFTER the first
of the month


This way, with the "ON OR AFTER" option, if you don't happen to turn
on the machine on Saturday, it will "remember" that it was SUPPOSED
to run on Saturday, and when you start up on the following Monday, (for
instance) it will run it.

The @+ operator can be used before either a DAY or a NUMBER:
@+THU is fine, as is @+15


NOTE THAT THERE SHOULD BE NO SPACES BETWEEN THE @ (OR @+) AND THE DAY!


--------------------------------------
ERRORLEVEL responses:

If you run DO-ONCE and the requested program is RUN, it returns an
ERRORLEVEL of 0.

If you run DO-ONCE and the requested program is NOT RUN, it returns an
ERRORLEVEL of 1.

If you run DO-ONCE without any parameters, it gives a synopsis of the
command syntax, and exits with an ERRORLEVEL of 2.

If you run DO-ONCE and the environment variable is SET to an invalid
or non-existent directory, it exits with an errorlevel of 3.

------------------------------------

CAUTIONS:

1) You should not use DO-ONCE to load TSR's, even from a batch file. DO-ONCE
uses a secondary command processor to load and run programs. If you load
any resident programs from within DO-ONCE, although they will run just fine,
you will be wasting a big chunk of your valuable RAM. This chunk will
remain unavailable until you either remove the TSR or reboot. If you
absolutely need to load a TSR once a day/week/month, do it this way
instead:

DO-ONCE ECHO Loading FOO-BAR-TSR...
IF ERRORLEVEL 1 GOTO :CONTINUE
FOO-BAR-TSR
:CONTINUE

This will load the FOO-BAR-TSR (or whatever it's called), not from
within the DO-ONCE program, but from the regular batch file. This way
your memory will not be wasted on excess copies of COMMAND.COM.

2) Please note (as explained in the "re-direction" section below) that
you should not use a disk-optimizing program while output is being
re-directed to a file, or cross-linking of file clusters can occur.


----------------------------- EXAMPLES -------------------------------

Example: Every Monday (and ONLY if it's a Monday), when I first start
my machine, I want it to run the TIMESET program, in AUTO mode.
But if I reboot my machine, I don't want it to run TIMESET every
time...just the first time. So my AUTOEXEC.BAT file has the
following line:

DO-ONCE @MONDAY TIMESET AUTO


Example: Every day, when I first start up my machine, I want it to run
the VOPT program, optimizing my hard disk on Drive C and again
on Drive D. But I don't want to run VOPT every time I hang and
reboot the computer, so my AUTOEXEC.BAT file contains the
following lines:

DO-ONCE VOPT C:
DO-ONCE VOPT D:


Example: On the first of each month, I want to run a batch file called
POSTACCT, which posts my accounting program entries for the last
month, and starts a new month. But if the first of the month
happens to occur on a Sunday, when I don't boot up my machine, I
would like it to POSTACCT on the following day, or whenever I next
start up. Soooooooooo.... I put the following line in my
autoexec.bat:

DO-ONCE @+1 POSTACCT

Example: Every day, I want to run CHKDSK on my hard disk, with the /F
parameter...and to automatically toss out any lost clusters
it may find...but I don't want to have to answer "No" to CHKDSK's
question about such lost clusters...sooooooooooo, I put this line in
my AUTOEXEC.BAT

DO-ONCE ECHO N `^ CHKDSK /F

which DO-ONCE will pass to DOS as the command line:
ECHO N | CHKDSK /F


________________
STACKING DO-ONCE
----------------
Example: I have a Lions Club meeting on the first Friday of each month, and
I like to have a reminder when I start the machine, so that I don't
forget about the Club lunch. Here I can STACK the DO-ONCE commands
(combine them) so that the following line will accomplish the task:

DO-ONCE @Friday DO-ONCE @+1 LIONCLUB.BAT

hence, the LIONCLUB.BAT file will get run on or after the first day
of the month....BUT...it never even gets requested to run unless it's
Friday, so it will ONLY be run on the first Friday of the month...
and then not until the next month!

To stack them properly, you should place the less restrictive re-
quirement FIRST, and the more restrictive requirement second. That
is, place the @FRIDAY (which occurs more often) first, and the
@+1 (which occurs less often) second. You can figure the logic
through, or just take my word for it.

--------------------------------- MORE JUNK --------------------------------

For those of you who like to keep your root directory free of all un-necessary
files, you can instruct DO-ONCE to keep its data file in another directory, or
even on another drive. To do so, just set an environment variable with the
name of the desired drive\path...by putting a line in your AUTOEXEC.BAT file
like this:

SET DO-ONCE=C:\UTIL

(with or without the final backslash)

Make sure this line occurs in your AUTOEXEC.BAT *before* any lines which
run DO-ONCE, or DO-ONCE won't know where to find your data file, and it will
use the default (root) directory of the current drive for its data file.

- - - - - - - - - - -

For those of you who also like to keep your screen uncluttered, a QUIET MODE
can be specified by placing the "quiet switch" in the environment variable.
The quiet switch is /Q placed AFTER the directory name, like so:

SET DO-ONCE=C:\UTIL /Q

Make sure there is at least one space separating the directory name and the
quiet switch, as shown above. You can activate the quiet switch without
specifying a directory with the command: SET DO-ONCE=/Q

The quiet switch will suppress all extraneous information regarding when
the requested program was last run, etc. If the DO-ONCE copyright notice
is already displayed on the screen (which I assume would mean you've just
run it -- unless you just like "ECHO"ing my name to your screen!) the
quiet switch will suppress repeated displays of it, so you don't have to
stare at 20 copies of my name on your screen. You will, however see
a . displayed each time, just to let you know it's working.

If the requested program is going to be run, the command line will be
displayed on the screen, just as if you'd typed it in from DOS. This is
true whether you're running in quiet mode or not. If you REALLY like a
clear screen, you can clear even this up by redirecting output to
the NUL device...like so:

DO-ONCE Myprog >NUL

The copyright notice will not be suppressed by re-direction.

Even in quiet mode, any DOS error messages will continue to be displayed, as
will any output from your program, just like normal.

- - - - - - - - - - -

For those command lines which require re-direction, instead of including
the > symbol on the DO-ONCE command line (which DOS will interpret as re-
directing the output of DO-ONCE, not your program)...you can insert the
following two part symbols:

`] will be replaced with the > symbol.
`[ will be replaced with the < symbol.
`^ will be replaced with the | symbol.

Please note, this is a backwards apostrophe (ASCII character 96), followed
by a right square bracket, left square bracket, or caret mark.

CAUTION: Using a disk-optimizing program while output is being redirected to
a file can cause cross-linkage of file clusters. This has nothing to do with
DO-ONCE, but is true whenever such programs are run. This caution is being
included here just to save you some headaches. If you are using such a
program, or any program which *directly* manipulates the File Allocation
Table (FAT) then do NOT re-direct output to a file. (You can still redirect
output to a device such as NUL or PRN without any problems.)

Example: DO-ONCE @SUN DIR `] SUN.DIR will be executed on Sunday as
DIR > SUN.DIR

If you have no idea what I'm talking about with re-direction and piping,
that's OK. If you haven't found it necessary to learn these DOS tools yet,
you needn't learn them just for DO-ONCE.


----------------------------- HOW DO-ONCE WORKS -----------------------------
------------------------ (useless technical details) ------------------------

What DO-ONCE does is to keep a record of requested programs (a requested
program is like TIMESET or VOPT, in the above examples). It keeps a record
of requested programs in a file DO-ONCE.DAT. This file is kept in the
root directory of the currently active drive. (unless a different directory
is SET in the environment) When I request a program, it first checks to see
if I've requested it to occur only on one particular day, for instance only
on Mondays, or only on the 15th of the month. If I have, and it isn't
currently Monday, then DO-ONCE checks to see if I've requested the "or after"
function, and if the program was run on the last requested day. If it WAS
so run, DO-ONCE immediately quits, and my AUTOEXEC.BAT file continues on as
usual.

If it is Monday, etc., or if no @DAY request has been made, then it checks the
DO-ONCE.DAT file to see when that program was last requested. If the date
it was last requested isn't the same as the current day, month, and year, then
DO-ONCE loads a copy of COMMAND.COM, and passes the FILENAME and any parameters
on to DOS. This way, you can run a BAT file, COM file, or EXE file using
DO-ONCE. Note, however, the caution below that you should NEVER request
a resident or TSR program directly from DO-ONCE. Finally, DO-ONCE updates
the DO-ONCE.DAT file to reflect the fact that it has now run that particular
requested program. (note, since it runs the requested program from within
a secondary copy of COMMAND.COM, you can tell it to run a BATCH file, and
when that batch file is finished, it will return back to your autoexec batch
file and continue where it left off.)

Note that DO-ONCE closes all data files and cleans up its directory entries
before running the requested program, so that programs like disk optimizers
or non-destructive low level formatters can operate without messing up the
DO-ONCE files.

The structure of the DO-ONCE.DAT file is as follows:

Year : Word (2 bytes)
Month : Word (2 bytes)
Day : Word (2 bytes)
Len : Byte (length of the command line executed)
C_line : 128 bytes (normal limit for DOS command line)

The reason the C_Line field is 128 bytes is that DOS can accept a command line
only that long.

If the requested program has not yet been run (that is, if there is no match
for the command line) then the name and date are added to the file, and the
program is run.

NOTE: -- DO-ONCE will ALWAYS run a program the first time it is requested,
even if it's NOT Monday, or whatever.

Note that you need not enter any extension for the FILENAME. (.BAT, .COM,
etc), unless you want to force DOS to run a BAT program instead of an
identically named COM program, etc.

Also note that it records the [d:\path\]FILENAME *and* any parameters. It
will EXECUTE the FILENAME with any parameters you put after it, and also store
it as such, so that the same program can be run with different parameters, as
in the VOPT example above.

The "quiet mode" checks to see if the DO-ONCE copyright notice is found
somewhere on the screen (which usually means you've got several DO-ONCE
requests in a row). If it finds the notice, it supresses repeated
displays of the copyright notice; It will also supress any information
regarding the requested program. All you will see is a collection of
dots -- one for each time DO-ONCE is run. That way, you only have to
look at the copyright notice once. (I use DO-ONCE about 10 times in a row
in my AUTOEXEC.BAT, and I got tired of seeing my own name filling up the
screen all the time...I mean, I like my name as much as anyone, but that's
ridiculous!)

Although the data file is actually accessed and read each time you run
DO-ONCE, sometimes it doesn't actually change anything, but just ends up
leaving the file exactly as it was. You will notice, however,
that the file date and time stamp are updated...so you can tell the last
time you ran DO-ONCE just by looking at the date of your DO-ONCE.DAT file.

DO-ONCE was written using Borland's Turbo Pascal, Version 4.0.
It also makes use of Bob Ainsbury's excellent shareware function library,
the "TechnoJock's Turbo Toolkit." (Yes, I registered it, did you?)

The source code for DO-ONCE is not available for distribution because
1) I don't want everyone making fun of my code (OK, I'll admit it).
2) I don't want to have to comment every line of the source.
3) It uses several of my own units for date, string, and environment
handling which I do not want released yet.
4) I don't want J. Random Dufus to modify (and mess up) the program.
That's why it's copyrighted.

- - - - - - - - - - -

If you have any questions, problems, or suggestions, please let me know. If I
can make the program more useful for you, also let me know.

Thanks to Bob Gellman, Mike Focke, Andy Glass, Paul Shahood, Mark Freeman, and
Paul Thorpe for suggestions and improvements.

Until June 15, 1989
Glenn Snow
1600 Webster St. NE
Washington, DC 20017
(202) 526-1221 (voice only, please)

After June 15, 1989
Glenn Snow
1 Carmel Parkway
Mundelein, IL 60060
(312) 566-4070 (voice only, please)

-------------------------------------------------
Version history

1.0 -- Original DO-ONCE, written in ASM. Limited release to the public.
(May, 1987)

1.1 -- Fixed bug which cut command line short when @DAY parameter used with
entire day name. (Nov, 1987) First release as freebie. (NO donations
requested.)

1.2 -- Re-written in Turbo Pascal 4.0 -- Accepts a path designation in front
of the requested program. Identifies itself with DO-ONCE message when
run. (Thanks to Bob Gellman for the suggestion).

1.3 -- Now stores ENTIRE command line, including parameters, like the VOPT
example above. (Thanks to Mike Focke for the suggestion). Also
identifies the requested program before it runs it.

1.4 -- Displays requested program on screen while checking to see if it should
be run. Added carriage return and line feed before identifying itself.

2.0 -- A dog. Although several "enhancements" were added, several bugs
were added as well...Fatal Error #127 (Incredible Programmer Stupidity)
was the main cause. If you have this version, get rid of it!
(Bad dog! Bad dog! Down boy!)

2.1 -- Several enhancements, which now work. All unintended "features" (bugs)
were removed.
a) Added the monthly option
b) Added the "or after" option
c) Allowed the data file to exist elsewhere than in the root directory
by the use of the DO-ONCE environment variable
d) Gives a more detailed run/no-run message
e) Returns consistent ERRORLEVEL responses
(Thanks to Andy Glass and Paul Shahood for the GREAT suggestions,
and again to Paul Shahood for patience with the Bad Dog version)

2.2 -- Two simple enhancements and a bug fix.
a) Enhancement: Quiet mode is added.
Thanks to Paul Thorpe for the suggestion.
b) Supports redirection and piping.
Thanks to *me* for the suggestion.
b) Bug fix: If the DO-ONCE.DAT file does not need to be changed
(i.e. the requested program was not run) then its archive bit is
left as it was. This means that it will not be incorrectly marked
as needing backup. Thanks to Mark Freeman for the suggestion.


--------------------------- END OF DOCUMENTATION ------------------------