Incode Systems Home Page Incode Systems, Inc.


ERRORLEVEL



ERRORLEVEL is a number value which is set by programs and may be tested within a DOS Batch file.

The following batch statements are examples of testing ERRORLEVEL:
CONFIRM Do you really want to exit? (Esc to cancel)
IF ERRORLEVEL 1 GOTO RESUME
GOTO END

The CONFIRM program above displays a message on the screen and waits for a keystroke. If the keystroke is the Esc key, ERRORLEVEL is set to 1, any other key sets ERRORLEVEL to 0. The IF ERRORLEVEL statement above branches to the RESUME label if the user presses Esc, otherwise the GOTO END statement is executed branching to the END label.

The IF ERRORLEVEL statement does not check for equality, but is really a "greater than or equal to" comparison. For example, IF ERRORLEVEL 5 really means: "if ERRORLEVEL is 5 or higher".

If you need to check for a number of ERRORLEVEL possibilities, use a number of IF ERRORLEVEL statements testing from high to low, like this:

IF ERRORLEVEL 10 GOTO LABEL10
IF ERRORLEVEL 9 GOTO LABEL9
IF ERRORLEVEL 8 GOTO LABEL8
IF ERRORLEVEL 7 GOTO LABEL7
IF ERRORLEVEL 6 GOTO LABEL6
IF ERRORLEVEL 5 GOTO LABEL5
IF ERRORLEVEL 4 GOTO LABEL4
IF ERRORLEVEL 3 GOTO LABEL3
IF ERRORLEVEL 2 GOTO LABEL2
IF ERRORLEVEL 1 GOTO LABEL1
GOTO LABEL0

Another way to test ERRORLEVEL is to preceed it with NOT to test for "less than", like this:
IF NOT ERRORLEVEL 10 GOTO Less_than_10

To test for a single ERRORLEVEL or a range, do this:
IF ERRORLEVEL 10 IF NOT ERRORLEVEL 11 GOTO Err_10
IF ERRORLEVEL 5 IF NOT ERRORLEVEL 10 GOTO Err_5_to_9


To set the ERRORLEVEL from a batch file:
EXIT /B 1

(Note: parameters for the EXIT command are supported in Windows 2000 and up. For older versions of Windows and DOS, or to set ERRORLEVEL without exiting, use SETERR)

The command interpreter (Command Prompt) sets ERRORLEVEL 9009 when a batch attempts to execute a program that is not found. The line below may be added to a batch file immediately after the line that executes a program so that the batch will branch to the ProgNotFound label and exit gracefully instead of blindly continue running:

MyProg1.exe
IF ERRORLEVEL 9009 IF NOT ERRORLEVEL 9010 GOTO ProgNotFound
.
.
.
:ProgNotFound
ECHO One or more programs required by this routine were not found. These
ECHO programs are required for this routine:
ECHO MyProg1.exe
ECHO MyProg2.exe

The command interpreter (Command Prompt) sets ERRORLEVEL 1 when a batch attempts to CALL another batch and the batch is not found. Unfortunately, if ERRORLEVEL was not zero before a CALL and the CALL to another batch is found, the ERRORLEVEL is NOT set to 0. So, checking IF ERRORLEVEL 1 after a CALL is true if the batch file was not found or if a previously untrapped ERRORLEVEL was set. The SETERR utility may be used to set ERRORLEVEL in batches, or reset it to 0, without exiting.

The command interpreter (Command Prompt) sets ERRORLEVEL 9059 when START is used to start a program or a batch and it is not found.

The internal command DEL (or ERASE) do not set an errorlevel if the file is not found, but sets ERRORLEVEL 18 if an "Access is denied" error occurs.

The internal command CD (or CHDIR) sets ERRORLEVEL 1 if path not found.

The internal command MD (or MKDIR) sets ERRORLEVEL 1 if file already exists.

The GOTO batch command sets ERRORLEVEL 1 if label is not found. While it is not difficult to determine that all of the labels referenced by GOTO in your batch files exist, checking the ERRORLEVEL after a GOTO would work well in a situation where you are using GOTO with a label name that is derived from a batch parameter or an environment variable. For example, both of these GOTO statements are valid and checking the ERRORLEVEL after these indirect GOTO references will allow the batch to self diagnose an invalid label:

GOTO %1
GOTO %MyEnvVar%

ERRORLEVEL is set to -1073741510 if user uses Ctrl-C or Ctrl-Break to exit a command line program. Test for this with:

IF ERRORLEVEL -1073741510 IF NOT ERRORLEVEL -1073741509 ECHO User Break