BATCH FILE TIPS AND UTILITIES

The Fourth in a series by Mitchell A. Hoselton


This month's article will introduce a trick that is just too good to be true. 
It's a method for creating small executable utilities.  It would be hard for 
the average PC user to create new utilities this way.  Doing so requires a 
thorough knowledge of machine code or assembly language programming.  However,
utility programs created by others can easily be recreated for personal use.  
There is no need to search bulletin boards to find these utilities or to order
expensive programming software to create them.  DOS owners already own all 
they require, except the script file, to create their own copies of these 
utilities.  Users can create their own script files with the same ASCII text 
editor they use to create their batch files.  DOS's DEBUG will convert the 
script file into a working utility.

PC Magazine and PC/Computing, among others, use this method in some of their 
columns to help readers create small programs.  The procedure only works for 
small utilities.  All that readers have to do is create the script file from 
the published listing in the magazine.  Then they must issue a single command 
at the DOS prompt to create the program from the script.

Every single character in a script file is important.  Even the blank lines 
are important.  It is essential to reproduce the script exactly the way it 
appears in LISTING 1.  It is essential to use a pure ASCII text editor to 
create the script.  Finally, it is essential to test every utility created 
from a script immediately to see if it works properly.  If a newly created 
utility does not work properly, erase it before it can do any damage.  Then 
edit the script to correct the mistake before attempting to create the utility
again.

This article will demonstrate the general method for using scripts by creating
ISDEV.COM, the batch file utility introduced last month.  This utility first 
appeared in the February 1991 edition of PC/Computing.  The script is in 
hexadecimal format.  This article will include another version of a script 
file later on.  That script will demonstrate DEBUG's assembler language format
and create another utility called ANSIX.COM


CREATING SCRIPT FILES


The first job is to create a script file named ISDEV.SCR.  ISDEV.SCR will be 
the input script to another program, called DEBUG.  DEBUG will read the script
and create a new file called ISDEV.COM.  First, create a subdirectory on the 
hard disk called TESTUTIL.  Copy DEBUG.EXE from the DOS directory into 
TESTUTIL.  Then use an ASCII text editor to create ISDEV.SCR and save it into 
the TESTUTIL directory.

ISDEV.SCR should contain the text lines shown in LISTING 1.

============================================================================
LISTING 1 - Script file ISDEV.SCR

N ISDEV.COM
E 0100 80 3E 80 00 03
E 0105 75 2F 80 3E 83
E 010A 00 3A 75 28 A0
E 010F 82 00 0C 20 2D
E 0114 60 00 33 DB 8A
E 0119 D8 B8 04 44 B9
E 011E 01 00 BA 56 01
E 0123 CD 21 73 28 25
E 0128 FF 00 3C 0F 72
E 012D 04 F5 EB 1E 90
E 0132 F8 EB 1A 90 BA
E 0137 5D 00 B8 00 3D
E 013C A2 65 00 CD 21
E 0141 72 0C 8B D8 B8
E 0146 00 44 CD 21 72
E 014B 03 D0 E2 F5 B8
E 0150 00 4C 14 00 CD
E 0155 21 00

RCX
57
W
Q

============================================================================

The first line in the file must be N ISDEV.COM.  There should be one blank 
line ahead of the RCX and another blank line after the final Q.  Leave single 
spaces between the groups of letters and numbers as shown.  Check and double 
check each line of the script file before attempting to create the utility 
program.  All the letters shown in the script as capitalized letters, but 
DEBUG is not case sensitive.  Use small letters if you find them easier to 
read.  Notice there is no letter O (oh) in the script.  Anything that looks 
like the letter O, is actually a numeral zero (0).


CREATING ISDEV.COM


Keep both DEBUG.EXE and ISDEV.SCR in the same directory.  Use the CD\TESTUTIL 
command at the DOS prompt to change to the directory where DEBUG and the 
script file are stored.  Still at the DOS prompt, issue the following command.

         DEBUG <ISDEV.SCR

