SQLGetData 関数

[アーティクル]
05/23/2023

準拠
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

まとめ
SQLGetData は、結果セット内の 1 つの列のデータ、または SQLParamData がSQL_PARAM_DATA_AVAILABLEを返した後の単一パラメーターのデータを取得します。これを複数回呼び出して、一部の可変長データを取得できます。

構文

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

引数

StatementHandle
[入力]ステートメントハンドル。

Col_or_Param_Num
[入力]列データを取得する場合は、データを返す列の番号です。結果セットの列には、1 から始まる列の順序が増えて番号が付けられます。ブックマーク列は列番号 0 です。これは、ブックマークが有効になっている場合にのみ指定できます。

パラメーターデータを取得する場合、これはパラメーターの序数であり、1 から始まります。

TargetType
[入力]*TargetValuePtr バッファーの C データ型の型識別子。有効な C データ型と型識別子の一覧については、「付録 D: データ型」の「C データ型」セクションを参照してください。

TargetType がSQL_ARD_TYPE場合、ドライバーは、ARD のSQL_DESC_CONCISE_TYPE フィールドで指定された型識別子を使用します。 TargetType がSQL_APD_TYPEの場合、SQLGetData は SQLBindParameter で指定されたのと同じ C データ型を使用します。それ以外の場合、SQLGetData で指定された C データ型は、SQLBindParameter で指定された C データ型をオーバーライドします。 SQL_C_DEFAULT場合、ドライバーは、ソースの SQL データ型に基づいて既定の C データ型を選択します。

拡張 C データ型を指定することもできます。詳細については、「ODBC の C データ型」を参照してください。

TargetValuePtr
[出力]データを返すバッファーへのポインター。

TargetValuePtr を NULL にすることはできません。

BufferLength
[入力]*TargetValuePtr バッファーの長さ (バイト単位)。

ドライバーは、文字やバイナリデータなどの可変長データを返すときに、*TargetValuePtr バッファーの末尾を超えて書き込みを回避するために BufferLength を使用します。 *TargetValuePtr に文字データを返すときに、ドライバーは null 終端文字をカウントすることに注意してください。 *したがって、TargetValuePtr には null 終端文字の領域が含まれている必要があります。または、ドライバーによってデータが切り捨てられます。

ドライバーが整数や日付構造などの固定長データを返す場合、ドライバーは BufferLength を無視し、バッファーがデータを保持するのに十分な大きさであると想定します。そのため、アプリケーションで固定長データに十分な大きさのバッファーを割り当てるか、ドライバーがバッファーの末尾を超えて書き込む必要があります。

BufferLength が 0 未満の場合、SQLGetData は SQLSTATE HY090 (文字列またはバッファーの長さが無効) を返しますが、BufferLength が 0 の場合は返しません。

StrLen_or_IndPtr
[出力]長さまたはインジケーター値を返すバッファーへのポインター。これが null ポインターの場合、長さまたはインジケーター値は返されません。これは、フェッチされるデータが NULL の場合にエラーを返します。

SQLGetData は、長さ/インジケーターバッファーで次の値を返すことができます。

返されるデータの長さ
SQL_NO_TOTAL
SQL_NULL_DATA

詳細については、このトピックの「長さ/インジケーター値の使用」および「コメント」を参照してください。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLGetData がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。次の表に、SQLGetData によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバーマネージャーによって返される SQLSTATEs の説明の前にあります。特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

