16.20 - Checking and Setting the NullBitVector - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
16.20
Release Date
April 2020
Content Type
Programming Reference
Publication ID
B035-1147-162K
Language
English (United States)

A NullBitVector identifies which elements in an ARRAY are present and not NULL, or present but is set to NULL.

A NullBitVector is an array of bytes that contain the presence bit for each initialized element in an ARRAY. Each byte contains 8 presence bits. The bits are stored in row-major order and are numbered from 0. A bit value of 1 means that the corresponding ARRAY element contains a non-null value. A bit value of 0 means that the ARRAY element is present but set to NULL.

The data type used to access the NullBitVector is defined in sqltypes_td.h as:

typedef unsigned char NullBitVecType;

Teradata provides the following library functions to check and set the bits of a NullBitVector.

Library Function Description
FNC_CheckNullBitVector Checks the value of one bit in a NullBitVector.
FNC_CheckNullBitVectorByElemIndex Checks the value of one bit in a NullBitVector where the bit to be checked may be referenced by the ARRAY type element index as specified by dimension.
FNC_SetNullBitVector Sets either one bit or all bits in a NullBitVector to the specified value.
FNC_SetNullBitVectorByElemIndex Sets one bit in a NullBitVector where the bit to be set may be referenced by the ARRAY type element index as specified by dimension.

The following shows a typical usage of a NullBitVector:

  1. Call FNC_GetArrayTypeInfo to find out the number of elements in the ARRAY argument. Alternatively, you can call FNC_GetArrayElementCount to find out the total number of elements that are currently present in the ARRAY argument.
  2. Allocate a new NullBitVector array:
    NullBitVector = (NullBitVecType*)FNC_malloc(nullVecBufSize);

    where nullVecBufSize is based on the number of elements in the ARRAY.

  3. Initialize the NullBitVector by setting all bits to 0 (not present):
    memset(NullBitVector, 0, nullVecBufSize);
  4. Call FNC_GetArrayElements to get the values of one or more ARRAY elements, passing the NullBitVector to the function. FNC_GetArrayElements modifies the NullBitVector to indicate which of the requested elements are present and not NULL, or present but set to NULL.
  5. Call FNC_CheckNullBitVector or FNC_CheckNullBitVectorByElemIndex with the modified NullBitVector to interpret the results returned by FNC_GetArrayElements.
  6. Call FNC_free to release allocated resources once you have processed the data.

For detailed information about these functions, see C Library Functions.