September 26th, 2008

ERRORLEVEL is not %ERRORLEVEL%

The command interpreter cmd.exe has a concept known as the error level, which is the exit code of the program most recently run. You can test the error level with the IF ERRORLEVEL command:

IF ERRORLEVEL 1 ECHO error level is 1 or more

<sidebar>
The IF ERRORLEVEL n test succeeds if the error level is n or more. This was presumably because there were programs that expressed different degrees of failure with higher and higher exit codes. For example, the diff program has three exit codes: 0 means the files are the same; 1 means the files are different; 2 means that something terrible happened. There are also programs that use an exit code of zero to mean success and anything else to mean failure.
</sidebar>

In addition to this internal state, you can, if you wish, create an environment variable with the name ERRORLEVEL, in the same way that you can create an environment variable called FRED. But, as with FRED, that variable won’t have any effect on the error level.

rem this next command sets the error level to zero
CMD /C EXIT 0
set ERRORLEVEL=1
if ERRORLEVEL 1 echo Does this print?

The message is not printed because the ERRORLEVEL environment variable has no effect on the error level. It’s just a variable whose name happens to coincide with a command processor concept.

set BANKBALANCE=$1,000,000.00

“Hey, when I tried to withdraw the money, I got an insufficient funds error. What am I doing wrong?”

Now, it does happen to be the case that if command extensions are enabled and you say %ERRORLEVEL%, then the command processor first looks for an environment variable called ERRORLEVEL, and if it can’t find one, then it replaces %ERRORLEVEL% with the current value of the internal error level value. It’s a fallback step, in the same way that your neighbor is a fallback delivery location if you aren’t home. If you file a change-of-address form for yourself, that doesn’t affect packages sent to your neighbor.

The same behavior can be seen with %CD%: If you did not explicitly set an environment variable called CD, then %CD% expands to the command processor’s current directory. But you can’t change directories by saying set CD=C:\Windows.

I can think of a few reasons why this feature may have been added.

  • So you can include the error level in a log file:
    ECHO error level is %ERRORLEVEL%>logfile
  • So you can perform other types of tests against the error level, for example, to perform an equality test:
    IF %ERRORLEVEL% EQU 1 echo Different!

But I’m digressing. My point for today is that the error level is not the same as the ERRORLEVEL environment variable.

Topics
Code

Author

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

0 comments

Discussion are closed.