In Microsoft Windows and MS-DOS, an errorlevel is the integer number returned by a child process when it terminates.

Errorlevel is 0 if the process was successful.

Errorlevel is 1 or greater if the process encountered an error.

Testing errorlevel

Testing errorlevel is useful when you are executing several commands, either at the command line or in a batch file.

• Testing errorlevel.

• Conditional “if [not] errorlevel.”

• Testing success: if not errorlevel.

• Testing failure: if errorlevel.

• Branching execution with if..else.

• %ERRORLEVEL% environment variable.

• Using %ERRORLEVEL% in conditionals.

• Note: %ERRORLEVEL% is not always correct.

• Errorlevel lookup tool.

• Related information.

• Testing success: if not errorlevel.

• Testing failure: if errorlevel.

• Branching execution with if..else.

• Using %ERRORLEVEL% in conditionals.

• Note: %ERRORLEVEL% is not always correct.

Using a conditional expression, you can specify commands to occur only if a previous command was successful. You can also test for failure, executing commands only if the previous command failed. Sometimes, if the program supports it, you can also test for specific types of errors.

You may also branch command execution, so that a different set of commands is executed if the previous command failed.

Conditional “if [not] errorlevel”

The conditional expression “if errorlevel n” is true if the errorlevel is greater than or equal to n.

Similarly, “if not errorlevel n” is true if the errorlevel is less than n.

Let’s look at examples of how these can be used, by running some commands on the Windows command line.

To begin, open a command prompt window: press Win + X (hold down the Windows key and press X), and choose Command Prompt.

Now let’s run a simple command:

mkdir mydirectory

When we run mkdir (assuming there is not already a directory called “mydirectory” in the current directory), the directory mydirectory is created. The command was successful, so when mkdir terminates, it sets the errorlevel to 0.

Let’s test for errorlevel 0.

Testing success: “if not errorlevel”

We can test for errorlevel 0 (success) with the conditional statement if not errorlevel 1. If that’s true (errorlevel is less than 1), the command which follows the conditional runs. In the examples below, we’ll use the echo command to print a message on the screen.

if not errorlevel 1 echo The last command was successful.

The last command was successful.

As indicated, the mkdir command we ran above was successful.

However, if we try to make the directory again, mkdir fails, because the directory mydirectory already exists:

A subdirectory or file example already exists.

When mkdir fails, it provides its own error message, “A subdirectory or file example already exists,” and sets the errorlevel to 1. If we run our conditional statement again:

Nothing happens. Our echo command does not run, because we tested for success — errorlevel less than 1 — and that condition is false.

Testing failure: “if errorlevel”

We can specifically test for failure with if errorlevel 1, which returns true if the errorlevel is 1 or greater.

if errorlevel 1 echo The last command failed.

The last command failed.

The condition is met (because mkdir previously set the errorlevel to 1), and the echo command runs. It would also run if the errorlevel was 2, 3, 4, etc. If the errorlevel was 0, it would not run.

Branching execution with if..else

In the examples above, we tested for success or failure, but not both.

We can test for both success and failure using an if/else statement of the form:

if [not] errorlevel n (command1) else (command2)

For example:

mkdir newtest

if not errorlevel 1 (echo Success) else (echo Failure)

Success

A subdirectory or file newtest already exists.

Failure

%ERRORLEVEL% environment variable

Often, the errorlevel is also stored in the environment variable %ERRORLEVEL%. Its value is a convenient way to access your current errorlevel.

The parentheses are necessary to separate the commands from the word else.

In the following example, we run the dir command twice, once successfully, and once unsuccessfully. After each, we echo the value of %ERRORLEVEL%.

mkdir example

dir example

Directory of C:\Users\Hope\example

06/10/2018 09:43 PM