IBM batch programs provide a convenient way to carry out a series of DOS (Disk Operating System) commands at once. This month we'll cover some batch programming fundamentals. Part 2 will show how to add multiple-option menus, color, and graphic displays to batch programs.

---

In IBM parlance a batch program is simply a disk file containing a series (batch) of DOS commands. The batch file executes these commands in sequence, just as if you manually typed them yourself. Batch files are identified with the BAT filename extension. The most familiar example of a batch program is AUTOEXEC.BAT, used to issue startup commands to configure the system to your liking. Here's what a typical AUTOEXEC.BAT file might contain:

MODE CO80
DATE
TIME
CHKDSK
BASICA MENU
    The first four commands in this batch file are familiar DOS commands to set the display mode to 80 columns, let you input the date and time, and analyze the disk directory. (Note that if the AUTOEXEC.BAT file doesn't include DATE and TIME, the system doesn't ask for date and time inputs when it boots.) The last command activates BASICA, then loads and runs a BASIC program named MENU. A file named AUTOEXEC.BAT differs from other batch files only in that it runs automatically when you turn on the system.
    To run a batch program that doesn't automatically run, simply enter the filename at the DOS prompt (you can leave off the BAT extension). This tells DOS to load the batch file from disk and carry out each of its commands in order. For instance, to run a program named SETUP.BAT you would type SETUP after the DOS prompt and press Enter.
    This article presents several example batch programs. Since these are not BASIC programs, don't try to enter them with the "IBM Automatic Proofreader." The DOS manual explains how to type in short batch programs using the COPY CON: command from DOS. However, for any batch program longer than a few lines, it's easier to use a word processor or any text editor that creates standard ASCII files. Most commercial programs are suitable. You can also use the EDLIN program (on the DOS Supplemental Programs disk), though it lacks the convenient editing features of word processors.

Chains And Parameters
In the AUTOEXEC.BAT example above, the batch program ends by loading BASIC and running a BASIC program. A batch program can also end by returning control to DOS, or by running a second batch program (permitting you to "chain" two or more programs together). For instance, ending a batch program with SECOND causes the system to load and run the batch program named SECOND.BAT. You can also use COMMAND /C to run one batch program from within another: For example, COMMAND /C SECOND runs SECOND.BAT.
    Passing parameters (information) to a batch program is straightforward. Simply include the needed information after the filename when running the program. For example, typing FIRST JULIA 123 runs the FIRST.BAT program and passes two parameters to it: a string (JULIA) and a number (123). In much the same way, one batch program can pass parameters to another. Let's use an example to demonstrate parameter passing in chained programs. Enter the following batch program and save it to disk with the filename FIRST.BAT:


Now enter the following program and save it with the filename SECOND.BAT:


Finally, enter the following program and save it with the filename THIRD.BAT:


    At this point you have three batch programs, all of which expect parameters. To run the programs, enter FIRST followed by any three strings or numbers. Be sure to separate each parameter with a space. For instance, you might enter FIRST PARAM/ONE &H464 IBMBIO.COM. The FIRST.BAT program takes in all three parameters, processing the first (displaying it in an ECHO statement) and passing the other two when it runs SECOND. SECOND.BAT processes the second parameter and passes the third to THIRD.BAT.
    As shown in these examples, batch programs use dummy parameters (% followed by a digit from 0-9) to mark the spot where the real parameter is expected. When you run a batch program, each dummy parameter is replaced by actual data in the order it is received. Thus, the FIRSIBAT program above uses % 1 to signify the first parameter, %2 to represent second, and so on. Dummy parameter %0 can only be replaced by a drive designator (A or B) and filename: Don't use it unless you want to pass such information.
    Be sure to keep the dummy parameter numbers straight when chaining batch programs. The dummy number represents the order in which that program receives the data. In the example above, FIRST.BAT received three parameters, which it represents with the three dummies %1, %2, and %3. SECOND.BAT receives two parameters, using % 1 to signify the first parameter it receives, and %2 to represent the second. Likewise, THIRD.BAT uses %1 to represent its single parameter. (Note that THIRD.BAT can't use %3 for the dummy. Though you, the programmer, may think of this parameter as the "third," it's the first one that THIRD.BAT receives.)

Batch Commands
In addition to ordinary DOS commands, a batch program may include the following special batch commands: ECHO, FOR, GOTO, IF, SHIFT, PAUSE, and REM. ECHO ON causes DOS commands to be displayed as they're performed in a batch program; ECHO OFF turns off the display. As you saw above, ECHO can also display messages. GOTO is discussed in Part 2 of this article. REM lets you include remarks, and SHIFT is used when more than ten parameters are passed at one time.
    The remaining commands (FOR, IF, and PAUSE) permit loops, conditional tests and limited user input. The short file copying program listed below demonstrates all three of these commands. Enter the program as listed, saving it with the filename COPYUNQ.BAT (or any other name ending in .BAT).


