SQLGetSubString() - ストリング値の部分を取り出す
SQLGetSubString() は、LOB ロケーターによって参照されるラージ・オブジェクト値の部分を取り出します。
SQLGetSubString() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| なし | なし | なし |
構文
SQLRETURN SQLGetSubString (SQLHSTMT hstmt,
SQLSMALLINT LocatorCType,
SQLINTEGER SourceLocator,
SQLUINTEGER FromPosition,
SQLUINTEGER ForLength,
SQLSMALLINT TargetCType,
SQLPOINTER rgbValue,
SQLINTEGER cbValueMax,
SQLINTEGER FAR *StringLength,
SQLINTEGER FAR *IndicatorValue);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。 |
| SQLSMALLINT | LocatorCType | 入力 | 以下のいずれかの値を持つソース LOB ロケーターの C タイプを指定し
ます。
|
| SQLINTEGER | ロケーター | 入力 | ソース LOB ロケーター値を指定します。 |
| SQLUINTEGER | FromPosition | 入力 | 取り出すストリングが始まる位置を指定します。BLOB および CLOB の場合 、これは、関数が戻す最初のバイトの位置です。DBCLOB の場合、これは先頭文字です。開始バイト または開始文字には番号 1 が付けられます。 |
| SQLUINTEGER | ForLength | 入力 | SQLGetSubString() が取り出すストリングの長さを指定します。
BLOB および CLOB の
場合、これはバイト単位での長さです。DBCLOB の場合、これは文字単位での長さです。 引数 FromPosition の指定値が、ソース・ストリングの長さより 短くても、FromPosition + ForLength -1 がソース・ストリングの最後の位置を 超えている場合は、その結果は、右側に必要な文字数 (BLOB の場合は X'00'、CLOB の場合は 単一バイト・ブランク文字、および DBCLOB の場合は 2 バイト・ブランク文字) が埋め込まれます。 |
| SQLSMALLINT | TargetCType | 入力 | 引数 rgbValue が指すバッファーの中に取り出すことができる
ストリングのターゲット C データ・タイプを指定します。
このターゲットは、以下のいずれかのタイプの LOB ロケーター C バッファーが可能です。
|
| SQLPOINTER | rgbValue | 出力 | 取り出されたストリング値または LOB ロケーターが保管され るバッファーを指すポインター。 |
| SQLINTEGER | cbValueMax | 入力 | 引数 rgbValue が指しているバッファーの最大サイズ (バイト) を 指定します。 |
| SQLINTEGER * | StringLength | 出力 | ターゲット C バッファー・タイプが、ロケーター値ではなく、バイナリー
または文字ストリング変数を対象としている場合、この引数は、取り出されるサブストリング
の長さ (バイト1) を指します。
NULL ポインターが指定されている場合は、値は戻されません。 |
| SQLINTEGER * | IndicatorValue | 出力 | 常にゼロを戻します。 |
| 注:
|
|||
使用法
- 該当する C ストリング変数。
- サーバー上で作成される新しい LOB 値。 この値の LOB ロケーターは、クライアント上のターゲット・アプリケーション変数 に割り当てることができます。
SQLGetSubString() は、データを分割して取り出す際に、SQLGetData() の代わりとして 使用することができます。SQLGetSubString() を使用してデータを分割して取り出すには、 まず最初に列を LOB ロケーターにバインドします。次に、この LOB ロケーターを使用して、全体としてあるいは分割して LOB 値をフェッチします。
Locator 引数には、現行トランザクションでのフェッチまたは SQLGetSubString() 呼び出しによって戻された有効な LOB ロケーターを含むことができます。FREE LOCATOR ステートメントによって LOB ロケーターを解放しないでください。または、ロケーターが作成されたトランザクションとは別のトランザクションで SQLGetSubString() を行ってください。
ステートメント・ハンドルは、いずれの準備済みステートメント またはカタログ関数呼び出しにも関連付けてはなりません。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
40| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 戻されるデータの量が cbValueMax より長くなっています。 戻すのに使用可能な実際の長さ (バイト) は、StringLength に保管されています。 |
| 07006 | 変換が無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 0F001 | 現在 LOB トークン変数は何の値も表していません。 | Locator または SearchLocator に指定された 値は、現在は LOB ロケーターではありません。 |
| 22011 | サブストリング・エラーが発生しました。 | FromPosition がソース・ストリングの長さより大きくなっています。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY003 | プログラム・タイプが範囲外です。 | LocatorCType は、以下のいずれでもありません。
|
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY024 | 引数の値が無効です。 | FromPosition または ForLength に指定され た値は、正の整数ではありません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | cbValueMax の値が 0 より小さい値です。 |
| HYC00 | ドライバーは使用できません。 | アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。 |
制約事項
この関数は、ラージ・オブジェクトをサポートしない Db2 サーバーに 接続されている場合は利用できません。 関数タイプを SQL_API_SQLGETSUBSTRING に 設定して SQLGetFunctions() を呼び出し、fExists 出力引数をチェックして、 現在の接続でこの関数がサポートされるかどうかを判別してください。
例
関連例については、関数 SQLGetPosition() を参照してください。