7. OpenSQL Features : Status Information : The SQL Communications Area (SQLCA)
 
Share this page                  
The SQL Communications Area (SQLCA)
The SQL Communications Area (SQLCA) consists of a number of variables that contain error and status information accessible by the program. This information reflects only the status of executed embedded OpenSQL database statements. Forms statements do not affect these variables. Because each embedded OpenSQL statement has the potential to change values in the SQLCA, the application must perform any checking and consequent processing required to handle a status condition immediately after the statement in question. Otherwise, the next executed OpenSQL statement might change the status information in the variables.
Each host language implements the SQLCA structure differently. For instructions on how to include the SQLCA in your applications, see the Embedded SQL Companion Guide.
The following list describes the variables that compose the SQLCA (not all of the variables are currently used):
sqlcaid
An 8‑byte character string variable initialized to “SQLCA.” This value does not change.
sqlcabc
A 4‑byte integer variable initialized to the length in bytes of the SQLCA, 136. This value also does not change.
sqlcode
A 4‑byte integer variable indicating the OpenSQL return code. Its value falls into one of three categories:
 
= 0
The statement executed successfully (though there may have been warning messages ‑ see sqlwarn0).
 
< 0
An error occurred. The value of sqlcode is the negative value of the error number returned to errorno. (For a discussion of errorno, see Error Handling (see page Error Handling).) A negative value sets the sqlerror condition of the WHENEVER statement.
 
>0
The statement executed successfully but an exceptional condition occurred. The value +100 indicates that no rows were processed by a DELETE, FETCH, INSERT, SELECT, UPDATE, MODIFY, COPY, CREATE INDEX, or CREATE...AS SELECT statement. This value (+100) sets the not found condition of the WHENEVER statement.
sqlerrm
A varying-length character string variable composed of an initial 2-byte count and a 70‑byte long buffer. This variable is used for error messages. When an error occurs for a database statement, the leading 70 characters of the error message are assigned to this variable. If the message contained within the variable is less than 70 characters, the variable contains the complete error message. Otherwise, the variable contains a truncated error message.
To retrieve the full error message, use the INQUIRE_SQL statement with the errortext object. If no errors occur, sqlerrm will contain blanks. For some languages, this variable is divided into two other variables: sqlerrml, a 2-byte integer count indicating how many characters are in the buffer, and sqlerrmc, a 70-byte fixed-length character string buffer.
sqlerrp
An 8-byte character string variable, currently unused.
sqlerrd
An array of six 4‑byte integers. Currently only sqlerrd(1) and sqlerrd(3) are in use. sqlerrd(1) is used to store error numbers returned by the server. For more information about sqlerrd(1), see Local and Generic Errors (see page Local and Generic Errors).
 
sqlerrd (3) indicates the number of rows processed by a DELETE, FETCH, INSERT, SELECT, UPDATE, MODIFY, COPY, CREATE INDEX, or CREATE...AS SELECT statement. All other database statements reset this variable to zero. Some host languages start array subscripts at 0. In these languages (C, BASIC), use the subscript 2 to select the third array variable.
qlwarn0 through
sqlwarn7
A set of eight 1-byte character variables that denote warnings when set to “W.” The default values are blanks.
 
sqlwarn0
If set to “W,” at least one other sqlwarn contains a “W.” When “W” is set, the sqlwarning condition of the WHENEVER statement is set.
 
sqlwarn1
Set to “W” on truncation of a character string assignment from the database into a host variable. If an indicator variable is associated with the host variable, the indicator variable is set to the original length of the character string.
 
sqlwarn2
Set to “W” on elimination of nulls from aggregates.
 
sqlwarn3
Set to “W” when mismatching number of result columns and result host variables in a FETCH or SELECT statement.
 
sqlwarn4
Set to “W” when preparing (prepare) an UPDATE or DELETE statement without a WHERE clause.
 
sqlwarn5
Currently unused.
 
sqlwarn6
Set to “W” when the error returned in sqlcode caused the abnormal termination of an open transaction.
 
sqlwarn7
Currently unused.
sqlext
An 8-byte character string variable not currently in use.