(Image: DOS Logo)


Doctor
DOS
Betamax's

DOS
EXIT CODES /
ERROR LEVELS


A Short Discussion of
Program Exit Numbers

(Image: EXIT Sign)
 


********


Another step on the road to DOS power usage is to
utilise a command's exit codes. These tell what the result
was after a command has performed its task. Batch file
decisions may be made based on what code was generated.


    This webpage gives a short discussion of 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.

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


INFORMATION BELOW MAY NOT 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 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 all available codes is XXCOPY. (See the link at the end of this article, or if you use XXCOPY, issue "XXCOPY /HELP" .)



 EXIT: Can you Give an Example?
    Yes. Take 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.

    The preceding exits codes were for the FreeDOS "FIND" command. Be aware that other DOSes 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 here 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:


::NATION.bat
::
@ECHO OFF

:FIND
FIND "Canada" NATION.TXT
IF ERRORLEVEL 2 GOTO PROBLEM
IF ERRORLEVEL 1 GOTO END
IF ERRORLEVEL 0 GOTO PRINT

:PROBLEM
ECHO    A Problem with "FIND" Has Occurred
ECHO     Please Correct It and Try Again
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. FIND will generate an exit code of `0' if it is, `1' if it is not, and a code of `2' if a problem regarding the FIND command occurs. If there is a problem, the batch file branches to the "PROBLEM" section, places some text on the screen via ECHO commands and then ends. If the word is not found, the batch file is directed to end. If neither of these numbers are generated, an error level of `0' has occurred meaning the word "Canada" has been found, and so the batch file goes to the "PRINT" section.

    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 much longer lines of code. It is not being presented here as it might potentially add confusion to this discussion.)



 EXIT: Could You Give Another Example?
    Sure. Let's look closer at the CHOICE command. It is 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    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 "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.



 EXIT: What About Exit Codes in DOS Software, as Mentioned Previously?
    Although most 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 may write much smarter batch files to take advantage of them.

    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 problems 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 come out 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 makes 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 you can see, using a program's exit codes allows batch files to make intelligent decisions to 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 some websites with
    Exit Code information:



Main DOS Page