RXS_throwError()

RXS_throwError() and RXS_catchError() are used as an extension to the RPG compiler’s MONITOR op-code. When IBM added the MONITOR op-code they only allowed for compiler predefined error messages to be “caught” on the corresponding ON-ERROR statement. That means you can’t have an ON-ERROR statement watching for a programmer defined error code. With just a little bit of additional code we can utilize the MONITOR and ON-ERROR clauses to our benefit. By surrounding a piece of code that could be erroneous with the MONITOR op-code we can use the ON-ERROR clause to catch any errors that are thrown by programs further down the program call stack, and then using RXS_catchError() to retrieve the most recent error off of the program call stack.

For example, if PGMA wraps a MONITOR around a call to PGMB and PGMB uses RXS_throwError() to generate an error, then the next line of code executed will be the ON-ERROR clause in PGMA because the RPG runtime recognizes that an error occurred and it looks for it’s next stopping point (ON-ERROR is one such stopping point). RXS_catchError can then be used within the ON-ERROR clause to retrieve the last error off of the program call stack. At that point PGMA has access to the error code, severity, program name and error text. The decision of how to continue is up to PGMA as it caught the error and avoided an abnormal end. This is similar to using a *PSSR subroutine except that with *PSSR your program doesn’t regain control after the *PSSR sub routine executes.

See the program ERR1 for more details on how to use this API.