Purpose
Returns the locator of a LOB attribute of a structured type that is defined to be the return value of a UDF or UDM or an INOUT or OUT parameter to an external stored procedure.
Syntax
void FNC_GetStructuredResultLobAttributeByNdx ( UDT_HANDLE udtHandle, int *attributeIndex, LOB_RESULT_LOCATOR *object )
- UDT_HANDLE udtHandle
- the handle to a structured UDT that is defined to be one of the following:
- The return value of a UDF or UDM or an INOUT or OUT parameter to an external stored procedure
- A nested attribute in the structured UDT return value of a UDF or UDM or an INOUT or OUT parameter to an external stored procedure
- int 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.
- LOB_RESULT_LOCATOR *object
- a pointer to the LOB locator for the LOB attribute.
Usage Notes
You can use FNC_GetStructuredResultLobAttributeByNdx to obtain the LOB locator for a distinct type attribute that represents a LOB type.
After you obtain the LOB locator for the attribute of the structured type, use the LOB access functions, such as FNC_LobOpen, to append data.
By default, a structured UDT that an external routine returns has all of its attributes (except attributes that are themselves structured UDTs) set to null. If an external routine does not append any data to a LOB attribute of a structured type, that attribute remains null.
Setting the result indicator argument to -1 for an external routine that uses parameter style SQL discards any data that was appended to a LOB attribute. An external routine that appends data to a LOB attribute cannot reset the LOB attribute back to null if the result indicator argument is not set to -1.
A LOB attribute of a structured type that is defined to be an INOUT parameter to an external stored procedure retains the input version if no data is appended to the LOB attribute.
Getting the Locator of a Nested LOB Attribute
To get the locator of a nested LOB attribute in a structured UDT that is defined to be the return value of a UDF or UDM, or OUT or INOUT parameter to an external stored procedure, follow these steps:
- 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.
- Call FNC_GetStructuredResultLobAttributeByNdx, passing in the UDT handle of the structured UDT attribute that contains the target LOB 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_GetStructuredResultLobAttributeByNdx
void document_t_lowerCase( UDT_HANDLE *documentUdt,
UDT_HANDLE *resultDocumentUdt,
char sqlstate[6])
{
LOB_RESULT_LOCATOR resultDocLoc;
/* Get a LOB_RESULT_LOCATOR for the result doc attribute. */
FNC_GetStructuredResultLobAttributeByNdx(*resultDocumentUdt, 0, &resultDocLoc);