Handling errors

In any REXX script, the SYNTAX condition may be raised as a result of either an improperly written REXX script, or because you pass improperly formatted arguments to a function, or even because of some "severe" run-time error such as low memory.

For more information about SYNTAX handling in a GUI script, see GUI errors.

Non-syntax (Unzip) errors

With the exception of UnzipErrMsg(), the Unzip functions will return an empty string if the Unzip operation is successful, or an error message if a problem occurs. So, you can check the return from a Unzip 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 Unzip 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 UnzipOpen (note: we assume OPTIONS "C_CALL"):

/* Open a ZIP archive. */
err = UnzipOpen("ZipHandle", "MyTest.zip")

/* Check if UnzipOpen succeeded. */
IF err == "" THEN DO

   /* Yes, UnzipOpen 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 Unzip function caused the failure. For example, if UnzipGetItem fails to unzip an item, then the error message will be DLL function "UNZIPGETITEM" reports "Can't create/open file". This is more informative when you present the error message to the user.

To enable headings, you must set a variable named ZipHeading once:

/* Add a heading to error messages. */
ZipHeading = 1

To restore the default of no headings, then DROP ZipHeading.

SYNTAX

Alternately, you can choose to have Reginald raise the SYNTAX condition when an error occurs with a Unzip 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 Unzip 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 Unzip functions return an error number of 199), and CONDITION('M') to display a message box to the user containing the error message.

To enable the SYNTAX reporting feature, set ZipErr to the value 'SYNTAX' before calling any Unzip functions. Here, we enable the 'SYNTAX' option, and we CATCH SYNTAX. You'll note that we no longer have to check the return from UnzipOpen. Why? Because if an error occurs, we will jump directly to the CATCH SYNTAX. So, it's irrelevant what UnzipOpen returns.

/* Enable SYNTAX option and headings. */
ZipErr = 'SYNTAX'
ZipHeading = 1

/* A useful option. */
OPTIONS "C_CALL"

DO

   /* Open a ZIP archive. */
err = UnzipOpen("ZipHandle", "MyTest.zip")

   /* UnzipOpen 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 Unzip function.

If you have not set up your own CATCH ERROR handler, then the Unzip 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 ZipErr to the value 'ERROR' before calling any Unzip functions.

/* Raise ERROR whenever a Unzip function has an error. */
ZipErr = 'ERROR'

FAILURE

Another alternative you have is for Reginald to raise the FAILURE condition when an error occurs with a Unzip function.

If you have not set up your own CATCH FAILURE handler, then the Unzip 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 ZipErr to the value 'FAILURE' before calling any Unzip functions.

/* Raise FAILURE whenever a Unzip function has an error. */
ZipErr = 'FAILURE'

USER

Another alternative you have is for Reginald to raise one of the USER conditions when an error occurs with a Unzip function.

If you have not set up your own CATCH USER handler, then the Unzip 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 ZipErr to the number of the desired USER condition before calling any Unzip functions. Here, we have modified our example to use USER 10 condition:

/* Enable USER 10 option and headings. */
ZipErr = 10
ZipHeading = 1

/* A useful option. */
OPTIONS "C_CALL"

DO

   /* Open a ZIP archive. */
err = UnzipOpen("ZipHandle", "MyTest.zip")

   /* UnzipOpen succeeded if we didn't jump to CATCH SYNTAX. */

   CATCH USER 10
      /* Display an error message. */
      CONDITION('M')

END