What is a Batch File

Creating Batch Files with Edit

Creating Batch Files with COPY

Running Batch Files

Stopping Batch Files

Displaying Messages

Using Replacement Variables

Using Environment Variables

Controlling Execution of Commands

Using System Information

Running a Batch File from Inside Another

Batch File Command Reference

What are Macros

Creating Macros Using DOSKEY

Editing Macros

Running and Stopping Macros

Saving Macros in Batch Files

This chapter describes two methods of batch processing: batch files and macros.

What is a Batch File?

Batch processing allows you to collect all the commands you need to carry out a task into a single batch file so that you do not need to enter each command individually. When you enter the name of the batch file at the system prompt, each command in the file is executed as if you had entered them one at a time. Using a batch file also ensures that a procedure is carried out in exactly the same way every time.

For example, assume that you use the following commands every day to back up your files:

CD \LETTERS <Enter>

(to make LETTERS the current directory)

ERASE *.OLD <Enter>

(to erase all files with the extension .OLD)

MD A:\DAYSWORK <Enter>

(to create the directory DAYSWORK on the A: drive)

COPY *.DOC A:\DAYSWORK <Enter>

(to copy all files with the extension .DOC to A:\DAYSWORK)

You can create a batch file that contains all of these commands called DAYOVER.BAT. Then, at the end of the day, you would only need to enter the following to execute all of the commands:

DAYOVER

Creating Batch Files with EDIT

NOTE: If you want to use a word processor other than EDIT, make sure that the completed batch file is in ASCII format. Refer to the word processor documentation for more information.

The rules for naming a batch file are the same as for any other file except that you must use the extension .BAT. Also, you must enter each command in the batch file on a separate line.

To create the batch file described in the previous section, for example, type the following at the system prompt:

EDIT DAYOVER.BAT <Enter>

Because this is a new file, you see a message asking you whether you want to create it. Press <OK> and the EDIT screen is displayed.

Type the commands you want in the batch file, as follows, pressing <Enter> at the end of each line:

 CD \LETTERS

 ERASE *.OLD

 MD A:\DAYSWORK

 COPY *.DOC A:\DAYSWORK

Press <Ctrl> KX to save the file and exit EDIT.

NOTE:There are several other ways of saving files and quitting EDIT. Refer to Chapter 6, "Editing Text Files" for complete information.

Use this procedure to create any batch file you require.

Creating Batch Files with COPY

Use the following version of COPY:

COPY CON filespec

When you specify CON as the device, every character you enter is recorded in the destination file you specify (filespec), except for the line editing characters you use, such as <Enter> to start a new line or <Ctrl> H to delete the character to the left of the cursor. See the sections "Command Line Editing" and "Extended Command Line Editing" in the "Command Reference" chapter of DOSBook for a complete list of the command line editing keys.

Press <Ctrl> Z or <F6> when you have finished entering your file and close the file by pressing <Enter>.

Running Batch Files

Run a batch file by entering its name in the command line; you do not need to include the extension (.BAT).

When the batch file is finished executing, the system prompt returns.

Example

Assume you created the following batch file to copy two sets of files from the current drive to the root directory of the diskette drive: all files in the directory DIRA and then all files with the extension .DAT in the directory DIRB.

CD \DIRA

COPY *.* A:\

CD \DIRB

COPY *.DAT A:\

CD\

When you run the batch file, you might see something similar to the following at the system prompt as each command in the file is executed:

CD \DIRA

then

COPY *.* A:\

PGM1.EXE

PGM2.EXE

PGM3.EXE

3 File(s) copied

then

CD \DIRB

then

COPY *.DAT A:\

MON.DAT

TUES.DAT

WED.DAT

THURS.DAT

FRI.DAT

5 File(s) copied

then

CD\

Stopping Batch Files

Halt Batch Process (Y/N)?

Answer Y for YES and the remaining commands in the batch file are not executed. You return to the system prompt.

Answer N for NO and the remaining commands will be processed.

Displaying Messages

ECHO can also be used to display messages during batch file execution. When you include a message preceded by ECHO in your batch file, that message displays regardless of whether the ECHO feature itself is set to ON or OFF.

For example, assume you include the following statements at the beginning of a batch file:

@ECHO OFF

ECHO THIS IS MY FIRST

ECHO BATCH FILE

When you run the batch file, the following message is displayed:

THIS IS MY FIRST

BATCH FILE

Comments

When ECHO is ON, any comments or remarks that you include in a batch file are also displayed. You include comments by using the REM command; any line in a batch file that begins with REM is ignored during execution (other than being displayed when ECHO is ON).

Using Replacement Variables

Replacement variables are entered as %n, where n is a number from 0 through 9. %0 represents the batch file name. %1 represents the first parameter at the system prompt, %2 represents the second parameter, %3 the third parameter, and so on.

If you want to use more than 10 parameters, you must also use the SHIFT command in your batch file. SHIFT allows you to change the position of command line parameters by shifting them one parameter position to the left. Refer to the description of SHIFT in "Batch File Command Reference" starting on page 7-14.

If you want to use the % character in a filename within a batch file, you must enter it twice. If the filename is TEST%.DAT, for example, you must enter it in the batch file as TEST%%.DAT. Generally speaking, you should not use the % character in filenames.

When you run the batch file at the system prompt, always separate parameters with a space and make sure that they are entered in the correct sequence.

Example

The following batch file MOVEOVER.BAT, if created in C:\AMANDA\LETTERS, copies any file from C:\AMANDA\LETTERS to C:\QUERIES\DONEWITH and then deletes the original:

COPY %1 C:\QUERIES\DONEWITH

ERASE %1

So to run MOVEOVER.BAT to copy and delete a file called JONES.LET, you would simply type the following:

MOVEOVER JONES.LET <Enter>

The operating system would then execute the following commands:

COPY JONES.LET C:\QUERIES\DONEWITH

ERASE JONES.LET

To copy and delete SMITH.LET instead, you would type the following:

MOVEOVER SMITH.LET <Enter>

Using Environment Variables

Table 7-1 lists the standard environment variables.

Table 7-1
Environment Variables

Variable Name	Function
APPEND	The current APPEND search path.
COMSPEC	The location on disk of the command interpreter.
DRDOSCFG	The directory containing the system configuration files.
OS	The current operating system name.
PATH	The current PATH search path.
PEXEC	Used by the PROMPT command.
PROMPT	The current system prompt.
TEMP	The directory used to hold temporary files.
VER	The current operating system version.

To use the current value of an environment variable in a batch file, enclose it in % signs.

For example, the following command changes the current system prompt:

PROMPT %OS% $P$G <Enter>

Controlling Execution of Commands

Conditional Execution

You can specify that one string must equal another, for example. Assume that you want to create a batch file called GAME.BAT to start a certain computer game when you type the following command:

GAME FUN <Enter>

You could include the following statement in GAME.BAT so that the game is started only if %1 (the first parameter in the command line) is FUN. If %1 is not FUN, the operating system skips the PLAY command and processes the next line in the batch file.

IF "%1" == "FUN" PLAY

After PLAY is finished, the next line of the batch file is processed.

Changing Execution Flow

For example, when execution reaches the GOTO statement in the following lines, it is forced to jump back to the label START and continue processing from there.

:START

TYPE INFO.TXT

GOTO START

The next example shows a batch file with three GOTOs in it.

@ECHO OFF

REM GOTO.BAT - Example of Using GOTOs

GOTO LABEL1

REM This part is never executed

ECHO This part is never executed

:LABEL2

ECHO The program is at LABEL2

GOTO END

REM This part is executed first

:LABEL1

ECHO The program is at LABEL1

GOTO LABEL2

REM This part is executed last

:END

ECHO This is the end of the file

You can use GOSUB instead of GOTO when you want to force execution to a subroutine rather than an individual command. Statements are processed until a RETURN command is encountered.

Using IF and GOTO Together

Many external commands set a return code or "error level" when they finish. The value such a command returns can be tested using an IF ERRORLEVEL command. The following batch file, for example, tests the return code from an XCOPY operation:

XCOPY %1 %2

IF ERRORLEVEL 1 GOTO FAIL

DEL %1

GOTO END

:FAIL

ECHO Copy Failed - Not Deleting Files

:END

You can also specify that a certain file or condition must exist or must be true before a command is executed. The following batch file, for example, uses IF to test whether expanded memory is available before starting a calculator application called CALC:

IF EXIST EMMXXXX0 GOTO OK

ECHO EMS memory manager not loaded - Load EMS

ECHO driver

GOTO END

:OK

CALC

:END

Refer to the descriptions of IF, GOTO, and GOSUB in "Batch File Command Reference" starting on page 7-14 for more information about using these commands to control batch file execution.

Using System Information

The following variables are only available when you have the NetWare® drivers and shell loaded:

