RXS_throwError
From Wiki
|
| User Guide |
Contents |
Description
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.
Prototype
D RXS_throwError pr extproc('ERROR_THROW') D pCode value Like(RXS_Error.code) D pSeverity value Like(RXS_Error.severity) D pPgm value Like(RXS_Error.pgm) D pText value Like(RXS_Error.text)
Parameters
- pCode
- Specify a code that uniquely identifies this error. A common practice is to use codes similar to CPF errors (i.e. CPF0000). An example would be RXP0000001 which is an error code thrown from RXS_parse when the IFS file containing the XML to process cannot be found.
- pSeverity
- Specify the severity of the error. As a general practice this should be set to 100 (highest severity) as RXS_throwError should only be used in ‘hard error’ cases where processing cannot or shouldn’t continue.
- pPgm
- Specify the program that is creating or throwing the error.
- pText
- Specify the error text to be sent with the error. This can be any value that helps describe the error that occurred.
Return value
None.
Notes / Examples
See the program ERR1 Included RXS Example Programs