17.00 - 17.05 - FNC_GetStructuredResultLobAttribute - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL外部ルーチン プログラミング

Product
Advanced SQL Engine
Teradata Database
Release Number
17.00
17.05
Published
2020年6月
Content Type
プログラミング リファレンス
Publication ID
B035-1147-170K-JPN
Language
日本語 (日本)

目的

UDFまたはUDMの戻り値であると定義されているか、または外部ストアド プロシージャに対するINOUTまたはOUTパラメータであると定義されている、STRUCTURED型のLOB属性のロケータを戻します。

最良のパフォーマンスを得るには、このルーチンではなく、FNC_GetStructuredResultLobAttributeByNdxを使用してください。このルーチンは使いやすさのためにサポートされています。

構文規則

void
FNC_GetStructuredResultLobAttribute ( UDT_HANDLE          udtHandle,
                                      char               *attributePath,
                                      LOB_RESULT_LOCATOR *object )
UDT_HANDLE udtHandle
UDFまたはUDMの戻り値であると定義されているか、または外部ストアド プロシージャに対するINOUTまたはOUTパラメータであると定義されている、STRUCTURED型UDTへのハンドル。
char *attributePath
LOB属性に至る絶対パス(ピリオドを区切りとする)。

例えば、PersonUDTというSTRUCTURED型UDTがあり、それにはPassportUDT型のpassportという属性があり、その属性にはphotoというLOB属性があるとします。photo属性のロケータを取得するための絶対パスは、「passport.photo」です。

LOB_RESULT_LOCATOR *object
LOB属性のLOBロケータを指すポインタ。

使用上の注意

FNC_GetStructuredResultLobAttributeを使用すると、LOB型を表わすDISTINCT型属性のLOBロケータを取得することができます。

STRUCTURED型の属性のLOBロケータを取得した後、FNC_LobOpenなどのLOBアクセス関数を使用して、データを付加します。

FNC_GetStructuredResultLobAttributeを使用して、JSON属性にデータを書き込むことができます。この関数はJSON属性のデータを保存できるLOBを表わすLOB_RESULT_LOCATORを返します。このLOB_RESULT_LOCATORをLOB FNCルーチンと共に使用して、JSON属性にデータを書き込むことができます。書き込まれるJSONデータが64000バイトよりも大きい場合、FNC_GetStructuredResultLobAttributeを使用する必要があります。JSONデータが64000バイト以下の場合、FNC_GetStructuredResultLobAttributeを使用してデータを書き込むことができますが、代わりにFNC_SetStructuredAttributeを使用すれば、パフォーマンスを向上させることができます。

デフォルトでは、外部ルーチンから戻されたSTRUCTURED型UDTの場合、そのすべての属性(STRUCTURED型UDTである属性を除く)は、NULLに設定されています。外部ルーチンが、STRUCTURED型のLOB属性に対して何もデータを付加しないと、その属性はNULLのままになります。

パラメータ スタイルSQLを使用する外部ルーチンの場合に、結果標識引数を-1に設定すると、LOB属性に付加されたデータはすべて破棄されます。結果標識引数を-1に設定しない場合、LOB属性にデータを付加した外部ルーチンにおいて、LOB属性を元のNULLにリセットすることはできません。

LOBに何もデータを付加しない場合、外部ストアド プロシージャへのINOUTパラメータであると定義されているSTRUCTURED型のLOB属性は、その入力バージョンがそのまま保たれます。

制限

CLIv2を使用してSQLを実行する外部ストアド プロシージャは、未処理のCLIv2リクエストが完了するまで、この関数を呼び出すことはできません。

FNC_GetStructuredResultLobAttributeの使用例

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_GetStructuredResultLobAttribute(*resultDocumentUdt, "doc", 
                                        &resultDocLoc);