# abort

Definition: | abort(integer i)
Description: | Abort execution of the program. The argument i is a small integer status value to be returned to the operating system. A value of 0 generally indicates successful completion of the program. Other values can indicate various kinds of errors. Batch programs (.bat or .cmd) can read this value using the %ERRORLEVEL% feature. A Phix program can read this value using system_exec().
pwa/p2js: | Implemented as crash("abort(%d)",{i}).
Comments: | abort() is useful when a program is many levels deep in subroutine calls, and execution must end immediately, perhaps due to a severe error that has been detected. If you do not use abort(), the application normally returns an exit status code of 0. If your program fails with a compile-time or run-time error then a code of 1 is usually returned. If a try/catch handler is in place, invoking abort(n) is mapped to throw(42,"abort(n)").
Important: | On Windows, an application should not use STILL_ACTIVE (259 or #103) aka STATUS_PENDING as an error code. Otherwise any other application waiting for it to terminate may hang indefinitely (whether written in Phix or not), and it is also quite likely to hamper attempts to shutdown or reboot the operating system.
Example: |
    if x=0 then
        puts(ERR, "can’t divide by 0 !!!\n")
        abort(1)
    else
        z = y / x
    end if
Implementation: | via :%opAbort in builtins\VM\pStack.e (an autoinclude) - be warned however it is low-level complicated stuff that you do not need to know.
See Also: | crash_message, system_exec, try, throw
Technicalia | Some special handling is in place for "p -test" whereby abort(N) returns error code N when interpreted rather than terminating immediately. This is reflected back to the shell via the abort(eres) at the end of p.exw, let me know if it causes any problems. Obviously this means that test programs (test\t01type.exw etc) should avoid abort(0) otherwise the p -test run will continue blindly and report no errors, with the specific exception of test\t48init.exw where that is precisely what we want to happen.