BEEP - a Win32 batch utility to play simple sounds through a PC's internal 
       speaker.


Introduction
------------

BEEP.EXE is a small Win32 console-mode utility, written with Microsoft
Visual C/C++ v6.0, which plays simple sounds through a PC's soundcard or
internal PC speaker.

The utility has been written with the intent that it should be used within
Windows 95/98 batch scripts (files with a .BAT extension) and also
Windows NT 3.x/4.0/Windows 2000 batch scripts (files with a .BAT or .CMD 
extension).


Usage
-----

The program is executed using the syntax:

BEEP <frequency in Hertz> <duration>

<frequency in Hertz> may be any integer value between 37 and 10000; 
<duration> may be any positive integer value.

For example:

BEEP 250 1

- play a 250 Hertz sound for 1 (one) second.

If the program is executed without any command-line arguments, the 
following help text will be displayed:

BEEP usage: BEEP <Sound Frequency> <Duration>

<Sound frequency> (in hertz) can have a value between 37 and 10000.
<Duration> is the time (in seconds) that the sound should be made for.
Command-line arguments must be supplied in the order specified.


Just before attempting to play the sound, the program will display one of 
the following messages:

Using a frequency of nn hertz for 1 second.
Using a frequency of nn hertz for nn seconds.

where nn represents a numeric integer value.

Dozing for nn seconds .....

If a non-numeric command-line argument is supplied to the program as either 
the first or second parameter, the program will display one of the following 
messages before terminating:
    
First command-line argument XX supplied contains non-numeric or invalid 
data - terminating.
Second command-line argument XX supplied contains non-numeric or invalid 
data - terminating.

where XX represents a command-line argument.

If a negative value command-line argument is supplied to the program as 
either the first or second parameter, the program will display one of the 
following messages:

First command-line argument supplied (XX) contains a negative number ...
correcting.
Second command-line argument supplied (XX) contains a negative number ...
correcting.

where XX represents a command-line argument.

If the first command-line argument supplied to the program has a numeric
value less than 37 or greater than 10000, the program will display the 
following message before terminating:

First command-line argument supplied (XX) contains an out-of-range value ...
terminating.

where XX represents the first command-line argument supplied to the program.

If BEEP.EXE encounters a program when attempting to play the selected sound,
the program will display the following message before terminating:

Failed to process sound instruction. Error nn occured.

where nn is a numeric error code.

Note that the program's output may be directed to stdout if required, using
the > redirection character. For example: 

BEEP 500 2 > beep.txt

The nul device may also be used if required, if BEEP.EXE's message output is 
not required. For example:

BEEP 1000 3 > nul


Errorlevels
-----------

BEEP.EXE returns two possible exit values (errorlevels):

1 - A problem of some sort occurred; the program terminated abnormally.
0 - The program detected no error during execution and terminated normally.

Exit values can be checked with the 'if errorlevel' batch construct.


Testing
-------

The program has been tested on a Windows NT4.0 platform with service pack #5
applied. The program should operate within a Windows 9x COMMAND.COM session
and Windows NT 3.x/2000 CMD.EXE session, but this has not been verified due 
to a lack of test equipment.

Little testing has been performed using BEEP.EXE with large duration values - 
caveat emptor!


License/disclaimers
-------------------

See file LICENSE.TXT for further information. All registered trademarks etc.
are acknowledged.


Author's contact details.
-------------------------

Clem Dye
clem@bastet.com
