16.20 - USING-data-pointer-vector - Teradata Tools and Utilities

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

Teradata Tools and Utilities
September 2019
Programming Reference

When USING-data-pointer-vector is not zero, USING-data-pointer-vector is a four byte pointer to a vector of pointers to data that is referred to by the USING row descriptor in the request string. When Varying-length-request is not specified, the lengths of the data are specified by corresponding entries in the USING-data-length-vector. When Varying-length-request is specified, the length of the data precedes the data itself. The number of entries in the list is given by USING-data-count.

USING-data-pointer-vector exists only when DBCHINI had been called for a DBCAREA with Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller DBCAREA, USING-data-pointer-vector is ignored.

In this language... The variable name for ]USING-data-pointer-vector is...
C, C++ dbriUDPV
This routine... Does this for USING-data-pointer-vector...
DBCHINI writes
USING-data-pointer-vector is used by... To...
applications write

Before calling DBCHCL for the Initiate Request function and if the request contains a USING row descriptor, the application must build a data string.

The data string must contain the data described by the USING row descriptor, and the Varying-length-request will be set to either of the following:

When Varying-length-request is set to this value... Then...
Y the USING-data-length-vector is ignored and the each data area addressed by USING data-pointer-vector must point to the two-byte area containing the length of the using data string, which is followed by the actual using data string.
N the application must supply the length information in the entries of USING-data-length-vector.

Since DBCHCL does not parse the request string, it is the application’s responsibility to check whether the request string contains a USING row descriptor and then to set the using-data appropriately. The maximum number of fields in the Teradata SQL USING row descriptor may be obtained using the DBCHQE SQL-limits query.

IF the data... THEN the application...
cannot contain nulls sets Use-presence-bits to N in the DBCAREA.
can contain nulls inserts bytes containing indicator bits at the front of the data string and sets Use-presence-bits to 'Y'. See Use-presence-bits.

The application does the following, depending on the setting:

  • N - Places the address of the string or of the first byte of presence bits, if any, in the data addressed by each vector entry of USING-data-pointer-vector.
  • Y - Inserts a two-byte length field in front of the presence bytes or data string, if there are no presence bytes, and place the address of the first byte of the two-byte length field in the data addressed by each vector entry of USING-data-pointer-vector. See Varying-length-request.

If there is no USING row descriptor in the request string, set USING-data-count to zero.