FNC_GetStructuredInputLobAttribute Function | C Library Functions | Vantage - 17.10 - FNC_GetStructuredInputLobAttribute - 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)

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 )

Syntax Elements

udtHandle
the handle to a structured UDT that is defined to be an input parameter to a UDF, UDM, or external stored procedure.
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".

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.
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.
  • 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;
    }
    ....
}