CLI の手引きおよび解説書

SQLGetPosition - ストリングの開始位置を戻す

目的


仕様: DB2 CLI 2.1    

SQLGetPosition() は、LOB 値 (ソース) 内の、あるストリングの開始位置を戻すときに使用します。ソース値は LOB ロケーターでなければならず、パターン値は LOB ロケーターまたはリテラル・ストリングとすることができます。

ソースおよび探索 LOB ロケーターは、現行トランザクション中にフェッチまたは SQLGetSubString() 呼び出しによってデータベースから戻された任意のものです。

構文

SQLRETURN   SQLGetPosition   (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLSMALLINT       LocatorCType,
                              SQLINTEGER        SourceLocator,
                              SQLINTEGER        SearchLocator,
                              SQLCHAR      FAR  *SearchLiteral,
                              SQLINTEGER        SearchLiteralLength,
                              SQLUINTEGER       FromPosition,
                              SQLUINTEGER  FAR  *LocatedAt,
                              SQLINTEGER   FAR  *IndicatorValue);

関数引き数


表 115. SQLGetPosition 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。これはすでに割り振られているが、現時点で割り当てられたステートメントがまだ準備されていない任意のステートメント・ハンドルとすることができます。
SQLSMALLINT LocatorCType 入力 C タイプのソース LOB ロケーター。これは、次のいずれかです。
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
SQLINTEGER Locator 入力 Locator は、ソース LOB ロケーター値に設定しなければなりません。
SQLINTEGER SearchLocator 入力 SearchLiteral ポインターが NULL であるか、 SearchLiteralLength を 0 に設定する場合、 SearchLocator は探索ストリングに関連付けられた LOB ロケーターに設定しなければなりません。そうしないと、この引き数は無視されます。
SQLCHAR * SearchLiteral 入力 この引き数は、探索ストリング・リテラルを含む記憶域を指します。

SearchLiteralLength が 0 であれば、このポインターは NULL でなければなりません。

SQLINTEGER SearchLiteralLength 入力 SearchLiteral 内のストリングの長さ (バイト単位)。a

この引き数値が 0 の場合は、引き数 SearchLocator は有効です。

SQLUINTEGER FromPosition 入力 BLOB や CLOB の場合、これはソース・ストリング内で探索が始まる最初のバイト位置で、この値が関数で戻されます。 DBCLOB の場合、これは最初の文字です。最初のバイトまたは文字には、番号 1 が付けられます。
SQLUINTEGER * LocatedAt 出力 BLOB と CLOB の場合、これはストリングが置かれたバイト位置で、ストリングが置かれていない場合には値ゼロが戻されます。 DBCLOB の場合、これは文字位置です。

ソース・ストリングの長さがゼロの場合は、値 1 が戻されます。

SQLINTEGER * IndicatorValue 出力 常にゼロに設定されます。
注:

a
これは、DBCLOB データの場合であってもバイト単位です。

使用法

SQLGetPosition() は、ストリングの任意の部分をランダムな方法で取得するために、 SQLGetSubString() と、一緒に使用します。 SQLGetSubString() を使用するには、ストリング全体の中のサブストリングの場所を事前に知っておく必要があります。サブストリングの先頭を探索ストリングで検出できる場合、 SQLGetPosition() を使用してそのサブストリングの開始位置を取得することができます。

LocatorSearchLocator (使用されている場合) 引き数には、 FREE LOCATOR ステートメントを使用して明示的に解放されていない、または LOB ロケーターが作成されたトランザクションが終了したために暗黙的に解放されていない有効な LOB ロケーターが入ります。

LocatorSearchLocator は、同じ LOB ロケーター・タイプでなければなりません。

このステートメント・ハンドルは、作成済みステートメントまたはカタログ関数呼び出しに関連付けられていてはなりません。

戻りコード

診断


表 116. SQLGetPosition SQLSTATE
SQLSTATE 説明 解説
07006 変換が無効です。 LocatorCType と LOB ロケーター値の組み合わせは無効です。
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
42818 演算子または関数のオペランドに互換性がありません。 パターンの長さが 4000 バイトを超えています。
58004 予期しないシステム障害です。 回復不能システム・エラー。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 引き数値が無効です。 LocatedAt 引き数を指すポインターが NULL でした。

FromPosition の引き数値は、0 より大きい値ではありませんでした。

LocatorCType は、SQL_C_CLOB_LOCATOR、 SQL_C_BLOB_LOCATOR、または SQL_C_DBCLOB_LOCATOR のいずれかではありません。

HY010 関数の順序エラーです。 指定した StatementHandle は、割り振られて いません。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY090 ストリングまたはバッファー長が無効です。 SearchLiteralLength の値が 1 より小さく、かつ SQL_NTS ではありませんでした。
HYC00 ドライバーが機能していません。 アプリケーションは現在、ラージ・オブジェクトをサポートしないデータ・ソースに接続しています。
0F001 LOB トークン変数は、現在何も値を表していません。 Locator または SearchLocator で指定した値は現在、 LOB ロケーターではありません。

制約

ラージ・オブジェクトをサポートしない DB2 サーバーに接続している場合は、この関数は使用できません。関数タイプを SQL_API_SQLGETPOSITION に設定して SQLGetFunctions() を呼び出し、 fExists 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。

CLI サンプル dtlob.c

(ここで完全サンプル dtlob.c を使用することもできます 。)

/* From the CLI sample dtlob.c */
/* ... */
    /* get the starting postion of the CLOB piece of data */
    sqlrc = SQLGetPosition( hstmtLocUse,
                            SQL_C_CLOB_LOCATOR,
                            clobLoc,
                            0,
                            ( SQLCHAR * ) "Interests",
                            strlen( "Interests"),
                            1,
                            &clobPiecePos,
                            &ind ) ;
    
 

参照


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