アプリケーション開発の手引き


UDF のパラメーターや結果としての LOB ロケーターの使用

AS LOCATOR は、任意の LOB データ・タイプや、 CREATE FUNCTION ステートメントの LOB タイプに基づいた任意の特殊タイプに追加できます。これは、渡されるパラメーターと戻される結果の両方に適用されます。この場合、DB2 は次のことを行います。

ロケーター値は修正しないでください。修正すると値は使用できなくなり、API がエラーを戻します。

これらの特殊 API は、NOT FENCED として定義された UDF でのみ使用できます。これは、バグのある UDF によってシステムが損害を受ける可能性があるので、テスト段階にある UDF を実動データベース上で使用してはならない、ということを暗に示しています。テスト・データベースでの作業であれば、 UDF にバグがあったとしても、永続する損害は生じません。 UDF にエラーがないことが分かったら、実動データベースに適用できます。

次の API は、sqludf.h UDF インクルード・ファイルに含まれている関数プロトタイプを使って定義されています。

 
    extern int sqludf_length(
        sqludf_locator*     udfloc_p,       /* in:  User-supplied LOB locator value */
        sqlint32*           Return_len_p    /* out: Return the length of the LOB value */
    ); 
    extern int sqludf_substr(
        sqludf_locator*     udfloc_p,       /* in:  User-supplied LOB locator value */
        sqlint32            start,          /* in:  Substring start value (starts at 1) */
        sqlint32            length,         /* in:  Get this many bytes */
        unsigned char*      buffer_p,       /* in:  Read into this buffer */
        sqlint32*           Return_len_p    /* out: Return the length of the LOB value */
    ); 
    extern int sqludf_append(
        sqludf_locator*     udfloc_p,       /* in:  User-supplied LOB locator value */
        unsigned char*      buffer_p,       /* in:  User's data buffer */
        sqlint32            length,         /* in:  Length of data to be appended */
        sqlint32*           Return_len_p    /* out: Return the length of the LOB value */
    ); 
    extern int sqludf_create_locator(
        int                 loc_type,       /* in:  BLOB, CLOB or DBCLOB? */
        sqludf_locator**    Loc_p           /* out: Return a ptr to a new locator */
    ); 
    extern int sqludf_free_locator(
        sqludf_locator*     loc_p           /* in: User-supplied LOB locator value */
    );

次に、これらの API がどのように動作するかを説明します。データ・タイプに関係なく、すべての長さはバイト数で、 1 バイト文字や 2 バイト文字単位ではないことに注意してください。

戻りコード。各 API ごとに DB2 によって UDF に戻される戻りコードは以下のとおりです。

0
成功しました。
-1
API に渡されたロケーターは、呼び出しを行う前に sqludf_free_locator() によって解放されました。
-2
FENCED モードの UDF で呼び出しが試行されました。
-3
API に無効な入力値が指定されました。各 API に固有の、無効な入力値の例については、以下のその説明を参照してください。
その他
無効なロケーターか、他のエラー (たとえばメモリー・エラー) です。これらの場合に戻される値は、エラー条件に対応する SQLCODE です。たとえば、-423 は無効なロケーターを意味します。これら「その他」のコードとともに UDF に戻る前に、 DB2 がエラーの重大度について判断することに注意してください。重大エラーの場合、DB2 はエラーが発生したことを記録し、 UDF が DB2 に戻された場合には、UDF がエラー SQLSTATE を DB2 に戻すかどうかにかかわらず、 DB2 はそのエラー条件に対して適切な処置を取ります。重大エラーではない場合、DB2 はエラーが発生したことを記録せず、正しい処置を取れるかどうかの判断を UDF に任せるか、またはエラー SQLSTATE を DB2 に戻します。

これらの API の使用には、以下の注意事項が適用されます。

注:

  1. LOB ロケーターを戻すよう定義されている UDF には、使用可能ないくつかの値があります。以下のものが戻されます。

  2. 表関数は、1 つ以上の LOB ロケーターを戻すものとして定義することができます。そのおのおのは、前の項目で説明された値のいずれかです。そのような表関数では、いくつかの表関数列の出力と同じロケーターを戻すことも有効です。

  3. 入力引き数として表関数に渡された LOB ロケーターは、行生成プロセスの期間全体で有効です。事実、1 行を生成している間に、そのような LOB ロケーターを使用して LOB に表関数を追加することができます。次の行上に追加されたバイトが現れます。

  4. UDF からの LOB ロケーター出力として DB2 で生成された LOB を表示するために内部制御機構を使用すると、1950 バイト使用します。この理由により、また分類への入力である行サイズに制限があるため、 UDF の LOB ロケーターとして生成された複数の LOB を分類しようとする照会は、関係する他の列のサイズに応じて、1 行につき (最大で) 2 つの値に制限されます。これと同じ制限は、表に挿入される行にも適用されます。

LOB ロケーター使用のシナリオ

ここでは、実際に起こりうる、LOB ロケーターの有用性を示すシナリオを簡単に要約します。次の 4 つのシナリオは、ロケーターの使用のあらましで、必要な空間を減らして効率を上げる方法を示します。


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]