SQLGetLength() - ストリング値の長さを取り出す
SQLGetLength() はラージ・オブジェクト値の長さ (バイトで) 取り出します。ラージ・オブジェクト値は、 サーバーから返されるラージ・オブジェクト・ロケーターを使用して参照されます。ロケーターは、 現行トランザクション中にフェッチしたり、または SQLGetSubString() を呼び出したりすると得られます。
SQLGetLength() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| なし | なし | なし |
構文
SQLRETURN SQLGetLength (SQLHSTMT hstmt,
SQLSMALLINT LocatorCType,
SQLINTEGER Locator,
SQLINTEGER FAR *StringLength,
SQLINTEGER FAR *IndicatorValue);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。 |
| SQLSMALLINT | LocatorCType | 入力 | ソース LOB ロケーターの C タイプを指定します。これは以下のいずれかの値でなければなりません。
|
| SQLINTEGER | ロケーター | 入力 | LOB ロケーター値を指定します。この引数は、LOB 値そのものではなく、LOB ロケーターの値を 指定します。 |
| SQLINTEGER * | StringLength | 出力 | 引数 Locator が参照している LOB の長さ (バイト1) を受け取る バッファーを指しています。 |
| SQLINTEGER * | IndicatorValue | 出力 | この引数は、常にゼロを戻します。 |
| 注:
|
|||
使用法
SQLGetLength() を使用すると、LOB ロケーターが表すデータ値の長さを判別することができます。 アプリケーションは、その値の一部または全部を取得するための 適切な方法を選択できるように、それを使用して、参照される LOB 値の全体の長さを判別します。
引数 Locator には、有効であればどの LOB ロケーターを入れても構いませんが、そのロケーターは、明示的に解放 (FREE LOCATOR ステートメントを使用して) されていないか、または LOB ロケーター作成時のトランザクションが終了したため暗黙的に解放されていないロケーターです。
ステートメント・ハンドルは、いずれの準備済みステートメント またはカタログ関数呼び出しにも関連付けてはなりません。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
40| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 07006 | 変換が無効です。 | LocatorCType と引数 Locator が指定する値の組み合わせが無効です。 |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 0F001 | 現在 LOB トークン変数は何の値も表していません。 | 引数 Locator が指定する値は、LOB ロケーターに関連付けられていません。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY003 | プログラム・タイプが範囲外です。 | 引数 LocatorCType は、以下のいずれの値も指定していません。
|
| HY009 | NULL ポインターの使用は無効です。 | 引数 StringLength が NULL ポインターを指定しています。 |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HYC00 | ドライバーは使用できません。 | アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。 |
制約事項
この関数は、ラージ・オブジェクトをサポートしていない Db2 サーバーに 接続されている場合は、使用できません。 SQL_API_SQLGETLENGTH を設定してある 引数 fFunction 指定の SQLGetFunctions() を呼び出し、出力引数 fExists をチェックして、この関数が現行の接続でサポートされているかどうかを判別します。
例
関連例については、関数 SQLGetPosition() を参照してください。