This command will push the characters from the script file into DEBUG just as 
if they were coming from the keyboard.  The script tells DEBUG to create a 
file (N)amed ISDEV.COM and to (E)nter the code that takes up the bulk of the 
script.  The blank line ahead of the RCX marks the end of the data entry.  The
script tells DEBUG to (R)ead the CX register and store the hexadecimal value 
57h into it.  The value of 57h is the same as the decimal number 87 
((5*16)+7=87).  Putting this value in the CX register tells DEBUG to write 87 
bytes to the (N)amed file.  Then those 87 bytes are (W)ritten into the file.  
(Q)uit ends the DEBUG session and COMMAND.COM reactivates the DOS prompt.

That's all there is to it.  A few seconds after issuing the DEBUG command, the
process is complete and the DOS prompt reappears.  If the DOS prompt fails to 
appear, the PC may have to be rebooted by turning if off and on again.  This 
happens when users omit the blank line after the Q.  After the DOS prompt 
reappears, type a DIR command to be sure that DEBUG created ISDEV.COM and that
it appears in the TESTUTIL directory.


TESTING ISDEV.COM


ISDEV sets a register in COMMAND.COM called the exit code.  The exit code can 
be any value between 0 and 255, inclusive.  ISDEV sets the exit code to zero 
(0) if it finds the requested device driver name in memory and sets the exit 
code to one (1) if it fails to find the requested device driver.

There is no way to test ISDEV from the command line.  ISDEV on operates from 
within a batch file.  LISTING 2 shows a batch file written specifically to 
test ISDEV.COM.  This batch file, called TSTISDEV.BAT, performs four tests on 
ISDEV.  Two of the tests should issue exit codes of zero (0) and two should 
issue exit codes of one (1).  The IF ERRORLEVEL and IF NOT ERRORLEVEL commands
test the value of the exit code.  Next month's article will cover the IF 
command and exit codes in greater detail.  Readers should use their own disk 
drive and directory names in place of C: and TESTUTIL when writing 
TSTISDEV.BAT for their own use.

============================================================================
LISTING 2 - Text of TSTISDEV.BAT and its output when ISDEV.COM is working.

Text of TSTISDEV.BAT

@ECHO off
REM The TSTISDEV.BAT file used to test ISDEV.COM
C:
CD\testutil

ECHO Testing for Drive C:, which should be present
ISDEV C:
IF ERRORLEVEL 1 ECHO Drive C: was not found - That's BAD
IF ERRORLEVEL 1 GOTO end
ECHO Drive C: was found - OK.

ECHO Testing for Drive Z:, which should not be present
ISDEV Z:
IF NOT ERRORLEVEL 1 ECHO Drive Z: was found - That's BAD
IF NOT ERRORLEVEL 1 GOTO end
ECHO Drive Z: was not found - OK

ECHO Testing for CON, a driver name that should always be present
ISDEV CON
IF ERRORLEVEL 1 ECHO The CON driver was not found - That's BAD
IF ERRORLEVEL 1 GOTO end
ECHO The CON driver was found - OK

ECHO Testing for the phony driver called XXX000XX
ISDEV XXX000XX
IF NOT ERRORLEVEL 1 ECHO The phony driver was found - That's BAD
IF NOT ERRORLEVEL 1 GOTO end
ECHO The phony driver was not found - OK
:end
ECHO End of test.


Output from TXTISEDV.BAT when ISDEV.COM is working properly

Testing for Drive C:, which should be present
Drive C: was found - OK
Testing for Drive Z:, which should not be present
Drive Z: was not found - OK
Testing for CON, a driver name that should always be present
The CON driver was found - OK
Testing for the phony driver called XXX000XX
The phony driver was not found - OK
End of test.

============================================================================

If ISDEV.COM is working properly, TSTISDEV.BAT should produce exactly nine 
lines of output on the screen as shown at the bottom of LISTING 2.

ISDEV is working properly if all these messages and no others appear.  If 
ISDEV.COM fails this test, you must find the error before using ISDEV.COM 
again.  Assuming that TSTISDEV.BAT is correct, there must be an error in 
ISDEV.SCR.  Erase ISDEV.COM and re-edit the script file.  After finding and 
correcting the error, create ISDEV.COM from the revised script using DEBUG.

