15.10 - Using Data Pointer - 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

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

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 Variable Length Request is set to this value...

Then the length of the data string (including the bytes containing presence bits, if any) is provided as the...

 

 

N

value of Using Data Length.

 

 

Y

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 Variable Length Request will be set to either of the following:

 

When Variable 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” on page 186.

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 “Variable Length Request” on page 197..
  • 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).