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 is SE.RETURN,SE.VALUE and is where you put the return value for your wrapper function. For instance, if you want to return the number 10, you would write:

se.sePutNumber(SE.RETURN,SE.VALUE, 10);

That part is easy. However, the SE.RETURN object has four other boolean members: SE.ERROR, SE.EXIT, SE_.IELD, and SE.SUSPEND. The last two are used for fibers and are covered in Chapter XIII on fibers. 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:

se.sePutNumber(SE.RETURN,SE.VALUE, 10);

se.sePutBoolean(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. 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 Java statement:

System.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 Java System.exit() call using the SE.EXIT flag. This code does exactly that:

se.sePutNumber(SE.RETURN,SE.VALUE, 10);

se.sePutBoolean(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.