Return Codes

STx stores return codes in a number of different shell variables.

Command Return Codes

When an STx command is run, the return code is stored in the shell variable RC. If RC is 0, the command was successful, otherwise the command failed. An error message describing the error can retrieved using the command EMSG.

#t := new table *
set $#t NonexistantCommand
if '$RC' != 0 em $RC ; $(emsg $RC)
// will display a message box with the message "unknown, missing or illformed function name"

The commands IF, DO and GOTO are exceptions, and do not assign a value to RC.

Macro Return Codes

When a macro returns, the value passed to the EXIT command is stored in the calling shell variable RESULT. This, unlike the commands RC value, does not have to be an integer (it may, e.g., be a string: EXIT 1 SET 'baked beans'). The value of RESULT must be copied or processed before the next macro or class code is executed. The value of RESULT is also used for inline-call replacement and for the side-effect-assignment in inline calls.

#keyword := set 'green'
#default := set 'black'
BUTIL GETKEYWORD $#keyword ; $#default ; $(STXCONSTANTS COLORS)
if '$RESULT' == '$#keyword' um "$#keyword" is an {{STX}} color keyword
// or
if '$(BUTIL GETKEYWORD $#keyword ; $#default ; $(STXCONSTANTS COLORS))' != '$#keyword' then
        um "$#keyword" is not an {{STX}} color keyword
end

Class Function Return Codes

Class functions also store their return code in the shell variable RESULT.

SYSTEM Return Codes

The SYSTEM command can be used to call a Windows system command. Although the SYSTEM command itself stores its return code in the shell variable RC, the external command that SYSTEM called also has a return code, and this is stored in the shell variable XRC.

Runtime Errors

There are two types of command failure:

• Expected
• Unexpected

An expected command failure is not a problem. If you test to see if a directory exists, and it doesn't, you will probably write the code to handle this failure. Likewise, if you look for a value in a table, and can't find it, you will probably write the code that adds a new entry. However, some command failures are unexpected, and you, as the programmer, do not write any code to deal with this. These types of 'unexpected' error can be effectively debugged by turning runtime error reporting on. Runtime error reporting is turned on when the global variable @REPORTRUNTIMERRORS is set to 1. If turned on, a dialog is displayed whenever an error occurs, offering the user the change to display the debugger at the offending line of code, ignore the error or abort the script.

The Silent Flag

STx provides a mechanism to differentiate between expected and unexpected command errors: the 'silent' flag. Many commands take an option /S (or something similar) which tells the shell that any error that might occur when this command is executed is expected. If runtime error reporting is turned on, these errors will not be reported (although a warning will be generated).