16.20 - Parameter-descriptor-pointer - Teradata Tools and Utilities

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

Teradata Tools and Utilities
September 2019
Programming Reference

Parameter-descriptor-pointer is a four byte address. It is processed when Request-mode is 'P' (CLIv2 builds the request parcels), ignored when 'B' (the application builds the request parcels). When the DBCAREA Varyinge-length-request option is 'N', Parameter-descriptor-pointer specifies an area containing parcels describing the parameters in the Parameterized SQL request; the number of bytes in this area is specified by the DBCAREA Parameter-descriptor-length. When the DBCAREA Varying-length-request option is 'Y', Parameter-descriptor-pointer specifies an area that begins with a two-byte unsigned integer that contains the number of bytes in the data that immediately follows and contains parcels describing the parameters in the Parameterized SQL request.

Parameter descriptor parcels provide the same information for a question mark in SQL statements (indicated by question marks, '?') as the USING row descriptor provides for explicitly named variables in SQL statements (indicated by a colon followed by a name, ':a', for example). Refer to Variables in SQL Requests. CLIv2 does not inspect the SQL request so does not know whether variables are used, which type of variables are used, or whether there is a USING row descriptor. The application should ensure that any parameter descriptors and if needed, that the proper parameter descriptors are provided.

The data consists of parcels which describe each parameter in a Parameterized SQL request. One Data-Information parcel, one Data-Information-Extended parcel, or one pair of Statement-Information and Statement-Information-End parcels may be specified. These are used to specify at least the Teradata Database datatype and length of the data for each parameter. Statement-Information may provide additional information using either Limited_layout or Untransformed-Limited_layout layouts for each parameter, after which the End_information layout must be present. The actual data for each parameter is provided by either the USING-data-pointer or USING-data-pointer-vector.

Either original or alternate parcel headers may always be used to describe the parameters, whatever the setting of the DBCAREA Request-parcel-format option. While the parcel flavors and lengths must be valid, CLIv2 will rebuild the headers when adding them to the CLIv2 request buffer using the unvalidated and unchanged parcel body. So errors in the parcel body will only be detected by Teradata Database. The area specified by the Parameter-descriptor-pointer is never changed by CLIv2.

The DataInfoExtended may be used only when supported by Teradata Database. This parcel was added to support Large Objects, so the DBCHQE Integrated-LOB query may be used to verify this support. The StatementInformation and StatementInformationEnd parcel pair may be used only when supported by Teradata Database. The DBCHQE StatementInformation-Request-usage or Aggregate-support-list queries may be used to verify this support.

The maximum size of the parameter descriptors may be limited by other DBCAREA options. Since a DBCAREA Varying-length-request option of 'Y' provides their length in a two-byte unsigned field, so the maximum size is 65535 bytes. A DBCAREA Maximum-parcel of 'O' also limits the size to 65535. The parameter descriptors are included in the request, whose total length is limited by Teradata Database. The DBCHQE CLIv2-limits query may be used to verify that the total request size is not exceeded.

While multiple rows of parameter data may be indicated by a value greater than one for the DBCAREA USING-data-count value, the same parameter descriptors apply to all rows. It is the data that is varying by row, not the type of data in each row.

In this language... The variable name for Parameter-descriptor-pointer is...
C, C++ 'parmDescriptorPtr'
This routine... Does this for Parameter-descriptor-pointer...
DBCHINI writes
Parameter-descriptor-pointer is used by... To...
applications write