Use the [CTRL]-[BREAK] keystroke combination to terminate ISDEV if you observe
any strange characters on the screen or any other strange behavior while ISDEV
is running.  If an error in ISDEV.SCR file can't be found and the TSTISDEV.BAT
file is correct, do not try to create ISDEV.COM again.  Either there is an 
error in one of those two files or there is an error in LISTING 1.  It is not 
wise to leave a misbehaving utility on the hard disk.  Get a friend to go over
the script and batch files with you.  Sometimes fresh eyes will help.  

Try to be patient if the script does not work on the first attempt.  It should
take only a little practice and the utilities we are going to create are well 
worth a little effort.  Remember, too, that every character that appears in a 
script, including the blank spaces between groups and the blank lines, is 
important.  Each character represents a keystroke that is going to be fed into
DEBUG.  DEBUG takes each keystroke very seriously.  

If you have any doubts about how to prepare the script or how to feed it into 
DEBUG, get someone to help you.  Once you've seen it done, you'll find it is 
quite easy to do it yourself.


SOME GENERAL NOTES ABOUT BATCH FILES


It is worth mentioning a couple of points while TSTISDEV.BAT is still handy 
for reference.  

a) Batch files can contain any number of blank lines, just like CONFIG.SYS 
can.  This improves readability.  (This comment doesn't apply to script files,
so do not confuse the two.  In a script file every blank line means something 
to DEBUG and extra lines may ruin the script.)

b) The GOTO command is a very powerful way to move the execution pointer 
around in a batch file.  This is branching.  The execution pointer indicates 
the next line in the batch file that is going to execute.  The GOTO requires 
two lines of code.  The first line is the following GOTO command.

         GOTO label_name

The GOTO moves the execution pointer to the line following the line that 
contains the label_name preceded by a colon, as follows.

         :label_name

A colon (:) precedes the label_name in the second line.  In all other ways the
label_name after the colon must match the one after the GOTO.  The :label_name
can be anywhere in the batch file.  The label_name can be any combination of 
numbers and letters.  It can even include spaces, thought using spaces is 
discouraged.  It cannot include other separators such as the colon (:), period
(.),  comma (,), semicolon (;), equal sign (=), minus sign (-), plus sign (+),
slash (/), back slash (\), greater than (>), less then (<) or the piping 
symbol (|).  It may contain the underline character (_), however, and this is 
preferable to using blank spaces.

