SE_RETURN EXPLAINED

The SE_RETURN object is potentially the most confusing of the objects. However, it does not have to be. The main object,member pair associated with this object is SE_RETURN,SE_VALUE. This member is where you put the return value for your wrapper function. For instance, if you want to return the number 10, you would write:

sePutNumber(se, SE_RETURN,SE_VALUE, 10);

That part is easy. However, the SE_RETURN object has four other boolean members: SE_ERROR, SE_EXIT, SE_YIELD, and SE_SUSPEND. The last two are used for fibers and are covered in "Fibers and Threads". The first two are discussed next.

After you return a value (not before), you can mark that as an error result by setting the SE_RETURN,SE_ERROR member to be TRUE. Consider the JavaScript statement:

return 10;

versus

throw 10;

In the first case, the result is 10. In the second case it is also 10, but it is an error result of 10. If you don't understand the throw statement, you should consult a JavaScript reference. The return statement is identical to the example we gave above. The throw statement is done from the ScriptEase API as follows:

sePutNumber(se, SE_RETURN,SE_VALUE, 10);

sePutBoolean(se, SE_RETURN,SE_ERROR, TRUE);

Throwing arbitrary values in this way is not common and is usually reserved for complex scripts. Most often, you want to throw an exception. Some error happens, such as illegal parameters to your wrapper function, and you want to generate an error return. That is a common occurance, and ScriptEase provides the seThrow API call to do so. Explicitly setting SE_RETURN,SE_ERROR to TRUE is very uncommon, and you probably won't ever need to do it.

Similarly, the SE_EXIT flag indicates that the script should exit with the given value. Consider the C statement:

exit(10);

SE_EXIT is usually used to abort a script when an error occurs. Most of the time, you will use seThrow to generate an error. seThrow errors can be trapped using the try/catch statement allowing the script to recover from errors. However, if something so drastic has happened that the wrapper function decides the script must abort immediately and should not be trapped, you can duplicate the C exit() call using the SE_EXIT flag. This code does exactly that:

sePutNumber(se, SE_RETURN,SE_VALUE, 10);

sePutBoolean(se, SE_RETURN,SE_EXIT, TRUE);

There is one final thing you should know. Normally, you can keep overwriting SE_RETURN,SE_VALUE, and the last value returned is the result of the function. However, once any of the four boolean members is turned to TRUE, SE_RETURN,SE_VALUE becomes read-only. Any error is locked in this way. This means that if you call functions inside your wrapper function that generate an error, that error will also be the result of your own function, and propagated back to the user. This is usual desired behavior. In this way, you often do not need to check the error results of the ScriptEase functions you call, as those errors take precedence over whatever you try to return. This leads to small, easy-to-understand wrapper functions in most cases. If you have a more complex wrapper function that can recover from errors, you can unlock the error result by setting whichever of the four members that is TRUE back to FALSE.