SQLGetData 関数

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

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

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

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

Comments

SQLGetData は、指定した列のデータを返します。 SQLGetData は、 SQLFetch、 SQLFetchScroll、または SQLExtendedFetch によって結果セットから 1 つ以上の行がフェッチされた後にのみ呼び出すことができます。 可変長データが大きすぎて、(アプリケーションの制限のため) SQLGetData の 1 回の呼び出しで返すには、 SQLGetData を一部で取得できます。 一部の列を 1 行にバインドし、他の列に対して 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 の呼び出しをサポートし、アプリケーションはSQLSetPosを呼び出して、SQL_POSITION SQLGetData を呼び出す前に正しい行にカーソルを置くことができます。

• SQL_GD_BOUND。 このオプションが返された場合、バインドされた列とバインドされていない列 SQLGetData を呼び出すことができます。

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

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

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

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されます。 これは、SQL_ERRORと SQLSTATE 22001 (文字列データ、右切り捨て) を返す SQLFetch または SQLFetchScroll の呼び出しによって可変長ブックマークが切り捨てられる場合とは異なります。

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

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

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

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

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

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

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

   列のデータが 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 は常に、ゼロまたは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 を使用した出力パラメーターの取得