Table 7-3
System Information Variables (NetWare)

Variable Name	Explanation
Login_Name	User's login name
P_Station	Physical station number
Station	Station number

The following statements in a batch file, for example, cause the appropriate greeting (including the greeting time and login name) to display for any user. Mail will only be checked, however, if the user is FRED.

ECHO "Good %Greeting_Time% %Login_Name%"

IF NOT "%Login_Name%" == "FRED" GOTO NOMAIL

ECHO "Checking Mail"

...

...

:NOMAIL

Running a Batch File from Inside Another

To run a batch file from inside another and then return to the original batch file and continue processing, you can use the CALL command in the original file.

The following batch file OUTER.BAT, for example, displays a message and then calls another batch file, INNER.BAT. When INNER.BAT is finished, execution returns to OUTER.BAT and processes the next line (which displays another message):

@ECHO OFF

REM OUTER.BAT

ECHO I am in OUTER.BAT

CALL INNER

ECHO I am back in OUTER.BAT

You can call as many batch files as you like from inside another batch file.

Refer to the description of CALL in "Batch File Command Reference" starting on this page for more information.

Batch File Command Reference

As described previously in this chapter, however, there are also special commands available for use with batch files called batch file subcommands. Batch file subcommands allow you to write batch files that are like simple programs. This section describes each of these commands.

NOTE: All batch file subcommands (except CHOICE) are internal commands. CHOICE is an external command that is only used in batch files.

The conventions used in the following command descriptions are the same as those used in the "Command Reference" chapter in DOSBook; refer to this if you need an explanation of the conventions.

@

Explanation

Example

@ECHO OFF

?

Explanation

You can also specify the text of the prompt by including it between the question mark (?) and the beginning of the statement, enclosed by double quotation marks.

When you run a batch file containing a ? statement, a response to the prompt is required by the user before processing continues.

Note that the maximum length of a batch file statement (including ?) is 128 characters.

Example

?DEL C:\ACCOUNTS\*.OLD

So, when the file executes, the user sees the following:

DEL C:\ACCOUNTS\*.OLD (Y/N) ?

If the user answers Y, the DEL command is run and the files are deleted. If the user answers N, the command is ignored and the next line in the batch file is processed.

:label

Explanation

Only the first eight characters in a label are recognized; any additional characters are ignored.

Labels are not displayed during batch file execution.

CALL

Explanation

The search path defined by the PATH command is used to locate the second batch file.

Example

REM This file runs BATCH2 and then BATCH3

CALL BATCH2

CALL BATCH3

CHOICE

Explanation

NOTE: CHOICE is an external command that is only used in batch files and is therefore described here rather than in the "Command Reference" chapter of DOSBook.

Command Switches
/? or /H	Displays help text.
/C:choices	Specifies the keys that the user can select from; choices can be any keys that can be used on a command line except <Space>, <Tab>, and /. By default, CHOICE displays these key choices after any prompt text specified in the CHOICE command. If choices are not specified, CHOICE displays [Y,N]?.
/N	Disables the display of the choice keys and the question mark after the prompt text.
/S	Specifies that the choice keys are case-sensitive.
/T:c,nn	Specifies that CHOICE defaults to key c after nn seconds unless the user makes a selection before then. c must be one of the characters specified by the /C switch. If you do not specify the /C switch, c must be Y (for Yes) or N (for No). nn can be in the range 0-99 but if nn is 0, the /T switch is ignored.
text	Specifies the prompt text that precedes the key choices displayed to the user. The text must not include a forward slash (/).

CHOICE returns ERRORLEVEL 1 if the user selects the first of the key choices, ERRORLEVEL 2 if the user selects the second of the keys, and so on. If the user presses <Ctrl> C instead of selecting one of the keys, CHOICE returns 0.

If the user enters an invalid CHOICE command, ERRORLEVEL 255 is returned, and help text is displayed.

Examples

CHOICE /C:yne Yes, No, or Exit

the user sees the following message when the batch file runs:

Yes, No, or Exit [Y,N,E]

CHOICE returns ERRORLEVEL 1 if the user presses Y, 2 if they press N, and 3 if they press E.

In the following example CHOICE defaults to Y, unless the user makes a selection within 10 seconds:

CHOICE /C:yne /T:y,10 Yes, No, or Exit

The next example demonstrates how CHOICE can be used in conjunction with other batch file commands. In this example, the user is given the option to select one of three utilities: DOSBook, EDIT, or SETUP.

@echo off

:start

cls

