ERROR VARIABLE

Operating Condition

Syntax: SET ERROR VARIABLE varname
SET ERROR VARIABLE ON/OFF

SET ERROR VARIABLE defines an error variable to hold error message numbers. The variable name (varname) defines the variable R:BASE uses to hold R:BASE error codes. If set to off (the default), error variable processing is removed.

When an error occurs in a command file, R:BASE normally displays a system error message. SET ERROR enables a programmer to anticipate errors in command and procedure files and program the file to keep running even when an error occurs.
You must always set ERROR VARIABLE off, rather than clearing it with the CLEAR VARIABLES command.

R:BASE resets the error variable to zero as each command is successfully run. If an error occurs, the error variable is set to the error number value. To determine the error condition for any line, you must immediately check the value of the error variable or capture the error value in a global variable for later examination.

By checking the error variable for a non-zero value, you can detect (or trap) many errors and run a sequence of error-handling commands such as an error-recovery procedure. Once the error number is captured in an error variable, you can write error-handling command files to control a program's flow based on these errors (error values).

The error variable value is set for each command that is run, not each line in a command file. If you have placed multiple commands on a line, the last command's error value is placed in the error variable. A similar situation occurs for multi-line commands such as the subcommands you can use when loading a data block with the LOAD command. For example, a data block loaded with the LOAD command leaves the error variable with a value of zero because the END command runs successfully, whether or not the data is actually loaded.

Rule violations do not set the error variable to a non-zero value; they are not the same as errors recognized by R:BASE.

The command below defines errvar as the current error variable:

SET ERROR VARIABLE errvar

When a command is run, R:BASE sets the error variable errvar to the error code before anything else happens. The following command lines illustrate how to use errvar in a command file.

LABEL tryagain

FILLIN vdbname USING 'Enter the database name: '

CONNECT .vdbname

IF errvar <> 0 THEN

WRITE 'Database not found.'

GOTO tryagain

ENDIF

The first command establishes a label to return to, the second requests that the user enter the name of a database, and the third opens the specified database using the global variable defined by the FILLIN command.

The IF...ENDIF structure checks the error variable value. If the value is not zero (that is, if the database was not opened successfully), then it sends a message to the screen and passes control to the label tryagain so that the user is asked to enter the database name again.

You can also write a separate command file specifically designed to handle a variety of errors. In this case, the above code might look like this:

FILLIN vdbname USING 'Enter the database name: '

CONNECT .vdbname

SET VARIABLE verr1 = .errvar

IF verr1 <> 0 THEN

RUN errhandl.cmd USING .verr1

ENDIF

This series of commands captures the error value in the global variable verr1 so that it can be passed through the USING clause of the RUN command to an error-handling routine. The routine itself determines the nature of the error and how to take care of the problem.

You can use the WHENEVER command to run status-checking routines for SQL commands. WHENEVER uses the special R:BASE variable SQLCODE. For more information about SQLCODE, refer to the "Variables" entry in the Reference Manual.