Waitfor v0.58
Copyright (c) 1990
All Rights Reserved
William H. Bond 1:325/118


This program is freely available for non-commercial use. The only
thing I ask is that you let me know of any bugs, suggestions, etc..


Special thanks go to Ralf Brown for releasing DV-GLUE(c). The
Desqview(tm) functions incorporated in this program came from this
library. I'd also like to thank Don Dawson 1:141/730 and David Dyer-
Bennet 1:282/341 for their help in testing it and for making
suggestions that helped shape the program.


This program was developed using the following software: Qemm 5.0,
Desqview 2.26, MSC v6.0, DVGlue v1.01, MS-Dos 3.3.


This is a beta version. There is no warranty expressed or implied.
The user of this program assumes all responsibility for the operation
of, and any consequences of using, this program.


Waitfor is a simple utility program for use with Desqview, mainly as a
batch file utility. It allows the user to synchronize events in
multiple windows by delaying the current process. You can use it to
delay for a given amount of time, to allow a background process to
complete. You can have it wait for a specific file to exist, and
optionally kill the file when it is found. This can be used if a
background process creates a temporary file to signal that it has
completed a task. It can also be made to wait for a specific file to
not exist, and optionally create the file if it doesn't exist. You
can also specify the amount of available memory that needs to be free
before the program will exit.


By default Waitfor will exit as soon as the first condition becomes
true. This behavior may be modified so as to wait for all exit
conditions to become true before exiting by using the -! or -& option.


Desqview named mailboxes are also supported in addition to files. One
process may create or destroy a named mailbox to use as a semaphore
for other processes. The other processes may test for the existence
or non existence of the named mailbox and wait accordingly.


Waitfor can also perform a simple test for existence of a file,
mailbox or specific amount of available memory and exit immediately
with an appropriate errorlevel.


While Waitfor is waiting for a condition to be met it will give up
almost all of it's timeslice back to Desqview. This allows it to use
very little overhead while it is executing. The amount of time it
gives back to Desqview is configurable.







Syntax:


Waitfor [-Ddelay] [-Ttimeout] [-!] [-&] [-Ffreememory] [-Ahh:mm:ss]
[-Efilename] [-Nfilename] [-k] [-c] [-Rretries] [-q]
[-MEmbxname] [-MNmbxname] [-mk] [-mc]
[-WEfilespec] [-WNfilespec]

[-MMmbxname] [-MDmbxname] [-XAmem] [-XFfile] [-XMmailbox]


-d = Delay for 'delay' 100ths seconds between loops. While Waitfor is
executing it will by default 'sleep' for one second (-d100) after
checking for each exit condition. This causes it to use very
little processor time while it is executing. The -d option can
be used to vary this sleep time, though very little is gained by
increasing from the default. Note that if you specify a delay of
1 minute (-d6000), that no exit conditions are checked during the
delay time. The timeout value (if any) would also only be
updated on the screen once a minute.


-t = Wait for 'timeout' seconds before exit. This can be combined
with the other options to avoid halting a process forever if the
background task hangs. It can also be used as a simple countdown
timer. If the -t option is the only one specified the program
will wait until the timeout counts down. When combined with
other options the timeout will only count down while the other
conditions are false, when one of the other options (or all with
the -! option) become true the program will exit. The timeout
value must be between 1 and 65535. When the timeout is reached
Waitfor will exit with an errorlevel of 40.


-! = Will cause the program to wait for all exit conditions to be met
before exiting. Normally the program will exit immediately when
any of the conditions are true. If you are waiting for three
files to exist, the -! will cause an exit if all three have
existed during the execution of the program, they don't
necessarily have to exist at the same time. The -t (timeout)
option is not affected by this option, a timeout will always
cause an immediate exit. Waiting for multiple events will result
in an errorlevel corresponding to the last condition that became
true.


