2003-12-31

MS-DOS errorlevels

Eric Auer points us to a page of MS-DOS errorlevels:

See users.cybercity.dk/~bse26236/batutil/help/BATCHSUP.HTM#8.01

This explains the errorlevels of FIND, CHKDSK, CHOICE, DEFRAG, DELTREE, DISKCOMP, DISKCOPY, FC, FIND, FORMAT, KEYB, MSAV, REPLACE, RESTORE, SCANDISK, SETVER, XCOPY.

Because MS tools often only use very few different errorlevels, I vote for a command line switch "return MS style errorlevels" for tools like CHKDSK or FORMAT. Without that command line switch, "more verbose" FreeDOS style errorlevels would be allowed.

Cheats:

  REM | %comspec% /c choice /c:delay /t:d,2 > nul

or

  choice /t\,2 /c\ wait >nul <aux

users.cybercity.dk/~bse26236/batutil/help/EMM386S.HTM tells that ROM=... would mean "shadow rom here". So indeed, it is different from X=... which excludes areas from remapping.

users.cybercity.dk/~bse26236/batutil/help/FORMAT_S.HTM explains FORMAT /C ... Without that switch, FORMAT would copy the list of bad sectors from previous disk contants and skip them in surface scan. The new /C option forces re-scanning them. FreeDOS FORMAT always discards the bad cluster list and always scans all or nothing of the surface. [TODO ITEM...!]

HIMEM has an option /A20CONTROL:OFF which means "if A20 found on when HIMEM started, leave A20 on all the time".

It also has /SHADOWRAM:ON which means "do not attempt to disable ROM shadowing if < 2 MB RAM". This implies that if you have < 2 MB RAM, HIMEM would normally try to enable the "memory hole" in the UMB area, to get more free XMS (but shadowing is impossible then).

Thanks go to David of wishmaster.at for finding this site. He has also told me about the device information word of MS ANSI: It is 0xc053 - while NANSI only has 0x8013. The difference: IOCTL supported and "EOF on input". I think I can simply set those 2 flags when /P mode of NANSI is on, BUT somebody must first tell me what "EOF on input" is supposed to mean. Thanks!

Maybe it is that one (see RBIL 61 table 02597, device driver request header) ... (and see table 02595, values for device driver command code) ... 6 "input status" (PS: MS shell or kernel expects command 0x0a, output status, to be supported, this is why I had to set that one to "chain" in the last MORE$ update) ... no idea if 0x10, output until busy is used ... Int 21.4406 explains: reports "BUSY" if input is "at EOF", where "at EOF" means "EOF char 0x1a encountered". Guess only cooked mode, not raw mode should ever return "at EOF"?

Explanation for "output status": DOS 2+ files are even ready if disk full or no disk in drive. Verrry useful. Probably meant to block only for serial console stdout case?

From my experience, "output status" is queried before an actual char device write happens. Guess MS kernel / shell would stay in idle loop until output is no longer busy if "busy" status returned?

Matthias Paul replies:

[.. I vote for a command line switch "return MS style errorlevels" ..] Nice idea in general, but for maximum compatibility with /existing/ batchjobs, in some sense I would like to suggest just the opposite:

Try to implement MS-DOS/PC DOS tools errorlevels as close as possible, and in case no MS-DOS errorlevels are known/ documented, try to follow DR-DOS tools, instead.

If a user wants more specific error levels, she should add a command line parameter /R (as for "return code"), which will, depending on the specific utility, return more detailed but for the most part arbitrary error levels in the range 0..255.

BTW. Since 1997, several of the DR-DOS tools have been enhanced to support just this option /R, although a list of the more detailed error levels has not been published up to now, unfortunately. But in some cases (for example MEMMAX), the scheme is easy enough to derive reading the help screen and carrying out a few tests. I chosed /R in favour to /E (as for "errorlevel"), since there have been no naming conflicts in the tools I expected to get enhanced with this feature eventually, and /E was already in use by some of the tools for other purposes. However, you will always run into conflicts in case this idea would get extended to a broad range of utilities, so I suggest to choose /E as a second choice in case /R is already used up or is used for another purpose, either in the corresponding FreeDOS tool itself, or in the MS-DOS/PC DOS/DR-DOS/PTS-DOS tools it resembles. This way we will attempt to keep this as uniform as possible.

I haven't cross-checked your list of error levels at the moment (sorry, no time for it right now), but over the years I have collected a quite long list of observed errorlevels myself. My list not only lists the officially documented return codes of MS-DOS, PC DOS and DR-DOS, but also many (for sure not all) of the undocumented codes, including some PTS-DOS, OS/2 and NT ones, whereever this was applicable. Maybe this list could be useful to whoever jumps on this idea as well. You can find it as part of the MPDOSTIP.ZIP package downloadable on my (very outdated - sic) web-page to be found via my signature below. Meanwhile the material is also floating around on various other German web sites (sometimes with my permission, but most often without any authorization...)

The list is in German language, but I think, the list of errorlevels is easy enough to translate. But if someone has specific questions in regard to it, feel free to ask and I will try to clear up the issue as my time allows. Of course, if someone is willing to compile a "master list" from the various sources in the net in English language and wants to include my list, that's fine with me as well.