SQLGetData 関数

準拠
導入されたバージョン: 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されます。

説明

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 を呼び出すことができます。これにより、記述子フィールドの有効桁数と小数点以下桁数の値が使用されます。

パーツ内の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 は次の一連の手順を実行します。

1. 列のすべてのデータが既に返されている場合は、SQL_NO_DATAを返します。

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

   列のデータが NULL でない場合、 SQLGetData は手順 3 に進みます。

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

   Note

   SQL_ATTR_MAX_LENGTH ステートメント属性は、ネットワーク トラフィックを減らすことを目的としています。 通常、データ ソースによって実装され、ネットワーク経由でデータを返す前にデータが切り捨てられます。 ドライバーとデータ ソースは、サポートするために必要ありません。 そのため、データが特定のサイズに切り捨てられることを保証するために、アプリケーションはそのサイズのバッファーを割り当て、 BufferLength 引数でサイズを指定する必要があります。

4. データを 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 の呼び出しによって適切な記述子フィールドを明示的に設定 する必要があります。

5. データが文字やバイナリなどの可変長データ型に変換された場合、 SQLGetData はデータの長さが BufferLength を超えているかどうかを確認します。 文字データの長さ (null 終端文字を含む) が BufferLength を超える場合、 SQLGetData はデータを BufferLength に切り捨て、null 終端文字の長さを減らします。 次に、データを null 終了します。 バイナリ データの長さがデータ バッファーの長さを超えると、 SQLGetData によって BufferLength バイトに切り捨てられます。

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

   SQLGetData では 、固定長データ型に変換されたデータが切り捨てられることはありません。常に、*TargetValuePtr の長さがデータ型のサイズであると想定しています。

6. 変換された (および切り捨てられた可能性がある) データを *TargetValuePtr に配置します。 SQLGetData は行外のデータを返すことができないことに注意してください。

7. データの長さを *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 が同じ列に対して連続して複数回呼び出される場合、これは現在の呼び出しの開始時に使用できるデータの長さです。つまり、後続の呼び出しのたびに長さが減少します。

   • 他のすべてのデータ型の場合、これは変換後のデータの長さです。つまり、データが変換された型のサイズです。

8. 変換中に有意性を失わずにデータが切り捨てられる場合 (たとえば、整数 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;  
      }  
   }  
}  

関連する関数

参照

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