Official Content

Provides a dynamic way to perform user-specific actions when a database-related error occurs during program runtime.

Syntax

Error_Handler(‘subname');

Where:

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


Scope

Objects: ProcedureTransaction, Web Panel
Generators: .NET.NET Framework Java


Description

By using this rule, any transactional and connection errors are detected and a user-defined routine is executed.

It's a declarative rule which applies to the whole program, anywhere that an active error_handler command does not exist.

The scope of the rule or 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 that 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 standard variable to identify GeneXus Error as specified below:
 

Name

Data Type

Description

&Err

Numeric(3)

It contains the GeneXus standard error codes or 999 if an undefined database error code is detected. It is strongly recommended to use 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 (which can be assigned to the &Errmsg variable):

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                   Referential 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)  

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

&GxDbSqlState

Character(5)

It contains the native SQLSate error code.

&gxDBTxt

Character(255) 

It 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)  

It 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)  

It 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:  it will cancel the application at any SQL error.
3 = Perform default GeneXus processing: It's the Default value. It will behave in the same way as a program without an error handler, that is: some errors will be ignored as locked, duplicate, etc., and the rest will cancel the application's execution.

Considerations: 

  • If the &gxErrOpt is set to 0 or 1, the error will not be shown in the standard output because it's being captured by the GeneXus generated code.
  • If a Return command is executed within the subroutine called by the Error_Handler rule, the running object will end and it will return to the caller. In this case, the code that processes the error according to the &gxErrOpt value will not be executed. So, regardless of the value assigned to &gxErrOpt, the application will not cancel. In other words, if you assign &gxErrOpt=2 or &gxErrOpt=3 but a Return command is executed within the subroutine called by the Error_Handler rule, the application will not cancel.


Notes:

  • These Variables can be used on each object that has an Error_handler rule or command.
  • Any DBMS exception is caught by the error_handler rule or command. Then, the standard variables are loaded in the following cases:
    • &gxDBErr and &gxDBTxt are loaded in any case
    • &gxDBSqlState is loaded in:
      • Java
        • All DBMSes
      • .Net Framework:
        • PostgreSQL
        • Informix   
      • .Net:
        • MySQL
        • PostgreSQL

Samples


Consider a Transaction object with the following defined:

Rules:

error_handler('DBErrors');

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

See Also

Error_Handler Command

 



Last update: February 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant