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 (internet) errors

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

/* Initialize RexxInet. */
err = InetOpen()

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

   /* Yes, InetOpen 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 InetHeading once:

/* Add a heading to error messages. */
InetHeading = 1
To restore the default of no headings, then DROP InetHeading.


SYNTAX

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

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

/* Enable SYNTAX option and headings. */
InetErr = 'SYNTAX'
InetHeading = 1

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

DO

   /* Initialize RexxInet. */
   InetOpen()

   /* InetOpen 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 RexxInet function.

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

/* Raise ERROR whenever a RexxInet function has an error. */
InetErr = 'ERROR'

FAILURE

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

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

/* Raise FAILURE whenever a RexxInet function has an error. */
InetErr = 'FAILURE'

USER

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

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

/* Enable USER 10 option and headings. */
InetErr = 10
InetHeading = 1

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

DO

   /* Initialize RexxInet. */
   InetOpen()

   /* InetOpen succeeded if we didn't jump to CATCH USER 10. */

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

END