home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Overload
/
ShartewareOverload.cdr
/
progm
/
xbatch.zip
/
XBATCH.DOC
< prev
Wrap
Text File
|
1989-04-07
|
38KB
|
2,311 lines
X-BATCH Extended Batch Commands
Version 1.1
Copyright (c) 1989 by Gary R. Pannone
All rights reserved.
You may freely distribute this version of X-BATCH if
you include this documentation file and the demo batch
files.
If you find these programs useful, please send a
contribution ($20 suggested) to the address below.
For a contribution of $25 you will receive an enhanced
version of these programs and notification of planned
future versions.
Gary R. Pannone
35 Park View Rd.
Hamden, CT 06514
If you have problems with these programs, please send
a note to the address above.
TABLE OF CONTENTS
-----------------
1. Introduction..................................1
2. Running the Demo..............................2
3. Using the Extended Batch Commands.............3
3.1 Creating Batch Files........................3
3.2 Specifying Command Parameters and Keywords..3
3.2.1 Specifying Colors.........................4
3.2.2 Specifying Line and Column Numbers........6
3.2.3 Specifying Text...........................7
3.3 Checking the ERRORLEVEL Exit Code...........7
4. Commands......................................9
BOX.........................................10
CHKENVIR....................................12
CHKSCRN.....................................14
CLRSCRN.....................................16
COMPFILE....................................18
CREATE......................................20
CURSOR......................................21
DISPFILE....................................22
DISPLAY.....................................25
GETCHAR.....................................27
SHOW........................................29
SOUND.......................................31
WAIT........................................32
1. Introduction
-----------------
X-BATCH is a collection of useful utility programs.
Some of the programs (CLRSRCN, CREATE, SHOW, SOUND)
can be used by starting them at the DOS prompt. The
programs are especially useful, however, when used as
commands in batch files.
Command Description
--------- ----------------------------------
BOX Display a box with optional border
CHKENVIR Test environment variable
CHKSCRN Search screen for text
CLRSCRN Clear screen with selected colors
COMPFILE Compare date, time, or size of files
CREATE Create a file
CURSOR Position cursor on screen
DISPFILE Display text from file in box
DISPLAY Display text on screen
GETCHAR Wait for specific keys, and report
SHOW Display date, time, or day of week
SOUND Sound a specific tone for N seconds
WAIT Wait for time of day, key, or N seconds
If this manual is printed at 6 vertical lines per inch
(the standard), the pages can be cut to fit in your
DOS manual.
1
2. Running the Demo
---------------------
An instructional demonstration is provided on this
diskette. Although the demo can be run from the
diskette, it runs much faster from a hard disk.
To run the demo:
1. Copy the files on this diskette to an empty
subdirectory on your hard disk.
2. Start the demo:
a. If you are using a monochrome monitor, type-
DEMO /M <ENTER>
b. If you are using a color monitor, type-
DEMO <ENTER>
2
3. Using The Enhanced Batch Commands
--------------------------------------
3.1 Creating Batch Files
-------------------------
You can create batch files with almost any editor that
produces standard text files. These include:
. EDLIN
. The IBM Personal Editor
. The IBM Professional Editor
. Many popular word processors
If possible, save the batch file text without imbedded
tab characters.
3.2 Specifying Command Parameters
----------------------------------
Command parameters can be values, or keywords (such as
BRIGHT), or keywords followed by one or more values.
For example:
screens.dat
CHOICES "abc"
COLORS 7 3
BRIGHT
3
This manual describes the format of each command using
the same notation as your DOS manual:
. Optional parameters are enclosed in []
. Non-optional choices are enclosed in {}
. Choices are separated with |
For example:
filename.ext
Means that you must specify a filename.
[BLINK]
Means that the keyword "BLINK" is optional.
[COLOR fg | COLORS fg bg]
Means that you can, for example, specify "COLOR 5",
"COLORS 6 5", or neither.
{BYDATE | BYTIME | BYSIZE}
Means that you must specify "BYDATE", "BYTIME", or
BYSIZE".
Keywords can be typed in uppercase or lowercase
letters. Optional parameters can be entered in any
order after required parameters.
3.2.1 Specifying Colors
------------------------
There are several parameters that can be used to
specify colors.
4
The COLORS parameter lets you specify a foreground and
a background color. For example,
COLORS 4 3
specifies a foreground color of 4 and a background
color of 3.
The COLOR parameter lets you specify just a fore-
ground color. For example,
COLOR 5
specifies a foreground color of 5.
If you have a Color/Graphics Adapter, the available
foreground colors are:
0 Black 8 Gray
1 Blue 9 Light Blue
2 Green 10 Light Green
3 Cyan 11 Light Cyan
4 Red 12 Light Red
5 Magenta 13 Light Magenta
6 Brown 14 Yellow
7 White 15 Bright White
5
If you have a Monochrome Display Adapter, the avail-
able foreground colors are:
0 Black when the background color is 0 or 7,
white otherwise.
1 Underlined white.
2-7 White.
8 Black when background is 0 or 7, bright
white otherwise.
9 Underlined bright white.
10-15 Bright white.
If you specify a low intensity foreground color (0-7),
you can make it bright by specifying the BRIGHT
parameter.
You can make the characters blink by adding 16 to the
number of the desired foreground color, or by
specifying the BLINK parameter.
Background colors are always low intensity, and must
be in the range 0 to 7.
3.2.2 Specifying Line and Column Numbers
-----------------------------------------
Line numbers are numbered from 1 to 25. Line 1 is the
top line on the screen. Line 25 is the bottom line on
the screen.
6
Column numbers are numbered from 1 to 80. Column 1 is
the left-most column on the screen. Column 80 is the
right-most column on the screen.
3.2.3 Specifying Text
-----------------------
Some parameters are text strings:
. Text to be displayed (DISPLAY command)
. Text to be search for (CHKSCRN command)
. Text to be compared (CHKENVIR command)
. Environment variable names (CHKENVIR command)
. Valid characters list (GETCHAR command)
You can specify text with or without enclosing
quotation marks. For example:
DISPLAY text AT 6 30
or
DISPLAY "Some text" AT 6 30
The quotation marks are required only if the text
contains blanks. If enclosing quotation marks are
used, a quotation mark can be imbedded in the text by
inserting a back-slash (\) in front of the quotation
mark. For example, "He said \"Hello.\"".
3.3 Checking the ERRORLEVEL Exit Code
--------------------------------------
Every command returns an exit code that can be tested
using the IF ERRORLEVEL batch command.
7
The IF ERRORLEVEL command performs the specified
action if the exit code is GREATER OR EQUAL TO the
specified number. For example, the batch command:
IF ERRORLEVEL == 2 ECHO Exit code is >= 2
will display the message "Exit code is >= 2" if the
exit code is 2, or greater than 2.
Because of the way the IF ERRORLEVEL command works, be
sure to check for the highest exit codes first. For
example, to perform different actions depending on
exit code values of 0,1,2, or 9, you can write:
IF ERRORLEVEL == 9 action
IF ERRORLEVEL == 2 action
IF ERRORLEVEL == 1 action
default action
The description of each command lists the possible
exit codes. See your DOS manual for details on using
IF ERRORLEVEL, and see the sample batch files on this
diskette for examples of exit code checking.
Note: When a command detects a syntax
error or invalid parameter, it always
displays an error message on the screen
at the current cursor position.
8
4. Commands
-------------
This chapter contains descriptions of each X-BATCH
command.
9
BOX Command
-----------
Purpose:
The BOX command displays a box on the screen.
Optionally, a border is draw around the box.
Format:
BOX [FROM line1 col1] [TO line2 col2]
[BORDER | SINGLE | DOUBLE] [NOCLEAR]
[COLORS fg bg | COLOR fg] [BRIGHT]
[BLINK]
Remarks:
Specify parameters:
[FROM line1 col1] to set the screen line and
column of the upper-left corner of the box. The
default is the upper-left corner of the screen
(line 1 and column 1).
[TO line2 col2] to set the screen line and column
of the lower-right corner of the box. The default
is the lower-right corner of the screen (line 25
and column 80).
[BORDER] to draw a block border around the box.
The border will appear in the background color.
[SINGLE] to draw a single-line border around the
box.
[DOUBLE] to draw a double-line border around the
box.
[NOCLEAR] to prevent clearing the interior of the
box (inside the border).
10
BOX Command
-----------
[COLORS fg bg] to specify the foreground color and
the background color of the box (both border and
interior). The default foreground color is white
(7) and the default background color is black (0).
Note: See section 3.2.1 for a list of
the color choices.
[COLOR fg] to specify the foreground color.
[BRIGHT] to specify a bright foreground color.
[BLINK] to make the displayed characters blink.
Notes:
Borders connect the screen coordinates given by
the FROM and TO parameters. That is, the border
around a box specifed with the parameters "FROM 4
10 TO 20 70", will start on line 4 not line 3.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
BOX FROM 4 10 TO 20 69 COLORS 15 1
Clears a blue box, and sets the foreground color
within the box to bright white. The upper-left
corner of the box is at line 4 column 10.
BOX FROM 4 10 TO 20 69 COLORS 15 1 SINGLE NOCLEAR
Draws a bright-white-on-blue single line border
around a box. The upper-left corner of the border
is at line 4 column 10. The interior is unchanged.
11
CHKENVIR Command
----------------
Purpose:
The CHKENVIR command checks whether an environment
variable is defined, or whether it is set to a
specific value.
Format:
CHKENVIR varname [DEFINED | EQUALS "value" [CASE]]
Remarks:
Specify parameters:
[DEFINED] to test whether the variable is defined.
[EQUALS] "value" to test whether the variable is
set equal to "value".
[CASE] to make a case-sensitive comparison (upper-
case and lowercase letters are not considered
equal).
Notes:
DEFINED is the default action.
The quotation marks are required only if the value
contains blanks. If enclosing quotation marks are
used, a quotation mark can be imbedded in the text
by inserting a back-slash (\) in front of the
quotation mark. For example, "He said \"Hello.\"".
12
CHKENVIR Command
----------------
Returned exit codes:
0 Defined, or Equal to
1 Not equal to
2 Not defined
9 Command syntax error or invalid parameter
Examples:
CHKENVIR path DEFINED
Tests whether the environment variable PATH is
defined. The exit code is set to 0 if it is
defined, or 2 othewise.
CHKENVIR comspec EQUALS "C:\COMMAND.COM"
Tests whether the environment variable COMSPEC is
equal to "C:\COMMAND.COM" (uppercase and lowercase
letters are considered equivalent). The exit code
is set to 0 if it is equal, 1 if COMSPEC is
defined to a different value, or 2 if COMSPEC is
undefined.
13
CHKSCRN Command
---------------
Purpose:
The CHKSCRN command searches the screen for a text
string. You can check every line of the screen,
or only one line.
Format:
CHKSCRN "text string" [LINE n]
Remarks:
Specify parameters:
[LINE n] to check only screen line n.
Notes:
For CHKSCRN to find a match, the complete text
string must fit completely on one screen line.
Uppercase and lowercase letters are considered
equal.
The quotation marks are required only if the text
contains blanks. If enclosing quotation marks are
used, a quotation mark can be imbedded in the text
by inserting a back-slash (\) in front of the
quotation mark.
Returned exit codes:
0 Found
1 Not found
9 Command syntax error or invalid parameter
14
CHKSCRN Command
---------------
Examples:
CHKSCRN "Can't create directory"
Searches every line of the screen for the text
"Can't create directory".
CHKSCRN "Can't create directory" LINE 2
Searches screen line 2 for the text "Can't create
directory".
15
CLRSCRN Command
---------------
Purpose:
The CLRSCRN command clears the screen and sets the
selected foreground and background colors.
Format:
CLRSCRN [BCOLOR bg | COLORS fg bg] [BRIGHT]
[BLINK]
Remarks:
Specify parameters:
[COLORS fg bg] to specify the foreground and
background colors to be used. The default
foreground color is white (7), and the default
background color is black (0).
Note: See section 3.2.1 for a list of
the color choices.
[BCOLOR bg] to specify the background color.
[BRIGHT] to specify a bright foreground color.
[BLINK] to make the displayed characters blink.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
16
CLRSCRN Command
---------------
Examples:
CLRSCRN
Clears to screen to white on black. Equivalent to
the DOS CLS command.
CLRSCRN BCOLOR 4
Clears the screen to white on red.
CLRSCRN COLORS 4 2
Clears the screen to red on green.
17
COMPFILE Command
----------------
Purpose:
The COMPFILE command compares the sizes or
creation dates/times of two files.
Format:
COMPFILE [d:][path]filename1.ext
[d:][path]filename2.ext
{BYDATE | BYSIZE | BYTIME}
Remarks:
Specify parameters:
BYDATE to compare the creation dates of the files.
BYSIZE to compare the sizes of the files.
BYTIME to compare the creation dates and times of
the files. The dates are compared. If the dates
are equal, the times are compared.
Returned exit codes:
0 Equal to
1 File1 > file2
2 File2 > file1
9 Command syntax error or invalid parameter
Examples:
COMPFILE demo.bat dd2.dat BYDATE
Compares the creation dates of the files demo.bat
and dd2.bat.
18
COMPFILE Command
----------------
COMPFILE demo.bat dd2.dat BYTIME
Compares the creation dates and times of the files
demo.bat and dd2.bat.
19
CREATE Command
--------------
Purpose:
The CREATE command creates a file.
Format:
CREATE [d:][path]filename.ext
Remarks:
The CREATE command creates a zero-length (empty)
file if the file does not currently exist.
Returned exit codes:
0 Success
1 Already exists
2 Can't create
9 Command syntax error or invalid parameter
Examples:
CREATE temp.dat
Looks for a file called TEMP.DAT. If the file does
not exist, CREATE creates it.
20
CURSOR Command
--------------
Purpose:
The CURSOR command positions the cursor on the
screen.
Format:
CURSOR AT line col
Remarks:
The CURSOR command moves the cursor to the
specified line and column.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
CURSOR AT 2 5
Moves the cursor to the fifth column on the second
line.
21
DISPFILE Command
----------------
Purpose:
The DISPFILE command reads text from a disk file
and displays it in a box on the screen.
Format:
DISPFILE [d:][path]filename.ext [SCREEN n]
[FROM line1 col1] [TO line2 col2]
[BORDER | SINGLE | DOUBLE | EDGE]
[COLORS fg bg | COLOR fg] [NOCLEAR]
[BRIGHT] [BLINK]
Remarks:
Specify parameters:
[SCREEN n] to specify what text is to be
displayed. The screens are numbered starting at 1.
The text in the file must be separated into
"screens" by lines that begin with two dollar
signs ($$). The default screen number is 1.
Note: The DISPFILE command may not
work as expected if the text contains
tab characters, or other control
characters.
[FROM line1 col1] to set the screen line and
column of the upper-left corner of the box. The
default is the upper-left corner of the screen
(line 1 and column 1).
[TO line2 col2] to set the screen line and column
of the lower-right corner of the box. The default
is the lower-right corner of the screen (line 25
and column 80).
22
DISPFILE Command
----------------
[BORDER] to draw a block border around the box.
The border will appear in the foreground color.
[SINGLE] to draw a single-line border around the
box.
[DOUBLE] to draw a double-line border around the
box.
[EDGE] to draw a block border around the box. The
border will appear in the background color.
[COLORS fg bg] to specify the foreground color and
the background color of the box (both border and
interior).
Note: See section 3.2.1 for a list of
the color choices.
[COLOR fg] to specify the foreground color.
[NOCLEAR] to prevent clearing the interior of the
box (inside the border) before displaying the
text.
[BRIGHT] to specify a bright foreground color.
[BLINK] to make the displayed characters blink.
Notes:
Borders connect the screen coordinates given by
the FROM and TO parameters. That is, the border
around a box specifed with the parameters "FROM 4
10 TO 20 70", will start on line 4 not line 3.
23
DISPFILE Command
----------------
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
If the file TFILE.TXT contains the following text,
Screen 1 line 1
Screen 1 line 2
Screen 1 line 3
$$
Screen 2 line 1
Screen 2 line 2
Third line on Screen 2
$$
this command,
DISPFILE tfile.txt SCREEN 2 FROM 4 4 TO 12 76
displays the following text in the box:
Screen 2 line 1
Screen 2 line 2
Third line on Screen 2
24
DISPLAY Command
---------------
Purpose:
The DISPLAY command displays text on a line of the
screen.
Format:
DISPLAY "text" [AT line col | LINE line] [CLEAR]
[COLORS fg bg | COLOR fg] [CENTER]
[NORETURN] [BRIGHT] [BLINK]
Remarks:
Specify parameters:
[AT line col] to specify the screen line and
column where the text should be displayed.
[LINE line] to specify the line on which the text
should be displayed. The text is displayed
starting in column 1 unless the [CENTER] parameter
is also specified.
[CLEAR] to clear the entire line before the text
is displayed.
[COLORS fg bg] to specify the foreground color and
the background color of the text.
Note: See section 3.2.1 for a list of
the color choices.
[COLOR fg] to specify the foreground color.
[CENTER] to center the text on the line.
25
DISPLAY Command
---------------
[NORETURN] to leave the cursor at the end of the
text after it is displayed.
[BRIGHT] to specify a bright foreground color.
[BLINK] to make the displayed characters blink.
Notes:
If neither the LINE, nor the AT parameters are
specified, the text is displayed at the current
cursor position.
The quotation marks are required only if the text
contains blanks. If enclosing quotation marks are
used, a quotation mark can be imbedded in the text
by inserting a back-slash (\) in front of the
quotation mark. For example, "He said \"Hello.\"".
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
DISPLAY "any text" AT 3 10 COLORS 14 1
Displays "any text" on line 3 at column 10 in
yellow on blue.
26
GETCHAR Command
---------------
Purpose:
The GETCHAR command waits for the user to press a
key, and then returns the key's ASCII value.
Format:
GETCHAR [CHOICES "keys"] [AT line col]
[NOECHO] [CASE]
Remarks:
Specify parameters:
[CHOICES "keys"] to specify which keys to wait for
(by default, GETCHAR waits for any key). For
example, to wait for the M or K keys, specify:
CHOICES "mk" or CHOICES "MK" , etc.
[AT line col] to specify where to position the
cursor while waiting for the user to press the
key. If the AT parameter is not specified, the
cursor position is unchanged.
[NOECHO] to prevent GETCHAR from displaying the
character equivalent of the key on the screen.
[CASE] to specify that lowercase and uppercase
letters are NOT to be treated as equivalent.
27
GETCHAR Command
---------------
Notes:
You can specify special keys, such as the ENTER
key, by inserting a back-slash (\) followed by the
decimal value of the key's ASCII value. ASCII
values of 1 to 126 are allowed. For example:
Key Name Insert
----------- ------
ENTER \013
ESC \027
TAB \009
BACKSPACE \008
The quotation marks are required only if the text
contains blanks. If enclosing quotation marks are
used, a quotation mark can be imbedded in the text
by inserting a back-slash (\) in front of the
quotation mark. For example, "ab\"cd".
Returned exit codes:
1-126 ASCII value of key pressed
255 Command syntax error or invalid parameter
Examples:
GETCHAR
Waits until the user presses any key.
GETCHAR CHOICES "ab\027"
Waits until the user presses the A key, the B key,
or the ESC key.
28
SHOW Command
------------
Purpose:
The SHOW command displays the current date, time,
or day of the week.
Format:
SHOW {DAY | DATE | TIME | TIME12} [AT line col]
[NORETURN] [COLORS fg bg | COLOR fg]
[BRIGHT] [BLINK]
Remarks:
Specify parameters:
DAY to display the day of the week (e.g., Monday).
DATE to display the current date (e.g., 12/01/88).
TIME to display the current time in 24-hour format
(e.g., 17:15 is 5:15 PM).
TIME12 to display the current time in 12-hour
format (e.g., 5:15 is both 5:15 AM and 5:15 PM).
[AT line col] to specify the position on the
screen where the information should be displayed.
If the AT parameter is not specified, the text is
displayed at the current cursor position.
[NORETURN] to leave the cursor after the last
character displayed.
29
SHOW Command
------------
[COLORS fg bg] to specify the foreground color and
the background color of the displayed text.
Note: See section 3.2.1 for a list of
the color choices.
[COLOR fg] to specify the foreground color.
[BRIGHT] to specify a bright foreground color.
[BLINK] to make the displayed characters blink.
Notes:
If the AT parameter is not specified, the text is
displayed at the current cursor position.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
SHOW DATE
Displays the current date at the current cursor
position.
SHOW TIME AT 6 20 COLOR 14
Displays the time at line 6 column 20 in yellow on
black.
30
SOUND Command
-------------
Purpose:
The SOUND command sounds a tone (beeps).
Format:
SOUND [FREQ frequency] [FOR secs]
Remarks:
Specify parameters:
[FREQ frequency] to specify the frequency of the
tone. The default is 1000.
[FOR secs] to specify the duration of the tone in
seconds. The default is 1 second.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
Examples:
SOUND
Sounds a 1000 hertz tone for 1 second.
SOUND FREQ 3000 FOR 3
Sounds a 3000 hertz tone for 3 seconds.
31
WAIT Command
------------
Purpose:
The WAIT command waits for an event.
Format:
WAIT {ANYKEY | FOR secs | UNTIL time}
Remarks:
Specify parameters:
ANYKEY to wait until the user presses any key.
FOR secs to wait until a specific number of
seconds have passed.
UNTIL time to wait until a specific time of day.
The time must be specified as hh:mm in 24-hour
time.
Note: Both the hours and minutes must
be specified as 2-digit numbers. For
example, 7 AM is specified as 07:00,
not 7:00.
Returned exit codes:
0 Success
9 Command syntax error or invalid parameter
32
WAIT Command
------------
Examples:
WAIT anykey
Waits until the user presses any key.
WAIT FOR 5
Waits for 5 seconds.
WAIT UNTIL 13:05
Waits until 1:05 PM.
33