SQLSTATE	エラー	説明
01000	一般的な警告	ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004	文字列データ、右切り捨て	指定した列 (Col_or_Param_Num) のすべてのデータを、関数の 1 回の呼び出しで取得できるわけではありません。 SQL_NO_TOTAL、または SQLGetData の現在の呼び出しの前に指定した列に残っているデータの長さが *StrLen_or_IndPtr で返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 1 つの列に対して SQLGetData を複数回呼び出す方法の詳細については、「コメント」を参照してください。
01S07	小数部の切り捨て	1 つ以上の列に対して返されたデータが切り捨てられました。数値データ型の場合、数値の小数部が切り捨てられました。時刻、タイムスタンプ、および時刻コンポーネントを含む間隔データ型の場合、時刻の小数部が切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07006	制限付きデータ型属性違反	結果セット内の列のデータ値を、引数 TargetType で指定された C データ型に変換することはできません。
07009	記述子インデックスが無効です	引数 Col_or_Param_Num に指定された値は 0 で、SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_OFF に設定されました。引数 Col_or_Param_Num に指定された値が、結果セット内の列数より大きかった。 Col_or_Param_Num値が、使用可能なパラメーターの序数と等しくなっていません。 (DM) 指定された列がバインドされました。この説明は、SQLGetInfo の SQL_GETDATA_EXTENSIONS オプションのSQL_GD_BOUND ビットマスクを返すドライバーには適用されません。 (DM) 指定された列の数が、最も大きいバインドされた列の数以下でした。この説明は、SQLGetInfo の SQL_GETDATA_EXTENSIONS オプションのSQL_GD_ANY_COLUMN ビットマスクを返すドライバーには適用されません。 (DM) アプリケーションは、現在の行に対して SQLGetData を既に呼び出しています。現在の呼び出しで指定された列の数が、前の呼び出しで指定された列の数より小さかったため、ドライバーは SQLGetInfo の SQL_GETDATA_EXTENSIONS オプションのSQL_GD_ANY_ORDERビットマスクを返しません。 (DM) TargetType 引数がSQL_ARD_TYPEされ、ARD の Col_or_Param_Num 記述子レコードが整合性チェックに失敗しました。 (DM) TargetType 引数がSQL_ARD_TYPEされ、ARD の SQL_DESC_COUNT フィールドの値が Col_or_Param_Num 引数より小さかった。
08S01	通信リンクエラー	ドライバーとドライバーが接続されたデータソース間の通信リンクは、関数の処理が完了する前に失敗しました。
22002	インジケーター変数は必須ですが、指定されていません	StrLen_or_IndPtrは null ポインターであり、NULL データが取得されました。
22003	範囲外の数値	列の数値 (数値または文字列) を返すと、数値の一部全体 (小数部ではなく) が切り捨てられました。詳細については、「付録 D: データ型」を参照してください。
22007	datetime 形式が無効です	結果セットの文字列は C の日付、時刻、またはタイムスタンプ構造にバインドされ、列の値はそれぞれ無効な日付、時刻、またはタイムスタンプでした。詳細については、「付録 D: データ型」を参照してください。
22012	0 で除算しました	0 で除算された算術式の値が返されました。
22015	間隔フィールドのオーバーフロー	正確な数値または間隔の SQL 型から間隔 C 型に割り当てると、先頭フィールドの有効桁数が失われます。間隔 C 型にデータを返すときに、間隔 C 型の SQL 型の値の表現がありませんでした。
22018	キャスト指定の文字値が無効です	結果セット内の文字列が文字 C バッファーに返され、その列にバッファーの文字セットに表現がない文字が含まれていました。 C 型は、正確または概数、datetime、または間隔データ型でした。列の SQL 型は文字データ型でした。列の値が、バインドされた C 型の有効なリテラルではありません。
24000	カーソル状態が無効	(DM) 関数は、最初に SQLFetch または SQLFetchScroll を呼び出さずに呼び出され、必要なデータ行にカーソルを置きます。 (DM) StatementHandle は実行された状態でしたが、結果セットは StatementHandle に関連付けされませんでした。 StatementHandle でカーソルが開き、SQLFetch* または SQLFetchScroll が呼び出されましたが、カーソルは結果セットの開始前または結果セットの末尾の後に配置*されました。
HY000	一般的なエラー	特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 MessageText バッファー内の SQLGetDiagRec によって返されるエラーメッセージは、エラーとその原因について説明します。
HY001	メモリ割り当てエラー	ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY003	プログラムの種類が範囲外	(DM) 引数 TargetType は、有効なデータ型、SQL_C_DEFAULT、SQL_ARD_TYPE (列データを取得する場合)、またはSQL_APD_TYPE (パラメーターデータを取得する場合) ではありません。 (DM) 引数 Col_or_Param_Num が 0 で、引数 TargetType が固定長ブックマークまたは可変長ブックマークのSQL_C_VARBOOKMARKにSQL_C_BOOKMARKされませんでした。
HY008	操作が取り消されました	StatementHandle に対して非同期処理が有効になりました。関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出され、その後、その関数が StatementHandle で再度呼び出されました。関数が呼び出され、実行が完了する前に、SQLCancel または SQLCancelHandle がマルチスレッドアプリケーションの別のスレッドから StatementHandle で呼び出された後、その関数が StatementHandle で再度呼び出されました。
HY009	null ポインターの使用が無効です	(DM) 引数 TargetValuePtr が null ポインターでした。
HY010	関数シーケンスエラー	(DM) 指定された StatementHandle が実行された状態にありません。この関数は、SQLExecDirect、SQLExecute、またはカタログ関数を最初に呼び出さずに呼び出されました。 (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。この非同期関数は、SQLGetData 関数が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではない) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。この関数は、すべての実行時データパラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) StatementHandle は実行された状態でしたが、結果セットは StatementHandle に関連付けされませんでした。 SQLParamData ではなく、SQLExeceute、SQLExecDirect、または SQLMoreResults への呼び出しがSQL_PARAM_DATA_AVAILABLE返されましたが、SQLGetData が呼び出されました。
HY013	メモリ管理エラー	メモリが不足している可能性があるため、基になるメモリオブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY090	文字列またはバッファーの長さが無効です	(DM) 引数 BufferLength に指定された値が 0 未満でした。引数 BufferLength に指定された値が 4 未満で、 Col_or_Param_Num 引数が 0 に設定され、ドライバーが ODBC 2.x ドライバーでした。
HY109	カーソル位置が無効です	削除された行またはフェッチできなかった行にカーソルが置かれた (SQLSetPos、SQLFetch、SQLFetchScroll、または SQLBulkOperations によって)。カーソルは順方向専用のカーソルで、行セットのサイズが 1 より大きかった。
HY117	不明なトランザクション状態のため、接続が中断されます。切断関数と読み取り専用関数のみが許可されます。	(DM) 中断状態の詳細については、「SQLEndTran 関数」を参照してください。
HYC00	省略可能な機能が実装されていません	ドライバーまたはデータソースは、SQLFetchScroll 内の複数の行での SQLGetData の使用をサポートしていません。この説明は、SQLGetInfo の SQL_GETDATA_EXTENSIONS オプションのSQL_GD_BLOCK ビットマスクを返すドライバーには適用されません。ドライバーまたはデータソースは、TargetType 引数と、対応する列の SQL データ型の組み合わせで指定された変換をサポートしていません。このエラーは、列の SQL データ型がドライバー固有の SQL データ型にマップされている場合にのみ適用されます。ドライバーは ODBC 2.x のみをサポートし、引数 TargetType は次のいずれかでした。 SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT 「付録 D: データ型」の「C データ型」に記載されている間隔 C データ型。ドライバーは、3.50 より前のバージョンの ODBC のみをサポートし、引数 TargetType がSQL_C_GUIDされました。
HYT01	接続のタイムアウト	データソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。
IM001	ドライバーは、この関数をサポートしていません	(DM) StatementHandle に対応するドライバーは、関数をサポートしていません。
IM017	非同期通知モードでポーリングが無効になっている	通知モデルが使用されるたびに、ポーリングは無効になります。
IM018	SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。	ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。

Comments

SQLGetData は、指定した列のデータを返します。 SQLGetData は、SQLFetch、SQLFetchScroll、または SQLExtendedFetch によって結果セットから 1 つ以上の行がフェッチされた後にのみ呼び出すことができます。可変長データが大きすぎて、(アプリケーションの制限により) SQLGetData の 1 回の呼び出しで返される場合、SQLGetData は一部で取得できます。行の一部の列をバインドし、SQLGetData を呼び出して他の列に対して呼び出すことは可能ですが、一部の制限が適用されます。詳細については、「長いデータの取得」を参照してください。

ストリーム出力パラメーターで SQLGetData を使用する方法については、「SQLGetData を使用した出力パラメーターの取得」を参照してください。

SQLGetData の使用

ドライバーが SQLGetData の拡張機能をサポートしていない場合、関数は、最後にバインドされた列の数より大きい値を持つ非バインド列のデータのみを返すことができます。さらに、データ行内では、SQLGetData への各呼び出しのCol_or_Param_Num引数の値が、前の呼び出しのCol_or_Param_Numの値以上である必要があります。つまり、データは列番号の順序を増やして取得する必要があります。最後に、拡張機能がサポートされていない場合、 行セットのサイズが 1 より大きい場合、SQLGetData を呼び出すことはできません。

ドライバーは、これらの制限のいずれかを緩和できます。ドライバーが緩和する制限を判断するために、アプリケーションは次のいずれかのSQL_GETDATA_EXTENSIONS オプションを使用して SQLGetInfo を呼び出します。

SQL_GD_OUTPUT_PARAMS = SQLGetData を呼び出して、出力パラメーター値を返すことができます。詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。
SQL_GD_ANY_COLUMN。このオプションが返された場合、 バインドされていない列 (最後にバインドされた列より前のものも含む) に対して SQLGetData を呼び出すことができます。
SQL_GD_ANY_ORDER。このオプションが返された場合、 バインドされていない列に対して SQLGetData を任意の順序で呼び出すことができます。
SQL_GD_BLOCK。 SQL_GETDATA_EXTENSIONS InfoType の SQLGetInfo によってこのオプションが返された場合、ドライバーは、行セットのサイズが 1 より大きい場合に SQLGetData の呼び出しをサポートし、アプリケーションは SQLGetData を呼び出す前に、SQL_POSITION オプションを使用して SQLSetPos を呼び出して、カーソルを正しい行に配置できます。
SQL_GD_BOUND。このオプションが返された場合、 バインドされた列とバインドされていない列に対して SQLGetData を呼び出すことができます。

これらの制限には 2 つの例外と、ドライバーがそれらを緩和する機能があります。まず、 行セットのサイズが 1 より大きい場合は、SQLGetData を前方専用カーソルに対して呼び出さないでください。 2 つ目は、ドライバーがブックマークをサポートしている場合、アプリケーションが最後にバインドされた列の前に他の列の SQLGetData を呼び出すことを許可しない場合でも、列 0 に対して SQLGetData を呼び出す機能を常にサポートする必要があります。 (アプリケーションが ODBC 2*.x* ドライバーを使用している場合、 SQLGetData は、SQLFetch の呼び出し後に 0 と等しいCol_or_Param_Numで呼び出されると、ブックマークを正常に返します。これは、SQLFetch が ODBC 3*.x* Driver Manager によって SQL_FETCH_NEXT の FetchOrientation を使用して SQLExtendedFetch にマップされ、Col_or_Param_Numが 0 の SQLGetData は ODBC 3*.x* Driver Manager から sqlGetStmtOption にマップされ、fOption がSQL_GET_BOOKMARK。

SQLGetData を使用して、SQL_ADD オプションを指定して SQLBulkOperations を呼び出すことによって挿入された行のブックマークを取得することはできません。カーソルは行に配置されていないためです。アプリケーションは、SQL_ADDで SQLBulkOperations を呼び出す前に列 0 をバインドすることで、このような行のブックマークを取得できます。その場合、SQLBulkOperations はバインドされたバッファー内のブックマークを返します。 その後、SQLFetchScroll を SQL_FETCH_BOOKMARK で呼び出して、その行のカーソルの位置を変更できます。

TargetType 引数が間隔データ型の場合、既定の間隔の先頭の有効桁数 (2) と既定の間隔の秒の有効桁数 (6) は、それぞれ ARD の SQL_DESC_DATETIME_INTERVAL_PRECISION フィールドと SQL_DESC_PRECISION フィールドで設定されているデータに使用されます。 TargetType 引数がSQL_C_NUMERICデータ型の場合は、ARD の SQL_DESC_PRECISION フィールドと SQL_DESC_SCALE フィールドに設定されている既定の有効桁数 (ドライバー定義) と既定の小数点以下桁数 (0) がデータに使用されます。既定の有効桁数または小数点以下桁数が適切でない場合、アプリケーションは SQLSetDescField または SQLSetDescRec の呼び出しによって適切な記述子フィールドを明示的に設定する必要があります。 SQL_DESC_CONCISE_TYPE フィールドをSQL_C_NUMERICに設定し、SQL_ARD_TYPEの TargetType 引数を使用して SQLGetData を呼び出すことができます。これにより、記述子フィールドの有効桁数と小数点以下桁数の値が使用されます。

Note

ODBC 2*.x* では、アプリケーションは TargetType を SQL_C_DATE、SQL_C_TIME、またはSQL_C_TIMESTAMPに設定して、*TargetValuePtr が日付、時刻、またはタイムスタンプ構造であることを示します。 ODBC 3*.x* では、アプリケーションは TargetType を SQL_C_TYPE_DATE、SQL_C_TYPE_TIME、またはSQL_C_TYPE_TIMESTAMPに設定します。ドライバーマネージャーは、アプリケーションとドライバーのバージョンに基づいて、必要に応じて適切なマッピングを行います。

パーツ内の可変長データの取得

SQLGetData を使用すると、可変長データを含む列からデータを取得できます。つまり、列の SQL データ型の識別子がSQL_CHAR、SQL_VARCHAR、SQL_LONGVARCHAR、SQL_WCHAR、SQL_WVARCHAR、SQL_WLONGVARCHAR、SQL_BINARY、SQL_VARBINARY、SQL_LONGVARBINARY、または可変長型のドライバー固有の識別子である場合です。

一部の列からデータを取得するために、アプリケーションは同じ列に対して連続して SQLGetData を複数回呼び出します。呼び出しのたびに、 SQLGetData はデータの次の部分を返します。文字データの中間部分から null 終端文字を削除するには、パーツを再アセンブルする必要があります。返すデータが多い場合、または終了文字に十分なバッファーが割り当てられなかった場合、 SQLGetData はSQL_SUCCESS_WITH_INFOおよび SQLSTATE 01004 (データの切り捨て) を返します。データの最後の部分を返すと、 SQLGetData はSQL_SUCCESSを返します。列からデータを取得する最後の有効な呼び出しでは、SQL_NO_TOTALも 0 も返されません。アプリケーションでは、アプリケーションバッファー内のデータの量を認識する方法がないためです。 この後に SQLGetData が呼び出されると、SQL_NO_DATAが返されます。詳細については、次のセクション「SQLGetData を使用したデータの取得」を参照してください。

可変長ブックマークは、SQLGetData によって部分で返すことができます。他のデータと同様に、部分内の可変長ブックマークを返す SQLGetData の呼び出しでは、SQLSTATE 01004 (文字列データ、右切り捨て) が返され、返されるデータが増えたときにSQL_SUCCESS_WITH_INFOされます。これは、sqlFetch または SQLFetchScroll の呼び出しによって可変長ブックマークが切り捨てられ、SQL_ERRORと SQLSTATE 22001 (文字列データ、右切り捨て) が返される場合とは異なります。

SQLGetData を使用して、一部の固定長データを返すことはできません。 固定長データを含む列に対して SQLGetData が 1 行に複数回呼び出されると、最初の呼び出しの後のすべての呼び出しに対してSQL_NO_DATAが返されます。

ストリーミング出力パラメーターの取得

ドライバーがストリーム出力パラメーターをサポートしている場合、アプリケーションは小さなバッファーで SQLGetData を何度も呼び出して、大きなパラメーター値を取得できます。ストリーム出力パラメーターの詳細については、「SQLGetData を使用した出力パラメーターの取得」を参照してください。

SQLGetData を使用したデータの取得

指定した列のデータを返すために、 SQLGetData は次の一連の手順を実行します。

列のすべてのデータが既に返されている場合は、SQL_NO_DATAを返します。
*StrLen_or_IndPtr を、データが NULL の場合にSQL_NULL_DATAに設定します。データが NULL で 、StrLen_or_IndPtr が null ポインターであった場合、 SQLGetData は SQLSTATE 22002 を返します (インジケーター変数は必須ですが、指定されていません)。

列のデータが NULL でない場合、 SQLGetData は手順 3 に進みます。
SQL_ATTR_MAX_LENGTH ステートメント属性が 0 以外の値に設定されている場合、列に文字またはバイナリデータが含まれている場合、および SQLGetData が列に対して以前に呼び出されていない場合、データは SQL_ATTR_MAX_LENGTH バイトに切り捨てられます。

Note

SQL_ATTR_MAX_LENGTH ステートメント属性は、ネットワークトラフィックを減らすことを目的としています。通常、データソースによって実装され、ネットワーク経由でデータが返される前にデータが切り捨てられます。ドライバーとデータソースをサポートする必要はありません。そのため、データが特定のサイズに切り捨てられることを保証するために、アプリケーションはそのサイズのバッファーを割り当て、BufferLength 引数にサイズを指定する必要があります。
データを TargetType で指定された型に 変換します。データには、そのデータ型の既定の有効桁数と小数点以下桁数が指定されます。 TargetType がSQL_ARD_TYPEの場合は、ARD の SQL_DESC_CONCISE_TYPE フィールドのデータ型が使用されます。 TargetType がSQL_ARD_TYPE場合、データには、SQL_DESC_CONCISE_TYPE フィールドのデータ型に応じて、ARD のSQL_DESC_DATETIME_INTERVAL_PRECISION、SQL_DESC_PRECISION、およびSQL_DESC_SCALEフィールドの有効桁数と小数点以下桁数が指定されます。既定の有効桁数または小数点以下桁数が適切でない場合、アプリケーションは SQLSetDescField または SQLSetDescRec の呼び出しによって適切な記述子フィールドを明示的に設定する必要があります。
データが文字やバイナリなどの可変長データ型に変換された場合、SQLGetData はデータの長さが BufferLength を超えているかどうかを確認します。文字データの長さ (null 終端文字を含む) が BufferLength を超える場合、SQLGetData はデータを BufferLength に切り捨て、null 終端文字の長さを減らします。その後、データは null で終了します。バイナリデータの長さがデータバッファーの長さを超えると、SQLGetData によって BufferLength バイトに切り捨てられます。

指定されたデータバッファーが null 終端文字を保持するには小さすぎる場合、 SQLGetData はSQL_SUCCESS_WITH_INFOおよび SQLSTATE 01004 を返します。

SQLGetData では、固定長データ型に変換されたデータが切り捨てられることはありません。*TargetValuePtr の長さがデータ型のサイズであると常に想定されます。
変換された (および切り捨てられた可能性がある) データを *TargetValuePtr に配置します。 SQLGetData は行外のデータを返すことができないことに注意してください。
データの長さを *StrLen_or_IndPtr に配置します。 StrLen_or_IndPtrが null ポインターであった場合、SQLGetData は長さを返しません。
- 文字データまたはバイナリデータの場合、これは、BufferLength による変換後および切り捨て前の データの長さです。長いデータの場合と同様に、ドライバーが変換後のデータの長さを判断できない場合は、SQL_SUCCESS_WITH_INFOを返し、長さをSQL_NO_TOTALに設定します。 (最後の呼び出し SQLGetData は常に、ゼロまたはSQL_NO_TOTALではなく、データの長さを返す必要があります。SQL_ATTR_MAX_LENGTHステートメント属性が原因でデータが切り捨てられた場合、実際の長さではなく、この属性の値は *StrLen_or_IndPtr に配置されます。これは、この属性は変換前にサーバー上のデータを切り捨てるように設計されているため、ドライバーは実際の長さを把握する方法がないためです。 SQLGetData が同じ列に対して連続して複数回呼び出されると、これは現在の呼び出しの開始時に使用できるデータの長さになります。つまり、後続の呼び出しのたびに長さが減少します。
- 他のすべてのデータ型の場合、これは変換後のデータの長さです。つまり、データが変換された型のサイズです。
変換中に有意性が失われずにデータが切り捨てられる場合 (たとえば、整数 1 に変換すると実数 1.234 が切り捨てられる)、または BufferLength が小さすぎる (たとえば、文字列 "abcdef" が 4 バイトバッファーに配置されている) 場合、SQLGetData は SQLSTATE 01004 (データの切り捨て) とSQL_SUCCESS_WITH_INFOを返します。 SQL_ATTR_MAX_LENGTH ステートメント属性が原因でデータが有意性を失わずに切り捨てられた場合、 SQLGetData はSQL_SUCCESSを返し、SQLSTATE 01004 (データの切り捨て) を返しません。

バインドされたデータバッファーの内容 (バインドされた列で SQLGetData が呼び出された場合) と、SQLGetData がSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返さない場合、長さ/インジケーターバッファーは未定義です。

SQLGetData を連続して呼び出すと、要求された最後の列からデータが取得されます。以前のオフセットは無効になります。たとえば、次のシーケンスを実行するとします。

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

SQLGetData(icol=n) の 2 回目の呼び出しでは、n 列の先頭からデータが取得されます。列に対する SQLGetData の以前の呼び出しによるデータ内のオフセットは無効になります。

記述子と SQLGetData

SQLGetData は、記述子フィールドと直接対話しません。

TargetType がSQL_ARD_TYPEの場合は、ARD の SQL_DESC_CONCISE_TYPE フィールドのデータ型が使用されます。 TargetType がSQL_ARD_TYPEまたはSQL_C_DEFAULTの場合、データには、SQL_DESC_CONCISE_TYPE フィールドのデータ型に応じて、ARD のSQL_DESC_DATETIME_INTERVAL_PRECISION、SQL_DESC_PRECISION、およびSQL_DESC_SCALEフィールドの有効桁数と小数点以下桁数が指定されます。

コード例

次の例では、アプリケーションが SELECT ステートメントを実行して、名前、ID、電話番号で並べ替えられた顧客 ID、名前、電話番号の結果セットを返します。データ行ごとに SQLFetch を呼び出して、カーソルを次の行に配置します。 SQLGetData を呼び出してフェッチされたデータを取得します。SQLGetData の呼び出しでは、データのバッファーと返されるバイト数が指定されます。最後に、各従業員の名前、ID、電話番号を出力します。

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

情報	参照トピック
結果セット内の列にストレージを割り当てる	SQLBindCol
ブロックカーソル位置に関連しない一括操作の実行	SQLBulkOperations
ステートメント処理の取り消し	SQLCancel
SQL ステートメントの実行	SQLExecDirect
準備された SQL ステートメントの実行	SQLExecute
データブロックのフェッチまたは結果セットのスクロール	SQLFetchScroll
1 行のデータまたはデータブロックを順方向にフェッチする	SQLFetch
実行時のパラメーターデータの送信	SQLPutData
カーソルの配置、行セット内のデータの更新、または行セット内のデータの更新または削除	SQLSetPos

参照

ODBC API リファレンス
 ODBC ヘッダーファイル
 SQLGetData を使用した出力パラメーターの取得

次の方法で共有

SQLGetData 関数

構文

引数

返品

診断

Comments

SQLGetData の使用

パーツ内の可変長データの取得

ストリーミング出力パラメーターの取得

SQLGetData を使用したデータの取得

記述子と SQLGetData

コード例

参照

フィードバック

その他のリソース

次の方法で共有

SQLGetData 関数

構文

引数

返品

診断

Comments

SQLGetData の使用

パーツ内の可変長データの取得

ストリーミング出力パラメーターの取得

SQLGetData を使用したデータの取得

記述子と SQLGetData

コード例

関連する関数

参照

フィードバック

その他のリソース