15.10 - PrepInfoX - Call-Level Interface Version 2

Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems

prodname
Call-Level Interface Version 2
vrm_release
15.10
category
Programming Reference
featnum
B035-2417-035K

Purpose

Returns a description of the return data specified by a request, when that request is sent to the Teradata Database with a Request Processing Option of Prepare and a Response Mode of MultipartIndicator when Return‑statement‑info 'Y' was not specified.

The parcel also contains an estimate of the time it will take to execute the statement.

Usage Notes

If the PrepInfoX parcel contains zeros, the statement was an ECHO statement. The PrepInfoX parcel is generated by the Teradata Database.

Parcel Data

The following information applies to the PrepInfoX parcel.

 

Flavor

Parcel Body Length

Parcel Body Fields

125

12 to maximum body size

CostEstimate:

SummaryCount:

8 byte floating

2 byte unsigned integer

The following occur once for the SELECTed columns, and SummaryCount times for any WITH clauses.

ColumnCount:

2 byte unsigned integer

     For decimal columns, the following occur:

     DataType:

     DataLen:

     Unused:

     ColumnName:

 

 

     ColumnFormat:

 

     ColumnTitle:

2 byte unsigned integer

8 bytes

2 bytes

two byte unsigned integer plus the number of bytes specified by that integer

two byte unsigned integer plus the number of bytes specified by that integer

two byte unsigned integer plus the number of bytes specified by that integer

 

 

     For non-decimal columns, the following occur:

 

 

     DataType:

     DataLen:

     CharacterType:

     ColumnInformation

     ColumnName:

     ColumnFormat:

     ColumnTitle:

2 byte unsigned integer

8 bytes

1 byte unsigned integer

8 bits

2 to 92 bytes of characters

2 to 92 bytes of characters

2 to 182 bytes of characters

Field Notes

The following notes apply to PrepInfoX fields.

  • CostEstimate returns a time estimate, in milliseconds, of how long it will take to execute a request.
  • The CostEstimate field is set to zero if the estimated time is negligible.

  • SummaryCount specifies the number of WITH clauses in the request.
  • The SummaryCount field is set to zero if no summary data is returned, that is, if the request is not a SELECT statement or if the request is a SELECT statement without any WITH clauses, when Return‑statement‑info 'Y' was not specified.

  • ColumnCount specifies how many sets of column‑descriptive fields follow.
  • The first occurrence of ColumnCount indicates the number of columns returned by the statement.

    It is immediately followed by as many sets of the column‑descriptive fields as required to describe each column.

    Next, if SummaryCount is greater than zero, a group of fields is returned once for each WITH clause.

    Each group comprises a ColumnCount field that indicates the number of columns referenced in the clause, and as many sets of the column‑descriptive fields as required to describe each column in that clause:

  • DataType specifies a code associated with a column’s data type. See Table 65 on page 428 for the possible data types.
  • DataLen specifies a column‘s length in bytes.
  • However, if a column’s data type is DECIMAL, the first four bytes contain the integral digits and the second four bytes contain the fractional digits.

  • CharacterType specifies a code associated with a column’s data type, as follows:
  •  

    Table 71: PrepInfoX Data Types 

    If the data type is...

    Then the code is...

    Not character data

    0

    Latin1

    1

    Unicode

    2

    KanjiSJIS

    3

    Graphic

    4

    Kanji1

    5

  • ColumnInformation specifies whether the character column is case sensitive. If so, the value is hexadecimal '80'; otherwise the value is hexadecimal '00'.
  • ColumnName specifies a column‘s name, consisting of length in bytes of the name followed by that name in characters from the current session character set. The maximum length of a name currently may be obtained using the DBCHQE SQL‑limits query, though in the future the maximum might increase to allow character representation information. The absolute maximum is 65535.
  • If a column is the result of an expression, the first two bytes contain a length of zero and the text portion of the field is empty.

  • ColumnFormat specifies a column‘s format, consisting of length in bytes of the Format followed by that Format in characters from the current session character set. The maximum length is not externally provided by the Database so the only limit available is 65535.
  • If a column‘s format is null, the first two bytes contain a length of zero and the text portion of the field is empty.

  • ColumnTitle specifies a column’s title, consisting of length in bytes of the Title followed by that Title in characters from the current session character set. The maximum length is not externally provided by the Database so the only limit available is 65535.
  • If a column‘s title is null, the first two bytes contain a length of zero and the text portion of the field is empty.

    For example, consider the following SELECT statement,

    SELECT Name 
    FROM Employee 
    WITH COUNT (DeptNo), SUM (Salary) BY Salary
    WITH COUNT (DeptNo) BY DeptNo;

    This statement produces a PrepInfoX parcel with the following byte sequence:

    Parcel flavor is 86 with length 124
    40 4D BE B8 51 EB 85 1E 00 02 00 01 01 C0 00 00
    00 00 00 00 00 0C 01 80 00 04 D5 81 94 85 00 05
    E7 4D F1 F2 5D 00 04 D5 81 94 85 00 02 01 F1 00
    00 00 00 00 00 00 04 00 00 00 00 00 06 60 4D F1
    F0 5D F9 00 0B E2 E4 D4 4D C4 85 97 A3 D5 96 5D
    01 E5 00 00 00 0F 00 00 00 02 00 00 00 00 00 0A
    E9 E9 E9 6B E9 E9 F9 4B F9 F9 00 0B 53 75 6D 28
    53 61 6C 61 72 79 29 00 01 01 F1 00 00 00 00 00
    00 00 04 00 00 00 00 00 06 E2 E4 D4 4D E2 81 93
    81 99 A8 5D 00 0B 53 75 6D 28 44 65 70 74 4E 6F
    29

    The parcel fields, above, translate as follows (an explanation of each acronym follows):

    CE CE CE CE CE CE CE CE SC SC CC CC DT DT DL DL
    DL DL DL DL DL DL CS CI NL NL CN CN CN CN FL FL
    CF CF CF CF CF TL TL CT CT CT CT CC CC DT DT DL
    DL DL DL DL DL DL DL CS CI NL NL FL FL CF CF CF
    CF CF CF TL TL CT CT CT CT CT CT CT CT CT CT CT
    DT DT DL DL UU UU NL NL FL FL CF CF CF CF CF CF
    CF CF CF CF TL TL CT CT CT CT CT CT CT CT CT CT
    CT CC CC DT DT DL DL CS CI NL NL FL FL CF CF CF
    CF CF CF TL TL CT CT CT CT CT CT CT CT CT CT CT
     

    CostEstimate

    =

    CE, 8 bytes

    SummaryCount

    =

    SCxx, where xx is the number of WITH clauses, 2 bytes

    ColumnCount

    =

    CCxx, where xx is the number of columns, 2 bytes

    DataType

    =

    DT, 2 bytes

    DataLen

    =

    DL, 8 bytes

    Unused

    =

    UU, 2 bytes

    CharacterType

    =

    CS, 1 byte

    ColumnInformation

    =

    CI, 1 byte

    ColumnName

    =

    NLxx followed by CN, where xx indicates the field‘s length and CN represents the text, 2 to 92 bytes

    ColumnFormat

    =

    FLxx followed by CF, where xx indicates the field‘s length and CF represents the text, 2 to 92 bytes

    ColumnTitle

    =

    TLxx followed by CT, where xx indicates the field‘s length and CT represents the text, 2 to 182 bytes