17.00 - 17.05 - FNC_GetUDTHandles - 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
日本語 (日本)

目的

1つ以上のUDTを返します。このハンドルを使用すると、エレメント タイプがUDTのARRAYデータ型の構成要素を操作できるようになります。

構文規則

void
FNC_GetUDTHandles ( ARRAY_HANDLE  aryHandle,
                    int           numHandles,
                    void         *returnValue,
                    long          bufSize )
ARRAY_HANDLE aryHandle
外部ルーチンへの入力パラメータとして定義されたARRAY型へのハンドル。
int numHandles
取得するUDTハンドルの数。
void *returnValue
FNC_GetUDTHandlesでUDTハンドルを返すために使用するバッファへのポインタ。取得するUDTハンドルごとに、4バイトの割り当てが必要です。
long bufSize
returnValueバッファに割り当てられたサイズ(バイト単位)。

使用上の注意

FNC_GetUDTHandlesは、入力引数としてaryHandlenumHandles、およびbufSizeを受け取り、要求されたUDTハンドルをreturnValueバッファで返します。

aryHandleで指定したARRAYには、UDTのエレメント タイプを保持している必要があります。FNC_GetUDTHandlesを呼び出す前に、必要な数のUDTを保持できる十分な領域があるreturnValueバッファを割り当てておく必要があります。取得するUDTハンドルごとに、4バイトの割り当てが必要です。つまり、4 * numHandlesの割り当てが必要になるということです。データの処理後には、割り当てたリソースを確実に解放してください。

DISTINCT型UDTの値、またはSTRUCTURED型UDTの属性値にアクセスしたり、それらを設定する手順については、UDTインターフェースを参照してください。

FNC_GetUDTHandlesを呼び出して1つ以上のUDTハンドルを取得して、UDTのセットに対する操作を実行してから、それらのUDTを指定したFNC_SetArrayElementsまたはFNC_SetArrayElementsWithMultiValuesを呼び出すと、FNC_GetArrayElementsを呼び出す必要がなくなります。

制限

UDF、UDM、または外部ストアド プロシージャの実行中に、2000を超えるUDTのハンドルが割り当てられることはありません。そのため、FNC_GetUDTHandlesの呼び出しで2000を超えるUDTハンドルを取得することはできません。また、UDTハンドルを割り当てるそれ以外のFNCをルーチン内で呼び出す場合、この制限はさらに低くなります。

FNC_GetUDTHandlesの使用例

この例は、次のARRAY定義を基にしています。

/*Oracle-compatible and Teradata syntax respectively: */
CREATE TYPE phonenumbers_ary AS VARRAY(5) OF CHAR(10);
CREATE TYPE phonenumbers_ary AS CHAR(10) ARRAY[5];

/* This function sets the values of a set of consecutive elements */
/* which are UDTs by first obtaining a set of UDT handles, */
/* performing operations on them, and then calling */
/* FNC_SetArrayElementsWithMultiValues. */

void setMultiElement( ARRAY_HANDLE *ary,
                      INTEGER      *result,
                      char          sqlstate[6])
{
    int numHandles;
    void *newValues;
    long newValuesBufSize;
    bounds_t *arrayInterval;
    NullBitVecType *NullBitVector;
    long NullBitVectorBufSize;

    numHandles = 3;
    newValuesBufSize = sizeof(UDT_HANDLE)*numHandles;
    newValues = (void*)FNC_malloc(newValuesBufSize);
    FNC_GetUDTHandles(*ary, numHandles, newValues, newValuesBufSize);

    /* Perform some operations on the UDTs using existing FNC routines.*/

    ...

    /* Set the values of arrayInterval to correspond to the range [1:3]*/
    arrayInterval = (bounds_t*)FNC_malloc(sizeof(bounds_t));
    arrayInterval[0].lowerBound = 1;
    arrayInterval[0].upperBound = 3;

    /* Allocate space for NullBitVector and set all bits to Present. */
    numHandles % 8 == 0 ? NullBitVectorBufSize = numHandles / 8 :
       NullBitVectorBufSize = numHandles / 8 + 1;

    NullBitVector = (NullBitVecType*)FNC_malloc(NullBitVectorBufSize);
    FNC_SetNullBitVector(NullBitVector, -1, 1, NullBitVectorBufSize);

    /* Set the values of the UDTs operated on above. */
    FNC_SetArrayElementsWithMultiValues(ary, arrayInterval, newValues,
       newValuesBufSize, NullBitVector, NullBitVectorBufSize);

    FNC_free(NullBitVector);
    FNC_free(arrayInterval);
    FNC_free(newValues);
}