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

SQLGetLength() はラージ・オブジェクト値の長さ (バイトで) 取り出します。ラージ・オブジェクト値は、 サーバーから返されるラージ・オブジェクト・ロケーターを使用して参照されます。ロケーターは、 現行トランザクション中にフェッチしたり、または SQLGetSubString() を呼び出したりすると得られます。

SQLGetLength() の ODBC 仕様

表 1. SQLGetLength() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし なし なし

構文

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

関数の引数

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

表 2. SQLGetLength() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。
SQLSMALLINT LocatorCType 入力 ソース LOB ロケーターの C タイプを指定します。これは以下のいずれかの値でなければなりません。
  • SQL_C_BLOB_LOCATOR - BLOB データの場合
  • SQL_C_CLOB_LOCATOR - CLOB データの場合
  • SQL_C_DBCLOB_LOCATOR - DBCLOB データの場合
SQLINTEGER ロケーター 入力 LOB ロケーター値を指定します。この引数は、LOB 値そのものではなく、LOB ロケーターの値を 指定します。
SQLINTEGER * StringLength 出力 引数 Locator が参照している LOB の長さ (バイト1) を受け取る バッファーを指しています。
SQLINTEGER * IndicatorValue 出力 この引数は、常にゼロを戻します。
注:
  1. これは、DBCLOB データの場合でもバイト単位です。

使用法

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

引数 Locator には、有効であればどの LOB ロケーターを入れても構いませんが、そのロケーターは、明示的に解放 (FREE LOCATOR ステートメントを使用して) されていないか、または LOB ロケーター作成時のトランザクションが終了したため暗黙的に解放されていないロケーターです。

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

戻りコード

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

診断

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

40
表 3. SQLGetLength() の SQLSTATE
SQLSTATE 説明 説明
07006 変換が無効です。 LocatorCType と引数 Locator が指定する値の組み合わせが無効です。
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
0F001 現在 LOB トークン変数は何の値も表していません。 引数 Locator が指定する値は、LOB ロケーターに関連付けられていません。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY003 プログラム・タイプが範囲外です。 引数 LocatorCType は、以下のいずれの値も指定していません。
  • SQL_C_CLOB_LOCATOR
  • SQL_C_BLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
HY009 NULL ポインターの使用は無効です。 引数 StringLength が NULL ポインターを指定しています。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HYC00 ドライバーは使用できません。 アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。

制約事項

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

例

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