ASA Programming Guide
Embedded SQL Programming
The SQL Communication Area (SQLCA)
The fields in the SQLCA have the following meanings:
sqlcaid An 8-byte character field that contains the string SQLCA as an identification of the SQLCA structure. This field helps in debugging when you are looking at memory contents.
sqlcabc A long integer that contains the length of the SQLCA structure (136 bytes).
sqlcode A long integer that specifies the error code when the database detects an error on a request. Definitions for the error codes can be found in the header file sqlerr.h. The error code is 0 (zero) for a successful operation, positive for a warning and negative for an error.
For a full listing of error codes, see Database Error Messages.
sqlerrml The length of the information in the sqlerrmc field.
sqlerrmc Zero or more character strings to be inserted into an error message. Some error messages contain one or more placeholder strings (%1, %2, ...) which are replaced with the strings in this field.
For example, if a Table Not Found error is generated, sqlerrmc contains the table name, which is inserted into the error message at the appropriate place.
For a full listing of error messages, see Database Error Messages.
sqlerrp Reserved.
sqlerrd A utility array of long integers.
sqlwarn Reserved.
sqlstate The SQLSTATE status value. The ANSI SQL standard (SQL-92) defines a new type of return value from a SQL statement in addition to the SQLCODE value in previous standards. The SQLSTATE value is always a five-character null-terminated string, divided into a two-character class (the first two characters) and a three-character subclass. Each character can be a digit from 0 through 9 or an upper case alphabetic character A through Z.
Any class or subclass that begins with 0 through 4 or A through H is defined by the SQL standard; other classes and subclasses are implementation defined. The SQLSTATE value '00000' means that there has been no error or warning.
For more SQLSTATE values, see Database Error Messages.
The sqlerror field array has the following elements.
sqlerrd[1] (SQLIOCOUNT) The actual number of input/output operations that were required to complete a command.
The database does not start this number at zero for each command. Your program can set this variable to zero before executing a sequence of commands. After the last command, this number is the total number of input/output operations for the entire command sequence.
sqlerrd[2] (SQLCOUNT) The value of this field depends on which statement is being executed.
INSERT, UPDATE, PUT, and DELETE statements The number of rows that were affected by the statement.
On a cursor OPEN, this field is filled in with either the actual number of rows in the cursor (a value greater than or equal to 0) or an estimate thereof (a negative number whose absolute value is the estimate). It is the actual number of rows if the database server can compute it without counting the rows. The database can also be configured to always return the actual number of rows using the ROW_COUNT option.
FETCH cursor statement The SQLCOUNT field is filled if a SQLE_NOTFOUND warning is returned. It contains the number of rows by which a FETCH RELATIVE or FETCH ABSOLUTE statement goes outside the range of possible cursor positions (a cursor can be on a row, before the first row, or after the last row). In the case of a wide fetch, SQLCOUNT is the number of rows actually fetched, and is less than or equal to the number of rows requested. During a wide fetch, SQLE_NOTFOUND is not set.
For more information on wide fetches, see Fetching more than one row at a time.
The value is 0 if the row was not found but the position is valid, for example, executing FETCH RELATIVE 1 when positioned on the last row of a cursor. The value is positive if the attempted fetch was beyond the end of the cursor, and negative if the attempted fetch was before the beginning of the cursor.
GET DATA statement The SQLCOUNT field holds the actual length of the value.
DESCRIBE statement In the WITH VARIABLE RESULT clause used to describe procedures that may have more than one result set, SQLCOUNT is set to one of the following values:
0 The result set may change: the procedure call should be described again following each OPEN statement.
1 The result set is fixed. No re-describing is required.
In the case of a syntax error, SQLE_SYNTAX_ERROR, this field contains the approximate character position within the command string where the error was detected.
sqlerrd[3] (SQLIOESTIMATE) The estimated number of input/output operations that are to complete the command. This field is given a value on an OPEN or EXPLAIN command.