echo DOSBOOK

echo EDIT

echo SETUP

echo -------

choice /c:desq Select an option or Q to quit

if errorlevel 4 goto end

if errorlevel 3 goto setup

if errorlevel 2 goto edit

if errorlevel 1 goto dbook

:setup

setup

goto start

:edit

edit

goto start

:dbook

dosbook

goto start

:end

cls

NOTE: The IF statements in this example are true if the ERRORLEVEL value returned by CHOICE is greater than, or equal to, the ERRORLEVEL specified in the IF statement. Therefore, the IF statements are listed with the highest ERRORLEVEL first; if the order was reversed, the batch file would always jump to DOSBook.

ECHO

Explanation

NOTE: @ECHO OFF is often used at the beginning of a batch file to prevent all commands from being displayed, including ECHO OFF itself.

ECHO displays a message during batch file execution when you specify ECHO message. Use multiple ECHO statements to display more than one line of message text.

If you type a period immediately after ECHO in a batch file, a blank line appears when you run the batch file.

FOR

Explanation

You can use wildcards in filenames; all matching filenames on the current drive will be substituted.

Example

FOR %%f IN (ACCT.BAS ACCT2.BAS) DO TYPE %%f

GOSUB

Explanation

Example

TYPE INTRO.TXT

GOSUB LISTS

CALL SUMMARY

EXIT

:LISTS

TYPE LISTA.TXT

TYPE LISTB.TXT

TYPE LISTC.TXT

RETURN

GOTO

Explanation

You must include the label referenced by a GOTO. If the label is not found, you see the following error message:

Label xxxxxxxx not found

Note that only the first eight characters of a label are recognized.

Example

:START

TYPE INFO.TXT

GOTO START

IF

Explanation

The conditions can be any of the following:

ERRORLEVEL n

This condition is true when the error code produced by the previous program is greater than or equal to n (where n is a number).

string1 =|==|!=|<> string2

This condition is true when the relationship between the specified string (string1) and another string (string2) matches the specified symbol: "identical to" (= or ==) or "not identical to" (!= or <>). Strings can be literal strings or batch variables (%hour%, for example).

#value1 =|==|!=|<> #value2

This condition is true when the relationship between the absolute value of the specified variables matches the specified symbol.

EXIST filespec

This condition is true when filespec exists, in the specified directory or in the current directory (if no dirpath is specified in filespec).

DIREXIST dirpath

This condition is true when dirpath exists, in the specified directory or in the current directory (if no dirpath is specified in dirpath).

Examples

The following batch file uses several IF statements to test the ERRORLEVEL from an XCOPY operation:

REM XCOPY and DEL with ERRORLEVEL Testing

XCOPY %1 %2

IF ERRORLEVEL 5 GOTO FAIL5

IF ERRORLEVEL 4 GOTO FAIL4

IF ERRORLEVEL 3 GOTO FAIL2

IF ERRORLEVEL 2 GOTO FAIL1

DEL %1

GOTO END

:FAIL1

ECHO Files %1 not found - not deleting files

GOTO END

:FAIL2

ECHO Aborted - not deleting files

GOTO END

:FAIL4

ECHO Could not start XCOPY - not deleting files

GOTO END

:FAIL5

ECHO Disk write failure - not deleting files

:END

The following IF statement specifies that WHERE IS JOHN? displays only if JOHN is not the current value of the %1 parameter. Note that the strings are enclosed by quotation marks; you should always use quotation marks around strings to prevent syntax errors, especially when no parameters are specified:

IF "%1"<>"JOHN" ECHO WHERE IS JOHN?

The IF statement in the following set of statements means that the commands between DIR B: and the label XYZ will only be executed if MYFILE does not exist in the current directory:

IF EXIST MYFILE GOTO XYZ

DIR B:

.

.

:XYZ

.

.

PAUSE

Explanation

PAUSE always displays the following message:

Strike a key when ready . . .

You can specify an additional remark of up to 122 characters; this is optional, however.

Example

COPY A:*.* B:

@ECHO OFF

PAUSE Insert new disk in DRIVE A:

COPY A:*.* B:

When this batch file runs, the files on the diskette in the A: drive are copied to the diskette in the B: drive. Processing is then suspended and the following message appears on the screen:

Insert new disk in DRIVE A:

Strike a key when ready . . .

You can either insert a new diskette and press any key to continue or press <Ctrl> C to stop batch file processing.

REM

Explanation

NOTE: If ECHO is ON, REM lines will be displayed on the screen as the batch file executes.

