FNC_GetStructuredInputLobAttributeByNdx Function | C Library Functions | Vantage - FNC_GetStructuredInputLobAttributeByNdx - Advanced SQL Engine - Teradata Database

SQL External Routine Programming
Product
Advanced SQL Engine
Teradata Database
Release Number
17.10
Published
July 2021
Language
English (United States)
Last Update
2021-07-27
dita:mapPath
rin1593638965306.ditamap
dita:ditavalPath
rin1593638965306.ditaval
dita:id
B035-1147
lifecycle
previous
Product Category
Teradata Vantage™

Returns the locator of a LOB attribute of a structured type that is defined to be an input parameter to an external routine.

Syntax

void
FNC_GetStructuredInputLobAttributeByNdx ( UDT_HANDLE   udtHandle,
                                          int           attributeIndex,
                                          int         *nullIndicator,
                                          LOB_LOCATOR *object )

Syntax Elements

udtHandle
the handle to a structured UDT that is defined to be one of the following:
  • An input parameter to an external routine
  • An attribute of a structured UDT that is defined as an input parameter to an external routine
attributeIndex
the index of a non-nested LOB attribute within the UDT.

The range of values is from 0 to i-1, where 0 is the index of the first attribute in the UDT and i is the number of top-most level attributes in the UDT.

For example, consider a structured UDT called passportUDT that has two attributes: the first attribute is an INTEGER attribute called ID and the second attribute is a LOB attribute called photo. To get the locator of the photo attribute, use an index of 1.

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

    This can also indicate that the udtHandle argument is null.

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

Usage Notes

  • You can use FNC_GetStructuredInputLobAttributeByNdx 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 get the locator of a nested LOB attribute in a structured UDT that is defined to be an input parameter to an external routine, follow these steps:
    1. Call FNC_GetStructuredAttributeByNdx to obtain the UDT handle of the next structured UDT attribute in the path to the target attribute.

      Repeat this step, passing in the newly obtained UDT handle as the udtHandle argument, n-2 times, where n is the nesting level of the target attribute.

    2. Call FNC_GetStructuredInputLobAttributeByNdx, passing in the UDT handle of the structured UDT attribute that contains the target LOB 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_GetStructuredInputLobAttributeByNdx

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 (first) attribute */
    FNC_GetStructuredInputLobAttributeByNdx(*documentUdt, 0,                                            &nullIndicator, &inDocLoc);    if (nullIndicator == -1) {
        /* the CLOB attribute is set to null if we don't append to it. */
        return;
    }
    ....
}