Using PPRTEXT to Retrieve Return Codes - Preprocessor2 for Embedded SQL

Teradata Preprocessor2 for Embedded SQL Programmer Guide

Product
Preprocessor2 for Embedded SQL
Release Number
15.00
Language
English (United States)
Last Update
2018-09-27
dita:id
B035-2446
lifecycle
previous
Product Category
Teradata Tools and Utilities

Using PPRTEXT to Retrieve Return Codes

PP2 provides a mechanism for retrieving the CLIv2, TDP, PP2 runtime, or Teradata Database return codes; and the message text associated with the SQLCODE.

When SQL Flagger warnings are found, only the first such warning for a particular statement is available through PPRTEXT. The application issues a call to PPRTEXT, passing four parameters as input to the routine.

For additional information on PPRTEXT, see Messages (B035‑1096). The four parameters are defined below, along with an example as to how an application may call this routine.

In order, the four parameters PPRTEXT expects to receive are:

1 SQL_RDTRTCON—Precompiler-generated field set by the code generated at precompile time.

This data should never be altered by the application. It has a declaration of:

DCL  SQL_RDTRTCON  FIXED BIN(31);

2 ERROR_CODE—The application declares this field. The name is not important and is shown as an example.

PPRTEXT places the actual error code in this field. No initialization is necessary.

Declare this field as:

DCL  ERROR_CODE    FIXED BIN(31);

3 ERROR_MSG—The application declares this field. The name is not important and the name shown is just an example; PPRTEXT places the message text and the length of the text returned in this field and no initialization by the application is necessary. Declare this field as follows:

DCL ERROR_MSG   CHAR(255) VAR;

Note: The precompiler considers this field as varying character.

The ERROR_MSG field may be declared any size from one to 255.

PPRTEXT returns at most the number of bytes in the message, the value given in the next field (MAX_LENGTH), or both.

Remaining bytes are not filled with spaces.

The application may initialize the ERROR_MSG.arr field to spaces prior to calling PPRTEXT.

4 MAX_LENGTH—The application declares and initializes this field. The name is not important and is given as an example.

PPRTEXT uses this field to determine the amount of text that can be placed in the text receiving field (ERROR_MSG, above). The value can be less than the actual size of the text field.

If the message text exceeds this value, the text is truncated. If the value of this field exceeds the size of the receiving field, unpredictable results can occur.

Declare this field as:

DCL MAX_LENGTH FIXED BIN(15) INIT(255);

Note: The +255 is the maximum length that can be returned based on the declaration of ERROR_MSG in this example.

Code the call to PPRTEXT as follows:

CALL PPRTEXT   (SQL_RDTRTCON,
             ERROR_CODE,
             ERROR_MSG,
             MAX_LENGTH);

Typical PPRTEXT usage is shown in the “Dynamic Statement Example” on page 209.