1つ以上のUDTを返します。このハンドルを使用すると、エレメント タイプがUDTのARRAYデータ型の構成要素を操作できるようになります。
構文規則
void FNC_GetUDTHandles ( ARRAY_HANDLE aryHandle, int numHandles, void *returnValue, long bufSize )
構文要素
- aryHandle
- 外部ルーチンへの入力パラメータとして定義されたARRAY型へのハンドル。
- numHandles
- 取得するUDTハンドルの数。
- returnValue
- FNC_GetUDTHandlesでUDTハンドルを返すために使用するバッファへのポインタ。取得するUDTハンドルごとに、4バイトの割り当てが必要です。
- bufSize
- returnValueバッファに割り当てられたサイズ(バイト単位)。
使用上の注意
FNC_GetUDTHandlesは、入力引数としてaryHandle、numHandles、および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);
}