ERRLEV and SETERR

Two utilities for Windows "ErrorLevel"

by Rich Pasco
Revised Thursday, November 11, 2004
Copyright © 2004 Richard Pasco

ERRLEV
Display the ErrorLevel returned by executing a program

How it works: ERRLEV is a small "shell" which invokes your program. When your program exits, it returns control (and its ErrorLevel) to ERRLEV, which displays the ErrorLevel before exiting to the command shell which invoked it. ERRLEV also passes the ErrorLevel on to its command shell.

Invocation syntax:

   ERRLEV filename params
where filename is the name of the executable program. The extension .EXE or .COM is optional. ERRLEV will find it anywhere on your path, or you may explicitly specify a path if you prefer.

Note: ERRLEV only works with executable binary programs (.EXE, .COM). It does not support internal commands, batch (.BAT) files, or DOSKEY macros.

After introducing itself, ERRLEV gives the full path name of the executable file it found, and then executes it with the parameters you specified. When your executable program teminates; ERRLEV displays two lines of status. The first line tells whether the program terminated nomally, by Ctrl-Break, by a device error, or stayed resident. The second displays the errorlevel returned, as a decimal integer. ERRLEV then itself terminates, passing on to its invoking command shell the same error level with which your program terminated.

All output from ERRLEV itself is directed to the "Standard Error" device. This facilitates separation of the output of ERRLEV from the output of the program it is supervising. For example, if MYPROG generates a lot of output to the "Standard Output" device, that output can be redirected to a file, as

   ERRLEV MYPROG >OUTFILE.DAT

SETERR
Explicitly set an ErrorLevel from a BAT file

Invocation syntax:

   SETERR n
where n is an integer in the range 0..255. Hexadecimal number may be indicated by preceding with a dollar sign $. For examples,
   SETERR 1
   SETERR 255
   SETERR $FF
Application examples:
  1. This allows one BAT file to return some status to another one which calls it.
       BAT1.BAT                     BAT2.BAT
       --------                     --------
       ...                          ...
       SETERR 0                     call BAT1
       goto end                     if not errorlevel 1 goto end
       ...                          echo BAT1 returned ErrorLevel 1
       SETERR 1                     :end
       :end
    
  2. If a program is known to always exit with ErrorLevel=0, a BAT file may test whether or not it ran at all by explicitly setting the ErrorLevel to some nonzero value first:
       seterr 1
       format A:
       if not errorlevel 1 goto end
       echo Could not find FORMAT.COM
       :end
    

Installation

  1. Download and open errlev.zip.
  2. Move errlev.exe and seterr.exe into any directory on your command PATH.
  3. Save errlev.html (this file) for future reference.

Author: Rich Pasco