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_GetArrayTypeInfo_EON ( ARRAY_HANDLE       aryHandle,
                           array_info_eon_t  *arrayInfo,
                           bounds_t          *arrayScope)
ARRAY_HANDLE aryHandle
The handle to an ARRAY type that is defined to be an input parameter to an external routine.
array_info_eon_t *arrayInfo
A pointer to the buffer that will hold the information about the ARRAY input parameter.
The array_info_eon_t structure is defined in sqltypes_td.h as:
typedef struct array_info_eon_t {
   int numDimensions;
   int totalNumElements;
   element_info_eon_t elementInfo;
} array_info_eon_t;
where:
  • numDimensions = the number of dimensions defined for the ARRAY type.
  • totalNumElements = the total number of elements (across all dimensions) defined for the ARRAY type. This is also known as the maximum cardinality of the ARRAY type.
  • elementInfo = information about the elements of the ARRAY type. For details, see the description of the element_info_eon_t structure that follows.
The element_info_eon_t structure is defined in sqltypes_td.h as:
typedef struct element_info_eon_t {
   dtype_et data_type;
   SMALLINT udt_indicator;
   CHARACTER udt_type_name[FNC_MAXNAMELEN_EON];
   INTEGER_td max_length;
   SMALLINT total_interval_digits;
   SMALLINT num_fractional_digits;
   charset_et charset_code;
} element_info_eon_t;
where:
  • data_type = the data type of the elements of the ARRAY.
  • udt_indicator= whether the element is a UDT.
    The possible values of udt_indicator are as follows:
    • 0 = not a UDT
    • 1 = structured UDT
    • 2 = distinct UDT
    • 3 = Teradata proprietary internal UDT
  • udt_type_name = the UDT type name associated with the element if the element is a UDT.
  • max_length = the maximum length in bytes of an element value.

    You can use max_length as the size in bytes of the buffer you need to allocate before you make a call to FNC_GetArrayElement to get the values of one element of an ARRAY.

  • total_interval_digits = the precision value for certain element types. For example, the value n in a DECIMAL(n,m) type or in INTERVAL DAY(n) TO SECOND(m). The list of types that use this value is the same as that of attribute_info_t.total_interval_digits.
  • num_fractional_digits = the precision or scale value for certain element types. For example, the value m in a DECIMAL(n,m) type or in INTERVAL DAY(n) TO SECOND(m). The list of types that use this value is the same as that of attribute_info_t.num_fractional_digits.
  • charset_code = the server character set associated with the element if the element is a character type.
For more information about dtype_et, total_interval_digits, num_fractional_digits, or charset_et, see FNC_GetStructuredAttributeInfo_EON.
bounds_t *arrayScope
An array of bounds_t structures that describes the scope of each dimension in an n-D ARRAY. If the ARRAY type is 1-D, then the default scope information for that single dimension (beginning with 1, ending with n, where n is the size of the ARRAY) is provided in the first cell of the arrayScope array. If the ARRAY type is n-D, then subsequent dimension information is placed in cells 2 to 5 as needed, and provides the beginning and ending bound for each dimension.
The bounds_t structure is defined in sqltypes_td.h as:
typedef struct bounds_t {    int lowerBound;    int upperBound; } bounds_t;
where:
  • lowerBound = the lower bound of a dimension.
  • upperBound = the upper bound of a dimension.
The array has a size of FNC_ARRAYMAXDIMENSIONS, which is set to the value 5 to indicate that an ARRAY may have a maximum of 5 dimensions.
You should declare the arrayScope array as follows:
bounds_t arrayScope[FNC_ARRAYMAXDIMENSIONS];