ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/UTILITY/BATCH/RING13.ZIP/RING.DOC

Text File | 1990-08-28 | 7.8 KB | 208 lines

                                  RING, v1.3
                                -------------
                                from TifaWARE




What's New
----------


     With version 1.3 I have substantially reorganized RING's source code,
placing commonly-used routines in libraries and useful equates and macros
in separate files. From the user's point of view, however, there should be
no change in the program. Sharing code, equates and macros in this way
will make it easier for me to both develop and maintain other assembly
language programs.

     Version 1.2 introduces the '-e' option. If you're running DOS v3.30
you can use this option to sound a bell only when the previous program had
a non-zero return code; ie, exited with an error. This provides an ideal
way to notify users of problems when used in a batch file.

     Many of the principal functions in RING have been completely
rewritten for version 1.1. These changes will make it easier for me to
revise the program. From the user's point of view, though, nothing will
have changed.




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


     The PC has brought about great strides in productivity recently, but
one problem has been the lack of multitasking features in MS-DOS.  If you
have a long job to run, you not only tie up the computer but you also must
glance at the screen every once in a while to figure out whether the job
has finished.  Either that, or you risk leaving the computer idle because
you don't know how long the job will take.  This is clearly inefficient.

     RING provides a poor man's approach to multitasking.  No, it doesn't
let you run two programs at the same time; instead, it merely rings the
console bell a few times.  What's this got to do with multitasking, you
ask? It's quite simple - start your job in the usual fashion, type "RING",
and walk away.  While your computer's doing one task, you're free to go
about another - read a newspaper, grab a cup of coffee, shuffle some papers
around your desk, or talk with any who happens by your office.  As soon as
your job has finished, the PC's console bell will sound, advising you it's
time for more work.




Usage
-----


     Running this program is a breeze.  Assuming you've placed RING.COM on
your system where DOS can find it, type RING -? to display a brief help
message similar to the following:

     TifaWARE RING, v1.3a, 08/28/90 - rings the console bell.
     Usage: ring [-options] [count]

     Options:
       -e = ring bell only if errorlevel is non-zero
       -? = display this help message

     count denotes a repetition count and must be between 0 and 15.
     The default value of count is 3.

[If you don't remember anything else from reading the documentation, at
least remember how to display this help message.]

     Normally, you'll invoke RING without any arguments, and the console
bell will sound three times.  This is probably fine in most situations.
However, RING also allows you to specify how many times the bell should
ring - anything between 0 and 15 times.  Thus, you could create a batch
file to run a program and then ring the bell 1 time if the program was
successful and 15 times otherwise.

     With the '-e' option you can ring the console bell conditional on the
previous program's return code. No matter what that program was, RING will
examine its return code and sound the console bell only if it is non-zero.
Further, it uses this return code as its own. Thus, the main difference
between "RING -e" and the batch command "if errorlevel 1 RING" is that the
first command preserves the value of ERRORLEVEL from the previous program
while the second does *not*. This enables you to write cleaner batch files
yet still report errors. [NB: This option relies on undocumented
"features" of MS-DOS and hence may not work on all versions of DOS. Please
contact me if you're not running DOS v3.30 but would still like to use
this option.]




If You Have Any Trouble
-----------------------


     RING will attempt to let you know of any problems that arise.  Here
are the messages you might see and how you should deal with them:

     ring: invalid option -- x.
          - Type "RING -?" for a list of valid options.

     ring: invalid repetition count -- 100.
          - The repetition count must be an unsigned integer
            between 0 and 15. Note: RING reacts sensibly if
            a count of 0 is specified.

     ring: unable to locate errorlevel.
          - Make sure you're using COMMAND.COM as the parent
            shell and that it's from a supported version of
            DOS. [Currently only PC/MS-DOS v3.30 is supported.]

These error messages are written to the standard error device.  In this
way, they won't disappear down a pipe or into a file should you try to
redirect RING's output, although I can't imagine why you would ever do
this.

     Additionally, RING uses a return code to convey information about the
success or failure of its operation.  Possible return values are:

     Code      Meaning
     ----      -------
     0         Program completed successfully
     1         Help message was displayed

if the '-e' option was *NOT* specified or whatever the previous program's
return code was otherwise. You can test for these codes using the
ERRORLEVEL variable in a batch file.




Requirements
------------


     TifaWARE RING runs on machines operating under MS-DOS v2.xx or later,
and requires less than 2K of memory! [NB: To use the '-e' option, you must
be operating MS-DOS v3.30.] It does not use BIOS calls, make direct writes
to video RAM, or otherwise require machines to be "PC-compatible".  In
fact, RING even runs properly on a DEC Rainbow!




Who Owns It?
------------


     I am releasing this implementation of RING into the public domain.
Since my involvement with MS-DOS began in 1984, I've been a heavy user of
public domain software.  Public domain software is a terrific idea.  For
the most part, programs are useful and the source code instructive, all at
no cost! With this small contribution to the public domain I hope to pay
back, in some sense, my gratitude to those other programmers who have made
my computing so much easier.

     As a public domain program, RING carries no obligation on my part to
support users or provide future upgrades.  I have tried to write clean code
and believe it to be "bug-free".  Nevertheless, you must use this program
***AT YOUR OWN RISK***.  I strongly urge you to scan the source code
yourself, make any desired changes, and recompile the program, if this is
possible.  If you make this standard practice with newly acquired public
domain software, you'll not only protect your system from worms and viruses
but also get a better feel for exactly how each program works!

     As author of RING, I ask of you two things: First, if you distribute
this program, please keep together my original source code, documentation,
and executable.  This just makes it easier for others to use the software.
Second, let me hear what you think of RING.  You don't have to send any
money, just comments and suggestions.




Kudos
-----


     Many thanks go to Borland for its stand-alone debugger, which greatly
reduced the time spent developing this program. Thanks are also due to
Josep Fortiana Gregori (D3ESJFG0@EB0UB011) for providing a code fragment
suggesting how to locate ERRORLEVEL in memory and to Yan Juras for
pointing out where exactly to look.





                          George A. Theall

                             TifaWARE
                       506 South 41st St., #3M
                      Philadelphia, PA.  19104
                              U.S.A.

                         [phone]

              [e-mail] (ARPA Internet)