-& = Will cause the program to wait for all exit condition to be met
at the same time. This is similar to the -! option, but has one
important difference. If you are waiting for three files to
exist, the -& option will cause an exit only when all three files
exist at the same time. The -t (timeout) option is not affected
by this option, a timeout will always cause an immediate exit.
Waiting for multiple events will result in an errorlevel
corresponding to the last condition that became true.

The -& option also will change the look of program output. Each
condition specified will be displayed on the screen. The program
will then display a '-' or 'y' for each option depending on
whether or not the condition is true.








-f = Do not exit until 'freememory' free memory (in K) exists. This
may be used by itself or in combination with other options. If
used with other options you also need to use the -! option, this
will prevent an immediate exit if one of the other option(s)
become true, and allow the free memory to be checked. It checks
the largest available conventional or expanded memory area (as
shown by Memory Services) if either is larger than the specified
amount the program will be allowed to exit.


-a = Wait until the time specified as 'hh:mm:ss'. The time must be
specified in 24 hour format. Unlike the -t timeout option this
one does not force an unconditional exit when the time is
reached. The format is hh:mm:ss, hh:mm, or hh.


-e = Wait for the file 'filename' to exist. This can be used to halt
the current process until a background process creates a specific
file. More than one file may be specified (up to 10) by using
the -e option multiple times. As soon as the first file is found
Waitfor will exit with an errorlevel of 10 (this behavior may be
modified by the -! option).


-n = Wait for the file 'filename' to not exist. This will wait for
the specified file to disappear. You could have a process create
a temporary file while it is running and delete the file when the
job is complete. Any other task can check for the existence of
the file and wait until the file doesn't exist. More than one
file may be specified (up to 10) by using the -n option multiple
times. As soon as any specified file is found not to exist,
Waitfor will exit with an errorlevel of 11 (this behavior may be
modified by the -! option).


-k = Kill the 'filename' specified by the -e option before exiting.
By default the file is left intact after it is found to exist.
No specific errorlevel is generated. See note below.


-c = Create the file specified by the -n option if it doesn't exist.
This will first check for the existence of the -n filename, if
the file exists it will wait as usual. If the file doesn't exist
it will be created (0 length) and the -n checking for that file
will be disabled immediately. If the -n option is used in a
batch file along with the -c option, it will prevent the batch
file from being executed by two tasks at the same time. The
batch file should delete the -n file just before it ends. No
specific errorlevel is generated.


-r = Specify retry count for the -e and -k combination. This may be
used to modify the default retry value of 3 when combining the -e
and -k options. See notes section for description of potential
problems if SHARE is not loaded.


-q = Suppress copyright display.








The -m? options are similar to the above file options except they use
a Desqview global named mailbox instead of a filename. The mailbox is
visible in all windows. It will exist until the mailbox is killed, or
the window in which it was created is closed.


-me = Wait for the specified mailbox 'mbxname' to exist. More than
one mailbox may be specified (up to 10) by using the -me option
multiple times. When the first mailbox is found Waitfor will
exit with an errorlevel of 20 (this behavior may be modified with
the -! option).


-mn = Wait for the specified mailbox 'mbxname' to not exist. More
than one mailbox may be specified (up to 10) by using the -mn
option multiple times. When any mailbox is found to no longer
exist Waitfor will exit with an errorlevel of 21 (this behavior
may be modified with the -! option).


-mk = Kill the mailbox specified by the -me option when it is found to
exist. This releases the mailboxes' memory back to Desqview. No
specific errorlevel is generated.


-mc = Create the mailbox specified in the -mn option if it doesn't
exist. Each mailbox created uses some of the Common Memory as
shown in the Memory Services program. No specific errorlevel is
generated.


-mm = Create a mailbox named 'mbxname'. This option will create the
mailbox regardless of what other options are specified. If the
mailbox already exists the option is ignored. No specific
errorlevel is generated.


