In traditional Synergy, structured exception handling is the recommended error handling approach and is the conventional (and strongly recommended) approach in Synergy .NET, where ONERROR statements incur a performance penalty. To avoid a performance penalty in .NET, I/O error trapping should use I/O error lists instead of any form of error trapping or exception handling.
When Synergy DBL begins execution, all runtime errors are considered fatal. However, you can designate a subset of all possible runtime errors as trappable. This subset contains error conditions the program can resolve so that processing need not terminate.
A program can recognize and handle any subset of defined trappable errors with I/O error lists in the I/O statements and with the ONERROR statement. If an I/O error list exists, it supersedes any traps established by an ONERROR statement. For example, if both an I/O error list and ONERROR establish a label for the “End of file” error ($ERR_EOF), the label in the I/O error list is used.
When a trappable runtime error occurs, the runtime checks to see if the program has defined its own trap for the error. If it hasn’t, the program ends with the appropriate error message. If the program has defined a trap for the error, the operation causing the error is not completed and control is immediately transferred to the label associated with the error trap.
After an error is trapped, the program can determine which error caused the trap by either using the %ERNUM intrinsic function or calling the %ERROR subroutine. The ERROR subroutine or the %ERLIN intrinsic function returns the line number on which the error occurred. (In Synergy .NET, line numbers are only valid when the application is built in debug mode.) You can obtain the text of an error using the ERTXT subroutine.
The precedence of error traps is as follows:
- Specific I/O error trap
- ACCEPT, READS, or GETS end-of-file label
- General I/O error trap ([ERR=label])
- Qualified ONERROR statement
- Unqualified ONERROR statement
I/O error list
An I/O error list can be present in each Synergy DBL I/O statement. This list specifies labels to which control can be transferred if errors occur. Each particular error can be associated with a different label. This provides a simple but effective way to discriminate between possible errors an I/O statement might encounter. I/O error lists are the recommended way of handling I/O errors instead of incurring the overhead of ONERROR processing or structured exception handling.
An I/O error list is in effect only during the execution of the statement associated with the list. While the statement is being executed, any error specified in the list has precedence over the ONERROR list currently in effect.
An I/O error list has the following format:
One or more of the following items:
Any trappable error literal. Error literals are listed on the Synergy Errors tab.
Handle the “Channel has not been opened” error ($ERR_NOOPEN).
Handle the “Duplicate key specified” error ($ERR_NODUPS).
Handle past the end of the input file or overflow of output file errors ($ERR_EOF).
Handle any error not anticipated by other elements in the list.
Handle the ISAM “Key not same” error ($ERR_KEYNOT).
Handle record locking conflict errors ($ERR_LOCKED).
Handle the non-ISAM “Input exceeds size of input data area” error ($ERR_TOOBIG).
A label to which control is transferred if a specified error occurs.
We recommend that you use the error literal form in an I/O error list instead of specifying DUP, EOF, ERR, KEY, LOCK, or LONG.
The following example transfers control to the errlbl label if an “Invalid record size” error ($ERR_IRCSIZ) occurs on the READS statement:
reads(TTCHN, rec) [$ERR_IRCSIZ=errlbl]