Programming Guide

ONERROR

Sets the behavior of the error handler

Synopsis

DBMS ONERROR CALL function
 
DBMS ONERROR CONTINUE
 
DBMS ONERROR JPL jplEntryPoint
 
DBMS ONERROR STOP

Arguments

CALL function
Name of prototyped C function.

JPL jplEntryPoint
Install a user function as the error handler. If Panther or the database engine find an error, Panther updates the global error and status variables (the @dm variables) and calls the installed function.

function
Name of prototyped C function.

jplEntryPoint
Name of JPL procedure.

CONTINUE
Prevents default error handler from aborting a JPL procedure where a Panther error occurs. Message display is not changed.

STOP
Restores default error handler.

Description

Use DBMS ONERROR to set or change the behavior of the Panther database error handler for the application. The default error handler displays the following:

If an error occurs while executing a JPL procedure, the default handler aborts the procedure, returning -1 to the calling procedure.

An application can override the default error handler with the command DBMS ONERROR and an argument. The error handler is global to the application. Each execution of this command overrides the previous error handler.

The function displays any error messages and its return code controls whether or not JPL execution is aborted.

The function is passed three arguments:

  1. The first 255 characters of the statement; if the statement was executed from JPL, this is the first 255 characters after the command word DBMS or DBMS SQL.
  2. The name of the database engine for the statement.
  3. Context flag; for the error handler its value is 2.

The function's return code is returned to the application. If an ONEXIT function and an ONERROR function are both installed, the return code from the ONERROR function takes precedence.

If the error occurred while executing a JPL statement with a DBMS command:

If the error occurred while executing a statement with the dm_dbms library function, the function returns the error handler's return code.

To use a C function as an error handler, you must first install the function as a prototyped function. Refer to "Prototyped Functions" in Application Development Guide for more information on prototyped functions.

Example

//Error handler installed in JPL.
 
proc entry
DBMS ONERROR JPL dbi_err
return
 
proc dbi_err (stmt, engine)
if @dmengerrcode == 0
	msg emsg stmt "%N" "Panther error: " @dmretmsg
else
	msg emsg stmt "%N" "Panther error: " @dmretmsg "%N"\
		":engine error: " @dmengerrcode " " @dmengerrmsg
return

The next example first checks to see if the Panther error is DM_ALREADY_ON. In this case, it simply displays a message and returns 0. For all other errors, it checks for an engine error code. If there is an engine error, it calls another subroutine to check for engine-specific errors. For any other errors, it displays the standard Panther message. 

proc entry
DBMS ONERROR JPL dbi_error_handler
return
proc dbi_error_handler (stmt, engine, flag)

	if (@dmretcode == DM_ALREADY_ON)
	{
		msg emsg "You are already logged on."
		return 0
	}
 
	if (@dmengerrcode != 0)
	{
		msg emsg @dmretmsg
		call engine_errors (engine)
	}
	else
	{
		msg emsg "Application Error:  " \
			@dmretmsg \
			"See the DBA for assistance."
	}
	return 1
 
proc engine_errors (engine_name)
	if engine_name == "xyzdb"
	...
// Examine DBMS error codes here.

See Also

ONENTRY, ONEXIT, Chapter 12, "DBMS Global Variables," Chapter 37, "Processing Application Errors," in Application Development Guide