-md = Destroy the mailbox names 'mbxname'. This option also ignores
any other options that may have been specified. If the mailbox
doesn't exist the option is ignored. No specific errorlevel is
generated.


-we = Wait for the wildcard 'filespec' to exist. The filespec is
passed on to the DOS find first function exactly as specified.
More than one wildcard may be specified (up to 10) by using the
-we option multiple times. Any file matching the filespec will
cause an exit with an errorlevel of 30 (this behavior may be
modified with the -! option).


-wn = Wait for the wildcard 'filespec' to not exist. The filespec is
passed on to the DOS find first function exactly as specified.
More than one wildcard may be specified (up to 10) by using the
-wn option multiple times. When no file matching the filespec is
found, Waitfor will exit with an errorlevel of 31 (this behavior
may be modified with the -! option).









-xa = Check for 'mem' (in K) available conventional or expanded memory
and exit immediately. Any other options are ignored. If 'mem'
available memory exists Waitfor will exit with an errorlevel of
35, otherwise it will exit with an errorlevel of 36.



-xf = Test for the existence of the file 'file' and exit immediately.
Any other options are ignored. The errorlevel is set to 15 if
the file exists and 16 if the file doesn't exist.


-xm = Test for the existence of the named mailbox 'mailbox' and exit
immediately. Any other options are ignored. The errorlevel is
set to 25 if the mailbox exists and 26 if the mailbox doesn't
exist.



Notes:


Executing Waitfor without any options will display a short help
screen.

The options may be combined and are not case sensitive. You could
have the program wait for one file to exist while waiting for another
file to not exist, and specify a timeout at the same time.

Filename arguments may contain drive and/or path specifications.

Pressing escape or Control-C/Break will end the program with an
errorlevel of 50. Pressing 'C' or 'c' will end the program with an
errorlevel of 5.

Note that there are no spaces between the switch and the switch
argument. A '/' character may be used instead of the '-' character.

If the -c, -k, -mc, -mk options are used with multiple file names or
mailboxes, all files/mailboxes will be affected.

One suggestion for file names is DESQTMP?.???, check the Desqview
manual for details.



If SHARE.EXE is not loaded there is a potential problem using the -e
and -k options together. The problem occurs if Waitfor is waiting for
the specified file (-e) and the file is created by another process and
not immediately closed. In this case Waitfor will delete the file,
but the other process may still be writing to it. If SHARE is loaded
Waitfor will detect this condition and abort with an errorlevel of 52
if it cannot delete the file after 3 retries, with a delay (-d value
or the default of 1 second) between retries. This retry value may be
modified by using the -r option. If you're only creating 0 length
semaphore files (eg: rem >testfile) this should not present a problem.











Examples:


start of MAIN.BAT
Waitfor -nc:\bbs\batch.flg -c
... do some non reentrant stuff here.
if exist c:\bbs\batch.flg del c:\bbs\batch.flg
end of MAIN.BAT

When the above is executed there are two cases to consider:

1. If c:\bbs\batch.flg exists the execution of MAIN.BAT will be
suspended until MAIN.BAT is finished processing and deletes
c:\bbs\batch.flg.

2. If c:\bbs\batch.flg does not exist it will be created and
execution of MAIN.BAT will continue immediately. If a second copy of
MAIN.BAT starts executing concurrently it will be suspended as in case
1 above.


Waitfor -t60
Wait for 1 minute (60 sec.).


Waitfor -ewait.fil
Wait for the file 'wait.fil' to exist.


Waitfor -ewait.fil -k -t3600
Wait for the file 'wait.fil' to exist or 1 hour, whichever comes
first. The file will be deleted when found, unless the timeout is
reached first.


Waitfor -meflag
Wait for the a mailbox named 'flag' to exist.


Waitfor -mmflag
This will simply create a mailbox named 'flag'.


Waitfor -xftest.fil
Test for the existence of 'test.fil' and exit immediately.


Waitfor -eflag1 -eflag2 -eflag3
Exit as soon as any one of the three files are found.


