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, comments (I LOVE comments!), or bug reports, that
you drop me a line, call (at voice number listed at bottom),
or leave a message for me on

The Final Option BBS (703) 451-0457 or
The Byrd's Nest BBS (703) 671-8923 or
Compuserve 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.

------------------------------- 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.

Version 2.1 offers 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.


Note: Version 2.1 provides 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.

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

----------------------------- 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

________________
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...like so:

SET DO-ONCE=C:\UTIL

(with or without the final backslash)

make sure you SET this *before* you run DO-ONCE, or it will use the default
(root) directory of the current drive for its data file.


----------------------------- 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. Finally, it 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.

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, and Paul Shahood for suggestions
and improvements.

Glenn Snow
1600 Webster St. NE
Washington, DC 20017
(202) 526-1221 (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)


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