Error_Handler Rule

Official Content
This documentation is valid for:
Provides a dynamic way to perform user-specific actions when a database-related error occurs during program runtime. Transactional and connection errors are detected and a user-defined routine is executed.

Syntax

Error_Handler(‘subname');

Where:
subname
Is the name of a subroutine contained in the program which makes use of this rule.

Description

The error_handler rule is declarative. It applies to the whole program, anywhere that an active error_handler command does not exists.

The scope of the rule/command will only be taken into consideration by the program that makes use of it. This means that it will not affect any programs called by the program that uses it, and if a program that uses this rule/command happens to call another program which also makes use of it, the second program will ignore the specification of the rule/command belonging to the calling program (the original program) and will not affect the calling program at all. Again, it should be pointed out that the use of this rule/command is limited to the program that uses it.

The error_handler program is called whenever a database related error is detected at run time. It receives no parameters and it allows usage of the &err global variable to identify GeneXus Error as specified below:
 

Name

Data Type

Description

&Err

Numeric(4)

It contains the GeneXus standard error codes or 999 if an undefined database error code is detected. We strongly recommend using this variable whenever possible to identify errors. This technique will make your programs portable from one GeneXus platform to another. The following list shows &Err values and their meaning:

1                       Duplicate record
101                   End of file
103                   Object locked (record or file)
105                   Object not found
106                   Database already exists
500                   Parent primary key not found
600                   Referencial Integrity error raised (only Java Generator)
999                   Unexpected DBMS error.

Also, it is possible to receive more detailed information about database native error codes and descriptions, defining these variables

Name

Data Type

Description

&gxDBErr

Numeric(5)  

Contains the native DBMS error code. Its value is set only when &Err is greater than 500, otherwise its value is undefined.

&gxDBTxt

Character(255) 

Contains the native DBMS error message. Its value is set only when &Err is greater than 500, otherwise its value is undefined.

&gxOper

Character(30)  

Contains a descriptive identification of the operation that had been taking place when the error was encountered. Possible values for this variable are: Declare, Fetch, Insert, Update, Delete

&gxErrTbl

Character(30)  

Contains the name of the table (if any) that was being accessed when the error occurred. This variable may contain the special value 'N/A', if no table is related to the database operation (i.e. database creation, remote procedure calls, etc.).

&gxErrOpt

Numeric(1)  

Used as a return code by the error_handler. Depending on the value set by the error_handler, the program will:

0 = Continue processing - The error is ignored.
1 = Retry the operation (retries the specified amount using the Lock retry count property). If the error continues after the retries it continues with the processing 
2 = Cancel application execution (at any sql error it will cancel the aplication)
3 = Perform default GeneXus processing 
(Default value) (it will behave in the same way as a program without error handler (some error are ignored like locked, duplicate, etc , and the rest cancel the application execution))

If the &gxErrOpt is set to 0 or 1 it will not show the error in the standard output because its being captured by the genexus generated code.

These Variables are not Global though, and can be used on each object has an Error_handler program.

Any dbms exception is caught by the error_hanlder rule and &gxDBErr and &gxDBTxt are loaded according to the error.

Example

Rules:

error_handler('DBErrors');

Events:

Sub 'DBErrors'
    If &Err = 1
        Msg('Duplicate record')
    Endif 
EndSub

Scope

Objects: ProceduresTransactions, Web PanelsWork Panels
Languages: .Net, Java, Ruby (up to GeneXus X Evolution 3), Visual FoxPro (up to GeneXus X Evolution 3)

See Also

Error_Handler Command


Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.