仕様: | 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);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 | ||
---|---|---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。これはすでに割り振られているが、現時点で割り当てられたステートメントがまだ準備されていない任意のステートメント・ハンドルとすることができます。 | ||
SQLSMALLINT | LocatorCType | 入力 | C タイプのソース LOB ロケーター。これは、次のいずれかです。
| ||
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 | 出力 | 常にゼロに設定されます。 | ||
|
使用法
SQLGetPosition() は、ストリングの任意の部分をランダムな方法で取得するために、 SQLGetSubString() と、一緒に使用します。 SQLGetSubString() を使用するには、ストリング全体の中のサブストリングの場所を事前に知っておく必要があります。サブストリングの先頭を探索ストリングで検出できる場合、 SQLGetPosition() を使用してそのサブストリングの開始位置を取得することができます。
Locator と SearchLocator (使用されている場合) 引き数には、 FREE LOCATOR ステートメントを使用して明示的に解放されていない、または LOB ロケーターが作成されたトランザクションが終了したために暗黙的に解放されていない有効な LOB ロケーターが入ります。
Locator と SearchLocator は、同じ 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 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。
(ここで完全サンプル 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 ) ;
参照