FNC_SetNullBitVector Function | C Library Functions | Teradata Vantage - 17.10 - FNC_SetNullBitVector - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
17.10
Release Date
July 2021
Content Type
Programming Reference
Publication ID
B035-1147-171K
Language
English (United States)

Sets either one bit or all bits in a NullBitVector that was previously allocated by the caller.

Syntax

void
FNC_SetNullBitVector ( NullBitVecType *NullBitVector,
                       int             indexValue,
                       int             presenceValue,
                       long            bufSize)

Syntax Elements

NullBitVector
a NullBitVector array previously allocated by the caller.
The data type used to access the NullBitVector is defined in sqltypes_td.h as:
   typedef unsigned char NullBitVecType;
indexValue
an integer value set to one of the following:
  • The single bit to be modified (indexValue ≥ 0, as specified in row-major order for an ARRAY).
  • -1 to indicate that all bits in the NullBitVector should be modified.
presenceValue
the value that the presence bit (indicated by indexValue) should be set to. If indexValue is -1, then all the bits in the NullBitVector will be changed to the value of presenceValue. The valid values are 1 or 0.
bufSize
the size in bytes of the NullBitVector as allocated by the caller prior to initialization of the NullBitVector by setting all bytes to 0.

Usage Notes

FNC_SetNullBitVector takes NullBitVector, indexValue, presenceValue, and bufSize as input and sets the presence bits for one individual bit or for all bits in NullBitVector. You can call this function to perform one of the following:

IF you want to... THEN set indexValue to... AND set presenceValue to...
set 1 bit to PRESENT the bit you want to modify 1
set all bits to PRESENT -1 1
set 1 bit to NOT PRESENT the bit you want to modify 0
set all bits to NOT PRESENT -1 0

For more information about using NullBitVectors, see Checking and Setting the NullBitVector.

Example Using FNC_SetNullBitVector

In this example, a new vector is allocated after getting the appropriate information for the ARRAY by calling FNC_GetArrayTypeInfo. Then, FNC_SetNullBitVector is called to set all of the bits to "not present".

void ArrayUDF ( ARRAY_HANDLE  *ary_handle,
                char           sqlstate[6])
{
    NullBitVecType *NullBitVector;
    array_info_t arrayInfo;
    long nullVecBufSize;
    bounds_t arrayScope[FNC_ARRAYMAXDIMENSIONS];

    /* Call FNC_GetArrayTypeInfo first to find out the number of */
    /* elements in the array. */
    FNC_GetArrayTypeInfo(*ary_handle,
                         &arrayInfo,
                         arrayScope);
    (arrayInfo.totalNumElements % 8 == 0) ?
       (nullVecBufSize = arrayInfo.totalNumElements / 8) :
       (nullVecBufSize = arrayInfo.totalNumElements / 8) + 1;

    /* Allocate a new NullBitVector array. */
    NullBitVector = (NullBitVecType*)FNC_malloc(nullVecBufSize);

    /* Set all bits in NullBitVector to 0 (not present) */
    FNC_SetNullBitVector(NullBitVector, -1, 0, nullVecBufSize);
    ...
}