ECHO off
REM----------------------------
-------------------------------
--------
REM name: COPYUNQ.BAT
REM syntax: COPYUNQ
 source-drive-letter
 target-drive-letter (no
 colons)
REM purpose: Only unique files
 are copied from source to
 target disk
REM----------------------------
-------------------------------
--------
%1:
FOR %%f in (*.*) DO IF exist
 %2:%%f ECHO %%f WILL NOT BE
 COPIED
PAUSE READY TO BEGIN COPIES,
FOR %%f in (*.*) DO IF not
 exist %2:%%f COPY %1:%%f %2:
 /V
%2:

    The COPYUNQ.BAT program automatically copies files from a source disk to a target disk, copying only those files that don't already exist on the target disk. This ensures that existing files are not replaced, an improvement over DOS's COPY command, which would write over any like-named files on the target disk. To run this program, enter its name followed by the letter of the source drive and the letter of the target drive. Colons are not required after the drive letters. For instance, you would enter COPYUNQ.BAT A B when drive A holds the source disk and drive B holds the target disk. The program displays the names of files that are not copied.

FOR And IF
COPYUNQ.BAT offers a good demonstration of FOR and IF, which work very differently than their BASIC equivalents. Since a FOR statement can't contain another FOR statement, you can't use nested FOR loops (one FOR loop enclosed by another). FOR statements take the following general form:

FOR %%variable IN (set) DO DOS
 command

    The set value after IN represents a group of files and must be some variation of a filename and extension. This parameter determines which disk files the FOR loop will affect. Since the patternmatching symbols * and ? can be used, you may define this group to be very broad or very selective. The program shown above uses the statement IN (*.*) to affect the broadest possible group: every file on the disk. In other cases, you might use IN (*.BAS) to affect all files ending with .BAS, IN (ABC*.*) to affect all files starting with ABC, and so on.
    The first FOR statement in COPYUNQ.BAT (FOR %%f IN (*.*) DO) affects every file on the disk. As the FOR loop executes, the variable %%f represents each filename in order. Translated into plain English, this statement means "cycle through every filename on the source disk, using %%f to represent each filename in turn."
    IF can perform only a few tests. One of these (IF EXIST filename) tests whether a given file exists on the disk. Now you can understand the second part of the FOR statement (IF EXIST %2:%%f). The %2 parameter is a dummy, replaced by the second drive letter you entered when running the program. And the variable %%f is replaced by actual filenames when the program runs. In plain English, this statement means "if the current filename exists on the disk in the target drive...."
    Batch programs don't have the equivalent of BASIC's THEN statement (THEN is implied). But in other respects IF processing works much as it does in BASIC. Statements that come after the IF test (on the same line) are performed when the IF test is true, and skipped when the test is false. Consequently, in COPYUNQ.BAT, the ECHO command (which prints "filename WILL NOT BE COPIED") executes only when the file in question exists on both the source and target disks.
    Once you understand that much of COPYUNQ.BAT, the rest is not hard to decipher. PAUSE makes the system stop and display the message "Strike any key when ready." This is the only batch command that allows user input. Unfortunately, your choices are severely limited: You can continue only by pressing a key (perhaps after changing disks, etc.) or end the program by pressing Ctrl-Break. In Part 2 of this article, we'll show how to expand this number of options.

NOT And ERRORLEVEL
The second FOR line in COPYUNQ .BAT has a FOR loop and an IF test very similar to the first. However, in this case NOT reverses the logic of the IF test. When the named file does not exist on the target disk, the IF test is true and the file is copied.
    In addition to testing EXIST (with or without NOT), IF can test two conditions: the equality symbol (= =) and ERRORLEVEL. The equality symbol tests whether two strings are identical. ERRORLEVEL is always a number, ordinarily used to pass information from one program to another (indicating whether the first worked successfully and thus set ERRORLEVEL to the expected value). ERRORLEVEL is discussed further in Part 2.
    As shown in these brief examples, batch programs can be very powerful: IF lets you pick only the files you want, and FOR lets you repeat commands until the whole task is done. In one sense, the lack of opportunity for user input is an advantage: The entire procedure is automated, and you don't need to understand anything except how to type in the program name. On the other hand, batch programming can seem rigid, limiting, and visually quite dull. Part 2 improves on that situation, offering program examples and a routine that adds colorful graphic displays and multiple-option menu selection to batch programs.