SQLGetData - 列からのデータの入手

目的

仕様:

DB2 CLI 1.1

ODBC 1.0

ISO CLI

SQLGetData() は、結果セットの現在行の単一列のデータを取り出します。これは、SQLFetch() 呼び出しごとにアプリケーション変数にデータを直接転送するために使用する SQLBindCol() の代替となるものです。

SQLGetData() の前に SQLFetch() を呼び出す必要があります。

必要な列ごとに SQLGetData() を呼び出した後、SQLFetch() を呼び出して次の行を取り出します。

構文

SQLRETURN   SQLGetData       (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLUSMALLINT      ColumnNumber,      /* icol */
                SQLSMALLINT       TargetType,        /* fCType */
                SQLPOINTER        TargetValuePtr,    /* rgbValue */
                SQLINTEGER        BufferLength,      /* cbValueMax */
                SQLINTEGER   *FAR StrLen_or_IndPtr); /* pcbValue */

関数の引き数

表 66. SQLGetData の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLUSMALLINT	`ColumnNumber`	入力	データ検索を要求する対象の列番号。結果セットの列は順番に番号が付いている。列番号は 1 から始まります。
SQLSMALLINT	`TargetType`	入力	`ColumnNumber` によって示される列の C データ・タイプ。以下のタイプがサポートされる。 SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TINYINT SQL_C_DEFAULT の指定により、データはそのデフォルトの C データ・タイプに変換される。
SQLPOINTER	`TargetValuePtr`	出力	取り出した列データの保管先のバッファーを指すポインター。出力バッファーは、ワードで (均等に) 位置合わせする必要がある。 Motorola 68000 などの多くのプロセッサーにワード位置合わせの規則があり、文字以外のデータ・タイプの場合、アプリケーションはバッファーを正しく位置合わせする必要がある。
SQLINTEGER	`BufferLength`	入力	`TargetValuePtr` が指すバッファーの最大サイズ。 TargetType がバイナリーまたは文字ストリングを示している場合は、BufferLength は 0 より大きくなければならない。そうでない場合は、エラーとなる。また、この引き数は無視される。
SQLINTEGER *	`StrLen_or_IndPtr`	出力	DB2 CLI がデータを戻す際に使用できる `TargetValuePtr` バッファーのバイト数を示す値を指すポインター。データの切り捨てが発生した場合、ここには、列全体を取り出すのに必要な合計バイト数が含まれます。バイナリー・データ・タイプと文字データ・タイプの場合、アプリケーションで部分検索モードを選択して、大きなデータを少しずつ検索できます。このモードでは、`StrLen_or_IndPtr` 引き数の内容として、列に残っているバイトの数が入っています。列のデータ値がヌルの場合、このポインターの値は SQL_NULL_DATA である。このポインターが NULL で、`SQLFetch()` がヌル・データを含む列を入手した場合、この関数はこれを報告する方法がないために失敗する。 `SQLFetch()` がバイナリー・データを含む列を取り出した場合、`StrLen_or_IndPtr` へのポインターは NULL であってはならない。さもないと、`TargetValuePtr` バッファーに取り出されたデータの長さについてアプリケーションに知らせる方法がないため、この関数は失敗する。

使用法

SQLFetch() を使用する場合、同じ結果セットに関する、SQLBindCol() と共に SQLGetData() を使用することができます。一般的なステップは次のとおりです。

SQLFetch() によって最初の行に進み、最初の行を取り出し、バインド列に関するデータを転送します。
SQLGetData() によって指定した列に関するデータを転送します。
SQLGetData() によって、必要な列に関してステップ 2 を繰り返します。
SQLFetch() によって次の行に進み、次の行を取り出し、バインド列に関するデータを転送します。
結果セットの行ごとにステップ 2、3 および 4 を、結果セットが必要なくなるまで繰り返します。

検索を介して列データの一部を廃棄したい場合、アプリケーションでは、ColumnNumber を次の必要な列位置に設定して、SQLGetData() を呼び出すことができます。行全体において、取り出されなかったデータを廃棄する場合、アプリケーションは SQLFetch() を呼び出して次の行へ進む必要があります。あるいは、結果セットからのデータがこれ以上必要ない場合には、SQLFreeStmt() を呼び出します。

TargetType 入力引き数は、TargetValuePtr によって指し示されたストレージ域に列データを入れる前に必要なデータ変換がある場合には、そのタイプを指定します。

TargetValuePtr に戻される値は、検索対象の列データがバイナリー・データでない限り、ヌルで終了します。

小数点の右側の数字を切り捨てた場合、数値データ・タイプの切り捨ては警告として報告されます。切り捨てが小数点の左側で発生した場合、エラーが戻されます。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

SQLGetData() によって長さゼロのストリングが取り出された場合には、SQL_SUCCESS が戻されます。このような場合、StrLen_or_IndPtr に 0 が入り、TargetValuePtr にヌル終止符が入ります。

先行する SQLFetch() の呼び出しが失敗した場合、結果が未定義であるため、SQLGetData() を呼び出してはいけません。

診断

表 67. SQLGetData の SQLSTATE

SQLSTATE	説明	解説
01004	データが切り捨てられた。	指定した列 (`ColumnNumber`) に関して戻されたデータが切り捨てられる。ストリング値または数値は右側が切り捨てられる。 SQL_SUCCESS_WITH_INFO が戻される。
07006	無効な変換。	データ値は、引き数 `TargetType` によって指定した C データ・タイプに変換できない。この関数は以前、同じ `ColumnNumber` 値に関して、異なる `TargetType` 値を使用して呼び出されている。
22002	無効な出力バッファーまたは標識バッファーの指定。	引き数 `StrLen_or_IndPtr` に指定したポインター値がヌル・ポインターで、列の値がヌルである。SQL_NULL_DATA を報告する方法がない。
22005	割り当てのエラー。	戻り値が、引き数 `TargetType` によって示されるデータ・タイプと互換性がない。
40003 08S01	通信リンク障害。	関数の完了前に、アプリケーションとデータ・ソース間の通信リンクに障害が生じた。
58004	予期しないシステム障害。	回復不能なシステム・エラー。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを割り当てることができない。
HY002	無効な列番号。	指定した列が 0 より小さいか、結果の列数より大きい。
HY003	プログラム・タイプが範囲外。	`TargetType` が有効なデータ・タイプまたは SQL_C_DEFAULT ではない。
HY010	関数のシーケンス・エラー。	最初に `SQLFetch()` を呼び出さないで、この関数を呼び出した。
HY013	予期しないメモリー処理エラー。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーにアクセスできない。
HY090	無効なストリング長またはバッファー長。	引き数 `BufferLength` の値が 0 より小さく、引き数 `TargetType` が SQL_C_CHAR または SQL_C_BINARY であるか、あるいは `TargetType` が SQL_C_DEFAULT で、デフォルトのタイプが SQL_C_CHAR、 SQL_C_BINARY、または SQL_C_DBCHAR のいずれかである。
HYC00	ドライバーが使用不可である。	指定したデータ・タイプとして SQL データ・タイプが認識されたが、DB2 CLI によってサポートされていない。 SQL データ・タイプからアプリケーション・データ `TargetType` への要求された変換は、DB2 CLI またはデータ・ソースによって実行できない。

制約事項

なし。

関連した解説