Help Center/ GaussDB/ Developer Guide(Distributed_3.x)/ Application Development Guide/ ECPG-based Development/ Error Handling/ sqlca
Updated on 2024-05-07 GMT+08:00
View PDF
Share

sqlca

The embedded SQL API provides a global variable sqlca (short for SQL communication area). sqlca covers warnings and errors. If multiple warnings or errors occur during the execution of a statement, then sqlca will only contain information about the last one. In a multithreaded program, every thread automatically gets its own copy of sqlca.

The data structure is as follows: 
struct 
{ 
    char sqlcaid[8]; 
    long sqlabc; 
    long sqlcode; 
    struct 
    { 
        int sqlerrml; 
        char sqlerrmc[SQLERRMC_LEN]; 
    } sqlerrm;
    char sqlerrp[8]; 
    long sqlerrd[6]; 
    char sqlwarn[8]; 
    char sqlstate[5]; 
} sqlca;

If no error occurred in the last SQL statement, sqlca.sqlcode will be 0 and sqlca.sqlstate will be 00000. If a warning or error occurred, then sqlca.sqlcode will be negative and sqlca.sqlstate will be different from 00000. For details about the values of SQLSTATE and SQLCODE, see SQLSTATE and SQLCODE.

If the last SQL statement was successful, then sqlca.sqlerrd[1] contains the OID of the processed row, if applicable, and sqlca.sqlerrd[2] contains the number of processed or returned rows, if applicable to the command.

In case of an error or warning, sqlca.sqlerrm.sqlerrmc will contain a string that describes the error. sqlca.sqlerrm.sqlerrml contains the length of the error message that is stored in sqlca.sqlerrm.sqlerrmc, that is, the result of strlen(). Note that some messages are too long to fit in the fixed-size sqlerrmc array; they will be truncated.

When a warning is generated, sqlca.sqlwarn[2] is set to W.

The fields sqlcaid, sqlcabc, sqlerrp, and the remaining elements of sqlerrd and sqlwarn currently contain no useful information.

Example: 
/* Integrate WHENEVER and sqlca to implement error handling. */
EXEC SQL WHENEVER SQLERROR SQLCALL print_sqlca();  

void print_sqlca() 
{ 
    fprintf(stderr, "==== sqlca ====\n");  
    fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode); 
    fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml); 
    fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc); 
    fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2],
                                                          sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]); 
    fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2], 
                                                          sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5], 
                                                          sqlca.sqlwarn[6], sqlca.sqlwarn[7]);
    fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate); 
    fprintf(stderr, "===============\n"); 
}
The output is similar to the following (here is a misspelled table name): 
==== sqlca ==== 
sqlcode: -400 
sqlerrm.sqlerrml: 49 
sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38 
sqlerrd: 0 0 0 0 0 0 
sqlwarn: 0 0 0 0 0 0 0 0 
sqlstate: 42P01 
===============
Parent topic: Error Handling