It is a bad idea to include special characters like the apostrophe ('), grave 
accent (`), tilde (~), ampersand (@), exclamation point (!), pound sign (#), 
dollar sign ($), percent sign (%), caret (^), "and" sign (&), star (*), any of
the parenthesis signs ({[]}) or the question mark (?).  Some of these will 
work and some of them won't.  The results of testing these symbols in a 
systematic way are confusing and depend on the DOS version used in the test.

It is safest to stick with simple numbers and letters, and an occasional 
underline sign (_), when creating label_names.  The search by COMMAND.COM for 
the :label_name is not case sensitive.

c) When COMMAND.COM executes a GOTO, it starts reading the batch file from the
first line and moves down through the file.  It investigates all the lines 
that start with a colon (:).  When it finds one, it compares the label_name 
following the colon with the label_name that it read after the GOTO command.  
COMMAND.COM only checks the first eight (8) characters in the label_name 
against the first eight (8) characters in the :label_name.  (The colon (:) in 
front of the :label_name does not count as one of the characters.)  
Programmers can use longer labels and strings but COMMAND.COM does not read 
the extra letters.  It will not be able to distinguish between label_names 
that only differ after the eighth place.  

If the same :label_name appears more than once in a batch file, COMMAND.COM 
will always and only find the first appearance of that :label_name.  This is 
true no matter how many times or from which places in the batch file the GOTO 
executes.

d) With some exceptions, avoid using the unconditional GOTO.  That is, avoid 
the line "GOTO label_name."  Put the code after the :label_name in the place 
where the GOTO command is sitting.  The GOTO command slows down execution of 
the batch file because COMMAND.COM has to do an extra read operation on the 
entire batch file.  Whenever possible, it is better to rearrange the lines in 
the file to avoid using the unconditional GOTO command.

e) The efficient way to use the GOTO is as a conditional GOTO.  In a 
conditional GOTO, the GOTO label_name command appears as the 
command_to_execute in an IF command.  The TSTISDEV.BAT in LISTING 2 shows how 
to do this.  In a conditional GOTO the GOTO command only executes when the IF 
test produces a true result.

f) The command_to_execute in an IF command can be another IF command.  It is 
possible to string a series of IF commands together on a single line to create
a complex test. 

g) Conditional GOTO commands can create loops as well as branches in a batch 
file.  That is, the conditional GOTO can send the execution pointer back to an
earlier part of the batch file.  It can keep sending it back until the looping
condition is no longer satisfied.

Next month I will formally introduce the IF command in all its forms and 
permutations. 


TESTING FOR ANSI.SYS


As useful as it is, ISDEV cannot test for the presence of ANSI.SYS and several
other device drivers.  That is because ISDEV only examines the installed 
device driver names.  ANSI.SYS and some other device drivers have installed 
names that DOS also uses for internal purposes.  Testing for installed device 
driver names will always find these special names even if CONFIG.SYS installs 
no device drivers.  

The March 13, 1990 edition of PC Magazine introduced the ANSIX.COM utility.  
It is a variation by Neil J. Rubenking of another utility, ANSIHERE.COM, 
created by William Loud.  The text for the script file, ANSIX.SCR, appears in 
LISTING 3.

============================================================================
LISTING 3 - Script file ANSIX.SCR

N     ANSIX.COM
A100
JMP   010D

E 102 1B'[6n$'
E 107 0D 20 20 20 20 '$'
A10D
MOV   DX,102
MOV   AH,09
INT   21
MOV   AH,0B
INT   21
CMP   AL,FF
JZ    0128
MOV   DX,107
MOV   AH,09
INT   21
MOV   AX,4C00
INT   21
MOV   AH,6
MOV   DL,FF
INT   21
JNZ   128
MOV   AX,4C01
INT   21

RCX
35
W
Q

============================================================================

The script files usually begin with the N command.  The script includes two 
obvious blank lines; one after the JMP command in line three and another ahead
of the RCX command near the end.  There must also be a third blank line after 
the Q at the end of the script.  If the script omits the third blank line, it 
may be necessary to reboot the PC after running DEBUG.

The format of ANSIX.SCR differs from the format used in ISDEV.SCR.  DEBUG can 
handle input in different forms so don't let that difference put you off.  In 
fact, ANSIX.SCR switches DEBUG from ASSEMBLER mode to ENTER mode and back 
again, all in one script.  Create ANSIX.SCR using a standard ASCII text editor
and store it in the TESTUTIL directory along with the ISDEV.SCR and all the 
other scripts that we will create in this series.

Consult the PC Magazine article for some minor caveats about ANSIX.COM and its
use.  In a batch file, ANSIX writes the ANSI Device Status Report (DSR) to the
display and then checks to see if ANSI.SYS responded by placing a Cursor 
Position Report (CPR) into the keyboard buffer.  ANSIX assumes that anything 
it finds in the keyboard buffer is a CPR issued by ANSI.SYS.  This is a less 
than ideal way to test for ANSI.SYS.  First, any press of a key while the 
batch file is running will also load keycodes into the keyboard buffer.  
Second, any program written to mimic ANSI.SYS will also respond with a CPR.  
Several such enhanced ANSI drivers are widely available.  ANSIX is, therefore,
fairly easy to fool.  In most circumstances these are not serious problems, 
and ANSIX is better than nothing.

To create ANSIX.COM from the script file, ANSIX.SCR, issue the following DEBUG
command from the DOS prompt after switching to the TESTUTIL directory.

         DEBUG <ANSIX.SCR

ANSIX.COM sets the exit code to one (1) if ANSI.SYS resides in memory and it 
sets the exit code to zero (0) if ANSI.SYS does not reside in memory.  That is
backward from the pattern used in ISDEV, but it works fine.  To get ANSIX.COM 
to respond with an exit code of zero (0) when ANSI.SYS is in memory, swap 
lines 18 and 24 with each other.  Change the name of the program on the first 
line of the script to ANSIY.COM.  Call the script with the swapped lines 
ANSIY.SCR.  Use the version, ANSIX.COM or ANSIY.COM, that best suits your 
programming style.


TESTING ANSIX.COM


To test that the ANSIX.COM created with the original script file works 
properly, use the TSTANSIX.BAT file shown in LISTING 4.  To test ANSIY.COM 
swap the two ECHO commands in the TSTANSIX.BAT file to create TSTANSIY.BAT.

============================================================================
LISTING 4 - Text of TSTANSIX.BAT

@ECHO OFF
REM The TSTANSIX.BAT file for testing ANSIX.COM
C:
CD\testutil
ANSIX
IF ERRORLEVEL 1 ECHO ANSI.SYS is present.
IF ERRORLEVEL 1 GOTO end
ECHO ANSI.SYS is not present
:end

============================================================================

One of the TSTANSIX.BAT messages appears on the screen every time it runs.  If
TSTANSIX.BAT prints the wrong message or creates strange characters on the 
display, use the [CTRL]-[BREAK] key stroke combination to stop it.  Then erase
the ANSIX.COM program from the disk.  Reedit the ANSIX.SCR script file to 
correct the mistake.  Once ANSIX.COM is working, test it both when ANSI.SYS is
and is not resident in memory.  (Use the REM command to disable the DEVICE= 
command installing ANSI.SYS in CONFIG.SYS.) 


KEY WORDS


Ampersand (@)                      
And Sign (&)                       
ANSI.SYS                           
ANSIX.COM                          
ANSIX.SCR                          
ANSIY.COM                          
ANSIY.SCR                          
Apostrophe (')                     
ASCII Text Editor                  
Assembler                          
Assembly Language Programming      
Back Slash (\)                     
Batch File                         
Branching                          
Caret (^)                          
CD (Change Directory)              
Colon (:)                          
Comma (,)                          
Command Line                       
COMMAND.COM                        
Command_to_Execute                 
Conditional GOTO                   
Curly Brackets ({})                
Cursor Position Report (CPR)       
CX Register                        
DEBUG.EXE                          
Device Driver                      
Device Status Report (DSR)         
DEVICE=                            
DIR                                
Dollar Sign ($)                    
DOS                                
ECHO                               
Equal Sign (=)                     
Exclamation Point (!)              
Executable                         
Execution Pointer                  
Exit Code                          
GOTO                               
Grave Accent (`)                   
Greater Than Sign (>)              
Hexadecimal Format                 
Hexadecimal Value                  
IF Command                         
IF ERRORLEVEL                      
IF NOT ERRORLEVEL                  
ISDEV.COM                          
ISDEV.SCR                          
JMP                                
Keyboard Buffer                    
Keycodes                           
Label_Name                         
Less Than Sign (<)                 
Looping                            
Looping Condition                  
Machine Code Programming           
Minus Sign (-)                     
Parentheses (())                   
PC Magazine - March 13, 1990       
PC/Computing - February 1991       
Percent Sign (%)                   
Period (.)                         
Piping Symbol (|)                  
Plus Sign (+)                      
Pound Sign (#)                     
Question Mark (?)                  
RCX                                
REM                                
Script File                        
Semicolon (;)                      
Separator Character                
Slash (/)                          
Special Character                  
Square Brackets ([])               
Star (*)                           
TESTUTIL Directory                 
Tilde (~)                          
TSTANSIX.BAT                       
TSTANSIY.BAT                       
TSTISDEV.BAT                       
Unconditional GOTO                 
Underline Character (_)            
[CTRL]-[BREAK]