IF

Type: Internal (2.0 and later)

Syntax:

IF [NOT] EXIST filename (command) [parameters]
IF [NOT] (string1)==(string2) (command) [parameters]
IF [NOT] ERRORLEVEL (number) (command) [parameters]

Purpose: Allows for conditional operations in batch processing.

Discussion

When used in combination with the GOTO command, the IF command provides a way to transfer control within a batch file dependent on the outcome of a test.

For more information on using the IF command and other batch commands, refer to Chapter 5, Using Batch Files.

The IF test is indicated by the condition label in the command format. It can be one of three types:

Condition 1: IF [NOT] EXIST (filename) (command)

This condition is determined by a test to see if a file exists (or does not exist) on disk.

When this conditional test is included (it can be on any line of your batch file), DOS checks to determine if the specified file exists (you must specify the path so DOS can find the file). If the condition is true (as stated), the specified command is executed. If the condition is found to be false, the command is not acted on and processing proceeds to the next line in the batch file.

When the IF command is used together with the GOTO command, it provides a way to transfer control to a different line in the batch file dependent on the outcome of the test.

For example, to display a warning message only if the file DATA.1 does not exist in the current directory, enter

echo off
if not exist data.1 goto MESSAGE
echo The file DATA.1 exists on the current directory
goto END
MESSAGE
echo The file DATA.1 was not found.
echo The file must be in the current directory
:END

When you enter the name of this batch file, there are two possible outcomes. If the file DOES NOT EXIST in the current directory, the program will display:

echo off
The file DATA.1 was not found.
The file must be on the current directory

If the file DOES EXIST in the current directory, the program will display:

echo off
echo The file DATA.1 exists on the current directory.

In this example, the IF command is combined with the GOTO command to determine the optional branching. The command tells DOS to check the current disk to determine if the file DATA.1 exists. Since we are using the NOT EXIST form of the command, the condition is true if it DOES NOT find the file; since the condition is true, the specified command (in this case, the GOTO command) is acted on. The GOTO MESSAGE line passes processing to the :MESSAGE label and the messages on the following lines are displayed.

Condition 2: IF [NOT] string1==string2 (command)

This operation checks to determine if the first string you enter is equal (or is NOT equal) to the second string you enter. If the condition is true (as stated), the specified command will be carried out.

DOS judges this condition based on whether or not the two strings are EXACTLY identical. DOS WILL detect a difference between uppercase and lowercase letters.

You can create a very useful version of the IF command that checks to determine whether or not a parameter was passed to the batch file from the command line.

The following batch file acts conditionally depending on a test of whether or not any characters were entered on the command line after the batch file name.

echo off
if not x==%1x goto PRINT
echo You must enter a parameter immediately after batch file name
goto END
:PRINT
echo The passed parameter is [ %1 ]
:END

The first line of this batch file checks to determine whether or not a parameter has been passed at the command line. It uses the IF command to determine if string one (the character `x`) is equal to string two (the character `x` plus the %1 symbol that represents the first passed parameter). If a parameter WAS passed to the batch file, the two strings will not match and the condition, (stated as NOT equal) is true; the GOTO command will be acted on, transferring processing to the label :PRINT.

If the condition is found to be false (the two strings ARE equal), it means a parameter WAS NOT entered on the command line. In that case, the GOTO command on the same line as the IF command will not be acted on and processing will be transferred to the next line of the batch file. The next line includes the message You must enter a parameter immediately after the batch file name. The following line transfers the processing to the :END label and the program terminates.

If characters WERE entered after the batch filename, the program will display

echo off
The passed parameter is [ test ]

If characters WERE NOT entered after the batch filename, the program will display

echo off
You must enter a parameter immediately after batch file name


Condition 3: IF [NOT] ERRORLEVEL (number) (command)

This operation checks to determine if an ERRORLEVEL number is set (or is NOT set) at or greater than the specified value. The ERRORLEVEL number is set by programs and the value is retained in the computer`s memory. This command is used to check that value. DOS judges this condition to be true if the ERRORLEVEL code is equal to OR GREATER than the number you specify.

A common use of the IF command is to display a message to indicate that an ERRORLEVEL has been set. To display a message whenever any ERRORLEVEL number has been set (any value above zero), enter:

echo off
if errorlevel 1 echo The errorlevel is now greater than zero


When this line is acted on (and if the ERRORLEVEL is found to be set to a value), the ECHO command will be acted on and the program will display

echo off
The errorlevel is now greater than zero

If DOS does not find a value set for ERRORLEVEL, the program terminates without displaying the message.

Copyright ©1998 DEW Associates Corporation. All rights reserved.