Error trapping

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.

Synergy DBL is restricted to the characteristics of the underlying index subsystem (Synergy DBMS, RMS, and so forth). If an error occurs on an ISAM I/O statement such as FIND, READ, or READS (other than “Key not same” on an ISAM file), do not assume that the context or contents of the return buffers are the same on all subsystems. For example, if the first operation on a file is a FIND returning EOF, Synergy DBMS positions the next record as EOF, while RMS positions the next record as BOF—and a READS yields different results on each. Therefore, if you want to perform a READS after an erroneous operation, you must perform a FIND without error before performing the READS operation. Also, following a READ or READS error condition, the contents of the passed data record is undefined and should not be relied upon for subsequent operations. For example, on an ISAM file, if key is a field within the passed data record and an “End of file” error occurs, the key value must be reloaded before key can be used by the next READ. Additionally, an RFA retrieved via the GETRFA qualifier, the deprecated GETRFA routine, or the GETFA(“RFA”) routine should be disregarded immediately following an I/O error.

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:

element=label, ...

element

One or more of the following items:

err_literal

Any trappable error literal. Error literals are listed on the Synergy Errors tab.

CHN

Handle the “Channel has not been opened” error ($ERR_NOOPEN).

DUP

Handle the “Duplicate key specified” error ($ERR_NODUPS).

EOF

Handle past the end of the input file or overflow of output file errors ($ERR_EOF).

ERR

Handle any error not anticipated by other elements in the list.

KEY

Handle the ISAM “Key not same” error ($ERR_KEYNOT).

LOCK

Handle record locking conflict errors ($ERR_LOCKED).

LONG

Handle the non-ISAM “Input exceeds size of input data area” error ($ERR_TOOBIG).

label

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]