The results of SQL requests sent from an embedded SQL application are reported in the SQLCODE field of the SQLCA structure if the application is written to check SQLCODE values.
If the application is a stored procedure written to use SQLCODE, then status is reported to the SQLCODE status variable.
What Various Categories of SQLCODE Mean
The following table explains the general meanings of the three basic SQLCODE categories:
| WHEN SQLCODE is … | THEN … |
|---|---|
| negative | an error occurred during processing. The application can determine the source of the error using the SQLCODE in conjunction with the first SQLERRD element. SQLERRD shows the following:
The first SQLERRD element is zero when the error is detected directly by the preprocessor. These items are listed below:
When an error condition is detected by CLI, TDP, or the Teradata Database, the SQLCODE is set to the negative of the sum of the error code plus 10000. The application can look at the SQLCODE without interrogating the first SQLERRD element. Teradata Database error conditions are reported in the following distinct styles:
In either case, the first SQLERRD element contains the actual value returned by the Teradata Database. Use care in distinguishing between a precompiler execution time error and a Teradata Database error because some SQLCODE values are found in both categories of error. |
| zero | processing was successful, though there might be warnings. |
| positive | termination was normal. Positive values other than 0 or +100 indicate Teradata Database warnings, such as the end-of-data reached for a request. |
PPRTEXT
Applications can obtain additional diagnostic help for a nonzero SQLCODE by invoking PPRTEXT.
PPRTEXT returns the error code (normally the same value as in the first SQLERRD element) and the text message associated with the condition.
- The address of the runtime context area, SQL-RDTRTCON for COBOL and SQL_RDTRTCON for C and PL/I.
- A four-byte integer field to contain the actual error code.
- A varying character field up to 255 characters long to contain the error text.
- A two-byte integer field which contains the maximum size of the error text to be returned.
You can find examples of PPRTEXT usage in Teradata® Preprocessor2 for Embedded SQL Programmer Guide, B035-2446.
Warning Condition Reporting
Warning conditions are reported to the application by means of the SQLWARNn fields in SQLCA.
SQLWARN0 contains the value W if any warning condition is detected during execution.
The warning fields are used to signal such conditions as implicit rollbacks and data truncation.
See Teradata® Preprocessor2 for Embedded SQL Programmer Guide, B035-2446 for details of the exact values and conditions of each warning field.
Retryable Errors
Error codes for retryable events also are indicated via the SQLWARNn fields.
SQLWARN6 is set to R when such an error is detected. The application can then take the appropriate action.
For a list of retryable error codes, see Teradata Vantage™ - Database Messages, B035-1096.
Support for DSNTIAR
Whenever possible, the SQLERRM field of SQLCA contains message inserts usable by the IBM-supplied routine DSNTIAR. Details of the SQLERRM field are found in Teradata® Preprocessor2 for Embedded SQL Programmer Guide, B035-2446.
Refer to the IBM documentation for information about DSNTIAR.