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, 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. Typical PPRTEXT usage is shown in the “Dynamic Statement Example” on page 174. 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.

The application should never alter this data; it has a declaration of:

01 SQL-RDTRTCON  PIC S9(9) <comp>.

Where <comp> is COMP-5 for MF COBOL and COMP for all other COBOL compilers.

2 ERROR-CODE—the application declares this field. The name is not important; the name shown is an example.

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

Declare this field as:

01  ERROR-CODE    PIC S9(9) <comp>.

Where <comp> is COMP-5 for MF COBOL and COMP for all other COBOL compilers.

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

01 ERROR-MSG.
   49 ERROR-LEN   PIC S9(4) <comp>.
   49 ERROR-TXT   PIC X(255).

Where <comp> is COMP-5 for MF COBOL and COMP for all other COBOL compilers.

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

Declare the ERROR-MSG field any size from 1 to 255.

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 can initialize the ERROR‑TXT field to spaces prior to calling PPRTEXT.

    The application should use the ERROR‑LEN field to determine the size of the actual text returned.

    4 MAX-LENGTH—the application declares and initializes this field.

    The name is not important; the name given is 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:

    01  MAX-LENGTH PIC S9(4) <comp> +255.

    Where <comp> is COMP-5 for MF COBOL and COMP for all other COBOL compilers.

    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:

    CALL ’PPRTEXT’ USING SQL-RDTRTCON,
                         ERROR-CODE,
                         ERROR-MSG,
                         MAX-LENGTH

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