%ERROR

Return the number of the most recently trapped error

error = %ERROR([line], [status], [stv], [source_ file], {reserved1}{, reserved2})

xcall ERROR(error, [line], [status], [stv], [source_ file], {reserved1}{, reserved2})

Return value

error

The Synergy error number of the most recently trapped error. If no error has occurred yet, %ERROR returns a value of 0. (n)

Arguments

line

(optional) The variable that will be loaded with the line number of the statement that generated the error. (Program listings display the line number assigned to each line in a program. Line number information is only maintained for source lines in files that contain the PROC statement.) (n)

status

(optional) Returns the operating system error number from the last system call. (n)

stv

(optional) Returns the Synergy DBMS error number associated with the last I/O statement on Windows and UNIX or the RMS STV error number associated with the last I/O statement on OpenVMS. (n)

source_file

(optional) The variable that will be loaded with the number of the source file in which the error was generated. (n)

reserved1
reserved2

(optional) Reserved for internal use. (a)

Discussion

You will normally use %ERROR in the part of your program code that handles trappable errors. You can pass the result of %ERROR to the ERTXT subroutine to display the text of the error.

The most recent error and line numbers are global and are accessible to all routines in a program. You can easily access the same information with the %ERNUM and %ERLIN functions.

If the length of line is too short to hold all significant digits of the value being stored, an “Argument specified with wrong size” error ($ERR_ARGSIZ) occurs.

In Synergy .NET, source_file is always returned 0.

All I/O statements and many subroutines update the values returned by %ERROR. After you get an error with ONERROR or an I/O error list, we recommend that you use %ERROR to capture the error immediately, before it is updated by subsequent statements and subroutines.

On Windows and UNIX, only statements that perform file I/O can generate a Synergy DBMS error. On all operating systems, subsequent I/O can change the value, so retrieving the stv should be done as close to the I/O statement causing the error as possible. This value should be added to any application error logs in the event a failure occurs and Synergy/DE Developer Support is contacted.

With Synergy .NET, line has the following restrictions:

Line number information is accurate for Windows desktop and server applications only if the program is built in debug mode. And for x86 systems, if an application is built in debug mode, %ERROR returns the line number of the next executable line (if one exists) after the line for the requested routine. This is a Microsoft .NET Framework CLR limitation.
Line is ignored when using an I/O error list.

Examples

The following subroutine displays the most recent Synergy DBL error number, text, and line number.

subroutine proc_error
.define TTCHN   ,1
record
    msg         ,a45
proc
    xcall ertxt(%error, msg)
    writes(TTCHN, "Error#" + %string(%error) + ": " + msg +
  &        " at line " + %string(%erlin))
    return
endsubroutine