15.10 - Using PPRTEXT to Retrieve Return Codes - Preprocessor2 for Embedded SQL

Teradata Preprocessor2 for Embedded SQL Programmer Guide

prodname
Preprocessor2 for Embedded SQL
vrm_release
15.10
category
Programming Reference
featnum
B035-2446-035K

PP2 provides a mechanism for retrieving the CLIv2, TDP, 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 of how an application might 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:

char  *SQL_RDTRTCON;

2 ERROR_CODE—Application declares this field; the name is not important and the name shown is an example.

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

Declare this field as:

int   ERROR_CODE;

3 ERROR_MSG—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:

VARCHAR  ERROR_MSG[255];
or
struct
{
short len;
char  arr[255];
} ERROR_MSG;

Note: The precompiler considers this field as varying-character.

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

The VARCHAR form can be used if the variable definition is included in a declare section.

The precompiler expands the definition to the ERROR_MSG structure, which should be coded if the definition is outside a declare section.

PPRTEXT returns one or both of the following:

  • The number of bytes in the message
  • The value given in the next field (MAX_LENGTH)
  • Remaining bytes are not filled with spaces.

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

    As with other varying character fields, no terminating null is placed at the end of the error message.

    The application should use the ERROR_MSG.len field to determine the size of the actual text returned.

    4 MAX_LENGTH—Application declares and initializes this field.

    The name is not important and the name given is just an example.

    PPRTEXT uses this field to determine the amount of text that can be placed in the text receiving field (ERROR_MSG.arr, 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 follows:

    short  MAX_LENGTH = 255;

    Note: Code the call to PPRTEXT as follows:

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

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