The data structure SQLCA is automatically included in each ADABAS application program. The database stores information about the execution of the last SQL statement in the components of the SQLCA. This section explains the meanings of the SQLCA components that are important for application programming; the exact structure of the SQLCA is then described after this section.
The components of the SQLCA have the following meanings:
SQLCAID
is a character string of length 8.
It contains the character string 'SQLCA ' and serves to find the SQLCA during analyzis of a dump.
SQLCABC
is a 4-byte integer.
It contains the length of the SQLCA in bytes.
SQLCODE
is a 4-byte integer.
It contains the return code. The value 0 indicates the successful execution of a statement. Codes greater than 0 indicate normal exceptional situations which can occur during the execution of an SQL statement and which should be handled within the program. Codes smaller than 0, on the other hand, indicate errors which can arise through invalid SQL statements, the violation of restrictions, or database system errors; these errors should result in aborting the program. Precompiler errors lie in the ranges from -700 to -899 and from -9801 to -9820. They are described in the manual Messages and Codes.
Exceptional situations can be:
+100 ROW NOT FOUND
+200 DUPLICATE KEY
+250 DUPLICATE SECONDARY KEY
+300 INTEGRITY VIOLATION
+320 VIEW VIOLATION
+350 REFERENTIAL INTEGRITY VIOLATED
+360 FOREIGN KEY INTEGRITY VIOLATION
+400 LOCK COLLISION
+450 LOCK COLLISION CAUSED BY PENDING LOCKS
+500 LOCK REQUEST TIMEOUT
+600 WORK ROLLED BACK
+650 WORK ROLLED BACK
+700 SESSION INACTIVITY TIMEOUT
(WORK ROLLED BACK)
+750 TOO MANY SQL STATEMENTS (WORK ROLLED BACK)
SQLERRML
is a 2-byte integer.
It contains the length of the error message from SQLERRMC.
SQLERRMC
is a character string of length 70.
It contains an explanatory text for any SQLCODE value not equal to zero. The user can select the language of this text (e.g., English or German) via the SET menu of the tool components.
SQLERRD
is an array of six 4-byte integers.
SQLERRD indicates in the third element how many rows have been retrieved, inserted, updated, or deleted by the SQL statement. If it contains the value -1, the number of rows retrieved is not known. If errors occurred in array statements, it contains the number of the last row which was processed correctly.
If syntax errors occurred in the ADABAS command, the sixth element of SQLERRD indicates the position in the command buffer where the errors were detected. The indicated position does not refer to a position within the program text, but to a position within the command buffer at the point in time of sending to the ADABAS kernel. For array statements, this value is undefined. In all the other cases, it is zero.
A value not equal to 0 is also written to the trace file.
The other elements in the array are not used.
SQLWARN0
is a character.
It is set to 'W', if at least one of the warnings SQLWARN1 through SQLWARNF has the value 'W'. Otherwise, SQLWARN0 has the value ' '. The characters 'W' for warning set and ' ' for warning not set are convention and apply to all warnings.
SQLWARN1
is a character.
It indicates whether character strings (ADABAS data type CHAR) have been truncated during the assignment to host variables. When this character has the value 'W', then an indicator variable may exist which indicates the length of the original character strings. SQLWARN1 will also be set if the column definition allows larger values than the host variable. SQLWARN1 will also be set for numeric values.
SQLWARN2
is a character.
It is set if NULL values occurred and were ignored during the execution of the SQL functions COUNT (not COUNTC(*)), MIN, MAX, AVG, SUM, STDDEV, or VARIANCE.
SQLWARN3
is a character.
It is set if the number of result columns of a SELECT or FETCH is not equal to the number of host variables in the INTO clause.
SQLWARN4
is a character.
It is set if an UPDATE or DELETE has been executed without a WHERE clause, i.e., on the entire table.
SQLWARN6
is a character.
It is set if, for an operation on DATE or TIMESTAMP in the database, an adaptation was made to a correct date.
SQLWARN8
is a character.
It is set if, for the generation of a result table, it was necessary to search through the entire table(s).
SQLWARNA
is a character.
It is set when it was not possible to check all SERVERDBs in a distributed database for the following functions:
- for a SELECT statement on system tables.
- when accessing tables without an <authid> specification.
SQLWARNB
is a character.
It is set if a TIME value is > 99 (or > 23 in USA format). The value will be corrected to modulo 100 (or 24).
SQLWARNC
is a character.
It is set if, in the case of a SELECT statement, more rows could be found than are allowed by ROWNO in the WHERE clause.
SQLWARND
is a character.
It is set if, in the case of a SELECT statement, the search was performed via a simply-indexed column which may contain NULL values. NULL values are not written to the index list; i.e., the SELECT statement must be formulated differently if you want to obtain the NULL values.
SQLWARNE
is a character.
It is set if the value of the secondary key has changed (transition to the next index list) during the execution of the SQL statements SELECT NEXT, SELECT PREV, SELECT FIRST or SELECT LAST executed by means of a secondary key.
SQLWARNF
is a character.
It is set if the current SERVERDB does not belong to the majority and a select statement was executed on a replicated table. This table could have been changed in the majority. It is therefore not ensured that on this SERVERDB, the select statement produces the same result that would have been determined for a SERVERDB belonging to the majority.
SQLRESULTN
is a character string of length 18.
After calling a SELECT statement, it contains the result table name. After all the other calls, SQLRESULTN is set to blank.
SQLCURSOR
is a binary number of 2 bytes length.
It designates the last column number of a row on the screen after calling a QUERY or REPORT command.
SQLPFKEY
is a binary number of 2 bytes length.
It designates the last-used function key after calling a QUERY or REPORT command. Only the number of the function key is stored.
SQLROWNO
is a binary number of 2 bytes length.
After calling a REPORT command, it contains the number of the row (rowno) in the result list on which the cursor was positioned when leaving the report. If the cursor is not positioned, 0 is returned.
SQLCOLNO
is a binary number of 2 bytes length.
After calling a REPORT command, it contains the number of the column (colno) in the result list on which the cursor was positioned when leaving the report. If the cursor was not positioned, 0 is returned.
SQLDATETIME
is a binary number of 2 bytes length.
It indicates the way in which the data types DATE, TIME, and TIMESTAMP are interpreted.
Values: 1 = Internal, 2 = ISO, 3 = USA, 4 = EUR, 5 = JIS.
The components of SQLCA that are not described in detail are required for internal purposes.
SQLCA Structure
The following data area is integrated via the SQLCA in order to receive the ADABAS error messages:
01 SQLCA GLOBAL EXTERNAL.
05 SQLENV PIC S9(9) BINARY SYNC.
05 SQLCAID PIC X(8).
05 SQLCABC PIC S9(9) BINARY SYNC.
05 SQLCODE PIC S9(9) BINARY SYNC.
05 SQLERRML PIC S9(4) BINARY SYNC.
05 SQLERRMC PIC X(70).
05 SQLERRP PIC X(8).
05 SQLERRD OCCURS 6 PIC S9(9) BINARY SYNC.
05 SQLWARN.
10 SQLWARN0 PIC X.
10 SQLWARN1 PIC X.
10 SQLWARN2 PIC X.
10 SQLWARN3 PIC X.
10 SQLWARN4 PIC X.
10 SQLWARN5 PIC X.
10 SQLWARN6 PIC X.
10 SQLWARN7 PIC X.
10 SQLWARN8 PIC X.
10 SQLWARN9 PIC X.
10 SQLWARNA PIC X.
10 SQLWARNB PIC X.
10 SQLWARNC PIC X.
10 SQLWARND PIC X.
10 SQLWARNE PIC X.
10 SQLWARNF PIC X.
05 SQLEXT PIC X(12).
05 SQLRESULTNAME PIC X(18).
05 SQLCURSOR PIC S9(4) BINARY SYNC.
05 SQLPFKEY PIC S9(4) BINARY SYNC.
05 SQLROWNO PIC S9(4) BINARY SYNC.
05 SQLCOLNO PIC S9(4) BINARY SYNC.
05 SQLMFETCH PIC S9(4) BINARY SYNC.
05 SQLTERMREF PIC S9(9) BINARY SYNC.
05 SQLDIAPRE PIC S9(4) BINARY SYNC.
05 SQLDBMODE PIC S9(4) BINARY SYNC.
05 SQLDATETIME PIC S9(4) BINARY SYNC.
05 SQLSTATE PIC X(6).
05 SQLARGL PIC X(132) VALUE SPACES.