仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLGetData() は、結果セットの現在行で 1 つの列のデータを取り出します。これは SQLBindCol() の代わりになるものであり、 SQLFetch() または SQLFetchScroll() 呼び出しでアプリケーション変数または LOB ロケーターへデータを直接転送するのに使用されます。 SQLGetData() を使用して、大きなデータ値を分割して取り出すこともできます。
SQLFetch() は、SQLGetData() の前に呼び出す必要があります。
列ごとに SQLGetData() を呼び出した後で、 SQLFetch() または SQLFetchScroll() を呼び出して次の行を取り出します。
構文
SQLRETURN SQLGetData ( SQLHSTMT StatementHandle, /* hstmt */ SQLUSMALLINT ColumnNumber, /* icol */ SQLSMALLINT TargetType, /* fCType */ SQLPOINTER TargetValuePtr, /* rgbValue */ SQLINTEGER BufferLength, /* cbValueMax */ SQLINTEGER *FAR StrLen_or_IndPtr); /* pcbValue */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 | ||
---|---|---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル | ||
SQLUSMALLINT | ColumnNumber | 入力 | データ取り出しが要求されている列番号。結果セット列は、順番通りに番号が付けられます。
| ||
SQLSMALLINT | TargetType | 入力 | ColumnNumber による列識別子の C データ・タイプ。以下のタイプがサポートされます。
SQL_C_DEFAULT を指定するとデータが省略時の C データ・タイプに変換されます。詳細については、表 2 を参照してください。 | ||
SQLPOINTER | TargetValuePtr | 出力 | 検索された列データを格納するバッファーを指すポインター。 | ||
SQLINTEGER | BufferLength | 入力 | TargetValuePtr で指示されたバッファーの最大サイズ。 | ||
SQLINTEGER * | StrLen_or_IndPtr | 出力 | DB2 CLI が使用できるバイト数を示す値を指すポインターが、
TargetValuePtr バッファー内に返されます。データが分割して検索されている場合、これにはまだ残っているバイト数が入ります。
列のデータ値がヌルの場合、値は SQL_NULL_DATA です。このポインターが NULL で、 SQLFetch() でヌル・データを含む列を取得した場合、この関数はこのことを報告する手段がないので失敗します。
SQLFetch() が 2 進データを含む列を取り出した場合、 StrLen_or_IndPtr を指すポインターがヌル (NULL) であってはなりません。 NULL の場合、この関数は TargetValuePtr バッファーに取り出されたデータの長さについてアプリケーションに通知する他の手段がないので失敗します。 | ||
|
使用法
SQLGetData() は同じ結果セットに対しては、 SQLFetch() が使用されており SQLFetchScroll() が使用されていない場合に限り、 SQLBindCol() とともに使用できます。一般的なステップは以下のとおりです。
C データ・タイプ (TargetType) が SQL_C_CHAR、SQL_C_BINARY、 SQL_C_DBCHAR であるか、または TargetType が SQL_C_DEFAULT で列タイプがバイナリーまたは文字ストリングである場合、 SQLGetData() を使用して長い列を取り出すこともできます。
SQLGetData() の呼び出しごとに、戻りに使用できるデータが BufferLength 以上の場合には、切り捨てが行われます。切り捨ては、関数戻りコード SQL_SUCCESS_WITH_INFO とデータ切り捨てを示す SQLSTATE で示されます。アプリケーションは、同じ ColumnNumber 値を指定して SQLGetData() を再度呼び出し、アンバインドされた同じ列から切り捨て時以降のデータを入手することができます。列全体を取得するために、関数が SQL_SUCCESS を返すまでアプリケーションがこのような呼び出しを繰り返します。次の SQLGetData() 呼び出しは、SQL_NO_DATA_FOUND を返します。
SQLGetData() は LOB 列データの順次検索に使用できますが、 LOB データのごく一部または LOB 列データの少数のセクションが必要な場合には、 DB2 CLI LOB 関数を使用してください。
切り捨ては、SQL_ATTR_MAX_LENGTH ステートメント属性にも影響されます。アプリケーションは、 SQL_ATTR_MAX_LENGTH および列ごとに返される最大長の値を指定して SQLSetStmtAttr() を呼び出し、同サイズ (にヌル終止符を加えたもの) の TargetValuePtr バッファーを割り振って、切り捨てが報告されないように指定することができます。列データが設定された最大長より大きい場合、SQL_SUCCESS が返され、実際の長さでなく最大長が StrLen_or_IndPtr に返されます。
取り出しによって列データの部分を廃棄するために、アプリケーションは ColumnNumber を次の対象列の位置に設定して SQLGetData() を呼び出すことができます。行全体で検索されなかったデータを廃棄するには、アプリケーションで SQLFetch() を呼び出してカーソルを次の行に進めるか、または結果セットからのデータがこれ以上必要ない場合は、 SQLFreeStmt() を呼び出してカーソルをクローズします。
TargetType 入力引き数は、 TargetValuePtr で指示された記憶域に列データを入れる前に、必要なデータ変換 (存在する場合) のタイプを判別します。
SQL 図形列データの場合、以下のようになります。
TargetValuePtr に返される内容は、検索する列データが 2 進ではないか、または列の SQL データ・タイプが図形 (DBCS) であり、かつ C バッファー・タイプが SQL_C_CHAR であれば、常にヌル終了です。アプリケーションが複数の部分に分けてデータを検索している場合は、適切な調整を行う必要があります (たとえば、ヌル終了環境属性が有効であると想定して、各部分を連結し直す前にヌル終了文字 5 を除去します)。
切り捨てが小数点の右側の桁数に関係している場合、数値データ・タイプの切り捨ては警告として報告されます。切り捨てが小数点の左側で行われると、エラーが返されます (診断のセクションを参照)。
スクロール可能カーソルは例外ですが、データを検索するのに SQLFetchScroll() を使用するアプリケーションが SQLGetData() を呼び出すべきなのは、行セット・サイズが 1 (SQLFetch() を発行するのと同じ) のときだけです。 SQLGetData() は、カーソルが現在置かれている行の列データだけを取り出せます。
スクロール可能カーソルでの SQLGetData() の使用
SQLGetData() はスクロール可能カーソルとともに使用することもできます。結果セットにある任意の行へのポインター (ブックマーク) を保管することができます。アプリケーションは、そのブックマークを相対位置として使用して、情報の行セットを検索します。
SQLSetPos() を使用して、行セット内の行へカーソルをいったん位置決めすれば、 SQLGetData() を使用して列 0 からブックマーク値を得ることができます。多くの場合、列 0 をバインドして行ごとのブックマーク値を検索する必要はありませんが、 SQLGetData() を使用すると必要な特定行のブックマーク値を検索することができます。
詳細については、スクロール可能カーソルを参照してください。
戻りコード
先行の SQLGetData() 呼び出しでこの列のすべてのデータが検索されると、 SQL_NO_DATA_FOUND が返されます。
SQLGetData() で長さゼロのストリングが取り出されると、SQL_SUCCESS が返されます。この場合、StrLen_or_IndPtr に 0 が入れられ、TargetValuePtr にヌル終止符が入れられます。
直前の SQLFetch() 呼び出しが失敗した場合、結果は定義されないので SQLGetData() を呼び出すことはできません。
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
01004 | データが切り捨てられました。 | 指定された列 (ColumnNumber) に返されたデータは切り捨てられました。ストリングまたは数値は右方切り捨てされます。 SQL_SUCCESS_WITH_INFO が返されます。 |
07006 | 変換が無効です。 | 引き数 TargetType で指定された C データ・タイプにデータ値を変換することはできません。
この関数は以前に同じ ColumnNumber 値に対して呼び出されましたが、 TargetType 値が異なっています。 |
22002 | 無効な出力または標識バッファーが指定されました。 | 引き数 StrLen_or_IndPtr に指定されたポインター値はヌル・ポインターでしたが、列の値はヌルです。 SQL_NULL_DATA を報告する手段はありません。 |
22003 | 数値が範囲外です。 | 列の数値を (数値またはストリングとして) 返したため、数値の整数部分が切り捨てられたと考えられます。 |
22005 | 割り当てにエラーがありました。 | 返された値は、引き数 TargetType で指示されたデータ・タイプと互換性がありませんでした。 |
22007 | 日時形式が無効です。 | 文字ストリングから日時形式への変換が指定されましたが、無効なストリング表示または値が指定されたか、あるいは値が無効な日付になっています。 |
22008 | 日時フィールドがオーバーフローしました。 | 日時フィールドのオーバーフローが発生しました。たとえば、日付またはタイム・スタンプに関する算術演算で有効な日付の範囲内にない結果になるか、あるいは、バインドされた変数が小さすぎて、その変数に日時値を割り当てることができません。 |
24000 | カーソル状態が無効です。 | 直前の SQLFetch() の結果が SQL_ERROR であったか、または SQL_NO_DATA が検出されました。その結果、カーソルは行に置かれていません。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY002 | 列の番号が無効です。 | 指定された列は、0 より小さいか、結果の列数より大きい値でした。
指定した列は 0 でしたが、アプリケーションはブックマークの使用を許可しませんでした (SQL_ATTR_USE_BOOKMARKS ステートメント属性を設定)。
SQLExtendedFetch() がこの結果セットに呼び出されました。 |
HY003 | プログラム・タイプが範囲外です。 | TargetType は、有効なデータ・タイプまたは SQL_C_DEFAULT ではありませんでした。 |
HY010 | 関数の順序エラーです。 | 指定された StatementHandle がカーソル定位置状態にありませんでした。最初に SQLFetch を呼び出さずに、この関数を呼び出しました。
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 BufferLength の値は 0 より小さく、引き数 TargetType は SQL_C_CHAR、SQL_C_BINARY、 SQL_C_DBCHAR (または SQL_C_DEFAULT で、省略時タイプ SQL_C_CHAR、 SQL_C_BINARY、または SQL_C_DBCHAR のいずれか) です。 |
HYC00 | ドライバーが機能していません。 | 指定されたデータ・タイプの SQL データ・タイプは認識されますが、DB2 CLI ではサポートされません。
SQL データ・タイプからアプリケーション・データ TargetType への要求された変換を、 DB2 CLI またはデータ・ソースで行うことはできません。
列は SQLBindFileToCol() を使用してバインドされました。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
バインドされた列を使用する方法と SQLGetData() を使用する方法の比較については、 CLI サンプル utilcli.c を参照してください。
(ここで完全サンプル tbread.c を使用することもできます 。)
/* From the CLI sample TBREAD.C */ /* ... */ sqlrc = SQLGetData( hstmt, 2, SQL_C_CHAR, location.val, 15, &location.ind ) ; STMT_HANDLE_CHECK( hstmt, sqlrc);
参照