Home > Commands A-M > Batch I

IF


Description | Syntax | Parameters | Switches | Related | Notes | Examples | Errorlevels | Availability

Performs conditional processing in batch programs. If the condition specified by an IF command is true, it carries out the command that follows the condition. If the condition is false, it ignores the command. You can use this command only in batch programs.


Syntax

IF /?

Error Check Syntax:

IF [NOT] ERRORLEVEL nnn command

IF [NOT] DEFINED variable command

IF CMDEXTVERSION nnn command

String syntax:

IF [/I] [NOT] string1==string2 command

IF [/I] item1 compare-op item2 command

IF [/I] item1 compare-op item2 (command) ELSE (command)

File syntax:

IF [NOT] EXIST filename command

IF [NOT] EXIST filename (command) ELSE (command)


Parameters
CMDEXTVERSION (NT4)
If Command Extensions are disabled CMDEXTVERSION will return FALSE otherwise it will return "1".
If command extensions are significantly enhanced in a future version of Windows then CMDEXTVERSION will be incremented.
command (v2.0 Win95 NT3.5)
Specifies the command that should be carried out if the preceding condition is met.
string1==string2 (v2.0 Win95 NT3.5)
Specifies a true condition only if string1 and string2 are the same. These values can be literal strings or batch variables (%1, for example). Literal strings do not need quotation marks or brackets.
compare-op (NT4)
may be one of: This 3 digit syntax is necessary because the < and > are recognised as redirection symbols.
Any test made will always be a "string" comparison, so when comparing numbers note that "026" > "26".
DEFINED (NT4)
Will return true if the variable contains any value (even if the value is just a space).
ITEM (NT4)
May be a text string or an environment variable, a variable may be modified using either Substring syntax or Search syntax.
NOT (v2.0 Win95 NT3.5)
Specifies to carry out the command only if the condition is false.
ELSE (NT4)
Specifies what to carry out if the condition is false.
ERRORLEVEL nnn (v2.0 Win95 NT3.5)
Specifies a true condition only if the previous program run by COMMAND.COM returned an exit code equal to or greater than number.
Normal completion of a command will return ERRORLEVEL=0.
EXIST filename (v2.0 Win95 NT3.5)
Specifies a true condition if filename exists (this is not case sensitive).

Switches
/? (NTXP)
Displays help.
/I (NT4)
Do a case Insensitive string comparison.

Related

SET - Display, or Edit environment variables.
ECHO - Display message on screen.
IFMEMBER - NT Workgroup member (Resource kit).
SC - Is a Service running (Resource kit).
Equivalent Linux BASH commands:
case - Conditionally perform a command.
eval - Evaluate several COMMANDS/arguments.
if - Conditionally perform a command.
m4 - Macro processor.
until - Execute commands (until error).
while - Execute commands.


Notes

Parenthesis:

The use of parenthesis is only required if the command is run over several lines:

    IF EXIST filename (
    DEL filename
    ) ELSE (
    echo The file was not found.
    )

When piping commands, the expression is evaluated from left to right, so:

IF... | ... is equivalent to (IF ... ) | ...

you can use the explicit syntax IF (... | ...)

Testing ERRORLEVEL correctly:

It is possible to create a string variable called %ERRORLEVEL% if present such a variable will prevent the real ERRORLEVEL from being tested successfully.

Both ECHO %errorlevel% and IF %errorlevel% will respond to a string variable %ERRORLEVEL% in preference to a real ERRORLEVEL.

To test for this problem use SET errorlevel, or IF DEFINED ERRORLEVEL.

If you want to deliberately raise an ERRORLEVEL in a batch script use the command "COLOR 00".

If Command Extensions are disabled IF will only support direct comparisons: IF ==, IF EXISTS, IF ERRORLEVEL.


Examples

This example tests for the existence of a directory. The IF command cannot be used to test directly for a directory, but the null (NUL) device does exist in every directory on the hard drive. Therefore, you can test for the null device to determine whether a directory exists on the hard drive.

    IF EXIST C:\MYDIR\NUL GOTO PROCESS

This example displays the message 'Can't find data file' if the operating system cannot find the file PRODUCT.DAT:

    IF NOT EXIST PRODUCT.DAT ECHO Can't find data file

Using a variable in EXIST and GOTO syntax:

    IF NOT EXIST %FILE% GOTO NOSUCH

Errorlevel When a program stops, it returns an exit code to the operating system. For example, a value of 0 is typically used to indicate that a program was successfully executed. The ERRORLEVEL parameter lets you use exit codes as conditions.

This example displays an error message if an error occurs during formatting of the disk in drive A. If no error occurs, the error message is skipped.

    @ECHO OFF
     FORMAT A: /S
     IF NOT ERRORLEVEL 1 GOTO ERR
      ECHO An error occurred during formatting.
      GOTO END
    :ERR
      ECHO Successfully formatted the disk in drive A.
    :END

For another example of how the ERRORLEVEL parameter is used, see the CHOICE examples.

    IF EXIST C:\install.log (ECHO Installation complete) ELSE ECHO The Installation failed)

    IF DEFINED v_department ECHO Got the department variable

    IF DEFINED v_commission SET /A v_salary=%v_salary% + %v_commission%

    IF CMDEXTVERSION 1 GOTO :start_process

    IF ERRORLEVEL EQU 0 GOTO :okay

    :: Capture a specific errorlevel like this
    FOR %%G IN (0 1 2 3 4 5 6 7 8 9) DO IF ERRORLEVEL==%%G SET v_err=%%G
    IF [%v_err%]==[2] ECHO Errorlevel is 2

    :: Wildcards are not supported by IF but you can spoof the same thing using SET:
    :: This won't Work
    IF %COMPUTERNAME%==ABZ* GOTO :s_matched

    :: This will work
    SET v_part_name=%COMPUTERNAME:~0,3%
    IF NOT %v_part_name%==ABZ GOTO :s_matched

Errorlevels

none.


Availability
Internal
DOS
v2.0 v2.01 v2.05 v2.10 v2.11 v2.11R v2.12 v2.2 v2.25 v3.0 v3.20 v3.05 v3.1 v3.21 v3.25 v3.30 v3.3A v3.3R v3.3T v3.31 v3.40 v4.0 v4.01 v4.01A v5.0 v5.0A v5.00.02 v5.001A v5.01 v5.02 v6.0 v6.10 v6.2 v6.21 v6.22 v6.23 v7.00 v7.0R1 v7.10 v8.00
Windows
Win95 Win98 WinME
Windows NT
NT3.5 NT4 NT2000 NTXP NT2003