For more information about SYNTAX handling in a GUI script, see GUI errors.
Non-syntax (twain device) errors
With the exception of certain Twain functions, most Twain functions will return an empty string if the twain operation is successful, or an error message if a problem occurs. So, you can check the return from a Twain function, and if it's not an empty string, then do some error handling.
By default, you are expected to check the return string from the Twain function (except as noted in the individual pages under "Functions Reference") and do error handling if necessary. You will also need to take care of presenting a message to the user (if you desire that).
For example, here is error checking for TwainAcquire (note: we assume OPTIONS "C_CALL"):
/* Start the download process. */ err = TwainAcquire() /* Check if TwainAcquire succeeded. */ IF err == "" THEN DO /* Yes, TwainAcquire succeeded. */ END ELSE GuiSay(err)
Adding a heading to the message
If desired, you can tell Reginald to preface the error message with a heading. This heading will tell you which GUI function caused the failure. For example, if GuiGetMsg is called with no windows being open, then the error message will be DLL function "GUIGETMSG" reports "No open windows". This is more informative when you present the error message to the user.
To enable headings, you must set a variable named TwainHeading once:
/* Add a heading to error messages. */ TwainHeading = 1To restore the default of no headings, then DROP TwainHeading.
SYNTAX
Alternately, you can choose to have Reginald raise the SYNTAX condition when an error occurs with a Twain function.
If you have not set up your own SYNTAX handler in your script, then your script will immediately abort with a message box automatically displayed by Reginald. The message box will include the error message, the source line upon which the error occurred, the name of the script that caused the error, and a help button to bring up online help for that error.
On the other hand, if you've used CATCH SYNTAX to set up your own SYNTAX handler, then Reginald will automatically jump to that handler. You'll never even return from that call to the Twain function. Rather, you'll jump out of the function and jump directly to your CATCH SYNTAX instructions. You can use CONDITION('D') to retrieve the error message, CONDITION('E') to fetch the error number (all twain functions return an error number of 255), and CONDITION('M') to display a message box to the user containing the error message.
To enable the SYNTAX reporting feature, set TwainErr to the value 'SYNTAX' before calling any Twain functions. Here, we enable the 'SYNTAX' option, and we CATCH SYNTAX. You'll note that we no longer have to check the return from TwainAcquire. Why? Because if an error occurs, we will jump directly to the CATCH SYNTAX. So, it's irrelevant what TwainAcquire returns.
/* Enable SYNTAX option and headings. */ TwainErr = 'SYNTAX' TwainHeading = 1 /* A useful option. */ OPTIONS "C_CALL" DO /* Start downloading images. */ TwainAcquire() /* TwainAcquire succeeded if we didn't jump to CATCH SYNTAX. */ CATCH SYNTAX /* Display an error message. */ CONDITION('M') END
ERROR
Another alternative you have is for Reginald to raise the ERROR condition when an error occurs with a Twain function.
If you have not set up your own CATCH ERROR handler, then the Twain function will simply return the error message as it does by default. Your script will not abort. Of course, you should check the return string for an error message in this case.
On the other hand, if you've used CATCH ERROR to set up your own ERROR handler, then Reginald will automatically jump to your CATCH ERROR instructions, just like in our SYNTAX example above.
To enable the ERROR reporting feature, set TwainErr to the value 'ERROR' before calling any Twain functions.
/* Raise ERROR whenever a Twain function has an error. */ TwainErr = 'ERROR'
FAILURE
Another alternative you have is for Reginald to raise the FAILURE condition when an error occurs with a Twain function.
If you have not set up your own CATCH FAILURE handler, then the Twain function will simply return the error message as it does by default. Your script will not abort. Of course, you should check the return string for an error message in this case.
On the other hand, if you've used CATCH FAILURE to set up your own FAILURE handler, then Reginald will automatically jump to your CATCH FAILURE instructions, just like in our SYNTAX example above.
To enable the FAILURE reporting feature, set TwainErr to the value 'FAILURE' before calling any Twain functions.
/* Raise FAILURE whenever a Twain function has an error. */ TwainErr = 'FAILURE'
USER
Another alternative you have is for Reginald to raise one of the USER conditions when an error occurs with a Twain function.
If you have not set up your own CATCH USER handler, then the Twain function will simply return the error message as it does by default. Your script will not abort. Of course, you should check the return string for an error message in this case.
On the other hand, if you've used CATCH USER to set up your own USER handler, then Reginald will automatically jump to your CATCH USER instructions, just like in our SYNTAX example above.
To enable the USER reporting feature, set TwainErr to the number of the desired USER condition before calling any Twain functions. Here, we have modified our example to use USER 10 condition:
/* Enable USER 10 option and headings. */ TwainErr = 10 TwainHeading = 1 /* A useful option. */ OPTIONS "C_CALL" DO /* Start downloading images. */ TwainAcquire() /* TwainAcquire succeeded if we didn't jump to CATCH USER 10. */ CATCH USER 10 /* Display an error message. */ CONDITION('M') END