Result Reporting | Teradata VantageCloud Lake - Result Reporting

Result Reporting | Teradata VantageCloud Lake - Result Reporting - Teradata Vantage

Teradata® VantageCloud Lake

Deployment

VantageCloud

Edition

Lake

Product

Teradata Vantage

Published

January 2023

ft:locale

en-US

ft:lastEdition

2024-12-11

dita:mapPath

phg1621910019905.ditamap

dita:ditavalPath

pny1626732985837.ditaval

dita:id

phg1621910019905

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 Categories of SQLCODE Mean

The following table explains the meanings of the three basic SQLCODE categories:

SQLCODE	Meaning
Negative	An error occurred during processing. The application can determine the source of the error using the SQLCODE with the first SQLERRD element. SQLERRD shows the following: Error conditions detected by the precompiler execution environment Error conditions reported by CLI/TDP/database The first SQLERRD element is zero when the error is detected directly by the preprocessor. These items follow: A list of error codes The text associated with the code A possible explanation A possible solution for these errors When an error condition is detected by CLI, TDP, or the 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. Database error conditions are reported in the following distinct styles: Database codes that have similar or equivalent Database 2 (DB2) values are mapped to the DB2 value in the SQLCODE field. See Retryable Errors. Database codes that have no similar or equivalent code have the SQLCODE value set to the negative of the database code. In either case, the first SQLERRD element contains the actual value returned by the database. Use care in distinguishing between a precompiler execution time error and a database error because there are SQLCODE values that are found in both categories of error.
Zero	Processing was successful, though there may be warnings.
Positive	Termination was normal. Positive values other than 0 or +100 indicate database warnings, such as the end-of-data reached for a request.

SQLCODE

Meaning

Negative

An error occurred during processing.

The application can determine the source of the error using the SQLCODE with the first SQLERRD element.

SQLERRD shows the following:

Error conditions detected by the precompiler execution environment
Error conditions reported by CLI/TDP/database

The first SQLERRD element is zero when the error is detected directly by the preprocessor.

These items follow:

A list of error codes
The text associated with the code
A possible explanation
A possible solution for these errors

When an error condition is detected by CLI, TDP, or the 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.

Database error conditions are reported in the following distinct styles:

Database codes that have similar or equivalent Database 2 (DB2) values are mapped to the DB2 value in the SQLCODE field.
See Retryable Errors.
Database codes that have no similar or equivalent code have the SQLCODE value set to the negative of the database code.

In either case, the first SQLERRD element contains the actual value returned by the database.

Use care in distinguishing between a precompiler execution time error and a database error because there are SQLCODE values that are found in both categories of error.

Zero

Processing was successful, though there may be warnings.

Positive

Termination was normal.

Positive values other than 0 or +100 indicate database warnings, such as the end-of-data reached for a request.

PPRTEXT

Applications can get additional diagnostic help for a nonzero SQLCODE by invoking PPRTEXT.

PPRTEXT returns the error code (typically the same value as in the first SQLERRD element) and the text message associated with the condition.

The following four parameters are required to run PPRTEXT:

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 using 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 VantageCloud Lake - Database Messages.

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.

See the IBM documentation for information about DSNTIAR.