The maximum length of remark is 123 characters. You can use commas, spaces, and tabs to separate words. Empty comment lines (REM with no remark) are useful for adding space to a batch file, making it easier to read and edit.

RETURN

Explanation

SHIFT

Explanation

When SHIFT is executed, the value in %0 is replaced by the value in %1, %1 is replaced by %2, %2 by %3, and so on up to %8, which is replaced by the value of %9.

Use SHIFT as many times as you need to get all of the parameters in the command line, up to a maximum of 10 at a time. Think of the batch parameters as a "window"; SHIFT simply moves the window one position to the right.

Example

The batch file COPYX, for example, is designed to copy a number of files to a single destination directory; you would enter the following to run COPYX:

COPYX filename1 filename2 filename3... dirpath

COPYX.BAT would be written as follows:

@ECHO OFF

IF "%1" == "/?" GOTO HELP

REM COPYX requires at least 2 parameters if

REM the first parameter is not /?

IF "%2" == "" GOTO FAIL

SET COPYX_FILE =

:LOOP

REM If the second parameter is empty, the

REM first parameter must be the destination

IF "%2" == "" GOTO NO_MORE_FILES

REM Otherwise, add the first parameter to the

REM list of files to copy

SET COPYX_FILE = %COPYX_FILE% %1

REM Now SHIFT the parameters so that %1 is

REM replaced by %2, etc.

SHIFT

REM Go back to look at the rest of the

REM parameters

GOTO LOOP

:NO_MORE_FILES

REM The first parameter now contains the

REM destination

REM COPYX_FILE contains the list of files to

REM copy

FOR %%i IN (%COPYX_FILE%) DO XCOPY %%i %1

GOTO END

:FAIL

ECHO COPYX: At least 2 parameters are required

GOTO END

:HELP

ECHO COPYX: Multiple file copy program

ECHO Enter: COPYX filename1 filename2... dirpath

GOTO END

:END

SET COPYX_FILE =

SWITCH

Explanation

When the label is entered, execution jumps to that label in the batch file and returns to the line following SWITCH when a RETURN command is encountered.

The maximum number of labels you can use in a SWITCH command is nine.

Example

@ECHO OFF

:BEGIN

CLS

ECHO APPLICATIONS MENU

ECHO =================

ECHO 1 Word Processor

ECHO 2 Desktop Publisher

ECHO 3 Database

ECHO 4 Exit

ECHO Choose a number from 1 to 4

SWITCH WP, VP, DB, EX

GOTO BEGIN

:WP

EDIT

RETURN

:VP

CALL VPPROF

RETURN

:DB

CD \DATABASE

DB

RETURN

:EX

What are Macros?

The following sections in this chapter, about using macros, describe further differences between batch files and macros.

Creating Macros Using DOSKEY

To create a macro, simply type the DOSKEY command at the system prompt as follows:

DOSKEY macroname = commands <Enter>

The number of commands you can put in a macro is limited by the length of a single line (127 characters); all the commands in a macro must be on the same line.

Separate each command with $T (or $t). The following command line, for example, defines a macro that lists all the .TXT files in the current directory in order of size before copying them to the root directory of the A: drive:

DOSKEY CPYTXT = XDIR *.TXT /Z $t COPY *.TXT A:\

Besides $t, there are other special characters you can use in a macro. They are listed in the following table.

Special Character	Meaning
$L (or $l)	Equivalent to the less-than sign (<).
$G (or $g)	Equivalent to the greater-than sign (>).
$G$G (or $g$g)	Equivalent to the double greater-than sign (>>).
$B (or $b)	Equivalent to the piping symbol (|).

Note the following restrictions about what you can use in macros:

• You cannot use GOTO commands in macros or start a macro from inside another macro. You can run a batch file from inside a macro, however.
• Replacement variables are $1 through $9 in macros instead of %1 through %9 as in batch files.
• You can define an environment variable in a macro using SET but you cannot use any environment variables in the macro itself.

Running and Stopping Macros

To stop a macro, press <Ctrl> C. This stops the command that is currently executing. Press <Ctrl> C as many times as necessary to stop every command in the macro.

Saving Macros in Batch Files

To save macros this way, use the DOSKEY command with the
/macros option and a redirection symbol. The following command, for example, stores all the macros currently stored in memory in a batch file called MACROS.BAT:

DOSKEY /MACROS >MACROS.BAT

Saving macros in batch files also means you can edit them in the future.