16.20 - FNC_GetStructuredInputLobAttribute - 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)

Purpose

Returns the locator of a LOB attribute of a structured type that is defined to be an input parameter to a UDF, UDM, or external stored procedure.

For best performance, use FNC_GetStructuredInputLobAttributeByNdx instead of this routine. This routine is supported for its ease of use.

Syntax

void
FNC_GetStructuredInputLobAttribute ( UDT_HANDLE   udtHandle,
                                     char        *attributePath,
                                     int         *nullIndicator,
                                     LOB_LOCATOR *object )
UDT_HANDLE udtHandle
the handle to a structured UDT that is defined to be an input parameter to a UDF, UDM, or external stored procedure.
char *attributePath
the dot delimited full path to the LOB attribute.

For example, consider a structured UDT called PersonUDT that has an attribute called passport that is a PassportUDT type, which in turn has a LOB attribute called photo. To get the locator of the photo attribute, the full path is “passport.photo”.

int *nullIndicator
whether the attribute is null.
If the value of nullIndicator is...
  • -1, then the attribute is null.

    A value of -1 can also indicate that the full path to the specified attribute includes a preceding null attribute.

  • 0, then the attribute is not null.
LOB_LOCATOR *object
a pointer to the LOB locator for the LOB attribute.

Usage Notes

You can use FNC_GetStructuredInputLobAttribute to obtain the LOB locator for a distinct type attribute that represents a LOB type.

After you obtain the LOB locator for the LOB attribute, use the LOB access functions, such as FNC_LobOpen, to read the data.

To read the data of a JSON attribute which has its data stored in a LOB, do the following:

  1. Call FNC_GetStructuredAttributeInfo_EON.
  2. If the lob_length returned from the previous function call is 0, you must use FNC_GetStructuredAttribute instead of FNC_GetStructuredInputLobAttribute.
  3. If the lob_length is not 0, use FNC_GetStructuredInputLobAttribute to get a LOB_LOCATOR which represents the LOB where the data of a JSON attribute is stored. You can use this LOB_LOCATOR with the LOB FNC routines to read the data from the JSON attribute.

Restrictions

An external stored procedure that uses CLIv2 to execute SQL must wait for any outstanding CLIv2 requests to complete before calling this function.

Example Using FNC_GetStructuredInputLobAttribute

void document_t_lowerCase( UDT_HANDLE *documentUdt,
                           UDT_HANDLE *resultDocumentUdt,
                           char        sqlstate[6])
{
    LOB_LOCATOR inDocLoc;
    int nullIndicator;

    /* Get a LOB_LOCATOR for the input doc attribute */
    FNC_GetStructuredInputLobAttribute(*documentUdt, "doc",                                        &nullIndicator, &inDocLoc);    if (nullIndicator == -1) {
        /* the CLOB attribute is set to null if we don't append to it. */
        return;
    }
    ....
}