Day: August 11, 2011

Understanding the Connection Between Application Output and ErrorLevel

Many readers have a disconnect between application output and the ErrorLevel variable found in batch files. I’ve received more than a few e-mails where readers don’t quite understand the whole concept behind the ErrorLevel variable. They think it actually signifies some sort of mystical operating system derived error, when it isn’t anything of the sort.

A large part of the problem is that those readers who commonly work with batch files aren’t developers and many developers don’t work with batch files. In fact, even though many administrators are moving back to command line utilities because working with the GUI is time consuming and inefficient, many developers have decided to eschew the console application in favor of GUIs with fancier user interfaces.

Another problem is that ErrorLevel is inappropriately named. It should really be named ApplicationOutput. I’m sure that at one time the intention truly was to convey some sort of error information, but even Microsoft uses ErrorLevel for other purposes.

Let’s take a practical look at the whole concept of ErrorLevel beginning with a simple C# application to generate the codes. When working with C#, you’ll find that the output is now called an ExitCode as shown here.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
namespace GenerateOutput
{
    class ExitCode
    {
        static void Main(string[] args)
        {
            // Create a variable to hold the exit
            // value.
            Int32 Value;
 
            // Make sure there is a variable provided as input.
            if (args.Count() > 0)
            {
 
                // Determine whether the input is actually a number.
                if (Int32.TryParse(args[0], out Value))
 
                    // If it is, then exit using that number.
                    Environment.Exit(Value);
                else
 
                    // Otherwise, exit with an error value of -2.
                    Environment.Exit(-2);
            }
            else
 
                // Exit with an error value of -1
                Environment.Exit(-1);
        }
    }
}

The only purpose of this application is to generate exit codes given certain circumstances. The first check determines whether the user has supplied any sort of input at all. If not, if the user simply types GenerateOutput without any arguments at all, then the application exits with a value of -1 to indicate an error. Likewise, if the user types something other than a number, such as GenerateOutput Hello, the application exits with a value of -2 to indicate a different sort of error. Only when the user supplies a number does the application exit with a numeric value.

The batch file used to test this application is equally simple. All it does is call GenerateOutput with the value (if any) that the user provides to the batch file, TestOutput.bat. Here’s the batch file code.

@Echo Off
 
REM Run the application.
GenerateOutput %1
 
REM Most application output are status indicators.
If ERRORLEVEL 2 GOTO HighOutput
 
REM You can perform specific actions for a specific status.
If ERRORLEVEL 1 GOTO ValueOne
 
REM Applications can also provide a success indicator.
If ERRORLEVEL 0 GOTO Success
 
REM Errors are normally negative numbers, but can be anything.
If ERRORLEVEL -1 GOTO Error1
If ERRORLEVEL -2 GOTO Error2
 
:HighOutput
ECHO The value you provided is higher than 1.
GOTO End
 
:ValueOne
ECHO You provided an input of precisely 1.
GOTO End
 
:Success
ECHO An output value of 0 indicates success!
GOTO End
 
REM Here is the beginning of the various messages.
:Error1
ECHO You must supply a number as an argument!
GOTO End
 
:Error2
ECHO You must supply a number and not text or special characters!
GOTO End
 
REM Here is the ending point.
:End

As you can see, the tests check for errors, success messages, and non-error application output. Any combination of console application and batch file can do the same thing provided the developer and administrator get together to work out the details or the developer at least documents the exit codes.

The process is the same each time. Test for an ErrorLevel value, then go to the label specified, execute the directions, and then go to the end of the batch file. The ErrorLevel values must appear in order from greatest to least in order to work correctly. Here is some test output from this test application and batch file pair.

ErrorLevel01

The point of this exercise is to ensure that developer and administrator alike realize the importance of the exit code (ErrorLevel). The application should use it to provide some sort of status information that the administrator can then use to track how well the application works in an automated setting. Let me know if you have any questions at [email protected].