16.20 - Syntax - 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)
void
FNC_GetArrayElements ( ARRAY_HANDLE     aryHandle,
                       bounds_t        *arrayInterval,
                       void            *returnValue,
                       long             returnValueBufSize,
                       NullBitVecType  *nullBitVec,
                       long             nullBitVecBufSize,
                       long             *length  )
ARRAY_HANDLE aryHandle
the handle to an ARRAY type that is defined to be an input parameter to an external routine.
bounds_t *arrayInterval
an array of bounds_t structures that provides the index to the set of ARRAY elements that will be retrieved.
For a 1-D ARRAY, the index to the set of elements is provided in the first cell of the arrayInterval array. If the ARRAY type is n-D, then subsequent dimension information is placed in cells 2-5 as needed.
The bounds_t structure is defined in sqltypes_td.h as:
typedef struct bounds_t {
   int lowerBound;
   int upperBound;
} bounds_t;
The value of lowerBound specifies the first value in the given dimension to be retrieved, and upperBound specifies the last value in the given dimension to be retrieved.
This range of elements must be sequential for a 1-D ARRAY, and must be specified as a slice or rectangle of elements for an n-D ARRAY. The boundaries (lower and upper) for each dimension must be within the limits defined for the ARRAY type.
void *returnValue
a pointer to a buffer that FNC_GetArrayElements uses to return the values of the elements. The elements are returned in the desired range specified by arrayInterval in row-major order.
For each element returned, the returnValue buffer contains the following information:
The first 4 bytes describe the size of the data. This is only applicable for variable-length element data types.
The remaining bytes allocated for each element are allocated to hold the maximum size of the element data type. This space contains the actual element value.
Therefore, for each element, space is allocated as:
  • (MAX_SIZE_OF_ELEMENT_DATA_TYPE + 4 bytes) for variable-length element data types.
  • (MAX_SIZE_OF_ELEMENT_DATA_TYPE) for fixed-length data types.
long returnValueBufSize
the size in bytes that was allocated to the returnValue argument.
NullBitVecType *nullBitVec
a pointer to a NullBitVector array previously allocated by the caller. For the range of elements requested, the relevant bits of nullBitVec will be set to:
  • 1 if the element is present and non-null.
  • 0 if the element is present but set to NULL.
long nullBitVecBufSize
the size of the NullBitVector as allocated by the caller prior to initialization of the NullBitVector by setting all bytes to 0.
This parameter is required for protected mode execution of FNC_GetArrayElements.
long *length
the size in bytes of the value that FNC_GetArrayElements returns in returnValue.
For character data types, the length includes the size of any null termination characters.