CLI の手引きおよび解説書

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

目的


仕様: 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);

関数引き数

表 120. SQLGetSubString 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。これはすでに割り振られているが、現時点で割り当てられたステートメントがまだ準備されていない任意のステートメント・ハンドルとすることができます。
SQLSMALLINT LocatorCType 入力 C タイプのソース LOB ロケーター。これは、次のいずれかです。
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
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 出力 常にゼロに設定されます。
注:

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

使用法

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 出力引き数を調べて、現行の接続でその関数がサポートされているかどうかを判別してください。

CLI サンプル dtlob.c

(ここで完全サンプル 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);
    
 

参照


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