DOS
Betamax's
DOS
EXIT CODES /
ERROR LEVELS
A Discussion of
Program Exit Numbers
|
|
Doctor DOS Betamax's |
DOS
|
|
A step on the road to DOS Power is the usage of
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 |
NOTHING IN THIS ARTICLE MAY BE REPRODUCED
WITHOUT PERMISSION FROM THE AUTHOR ©
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.
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.)
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.)
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.
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.
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.
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.
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.
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".
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.
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.
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:
