仕様: | DB2 CLI 2.1 |
|
SQLGetSubString() は、現行トランザクション中にサーバーから戻された (フェッチまたは直前の SQLGetSubString() 呼び出しによって戻された) ラージ・オブジェクト・ロケーターによって参照される、ラージ・オブジェクト値の一部を取り出すのに使用されます。
構文
SQLRETURN SQLGetSubString ( SQLHSTMT StatementHandle, /* hstmt */ SQLSMALLINT LocatorCType, SQLINTEGER SourceLocator, SQLUINTEGER FromPosition, SQLUINTEGER ForLength, SQLSMALLINT TargetCType, SQLPOINTER DataPtr, /* rgbValue */ SQLINTEGER BufferLength, /* cbValueMax */ SQLINTEGER FAR *StringLength, SQLINTEGER FAR *IndicatorValue);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 | ||
---|---|---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。これはすでに割り振られているが、現時点で割り当てられたステートメントがまだ準備されていない任意のステートメント・ハンドルとすることができます。 | ||
SQLSMALLINT | LocatorCType | 入力 | C タイプのソース LOB ロケーター。これは、次のいずれかです。
| ||
SQLINTEGER | Locator | 入力 | Locator は、ソース LOB ロケーター値に設定しなければなりません。 | ||
SQLUINTEGER | FromPosition | 入力 | BLOB と CLOB の場合、これは関数で戻される最初のバイトの位置です。 DBCLOB の場合、これは最初の文字です。最初のバイトまたは文字は番号 1 が付けられます。 | ||
SQLUINTEGER | ForLength | 入力 | これは、関数から戻されるストリングの長さです。
BLOB と CLOB の場合、これはバイト単位の長さです。
DBCLOB の場合、これは文字単位の長さです。
FromPosition がソース・ストリングの長さより小さい値で、 FromPosition + ForLength - 1 がソース・ストリングの終わりを超えている場合、その結果は必要な文字数で右側を埋め込まれます (BLOB の場合は X'00'、 CLOB の場合は単一バイト・スペース、DBCLOB の場合は 2 バイト・スペース)。 | ||
SQLSMALLINT | TargetCType | 入力 | DataPtr の C データ・タイプ。ターゲットは常に、LOB ロケーター C バッファー・タイプ (SQL_C_CLOB_LOCATOR、SQL_C_BLOB_LOCATOR、 SQL_C_DBCLOB_LOCATOR) または C ストリング変数 (CLOB の場合は SQL_C_CHAR、 BLOB の場合は SQL_C_BINARY、 DBCLOB の場合は SQL_C_DBCHAR) のどちらかでなければなりません。 | ||
SQLPOINTER | DataPtr | 出力 | 取り出されるストリング値または LOB ロケーターを保管するバッファーを指すポインター。 | ||
SQLINTEGER | BufferLength | 入力 | DataPtr で指示されたバッファーの最大サイズ。 | ||
SQLINTEGER * | StringLength | 出力 | ターゲットの C バッファー・タイプが 2 進または文字ストリング変数であり、ロケーター値ではない場合に、
DataPtr に戻される情報の長さ (バイト単位)a。
ポインターを null に設定すると、何も返されません。 | ||
SQLINTEGER * | IndicatorValue | 出力 | 常にゼロに設定されます。 | ||
|
使用法
SQLGetSubString() は、 LOB ロケーターで表されるストリングの部分を取得するときに使用します。ターゲットに関する選択項目には、次の 2 つがあります。
SQLGetSubString() を、SQLGetData の代わりとして使用し、データを分割して入手することができます。この場合、まず列を LOB ロケーターにバインドし、次にそのロケーターを使用して LOB を全体でまたは分割して取り出します。
ロケーター引き数には、FREE LOCATOR ステートメントを用いて明示的に解放されてはいない、またはロケーターが作成されたトランザクションが終了したために暗黙的に解放されていない有効な LOB ロケーターを入れることができます。
このステートメント・ハンドルは、作成済みステートメントまたはカタログ関数呼び出しに関連付けられていてはなりません。
戻りコード
診断
表 121. SQLGetSubString SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01004 | データが切り捨てられました。 | 戻りデータが BufferLength より長くなっています。戻りに使用できる実際の長さは、StringLength に保管されます。 |
07006 | 変換が無効です。 | TargetCType に指定された値は、SQL_C_CHAR、
SQL_C_BINARY、
SQL_C_DBCHAR、または LOB ロケーターではありませんでした。
TargetCType に指定された値は、ソースにとって不適切です (たとえば、BLOB 列に SQL_C_DBCHAR など)。 |
22011 | サブストリング・エラーが起きました。 | FromPosition が、ソース・ストリングの長さより大きくなっています。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY003 | プログラム・タイプが範囲外です。 | LocatorCType は、SQL_C_CLOB_LOCATOR、 SQL_C_BLOB_LOCATOR、または SQL_C_DBCLOB_LOCATOR のいずれでもありません。 |
HY009 | 引き数値が無効です。 | FromPosition または ForLength に指定した値は、正の整数ではありませんでした。 |
HY010 | 関数の順序エラーです。 | 指定した StatementHandle は、割り振られて いません。
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | BufferLength の値は、0 より小さい値でした。 |
HYC00 | ドライバーが機能していません。 | アプリケーションは現在、ラージ・オブジェクトをサポートしないデータ・ソースに接続しています。 |
0F001 | 現在ロケーターは割り当てられていません。 | Locator に指定した値は現在、LOB ロケーターではありません。 |
制約
ラージ・オブジェクトをサポートしない DB2 サーバーに接続している場合は、この関数は使用できません。関数タイプを SQL_API_SQLGETSUBSTRING に設定して SQLGetFunctions() を呼び出し、 fExists 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */ /* ... */ /* read the piece of CLOB data in buffer */ sqlrc = SQLGetSubString( hstmtLocUse, SQL_C_CLOB_LOCATOR, clobLoc, clobPiecePos, clobLen - clobPiecePos, SQL_C_CHAR, buffer, clobLen - clobPiecePos + 1, &clobPieceLen, &ind ) ; STMT_HANDLE_CHECK( hstmtLocUse, sqlrc);
参照