(Image: DOS Logo)

Doctor
DOS
Betamax's

DOS
EXIT CODES /
ERROR LEVELS


A Discussion of
Program Exit Numbers

(Image: EXIT Sign)

 


********

A step on the road to DOS Power is the usage of
Exit Codes. These provide a report after a command
or utility has performed its operations that informs the
user as to what took place. Batch file decisions regarding
subsequent operations are then enabled based on that code.

    This article discusses these codes and ways in which they might be used. Deep detail will not be gone into. If you want to know more, see your DOS manual and/or the On-Screen Help. Please note that for the purpose of this discussion, `Exit Code' will be capitalised.

Be aware that not everything presented here may
work as shown for the commands included with
the manufacturer or version of DOS you have.




NOTHING IN THIS ARTICLE MAY BE REPRODUCED
WITHOUT PERMISSION FROM THE AUTHOR ©

 EXIT:   What are Exit Codes?
    When DOS or its software finishes a command operation, it usually generates a numbered code upon exiting. When it gives that Exit Code, it is essentially saying: Here are the results of my work. Since these are generated after a command has finished and exited, they are known as "Exit Codes". These codes are hidden from the user but may be tested for via various methods.

    The codes give the computer system an idea of what happened during an operation or after it has completed. One code might signal that the task ended with no errors, or that it ended with no errors but that the operation was not successful. If an error did occur, a code might be generated depending on what the error was.


 EXIT:   Why Might I Want to Use Exit Codes?
    Since these codes can indicate what happened during a computer operation, they can be used in a batch file to tailor the direction of further procedures. So as an example, if one used the `FC' (File Compare) command and the outcome was that two files matched, a further procedure could be that the batch file be directed to delete one of the duplicate files. Another example of this is given farther on. (See this website's Batch File Tutorial for information on writing batch files.)



 EXIT:   What do Exit Codes Look Like?
    Each is one of 256 available values represented by a number from 0 (zero) through 255. `0' typically represents an operation that was completed with no errors. Other numbers might represent problems or various results. Note that not all available numbers will typically be used by a program. In fact, I know of only a few commands or programs that do use all numbers. In addition, there are also those that are programmed to generate random, meaningless numbers upon completion. They only generate one of these at a time but could eventually output all 256 numbers. However, they don't generate different, specific messages, or have designated purposes filling up every one of the 256 slots.

    One program that can use all 256 codes is the `CHOICE' command. This possibility would be represented by the case where a batch file programmer has made 254 choices available -- an unlikely situation. (Note that CHOICE's Exit Code `0' represents an interruption by the user, not a choice, and CHOICE's Exit Code `255' is generated if a syntax error occurs.) Another program that makes usage of almost all available codes is XXCOPY. (See the link at the end of this article, or if you use XXCOPY, go to its directory and issue "XXCOPY16 /HELPE" for a list of its DOS Exit Codes.)



 EXIT:   Can you Give an Example?
    Yes. Consider the DOS `FIND' command; it is used to search for a given text string. When it finishes (exits), it might generate an Exit Code of 0, 1, 2 or higher:


  0             FIND Completed Successfully and at least one Match was Found
  1             FIND Completed Successfully, but no Matches were Found
  2 or Higher   FIND did not Complete due to an Error

    The first means that FIND located at least one instance of the search string that was requested. The second means that FIND looked through the specified text but did not find the search string. The third means something happened and FIND was unable to finish or was unable to comply with the request. Perhaps the syntax of the request was incorrect or the user pressed Control-C to stop the action of FIND.

    The preceding Exit Codes were for the FreeDOS `FIND' command. Be aware that other DOS versions may use different codes or not generate a code other than `0' regardless of an operation's results.



 EXIT:   Do All DOS Commands Generate these Codes?
    No. Internal DOS commands in most versions do not. (4DOS is one exception.) However, most external ones do, but, as alluded to above, whether an external command does or not varies with different DOS manufactures, and the codes used also vary from manufacturer to manufacturer. They even vary from command version to version. See your manual or on-screen documentation.



 EXIT:   How Do I find Out what Codes are Available?
    Look in your DOS manual or on-screen help, or do an Internet search. Some DOS versions will give them, while others do not. There are utilities available that will display Exit Codes of a given command after completion, so it would be possible to develop a set for codes for a given command by experimenting with that under various conditions.



 EXIT:   Are all Code Numbers Utilised?
    As already touched upon above, generally, no. With 256 choices, few commands or programs could ever fill up all the slots unless they became very involved. In that case, they might conceivably have available a huge list of possible results. As was previously mentioned, some programs generate random codes upon completion, so over a period of time, all numbers might get used. However, since the numbers are random, they can serve no purpose to the end user and shall not be considered for the purposes of this article.



 EXIT:   Do Programs other than DOS Commands Give Exit Codes?
    Yes. Well-written command-line software will present a range of exit codes. The best generate a large array with enough specific circumstances covered to be very useful. View the documentation that accompanies each program to see if, and what, codes are available. In some cases, typing the program's executable name followed by ` /?' (space, forward slash, question mark) may present Exit Codes along with its syntax and switch list.



 EXIT:   Aren't Exit Codes also Called Something Else?
    Yes. Because these codes are mainly meant to show errors, they are known as "Error Codes" or "Error Levels". The idea of the latter is that when a command finishes, an error might occur. Generally, the worse the error, the higher the number, or level, of the error. Other, but less-used terms are "Return Values" or "Return Codes". That comes from the fact that when a command or program exits, it returns a value in the form of a number. I have also seen the term "Completion Codes".



 EXIT:   For What Purposes Can Exit Codes be Used?
    Besides finding out just what happened during a command or program's execution, one may use these codes to allow a batch file to make decisions. This was touched upon with the `FC' example farther back.

    To expand further, let's use the FIND example shown earlier. One might have a batch file perform an operation upon a file only if it contained a certain text string. This string could be a series of numbers, characters, or words. Conversely, if the file did not contain the string, a different operation might be done.

    To implement this, one uses the various Exit Code numbers within ERROR LEVEL tests to determine the next operation. Here's a specific example as a batch file. At the command line will be typed: "nation Canada" (without the quotation marks).

