Help Center/ GaussDB/ Developer Guide(Distributed_V2.0-8.x)/ Application Development Guide/ ECPG-based Development/ Error Handling/ Setting Callbacks
Updated on 2025-08-19 GMT+08:00
View PDF

Setting Callbacks

One simple method to catch errors and warnings is to set a specific action to be executed whenever a particular condition occurs. To set the callback, run the following command: 
EXEC SQL WHENEVER condition action;
condition can be one of the following:
  • SQLERROR: The specified action is called whenever an error occurs during the execution of an SQL statement.
  • SQLWARNING: The specified action is called whenever a warning occurs during the execution of an SQL statement.
  • NOT FOUND: The specified action is called whenever an SQL statement retrieves or affects zero rows.
action can be one of the following:
  • CONTINUE: ignores the callback error condition and continues the execution. It is usually used to stop a break condition. This is the default value.
  • GOTO label/GO TO label: jumps to a specified label (using the C goto statement).
  • SQLPRINT: prints a message to the standard error.
  • STOP: calls exit(1) to terminate the program.
  • DO BREAK: executes the C statement BREAK. This statement is used only in loops or switch statements.
The following is an example. 
/* It prints a simple message when a warning occurs and aborts the program when an error happens. */
EXEC SQL WHENEVER SQLWARNING SQLPRINT; 
EXEC SQL WHENEVER SQLERROR STOP;
  • The statement EXEC SQL WHENEVER is a directive of the SQL preprocessor, not a C statement. The error or warning actions that it sets apply to all embedded SQL statements that appear below the point where the handler is set, unless a different action was set for the same condition between the first EXEC SQL WHENEVER and the SQL statement causing the condition, regardless of the flow of control in the C program. Therefore, neither of the following C programs can achieve the expected effect: 
    /*  
 * ERROR  
 */ 
void func()
{
    ...     
    if (verbose) { 
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...     
    EXEC SQL SELECT ...;    
    ... 
}
    /* 
 * ERROR  
 */ 
void func()
{ 
    ... 
    set_error_handler(); 
    ... 
    EXEC SQL SELECT ...; 
    ... 
}  
static void set_error_handler(void) 
{ 
    EXEC SQL WHENEVER SQLERROR STOP; 
}
  • DO BREAK can be used only in the while, for, and switch scenarios. After DO BREAK is used, use the CONTINUE statement to ignore it.
Parent topic: Error Handling