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

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

prodname
Teradata Tools and Utilities
vrm_release
16.20
created_date
September 2019
category
Programming Reference
featnum
B035-2417-108K

USING-data-pointer is a four byte field that specifies the address of the data string that is referred to by the USING row descriptor in the request string. DBCHCL does not parse the request string.

If USING-data-count contains zero, USING-data-pointer addresses a single area containing using-data. Any other value indicates that USING-data-pointer addresses a list of pointers to areas containing using-data. The number of pointers in the list is the value of USING-data-count.

It is the application‘s responsibility to be certain that a data string exists and that it is pointed to by USING-data-pointer if a USING row descriptor is in the request string. The maximum number of fields in the Teradata SQL USING row descriptor may be obtained using the DBCHQE SQL-limits query.

In this language... The variable name for USING-data-pointer is...
COBOL DBCAREA-USING-DATA-PTR
PL/I USING_DATA_PTR
C, C++ using_data_ptr
IBM Assembler DBRIUDP
This routine... Does this for USING-data-pointer...
DBCHINI writes
DBCHCL reads (IWPF; IRQ)
USING-data-pointer is used by... To...
applications write
When USING-data-pointer has this value... Then the following things are true:
0

No USING row descriptor is to be in the request string

No data string is to accompany the request (thus, neither USING-data-pointer nor Use-presence-bits contain meaningful information)

The length of the nonexistent data string is zero

anything else A USING row descriptor begins the request string
A data string accompanies the request (thus, USING-data-pointer and Use-presence-bits contain meaningful information)
If Varying-length-request is set to N... Then the length of the data string (including the bytes containing presences bits, if any) is provided as the value of USING-data-length.
If Varying-length-request is set to Y... Then the length of the data string (including the bytes containing presences bits, if any) is provided as the value of two-byte length field preceding the data string

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.

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 - place the address of the string or of the first byte of presence bits, if any, in USING-data-pointer.
  • Y - insert 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 USING-data-pointer. See Varying-length-request.

If there is no USING row descriptor in the request string, USING-data-length should be set to zero or USING-data-pointer should be set to zero or to hex FF000000 (PL/I null pointer).