Dr. Batch File's Ultimate Collection: Chapter 1

Chapter 1
Anatomy of a Batch Files

My first book on batch files was MS DOS Batch Files Programming, which is now in its third edition. That book proved to be so popular that TAB BOOKS had me to write two more, MS DOS Batch File Utilities and Batch Files To Go. Those proved to be so popular that TAB BOOKS ask me to write Dr. Batch File's Ultimate Batch File Collection.

In the process of writing all these batch file books, I have written over 500 batch files! In addition, I've looked at countless batch files written by others. In the process of looking at all these batch files, I've developed some ideas on what a batch file should look like. I've tried to follow these ideas in writing the batch files in this book and I've found that it made the process much easier.

Too Much Documentation Is Never Enough!

As I mentioned above, between all my batch books I have a collection of over 500 batch files. I went back and reviewed many of them before starting this book and it struck me just how difficult it is to figure out what a batch file does just by looking at the code itself.

The primary method you have for documenting a batch file is by burying remark lines inside the batch file itself. That way, anyone looking at the batch file will be able to read your comments as they try to follow along. Of course, these comments are only useful if you use a lot of them and make them truly explanatory. Unless you have a very slow computer, even a large number of remarks will not significantly slow down your batch files.

A second form of documentation you can use is written documentation. You will find that in this book in the tables that list most of the batch files. The batch file code is on the left and a detailed explanation is on the right. Of course, you probability will not need to document your batch files in this level of detail. You may find it adequate to simply print out a listing of your batch files and write margins in the notes.

In my other batch file books, these two forms (internal remarks and tables) were the only documentation I used. In this book, I've added a third form, user documentation. In Chapter 20, you'll find a brief description of what each batch file does and what it needs as an input. If you use a lot of batch files on your system, you might find it useful to keep a similar listing of your own batch files. You might also find it useful to keep this sort of documentation on the utility programs you add to your system.

Self Documentation

DOS 5.0 adds a nifty new feature to most of its commands. If you're not sure what they do or how to use them, you can start them with a /? switch and get a screen of helpful information. That makes it quick and easy for the user to find out what a program does or what inputs it needs. I expect that, over time, this will be added to most programs.

Implementing it in the batch files is fairly easy. A section of code near the top of each of my batch files tests to see if the first replaceable parameter is a /?. If it is, the batch file displays a help screen and exits to DOS. I used the /? switch to be consistent with DOS 5.0 but personally, I don't see the need to type in two characters to get help. Therefore, all my batch files will also respond to just the question mark without the slash.

Starting Off Right

There is some information that is important enough that every batch file needs to have it. Since it's that important, we may as well put it at the top of each batch file. The first five lines of each batch file should be:

@ECHO OFF Unless you have some very good reason for echoing the commands, the first line of every batch file you write should turn command-echoing off. If you leave echo on, the screen quickly becomes cluttered and confuses the user.
REM NAME: The second line of the batch file gives the name of the batch file. This is not critical since you know the name from the DOS file name. However, some of the very useful batch files in Chapter 3 depend on finding this line so it's important to include it in each batch file.
REM PURPOSE: The third line of the batch file gives the purpose of the batch file. It will be important that you enter purpose in all capital letters and follow it immediately with a colon. In the sample batch files in the book, I've kept the purpose line fairly short and used multiple lines for a longer purpose. I've done that so the tables would look proper. It's actually better if you put a complete purpose on one line.
REM VERSION: The first version of the batch file is 1.00. A tiny change would make it 1.01, a larger change would make it 1.10 and a major change would make it 2.00. Since batch files tend to evolve over time, this line is a good indicator of how long a batch file has been in use. You may notice that many of the batch files in the book are version 1.0. That is not because I write perfect batch files each time. Rather, my batch files under go extensive beta testing before they are added to my book. As is common with many software vendors, I begin numbering my beta copies at zero. They only reach number 1.00 after they have finished this extensive beta testing. As a result, they don't get a number higher than 1.00 unless I enhance them or fix a bug after they finish of beta testing.
REM DATE: This is the date of the last modification to the batch file. A batch file that has not been updated for a very long time is either very stable or not used very often.

Following this scheme, the top of a typical batch file will look something like this:

@ECHO OFF
REM NAME: MULTI.BAT
REM PURPOSE: Issue Multiple DOS Commands On a Single Line
REM VERSION: 1.10
REM DATE: May 7, 1991

If you study the sample batch files that come with this book, you will see that almost all of them follow this documentation scheme. It is also important that you decide on a capitalization scheme for the text. Some of the batch files in Chapter 3 allow you to search for specific text in these batch files and that is easier if you know how that text is capitalized.

A Different Kind Of Top

The above scheme requires an REM at the beginning of each line so DOS will treat the line as a remark and skip it. If you plan on entering a lot of documentation at the top of the batch file, it can be tiring to type REM at the beginning of each line. You can avoid this by adding a label below the documentation where the working commands of the batch file start and making the second line of the batch file a GOTO command to jump over the remarks. Using that scheme, the top of the above batch file would look like this:

@ECHO OFF
GOTO TOP
NAME: MULTI.BAT
PURPOSE: Issue Multiple DOS Commands On a Single Line
VERSION: 1.10
DATE: May 7, 1991

:TOP

The GOTO TOP command causes DOS to skip over all the remarks so they don't need the REM at the beginning to tell DOS to skip over them. However, this approach looks a little confusing to users not expecting it so you might want to reserve using it to batch files with a lot of comments at the top.

Speaking Of Capitalization

In working with batch files, I've developed a style of capitalization I'm comfortable with. Since you'll be reading a lot of my batch files, I will explain my style:

I use all capital letters for batch commands, DOS commands and program names.
I capitalize the first letter of each word in most messages and remarks.
When a message tells you what to enter on the command line, I capitalize the command line.
When a message is very important, I capitalize the entire message, something like WARNING: THIS TAKES AN HOUR.
When a message is extremely important, I surround it with asterisks, something like **WARNING: THIS TAKES ALL NIGHT**.

Spacing

In a long batch file, it can be difficult to see the different sections if you enter text on each line. To visually break the batch file up into different sections, I leave one or more blank lines between each section. These blank lines do not affect the operation of the batch file but they do make it much easier to read.

While the batch files in this book do have blank lines between the sections, I've left those blank lines out of the tables. I've found that while blank lines enhance the readable of batch files, they do not enhance the tables.

Section Markers

Many of my batch files have discrete sections that perform one task, like displaying help or an error message. As I mentioned above, I separate these sections with blank lines. In addition, I also use markers to differentiate the sections.

Most sections begin with a label (like :HELP) so the batch file can jump to that section when needed. When a section begins with a label, I also end it with a label. I construct this label by adding END plus an underscore to the label used for the top of the section. So the help section would end with an END_HELP label and might look like this:

:HELP
ECHO This Batch File Runs You Backup Program
ECHO You Must Start It With Either An F or I
ECHO On The Command Line
ECHO The F Is For A Full Backup
ECHO The I Is For An Incremental Backup
GOTO END
:END_HELP

Adding four characters to the beginning of a label will often make that label exceed eight characters and most versions of DOS limit labels to eight characters of less. When a label exceeds eight characters, most version of DOS only consider the first eight characters. As a result, DOS would treat END_ERROR1, END_ERROR2 and END_ERROR3 as the same label, namely END_ERRO. As a result, you generally can not GOTO a label marking the end of a section. That should not be a problem. Since these labels are at the end of a section you should not need to jump to them.

Additionally, some batch file compilers and a few versions of DOS will object if you use long labels. If you face that problem, you can add an REM to the front of the label so DOS or your compiler treats the offending line as a remark.

Indenting Sections

I've also found that it can be useful to indent the lines of a section between the beginning and ending label of the section. If you do that, the above batch file segment looks like this:

:HELP
 ECHO This Batch File Runs You Backup Program
 ECHO You Must Start It With Either An F or I
 ECHO On The Command Line
 ECHO The F Is For A Full Backup
 ECHO The I Is For An Incremental Backup
 GOTO END
:END_HELP

As you can see, it makes it clear which statements belong in this section. This is especially useful in longer batch files.

Because of the limited space in the tables, I have not indented the sections for the batch files in this book. However, this is something I do use on my own personal batch files. Also note that some batch file compilers require labels to start at the left margin so you may not be able to indent labels.

Message Length

You will notice that most of the echo commands in my batch files have fairly short lines. For longer messages, I use multiple echo commands rather than longer lines. It's been my experience that shorter lines are easier to read on the screen than longer ones. It's a lot like printing your documents in multi-column format only the batch files only use the left column.

Summary

Internal documentation makes it easier to modify a batch file at a later date.
Batch files that can display help when started with a /? switch make it easier for the user to find out how to use them.
Most batch files should start with a line to turn off command echoing and lines giving the name, purpose, revision number and revision date of the batch file.
A batch file can avoid needing an REM command at the start of each remark line by using a GOTO command to jump over the remarks.
Using consistent capitalization makes it easier to read a batch files.
Blank lines between sections can make a batch file much more readable.
Using labels to mark the end of a section can make a batch file much easier to follow.
Indenting the commands within a section is a nice way to visually highlight the boundaries of a section.
Messages using shorter lines are easier to read than messages using longer lines. Of course, using shorter lines requires additional lines to display the entire message.

Important Notice

The information for this book was taken from the last draft I submitted to the publisher. Since the publisher performed minor editing, the version you purchase in the store will be slightly different.

Order This Book On-Line

Order One Of These Books. Amazon.com is an on-line bookstore with a very large list of books, including all of mine that are still in print. This link will take you to Amazon.com using a special page they set up to showcase all my books. They are the easiest way I know of to order my books on-line. Of course, you can use this page to order any of the books they carry.