::NATION.bat
::
@ECHO OFF

:FIND
FIND %1 NATION.TXT
IF ERRORLEVEL 2 GOTO PROBLEM
IF ERRORLEVEL 1 GOTO NOT-FOUND
IF ERRORLEVEL 0 GOTO PRINT

:PROBLEM
ECHO    A Problem with FIND Has Occurred
ECHO     Please Correct It and Try Again
GOTO END

:NOT-FOUND
ECHO     `%1' Was Not Found
GOTO END

:PRINT
PRINT NATION.TXT

:END

    The batch file above requests that FIND look through a file called `NATION.txt' to see if the word `Canada' is in there. (`%1' represents the word "Canada" in this example.) FIND will generate an Exit Code of `0' if it is, and the batch file is directed to PRINT the NATION.txt file. `1' is generated if `Canada' is not found, wherby a message appears on the screen via an ECHO command to say so:

`Canada' Was Not Found

    If a code of `2' is generated a problem has occured regarding the FIND command. Should there be such a problem, the batch file branches to the PROBLEM section, places some text onto the screen and then ends. Notice that in the cases of the latter two Exit Codes, that the PRINT section is bypassed; NATION.txt will only be printed if `CANADA' is found.

    Despite the term "Exit Codes", "ERRORLEVEL" is used for the tests. Batch files test for exit codes by looking at number levels. Thus, "IF ERRORLEVEL 2 GOTO PROBLEM" means that if the Exit Code is number `2' (at a level of `2'), the batch file is to branch to the PROBLEM section.

    You can see in the example that the tests for these levels are done in descending order. This is because IF ERRORLEVEL does not just mean if the Exit Code is `n' number, it actually means if it is `n' number or higher. So "IF ERRORLEVEL 2 GOTO PROBLEM" actually says if the exit code is level `2' or higher, the batch file is to branch to the PROBLEM section. If the tests were done in ascending numerical order, the line "IF ERRORLEVEL 0 GOTO PRINT" would always be true because no matter what the Exit Code number is, it would always be equal to `0' or some number higher. So NATION.TXT would always be printed no matter what. Thus, tests are done in descending order.

Note that there is a way to do the tests in ascending order
but it means longer lines of code. It is not being presented
here as it might potentially add confusion to this discussion,
and because I like code to be as efficient as possible.



 EXIT:   Could You Give Another Example?
    Sure. Let us look closer at the CHOICE command. It's used to take a user's selection and act upon it. Here's a simple `Menu' batch file:


:: MENU.bat
::
@ECHO OFF

:MENU
ECHO         MENU
ECHO.
ECHO    1. Word Processor
ECHO    2. Spreadsheet
ECHO    3. Database
ECHO.
ECHO    Esc: Exit Menu
ECHO.

CHOICE /C:123<- /N > NUL
IF ERRORLEVEL 4 GOTO END
IF ERRORLEVEL 3 GOTO DATABASE
IF ERRORLEVEL 2 GOTO SPREADSHEET
IF ERRORLEVEL 1 GOTO WORD-PROCESSOR
GOTO END

:WORD-PROCESSOR
(start word processor program)
GOTO MENU

:SPREADSHEET
(start spreadsheet program)
GOTO MENU

:DATABASE
(start database program)
GOTO MENU

:END


    Here, the CHOICE command uses Exit Codes to show what number the user has pressed. One might interpret the line "IF ERRORLEVEL 3 GOTO DATABASE" as reading "If Choice Number 3 is selected, go to the `DATABASE' label and follow the instructions below it." After ending the database program, the menu is re-displayed allowing the user to choose a new task.

    Note that the left-pointing arrow ( <- ) in the "CHOICE" selection represents the `Escape' key on the keyboard. Also, realise that the `/N' switch tells CHOICE not to display the choices. Why? It's because the batch file has already displayed choices in the form of a menu via the ECHO lines. Finally, "> NUL" is used to prevent any of CHOICE's messages or other prompts from appearing on screen. This provides a clean look.



 EXIT:   What About Exit Codes in DOS Software, as Mentioned Previously?
    Although many softwares give no Exit Codes or always one of `0' when they are terminated (ended) by the user, utilities often include a good range of Exit Codes. Peruse the documentation that comes with each program to see if Exit Codes are given. Once they are known, you will be able to write much smarter batch files so as to take advantage of these codes.

    As an example, if one uses a program that converts graphic formats and it incorporates Exit Codes, placing the conversion operation into a batch file would allow lines to be written to make usage of these codes. So if the software has codes for various outcomes that might be encountered during a conversion, one could have the batch file automatically re-run itself using different command-line switches. These would instruct the converter to configure itself to make changes to the conversion process so as to have it result the way you prefer. (See DOS Switches for information on command-line switches.)

    All this would occur with little or no intervention from yourself. It is done by taking each Exit Code and deciding how you would fix the first result to make a second, more pleasing result. You would have specific instructions for each possible outcome that the program might present upon its completion. This way, the batch file will make the decisions for you, but with your predetermined criteria -- all with no additional input from you. This automates a chore that used to see you having to answer questions or checking boxes every time you used the program.



As has been seen, employing a program's Exit Codes allows
batch files to make intelligent decisions that automatically
direct a given program or do additional tasks based on a
program's outcome. If implemented well, the result will
be achievement of a higher DOS Power-User status.



  Here are other websites with
    Exit Code information:



Main DOS Page