home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-385-Vol-1of3.iso
/
w
/
wtdisk11.zip
/
WAITDISK.DOC
< prev
next >
Wrap
Text File
|
1992-11-14
|
20KB
|
459 lines
WaitDisk User's Guide
Copyright (C) 1992 Larry B. Rice
License
This program is licensed for evaluation use only. The program
may be installed and used on single or multiple user systems for
a period of time not to exceed two weeks. Only registered
copies may be used beyond this time.
Disclaimer & Limit of Liability
WaitDisk and the WaitDisk User's Guide are distributed 'as is'.
The Author make no warrants, either express or implied, as to
appropriateness or suitability for any particular use of this
product, or to the accuracy of this or other related
documentation, nor to the error-free operation of the software.
Except as may be provided by law, neither the Author nor any
duly authorized representatives may be held liable for any
damages or loss resulting from the use of, or the inability to
use, this product. Under no circumstances shall any liability
for the use of the software, or the information contained in
this and other related documentation exceed the purchase price
of the program.
WaitDisk is NOT in the Public Domain and may not be marked or
displayed as such.
WaitDisk IS distributed as Shareware. For Distribution
information, see the file VENDOR.DOC. For Ordering and
Licensing information, see the file ORDER.DOC.
If you have questions or comments, please contact the Author:
Larry Rice 2907 St. Tropez Dr., Ontario, CA 91761
CONTENTS
What is WaitDisk?. . . . . . . . . 1
Who can use it?. . . . . . . . . . 1
Why use WaitDisk?. . . . . . . . . 2
How is it used?. . . . . . . . . . 3
Using WaitDisk in Batch Files. . . 5
Using WaitDisk in Another Program. 6
Sample WaitDisk Calls. . . . . . . 7
Compatibility Problems . . . . . . 7
----------------------------------------------------------------
WaitDisk User's Guide Page 1
** What is WaitDisk? **
Users of Apple's MacIntosh or Commodore's Amiga computers may be
familiar with their ability to prompt a user for a specific
floppy disk and wait for it to be placed into a specific drive.
WaitDisk brings this feature to DOS computers. Briefly, for
those who may not familiar with either of these computers,
WaitDisk may be called from a DOS Batch File or from another
program to prompt the user to place a specified disk into a
specific drive. WaitDisk will then wait until the disk is
either inserted into the drive or until the user cancels the
operation. Waitdisk returns a code to inform DOS or the calling
program which action has occurred.
WaitDisk supports the use of a mouse and uses a pop-up prompt
window that saves the underlying screen. This allows WaitDisk
to be used seamlessly in a variety of applications. WaitDisk is
compatible with Monochrome, CGA, EGA and VGA adapters, requires
DOS version 3.0 or newer and works from either floppy or
harddrives. WaitDisk can read Volume Labels from disks
formatted with DOS v2.0 and later, and Serial Numbers from disks
formatted with DOS v4.0 and later.
IMPORTANT: Some older disk drives can take a detectable amount
of time to return information or their status to WaitDisk.
Because of this, there may be a slight delay when the proper
disk is inserted or the user cancels the request before WaitDisk
can respond.
** Who can use it? **
Anyone familiar with DOS batch files may easily use WaitDisk.
In its simplest form, WaitDisk may be called to wait for ANY
disk to be placed into a floppy drive. For example,
waitdisk -da
will prompt the user to place ANY disk into drive A:. WaitDisk
will return an ERRORLEVEL code of 0 to indicate that drive A:
contains a disk. An ERRORLEVEL code of 1 indicates that the
user CANCELED the operation and that Drive A: does NOT contain a
diskette.
Another parameter, -v, can be used to supply WaitDisk with a
Volume name. In this case, WaitDisk will return an ERRORLEVEL
code of 0 ONLY when a diskette with the specified volume name is
placed into the specified drive.
WaitDisk can also be supplied with a Disk Title, that is, a name
used on the disk's label. This name can be up to 28 characters
long and is prominently displayed in WaitDisk's prompt window.
----------------------------------------------------------------
WaitDisk User's Guide Page 2
For developers, script writers and DOS programmers, WaitDisk can
also be supplied with a Volume Serial Number, for more precise
disk identification, and row and column coordinates to locate
the pop-up window on the screen so that it does not cover other
important information. And, WaitDisk can be set to 'silent'
mode to test the current disk to determine if the user needs to
be prompted at all.
** Why use WaitDisk? **
While DOS provides a mechanism for identifying individual
diskettes through Volume Labels it doesn't provide a useful way
of using them. WaitDisk not only provides that, it lets you
avoid getting trapped by the infamous
Abort, Retry, Fail?
prompt. This prompt appears anytime DOS attempts to access a
disk drive that is not ready to be accessed, either because it's
empty, the drive door has not been properly closed or you've
accidentally placed an unformatted or improperly formatted disk
into the drive.
Computer owners who keep a number of occasionally used programs
and utilities on floppy diskette will find WaitDisk a convenient
way to build batch files or menus that ask and wait for disks by
name.
Developers will find a number of uses for WaitDisk. By
specifying a Volume Label AND Volume Serial Number, you can be
virtually certain that a needed program or data diskette has
been placed into the proper drive. WaitDisk preserves the
current screen and cursor location, and restores them even if
the user cancels the operation. This way your code can decide
on further action, not DOS. WaitDisk reliably traps Int 24
(Critical Error) calls and prevents the
Abort, Retry, Fail?
message from appearing over your carefully designed screens.
Best of all, you can license WaitDisk for royalty-free use for
less than it would take to develop a similar feature yourself.
----------------------------------------------------------------
WaitDisk User's Guide Page 3
** How is it used? **
When called, WaitDisk will display a prompt window on top of the
current application (or DOS) showing prompting the user for the
requested disk. At the same time, WaitDisk will check the
specified drive for the requested disk. If it is already
present, WaitDisk will promptly terminate and return a 0
ERRORLEVEL code. If the disk is not present, WaitDisk will
continuously check the specified drive until the disk is
inserted or the user cancels the request. Note that the drive
light will remain on during this time.
The only action required by the user is to place the requested
disk into the specified drive. Either the 'C' or ESC keys may
be used to cancel the request. WaitDisk automatically checks
for the presence of a mouse driver. If one is loaded, the user
may click on the Window Close button in the upper left corner of
the window or click on the Cancel button to cancel the request.
Developer's Note: You will probably need to reset the mouse
driver after a call to WaitDisk. WaitDisk requests only Left
Button down events from the driver.
WAITDISK -D [-V] [-S] [-N] [-R] [-C] [-X]
Parameters may be passed using either upper or lower case
letters. WaitDisk translates Drive, Volume Label and Serial
Number letters to upper case before doing comparisons.
Parameters shown in brackets ([]) are optional.
-D The Disk Drive where WaitDisk should look for a disk. This
is the only required parameter. If the Drive is not
specified, an error message will appear along with general
use instructions. Examples:
-da (Check Drive A)
-db (Check Drive B)
Note that -Da, -dA, -dA: are all valid Drive parameters.
-V Look for a specific Volume Label. Volume Label are
generally assigned during formatting but may be added or
changed later using DOS's LABEL command. The Volume Label
may be up to 11 characters long.
waitdisk -dB: -vVolume_1
If WaitDisk is not provided with a Volume Label, it will
prompt the user for ANY volume in the specified drive.
Note that spaces MAY BE USED in Volume Labels. "Util Disk"
is a valid Volume Label and is passed to WaitDisk as
waitdisk -dB: -v"Util Disk"
----------------------------------------------------------------
WaitDisk User's Guide Page 4
Case is NOT significant. WaitDisk changes the Volume Label
to all upper case letters before comparison with the disk's
volume label. vutil_1 and -vUTIL_1 are identical volume
label parameters.
Developer's Note: Volume Labels are available on disks
formatted with DOS versions 2.0 and later. DOS returns the
Volume Label as a filename, using the file extension to
extend the name to eleven characters and padding short names
to eleven characters using spaces. However, the Volume
Label should be passed to WaitDisk just as it was entered on
formatting, that is, without an extension (and obviously,
unpadded). WaitDisk will transform the disk's volume label
as returned by DOS into a similar string for comparison.
IMPORTANT: When a Serial Number is provided (see -s) BOTH
the Volume Label and Serial Number are read from the disk's
boot sector.
-S FOR DISKS FORMATTED WITH DOS V4.0 OR LATER. Search for a
specific volume Serial Number. Beginning with version 4.0
of DOS, formatted disks are automatically assigned a Serial
Number. Use the format xxxx-xxxx, i.e.
-s14FE-779A
to supply the serial number. This is the same format used
by DOS to display the Serial Number after a disk has been
formatted.
Generally Serial Numbers will provide a more reliable method
of identifying a disk since the Serial Number is composed of
a date and time stamp when the disk was formatted. When
used with the Volume Label (-v), identification of a
specific disk is virtually assured. This parameter is
primarily intended for use by developers but may be used by
others as well.
Note that when the -s parameter is provided, WaitDisk
retrieves the Serial Number AND Volume Label from the boot
sector of the disk in the specified drive. If a disk is
inserted into the specified drive that has been formatted
with an earlier version of DOS, WaitDisk will only identify
the Current Volume as
Pre-4.0 Format
----------------------------------------------------------------
WaitDisk User's Guide Page 5
-N Prompt the user for a specific Disk Name. Don't confuse
this with the Volume Label. The -n parameter is an (up to)
28-character name which may be found on the disk label.
More than one word may be used by enclosing the name in
quotation marks.
-n"Disk 4 - Utilities"
-n"Disk Utils #4"
-n"Virus Checkers"
If WaitDisk is not provided with a disk name, a "No Disk
Name Specified" message will appear in the prompt window.
-R Specify an upper-left Row (-R) and/or Column (-C) coordinate
-C for the WaitDisk prompt window. The column coordinate must
be in the range of 1 to 32 and the row coordinate in the
range of 1 to 13. The default values, c = 28 and r = 4, are
used for any coordinate NOT passed. If a coordinate is
passed that exceeds the maximum range, the maximum value
will be used.
-X Make a Silent test of the disk in drive -D. WaitDisk will
test the drive against the parameters supplied. If the disk
is inserted, WaitDisk returns 0. If the disk is not present
or the drive is not ready, WaitDisk returns 1. The prompt
window will ONLY appear if there is an error in one of the
arguments.
** Using WaitDisk in Batch Files **
WaitDisk will automatically return an ERRORLEVEL code of 0
(zero) when the proper disk is placed into the specified drive.
If the user cancels the operation, WaitDisk returns a 1 (one).
Examples:
@ECHO OFF
REM Wait for ANY disk in Drive A
waitdisk -da
IF ERRORLEVEL 1 GOTO Canceled
IF ERRORLEVEL 0 GOTO Success
:Success
ECHO There is a disk in Drive A
GOTO QUIT
:Canceled
ECHO User Canceled Request
GOTO QUIT
:Quit
----------------------------------------------------------------
WaitDisk User's Guide Page 6
Note that in this example, if Drive A already contains a
diskette, WaitDisk will immediately return with a Success code,
without any action on the part of the user.
** Using WaitDisk in Another Program **
This is an example of using WaitDisk with Turbo C's SPAWN
function. Other languages should have similar functions. The
return codes are:
0 - Requested Disk is in Drive
1 - User Canceled Request
#include <process.h>
#include <stdio.h>
main()
{
.
.
.
if (!spawnlp(P_WAIT, "WAITDISK", "WAITDISK", "-DA",
"-V\"UTILITY 12\"", NULL))
printf("Volume UTILITY 1 in in Drive A");
else printf("User Canceled Request.");
}
Two things are worth noting. First, the second "WAITDISK" is
actually 'argv[0]', which WaitDisk ignores but is normally the
path of the called program.
Second, note the use of quotation marks inside the -v parameter.
If they aren't provided, WaitDisk will be passed the '12' of
'Utility 12' as a separate argument (#3). As a result, WaitDisk
will display the error message:
ERROR in #3: 12
----------------------------------------------------------------
WaitDisk User's Guide Page 7
** Sample WaitDisk Calls **
Following are some other valid WaitDisk calls. Note that the
mixed use of upper and lower case is intended to show the
variety of ways in which parameters may be provided.
waitdisk -db -v"Utility 1"
Wait for Volume 'UTILITY 1' to be placed into Drive B.
waitdisk -db -vmy_progs -n"Basic Utilities"
Wait for Volume 'MY_PROGS' to be placed into Drive B. The
disk is titled "Basic Utilities".
waitdisk -db -sAC09-45F4
Wait for the disk with Serial Number AC09-45F4 to be placed
into Drive B. A Volume Label and Disk Title have not been
specified.
waitdisk -da -v"sp data 2" -s11fc-a0b0 -r11 -c29
Wait for a disk in Drive A with a Volume Label of 'SP DATA 2'
and Serial Number of 11FC-A0B0. Display the WaitDisk prompt
window in the lower right corner of the screen.
** Compatibility Problems **
WaitDisk uses BIOS interrupts 13H and 24H. Some disk utilities,
such as disk caching programs, may use these interrupts as well
in ways incompatible with WaitDisk. Currently, the only known
problem is with Hyperware's HyperDisk which WaitDisk must
temporarily disable in order to operate properly. (HyperDisk is
reenabled to your configuration when WaitDisk terminates. Note
that if you have configured HyperDisk for staged updates, any
disk in the specified drive will automatically be updated, if
needed, BEFORE HyperDisk is disabled.)
If you experience problems with WaitDisk, try disabling any
devices, drivers or other TSRs you may have installed, one by
one. If WaitDisk works properly after one of these has been
removed then you are experiencing a compatibility problem.
Please report the name of the program you have removed and its
version number to the author. Every effort will be made to
ensure compatibility with popular disk utilities.
END OF FILE
----------------------------------------------------------------