SQLGetData 関数

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

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: 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 バッファーの長さ (バイト単位)。

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

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

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

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 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of 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 で再度呼び出されました。関数が呼び出され、実行が完了する前に、マルチスレッドアプリケーションの別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出され、その関数が 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 に関連付けられなかった。 SQLExeceute、SQLExecDirect、または SQLMoreResults への呼び出しがSQL_PARAM_DATA_AVAILABLE返されましたが、SQLParamData ではなく 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	接続のタイムアウト	データソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001	ドライバーは、この関数をサポートしていません	(DM) StatementHandle に対応するドライバーは、関数をサポートしていません。
IM017	非同期通知モードでポーリングが無効になっている	通知モデルを使用するたびに、ポーリングは無効になります。
IM018	SQLCompleteAsync は、このハンドルに対する以前の非同期操作を完了するために呼び出されていません。	ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。

説明

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 によって sqlExtendedFetch にマップされ、SQL_FETCH_NEXTの FetchOrientation が指定された SQLGetData、Col_or_Param_Numが 0 の SQLGetData が ODBC 3*.x* ドライバーマネージャーによって SQLGetStmtOptionにマップされるためです。f SQL_GET_BOOKMARKのオプション。)

SQLGetData を使用して、SQL_ADD オプションを指定して SQLBulkOperations を呼び出すことによって挿入した行のブックマークを取得することはできません。カーソルは行に配置されていないためです。アプリケーションは、 sqlBulkOperations を呼び出す前に列 0 をバインドしてこのような行のブックマークを取得SQL_ADD。その場合、 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 に設定し、TargetType 引数が SQL_ARD_TYPE の 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に設定します。ドライバーマネージャーは、アプリケーションとドライバーのバージョンに基づいて、必要に応じて適切なマッピングを行います。

パーツ内のVariable-Length データの取得

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を返します。
データが NULL の場合、*StrLen_or_IndPtr を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 の最後の呼び出しでは、常に 0 または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 関数

構文

引数

戻り値

診断

説明

SQLGetData の使用

パーツ内のVariable-Length データの取得

ストリーム出力パラメーターの取得

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

記述子と SQLGetData

コード例

参照

フィードバック

フィードバック

その他のリソース

SQLGetData 関数

構文

引数

戻り値

診断

説明

SQLGetData の使用

パーツ内のVariable-Length データの取得

ストリーム出力パラメーターの取得

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

記述子と SQLGetData

コード例

関連する関数

参照

フィードバック

フィードバック

その他のリソース