Waitfor -eflag1 -eflag2 -eflag3 -!
Do not exit until all three files are found.


Waitfor -nflag1 -nflag2 -nflag3
Exit as soon as any one of the three files do not exist.









Waitfor -nflag1 -nflag2 -nflag3 -!
Do not exit until all three files do not exist.


Waitfor -efile1 -efile2 -efile3 -k -!
Wait for all three files to exist and kill each as they are found.


Waitfor -f384
Wait for at least 384k free conventional or expanded memory.


Waitfor -efile1 -f520 -!
Wait for file1 to exist, then don't exit until there is at least 520k
free memory.


Waitfor -xa420
Test for at least 420k available memory and exit immediately.


Waitfor -a5:00
Wait until 5:00am, then exit.


Waitfor -wed:\tossdir\*.*
Wait until any file exists in the 'd:\tossdir' directory.


Waitfor -wnd:\tossdir\*.*
Wait until the 'd:\tossdir' directory is emtpy.



Order of exit condition evaluation:

1. -xa available memory check, exit immediately
2. -xf file test, exit immediately
3. -xm mailbox test, exit immediately
4. escape key or 'c' key
5. -t timeout
6 -a specific time
7. -e existence of a file
8. -n non existence of a file
9. -me existence of a mailbox
10. -mn non existence of a mailbox
11. -we existence if a wildcard
12. -wn non existence of a wildcard
13. -f available memory check

Whichever condition becomes true first will cause the program to exit
with the corresponding errorlevel, unless the -! or -& option is also
given. Exit condition checking is only enabled for options specified
on the command line.












Option Summary:

-d = sleep for 'delay' 100ths seconds between loops, default 100.
-t = wait for 'timeout' seconds.
-! = Wait for multiple exit conditions to be met before exiting.
-& = Wait for all exit conditions to be met at the same time.
-f = Do not exit until 'freememory' (in K) free memory exists.
-a = Wait until the time specified as 'hh:mm:ss'.
-e = wait for 'filename' to exist.
-n = wait for 'filename' to not exist.
-k = kill 'filename' when found, use with -e.
-c = create 'filename' if it does not exist, use with -n.
-r = specify retry count for -e and -k combination.
-q = disable copyright display.
-me = wait for mailbox 'mbxname' to exist.
-mn = wait for mailbox 'mbxname' to not exist.
-mk = kill mailbox 'mbxname' when found, use with -me.
-mc = create mailbox 'mbxname' if it does not exist, use with -mn.
-mm = create a mailbox named 'mbxname', unconditional.
-md = destroy a mailbox named 'mbxname', unconditional.
-we = wait until the wildcard 'filespec' exists.
-wn = wait until the wildcard 'filespec' does not exist.
-xa = test for 'mem' available memory.
-xf = test 'filename' for existence.
-xm = test 'mbxname' for existence.



Errorlevel summary (most are also displayed on the usage screen):

0 = -mm or -md options created or destroyed a mailbox and no other
options were specified. -f option was the only one specified.
1 = -a time reached first
5 = 'c' continue key.
10 = -e file found first.
11 = -n file found not to exist first.
15 = -xf file exists.
16 = -xf file doesn't exist.
20 = -me mailbox found first.
21 = -mn mailbox not found first.
25 = -xm mailbox exists.
26 = -xm mailbox doesn't exist.
30 = -we wildcard exists.
31 = -wn wildcard does not exist.
35 = -xa memory is available.
36 = -xa memory is not available.
40 = Timeout value reached first.
50 = Escape or Ctrl-C.
51 = Command line or syntax error.
52 = File sharing error when -e and -k options are used.
55 = Fatal error, cannot create file or cannot delete file, or cannot
create mailbox.


Any bugs reports, comments or suggestions may be directed to Bill Bond
at 1:325/118@FidoNet.

Desqview is a trademark of Quarterdeck Office Systems.