7.7 Error handling

There are several ways of dealing with errors in Hollywood. The easiest is to let Hollywood do everything for you, which is the default behaviour. By default, Hollywood will always terminate your script when an error occurs inside a Hollywood function. Consider the following code:

 
LoadBrush(1, "xyz")

If the file xyz does not exist, Hollywood will terminate your script and show an error that says: "Cannot read file xyz!"

If you do not like this behaviour, you can also tell Hollywood to call a function provided by you whenever an error occurs. This is possible by calling the RaiseOnError() function and providing a callback function that Hollywood should run whenever an error occurs. Here is how you can replace Hollywood's default error handler with a custom error handler:

 
Function p_ErrorFunc(code, msg$, cmd$, line)
   DebugPrint(code, msg$, cmd$, line)
EndFunction
RaiseOnError(p_ErrorFunc)
LoadBrush(1, "xyz")

If you use the code above, calling LoadBrush() with a brush that doesn't exist, won't trigger Hollywood's default error handler but will instead call the user function p_ErrorFunc() and pass further information about the error that has just occurred to it. See RaiseOnError for details.

Sometimes, however, it can be useful to know if a single call succeeded or not. This can be achieved by temporarily disabling Hollywood's error handler and getting the error code from the last function call, for example like this:

 
ExitOnError(False)       ; disable default error handler
LoadBrush(1, "xyz")
error = GetLastError()
ExitOnError(True)        ; enable default error handler again

The code above temporarily disables Hollywood's default error handler just for the duration of the LoadBrush() call. Right after the LoadBrush() call we use GetLastError() to find out if the LoadBrush() call has succeeded or not. It is important to call GetLastError() immediately after LoadBrush() because the internal error flag will be reset whenever a Hollywood command is executed so if you call another function after LoadBrush() GetLastError() will return the error state of this function instead of LoadBrush().

Since the code above requires lots of typing for a rather simple thing, there is also some syntactic sugar which does the same as the code above while dramatically reducing the amount of typing that is required. Instead of calling ExitOnError() and GetLastError() manually like shown above, you can also have Hollywood do all that automatically for you by simply prefixing function calls with a question mark. Thus, the code above could also be written like this:

 
error = ?LoadBrush(1, "xyz")

In case a function returns other values and you use a question mark to obtain an error code from a function call, all other return values are simply shifted down. The error code will always be the first return value. For example, if we want to use automatic ID selection with LoadBrush() and combine this with the question mark syntax, we have to write the code like this:

 
error, id = ?LoadBrush(Nil, "xyz")

Normally, id would be the first return value but since we use the question mark syntax to obtain an error code from LoadBrush(), the first return value is shifted down and becomes the second return value now because the error code will always be in the first return value.

Finally, to check whether an error has occurred or not, you just have to compare the error code error against #ERR_NONE, which is defined as 0 for convenience, i.e. whenever error is not 0 you know that something went wrong. You could then use GetErrorName() to convert the error code into a human-readable string or implement some custom error handling depending on the error code that has been set. See Error codes for a list of all error codes.

Please note that there are some errors that cannot be caught. For example, if you pass the wrong number of arguments to a function or you pass wrong variable types to a function, Hollywood will always exit immediately with a fatal error and your script won't be given a chance to catch such errors. Even though they occur at runtime, Hollywood will consider such errors syntax errors and will immediately exit. Here is an example where we pass a string in the first argument of LoadBrush() which is forbidden because LoadBrush() expects a number:

 
ExitOnError(False)
LoadBrush("Hello", "xyz")
ExitOnError(True)

Although we have disabled Hollywood's error handler by passing True to ExitOnError(), Hollywood will still immediately halt the script's execution because passing "Hello" to LoadBrush() is just plain wrong and Hollywood will consider this a major mistake and won't allow your script to intercept this error in any way.


Show TOC