17.00 - 17.05 - FNC_SetStructuredAttribute - 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、または外部ストアド プロシージャの戻り値であると定義されている、STRUCTURED型のLOB以外の属性を設定します。

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

構文規則

void
FNC_SetStructuredAttribute ( UDT_HANDLE  udtHandle,
                             char       *attributePath,
                             void       *newValue,
                             int         nullIndicator,
                             int         length )
UDT_HANDLE udtHandle
UDFまたはUDMの戻り値であると定義されているか、または外部ストアド プロシージャに対するINOUTまたはOUTパラメータであると定義されている、STRUCTURED型UDTへのハンドル。
char *attributePath
属性に至る絶対パス(ピリオドを区切りとする)。
例えば、PersonUDTというSTRUCTURED型UDTがあり、それにはAddressUDT型のaddressという属性があり、その属性にはzipcodeという属性があるとします。zipcode値を設定するための絶対パスは、「address.zipcode」です。
指定された属性への絶対パスのうち、先行する部分にNULL属性が含まれている場合、FNC_SetStructuredAttributeは、通常、指定された属性の値を設定することなく戻ります。
void *newValue
属性の新しい値が入っているバッファを指すポインタ。
指定した属性がSTRUCTURED型UDTである場合、nullIndicator引数を使ってその属性をNULLに設定することはできますが、newValue引数とlength引数はFNC_SetStructuredAttributeによって無視されます。
int * nullIndicator
属性をNULLに設定するかどうかを示す標識。
nullIndicatorの値
  • -1の場合、FNC_SetStructuredAttributeは属性をNULLに設定します。

    newValue引数は無視されます。

  • 0の場合、FNC_SetStructuredAttributeは属性をnewValueが指す値に設定します。
int length
newValueバッファのバイト単位のサイズ。
指定した属性がSTRUCTURED型UDTである場合、nullIndicator引数を使ってその属性をNULLに設定することはできますが、newValue引数とlength引数はFNC_SetStructuredAttributeによって無視されます。

使用上の注意

JSONデータが64000バイト以下の場合のみ、FNC_SetStructuredAttributeを使用して、JSONドキュメントの文字列表現をJSON属性に書き込むことができます。JSONデータが64000バイトよりも大きい場合、代わりにFNC_GetStructuredResultLobAttributeを使用する必要があります。

newValueが指すバッファを定義するには、属性の基礎となる型にマッピングされるCデータ型を使用します。例えば、DISTINCT型がSQL INTEGERデータ型を表わす場合、次のようにバッファを定義することができます。

INTEGER value;
value = 2048;

使用できるCデータ型の詳細は、Cデータ型を参照してください。

属性の基礎となる型が文字列で、その型で定義されているサイズよりもnewValue文字列のほうが短い場合には、その右側にFNC_SetStructuredAttributeによってスペースが埋め込まれます。

文字データ型はNULL文字の埋め込みに対応しているため、length引数に入れて渡す値にNULL終了文字の分は含めないでください。

length引数に入れて渡す値が必ずTeradata Databaseのデータ型の長さに一致するようにするには、sqltypes_td.hヘッダー ファイルに定義されているこれらのマクロを使用します。

マクロ 説明
SIZEOF_CHARACTER_LATIN(len)
SIZEOF_CHARACTER_KANJISJIS(len)
SIZEOF_CHARACTER_KANJI1(len)
SIZEOF_CHARACTER_UNICODE(len)
文字数lenのCHARACTERデータ型のバイト単位の長さを戻します。例えば、以下の式は6 (3 * 2 = 6)の長さを戻します。
SIZEOF_CHARACTER_UNICODE(3)
SIZEOF_VARCHAR_LATIN(len)
SIZEOF_VARCHAR_KANJISJIS(len)
SIZEOF_VARCHAR_KANJI1(len)
SIZEOF_VARCHAR_UNICODE(len)
文字数lenのVARCHARデータ型のバイト単位の長さを戻します。例えば、以下の式は6 (3 * 2 = 6)の長さを戻します。
SIZEOF_VARCHAR_UNICODE(3)
SIZEOF_BYTE(len)
SIZEOF_VARBYTE(len)
指定されたBYTEデータ型またはVARBYTEデータ型のバイト単位の長さを戻します(lenは値の数)。
SIZEOF_GRAPHIC(len)
SIZEOF_VARGRAPHIC(len)
指定されたCHARACTER(n) CHARACTER SET GRAPHICまたはVARCHAR(n) CHARACTER SET GRAPHICのデータ型長がバイト数単位で返されます。lenはここで値の数を指定します。
SIZEOF_BYTEINT
SIZEOF_SMALLINT
SIZEOF_INTEGER
SIZEOF_BIGINT
SIZEOF_REAL
SIZEOF_DOUBLE_PRECISION
SIZEOF_FLOAT
SIZEOF_DECIMAL1
SIZEOF_DECIMAL2
SIZEOF_DECIMAL4
SIZEOF_DECIMAL8
SIZEOF_DECIMAL16
SIZEOF_NUMERIC1
SIZEOF_NUMERIC2
SIZEOF_NUMERIC4
SIZEOF_NUMERIC8
SIZEOF_NUMERIC16
SIZEOF_NUMBER
指定された数値データ型のバイト単位の長さを戻します。

NUMBERの場合、返される長さは4 + 2 + 17 = 23バイトになります。これは、Teradata Databaseが小数部分に最大長(17バイト)を割り当てるためです。

SIZEOF_DATE
SIZEOF_ANSI_Time
SIZEOF_ANSI_Time_WZone
SIZEOF_TimeStamp
SIZEOF_TimeStamp_WZone
指定された日付/時刻型のバイト単位の長さを戻します。
SIZEOF_INTERVAL_YEAR
SIZEOF_IntrvlYtoM
SIZEOF_INTERVAL_MONTH
SIZEOF_INTERVAL_DAY
SIZEOF_IntrvlDtoH
SIZEOF_IntrvlDtoM
SIZEOF_IntrvlDtoS
SIZEOF_HOUR
SIZEOF_IntrvlHtoM
SIZEOF_IntrvlHtoS
SIZEOF_MINUTE
SIZEOF_IntrvlMtoS
SIZEOF_IntrvlSec
指定されたINTERVAL型のバイト単位の長さを戻します。

制限

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

FNC_SetStructuredAttributeの使用例

void setX( UDT_HANDLE *pointUdt,
           INTEGER    *val,
           UDT_HANDLE *resultPoint,
           char        sqlstate[6])
{
    INTEGER x;
    INTEGER newval;
    int nullIndicator;
    int length;

    /* Set the x attribute of the result point. */
    nullIndicator = 0;
    newval = *val;
    FNC_SetStructuredAttribute(*resultPoint, "x", &newval, 
                                nullIndicator, SIZEOF_INTEGER);    ...
}