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_GetStructuredAttributeInfo ( UDT_HANDLE        udtHandle,
                                 int               attributePosition,
                                 int               bufSize,
                                 attribute_info_t *attributeArray )
UDT_HANDLE udtHandle
the handle to a structured UDT that is defined to be an input parameter to an external routine.
int attributePosition
whether this call returns information about one or all of the attributes.
If the value is...
  • 0 or greater, then the value identifies the position of the attribute in the structured UDT for which this call returns information. The position of the first attribute is 0.
  • -1, then this call returns information about all of the attributes.
int bufSize
the size in bytes that was allocated to the attributeArray argument.
attribute_info_t *attributeArray
an array of one or more attribute_info_t structures that describe the requested attribute or attributes in the structured UDT, as specified by attributePosition.
The attribute_info_t structure is defined in sqltypes_td.h as:
typedef struct attribute_info_t
{
   INTEGER          attrIndex;
   dtype_et         data_type;
   CHARACTER        attribute_name[256];
   SMALLINT         udt_indicator;
   CHARACTER        udt_type_name[256];
   INTEGER          max_length;
   FNC_LobLength_t  lob_length;
   SMALLINT         total_interval_digits;
   SMALLINT         num_fractional_digits;
   charset_et       charset_code;
} attribute_info_t;
where:
  • attrIndex specifies the position of the attribute in the structured type, where the position of the first attribute is 0.
  • data_type specifies the data type of the attribute. The sqltypes_td.h header file defines dtype_et as:
    typedef int dtype_et;

    Valid values are defined by the dtype_en enumeration in sqltypes_td.h. For a list of the valid values, see the dtype[] argument in FNC_CallSP.

  • attribute_name specifies the attribute name.

    For dynamic UDTs with attributes that are defined by column names and no , the attribute name is the column name.

  • udt_indicator specifies whether the attribute is a UDT and if so, which kind:
    • 0 meaning that it is not a UDT.
    • 1 meaning that it is a structured UDT.
    • 2 meaning that it is a distinct UDT.
    • 3 meaning that it is a Teradata proprietary internal UDT.
    • 5 meaning that it is a JSON attribute.
  • udt_type_name specifies the UDT type name associated with the attribute.

    This is meaningful only if the attribute is a UDT.

  • max_length specifies the maximum length in bytes of the value of the attribute.

    If the attribute is a non-LOB type, you can use max_length as the size in bytes of the buffer you need to allocate before you make a call to FNC_GetStructuredAttribute to get the value of the structured attribute.

    If the attribute is a LOB, max_length indicates the LOB_REF length. The lob_length member provides the length of the LOB data itself.

    For a JSON attribute, max_length indicates the maximum possible length of the JSON attribute.

  • lob_length specifies the length of a LOB attribute.

    This is meaningful only if the attribute is a LOB.

    For a JSON attribute, lob_length specifies the maximum possible length of the JSON attribute in bytes if the data is stored as a LOB; otherwise, this value is 0.

    You can use lob_length as the length of the LOB object that you pass to FNC_LobOpen when you establish a read context for the LOB attribute.

  • total_interval_digits specifies the precision of certain attributes. The value of total_interval_digits corresponds to the n value of the following types:
    • DECIMAL(n, m)
    • INTERVAL YEAR(n)
    • INTERVAL YEAR(n) TO MONTH
    • INTERVAL MONTH(n)
    • INTERVAL DAY(n)
    • INTERVAL DAY(n) TO HOUR
    • INTERVAL DAY(n) TO MINUTE
    • INTERVAL DAY(n) TO SECOND(m)
    • INTERVAL HOUR(n)
    • INTERVAL HOUR(n) TO MINUTE
    • INTERVAL HOUR(n) TO SECOND(m)
    • INTERVAL MINUTE(n)
    • INTERVAL MINUTE(n) TO SECOND(m)
    • INTERVAL SECOND(n, m)

    If the data type of the attribute does not appear in the preceding list, total_interval_digits is not meaningful for the attribute.

  • num_fractional_digits specifies the precision or scale of certain attributes. The value of num_fractional_digits corresponds to the m value of the following types:
    • DECIMAL(n, m)
    • TIME(m)
    • TIME(m) WITH TIME ZONE
    • TIMESTAMP(m)
    • TIMESTAMP(m) WITH TIME ZONE
    • INTERVAL DAY(n) TO SECOND(m)
    • INTERVAL HOUR(n) TO SECOND(m)
    • INTERVAL MINUTE(n) TO SECOND(m)
    • INTERVAL SECOND(n, m)

    If the data type of the attribute does not appear in the preceding list, num_fractional_digits is not meaningful for the attribute.

  • charset_code specifies the server character set associated with the attribute.

    This is meaningful only if the attribute is a character type.

    The sqltypes_td.h header file defines charset_et as:
    typedef int charset_et;
    Valid values are defined by the charset_en enumeration in sqltypes_td.h:
    typedef enum charset_en
    {
       UNDEF_CT=0,
       LATIN_CT=1,
       UNICODE_CT=2,
       KANJISJIS_CT=3,
       KANJI1_CT=4
    } charset_en; 

    For a JSON attribute, charset_code is LATIN_CT or UNICODE_CT depending on how the JSON attribute was defined.