FNC_GetStructuredInputLobAttribute Function | C Library Functions | Vantage - FNC_GetStructuredInputLobAttribute - Analytics Database - Teradata Vantage

SQL External Routine Programming
Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Analytics Database
Teradata Vantage
Release Number
17.20
Published
June 2022
Language
English (United States)
Last Update
2023-07-11
dita:mapPath
iiv1628111441820.ditamap
dita:ditavalPath
qkf1628213546010.ditaval
dita:id
B035-1147
lifecycle
latest
Product Category
Teradata Vantage™

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