SQLGetSubString() - ストリング値の部分を取り出す

SQLGetSubString() は、LOB ロケーターによって参照されるラージ・オブジェクト値の部分を取り出します。

SQLGetSubString() の ODBC 仕様

表 1. SQLGetSubString() 仕様
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);

関数引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetSubString() 引数
データ・タイプ 引数 使用 説明
SQLHSTMT hstmt input ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。
SQLSMALLINT LocatorCType input 以下のいずれかの値を持つソース LOB ロケーターの C タイプを指定し ます。
  • SQL_C_BLOB_LOCATOR - BLOB データの場合
  • SQL_C_CLOB_LOCATOR - CLOB データの場合
  • SQL_C_DBCLOB_LOCATOR - DBCLOB データの場合
SQLINTEGER 位置特定装置 input ソース LOB ロケーター値を指定します。
SQLUINTEGER FromPosition input 取り出すストリングが始まる位置を指定します。 BLOB および CLOB の場合 、これは、関数が戻す最初のバイトの位置です。 DBCLOB の場合、これは最初の文字です。 開始バイト または開始文字には番号 1 が付けられます。
SQLUINTEGER ForLength input SQLGetSubString() が取り出すストリングの長さを指定します。 BLOB と CLOB の場合、これはバイト単位の長さです。 DBCLOB の場合、これは文字単位の長さです。

引数 FromPosition の指定値が、ソース・ストリングの長さより 短くても、FromPosition + ForLength -1 がソース・ストリングの最後の位置を 超えている場合は、その結果は、右側に必要な文字数 (BLOB の場合は X'00'、CLOB の場合は 単一バイト・ブランク文字、および DBCLOB の場合は 2 バイト・ブランク文字) が埋め込まれます。
SQLSMALLINT TargetCType input 引数 rgbValue が指すバッファーの中に取り出すことができる ストリングのターゲット C データ・タイプを指定します。 このターゲットは、以下のいずれかのタイプの LOB ロケーター C バッファーが可能です。
  • SQL_C_CLOB_LOCATOR
  • SQL_C_BLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
あるいは、このターゲットは以下のいずれかのタイプの C ストリング変数が可能です。
  • SQL_C_CHAR - CLOB データの場合
  • SQL_C_BINARY - BLOB データの場合
  • SQL_C_DBCHAR - DBCLOB データの場合
SQLPOINTER rgbValue 出力 取り出されたストリング値または LOB ロケーターが保管され るバッファーを指すポインター。
SQLINTEGER cbValueMax input 引数 rgbValue が指しているバッファーの最大サイズ (バイト) を 指定します。
SQLINTEGER * StringLength 出力 ターゲット C バッファー・タイプが、ロケーター値ではなく、バイナリー または文字ストリング変数を対象としている場合、この引数は、取り出されるサブストリング の長さ (バイト1) を指します。

NULL ポインターが指定されている場合は、値は戻されません。
SQLINTEGER * IndicatorValue 出力 常にゼロを戻します。
注:
  1. これは、DBCLOB データの場合であってもバイト単位です。

使用法

SQLGetSubString() を使用して、LOB ロケーターが表すストリングの任意の部分を取得します。 このサブストリングのターゲットは、以下のいずれかのオブジェクトが可能です。
  • 該当する C ストリング変数。
  • サーバー上で作成される新しい LOB 値。 この値の LOB ロケーターは、クライアント上のターゲット・アプリケーション変数 に割り当てることができます。

SQLGetSubString() は、データを分割して取り出す際に、SQLGetData() の代わりとして 使用することができます。 SQLGetSubString() を使用してデータを分割して取り出すには、 まず最初に列を LOB ロケーターにバインドします。 次に、この LOB ロケーターを使用して、全体としてあるいは分割して LOB 値をフェッチします。

Locator 引数には、現行トランザクションでのフェッチまたは SQLGetSubString() 呼び出しによって戻された有効な LOB ロケーターを含むことができます。 FREE LOCATOR ステートメントによって LOB ロケーターを解放しないでください。または、ロケーターが作成されたトランザクションとは別のトランザクションで SQLGetSubString() を行ってください。

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

戻りコード

SQLGetSubString() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

40
表 3. SQLGetSubString() SQLSTATE
SQLSTATE 説明 説明
01 0 04 データが切り捨てられました。 戻されるデータの量が cbValueMax より長くなっています。 戻すのに使用可能な実際の長さ (バイト) は、StringLength に保管されています。
07006 無効な変換です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • TargetCType に指定された値は、SQL_C_CHAR、SQL_C_BINARY、SQL_C_DBCHAR、また は LOB ロケーターのいずれでもありません。
  • TargetCType に指定された値は、 ソースにとって不適切です (例えば、BLOB 列に SQL_C_DBCHAR など)。
08S01 通信リンク障害が発生しました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
0F001 LOB トークン変数は、現在何も値を表していません。 Locator または SearchLocator で指定した値は現在、 LOB ロケーターではありません。
22011 サブストリング・エラーが発生しました。 FromPosition がソース・ストリングの長さより大きくなっています。
580 04 予想外のシステム障害が発生しました。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りが失敗しました。 DB2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY003 プログラム・タイプが範囲外です。 LocatorCType は、以下のいずれでもありません。
  • SQL_C_CLOB_LOCATOR
  • SQL_C_BLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
HY013 予期しない、メモリーのハンドル・エラーです。 DB2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスすることができません。
HY024 引数の値が無効です。 FromPosition または ForLength に指定され た値は、正の整数ではありません。
HY090 ストリングまたはバッファーの長さが無効です。 cbValueMax の値が 0 より小さい値です。
HYC0 0 ドライバーは使用できません。 アプリケーションは現在、 ラージ・オブジェクトをサポートしないデータ・ソースに接続しています。

制約事項

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

例

関連例については、関数 SQLGetPosition() を参照してください。