Microsoft KB Archive/47351

Must Call _MSEXCODE Last to Return Error Level to Batch File

PSS ID Number: Q47351 Article last modified on 04-20-1993

3.00 3.00a MS-DOS

Summary: The error level detectable from an MS-DOS batch file is read from the AX register, which can be set by calling _MSEXCODE, a COBOL Versions 3.0 and 3.0a extension subroutine. The _MSEXCODE subroutine must be the last statement executed before exiting a program if the correct error level is to be detected in a batch file. If you don’t call _MSEXCODE to set the error level to 0 (zero), or the desired error level just prior to exiting, then the error level returned from the COBOL program will be unpredictable.

More Information: The COBOL 3.0 and 3.0a extension subroutine _MSEXCODE is analogous to the EXCODE extension subroutine found in COBOL Versions 2.0, 2.1, and 2.2. The _MSEXCODE routine allows the program to pass an error value to a calling batch file by setting the AX register to a specific value. COBOL Versions 2.x zeroed out the AX register for the programmer unless the EXCODE routine was called; therefore, if there was no error, the program would never have to execute the EXCODE statement. Under COBOL Versions 3.0 and 3.0a, the _MSEXCODE routine must be run just before exiting the program, whether an error occurred or not, or the batch file (if any) is given a meaningless, unpredictable error level. If the _MSEXCODE is called at any point before the very end of the COBOL program, the AX register may change in the course of the program, giving the batch file (if any) a meaningless, unpredictable error level. It is best to always call the _MSEXCODE routine as the last operation before exiting a COBOL 3.0 or 3.0a program, and to either set the error level to 0 (zero) or the appropriate error.

Code Example
IDENTIFICATION DIVISION. PROGRAM-ID. EXITTEST. DATA DIVISION. WORKING-STORAGE SECTION. 01 EXIT-CODE PIC 99 VALUE  16. PROCEDURE DIVISION. MAIN. CALL &quot;_MSEXCODE&quot; USING BY REFERENCE EXIT-CODE, BY CONTENT LENGTH OF EXIT-CODE. STOP RUN. To test the above program, you can create and run the following MS-DOS batch file, which runs the EXITTEST program and tests its MS-DOS exit code: EXITTEST ECHO OFF IF ERRORLEVEL = 16 GOTO WORKS IF ERRORLEVEL NOT = 16 GOTO FAILED GOTO THEEND :WORKS ECHO The EXITTEST program worked! GOTO THEEND :FAILED ECHO The EXITTEST program failed! :THEEND ECHO The EXITTEST program is done. End of batch file.

Additional reference words: 3.00 3.00a Copyright Microsoft Corporation 1993.