CLI の手引きおよび解説書

SQLGetLength - ストリング値の長さを取り出す

目的


仕様 DB2 CLI 2.1    

SQLGetLength() は、現行トランザクション中に (フェッチまたは SQLGetSubString() 呼び出しの結果として) サーバーから戻されたラージ・オブジェクト・ロケーターによって参照される、ラージ・オブジェクト値の長さを検索します。

構文

SQLRETURN  SQLGetLength      (SQLHSTMT          StatementHandle,  /* hstmt */
                              SQLSMALLINT       LocatorCType,
                              SQLINTEGER        Locator,
                              SQLINTEGER   FAR  *StringLength,
                              SQLINTEGER   FAR  *IndicatorValue);

関数引き数


表 113. SQLGetLength 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。これはすでに割り振られているが、現時点で割り当てられたステートメントがまだ準備されていない任意のステートメント・ハンドルとすることができます。
SQLSMALLINT LocatorCType 入力 C タイプのソース LOB ロケーター。以下のいずれかになります。
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
SQLINTEGER Locator 入力 LOB ロケーター値に設定する必要があります。
SQLINTEGER * StringLength 出力 ターゲットの C バッファー・タイプが 2 進または文字ストリング変数であり、ロケーター値ではない場合に、 rgbValue に戻される情報の長さのバイト数a

ポインターを NULL に設定すると、 SQLSTATE HY009 が戻されます。

SQLINTEGER * IndicatorValue 出力 常にゼロに設定されます。
注:

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

使用法

SQLGetLength() は、 LOB ロケーターで表されるデータ値の長さを判別するときに使用します。これは、参照される LOB 値の一部またはすべてを取得するための適切な方法を選択できるように、 LOB の全長を判別するためにアプリケーションが使用します。

ロケーター引き数には、FREE LOCATOR ステートメントを用いて明示的に解放されてはいない、またはロケーターが作成されたトランザクションが終了したために暗黙的に解放されていない有効な LOB ロケーターを入れることができます。

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

戻りコード

診断


表 114. SQLGetLength SQLSTATE
SQLSTATE 説明 解説
07006 変換が無効です。 LocatorCTypeLocator の組み合わせは無効です。
40003 08S01 通信リンクに障害が起きました。
58004 予期しないシステム障害です。 回復不能システム・エラー。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY003 プログラム・タイプが範囲外です。 LocatorCType は、SQL_C_CLOB_LOCATOR、 SQL_C_BLOB_LOCATOR、または SQL_C_DBCLOB_LOCATOR のいずれかではありません。
HY009 引き数値が無効です。 StringLength を指すポインターが NULL でした。
HY010 関数の順序エラーです。 指定した StatementHandle は、割り振られて いません。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HYC00 ドライバーが機能していません。 アプリケーションは現在、ラージ・オブジェクトをサポートしないデータ・ソースに接続しています。
0F001 LOB トークン変数は、現在何も値を表していません。 Locator に指定した値は、LOB ロケーターに関連付けられていません。

制約

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

CLI サンプル dtlob.c

(ここで完全サンプル dtlob.c を使用することもできます 。)

/* From the CLI sample dtlob.c */
/* ... */
    /* get the length of the whole CLOB data */
    sqlrc = SQLGetLength( hstmtLocUse, SQL_C_CLOB_LOCATOR,
                          clobLoc, &clobLen, &ind ) ;
    STMT_HANDLE_CHECK( hstmtLocUse, sqlrc);
    
 

参照


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