SQLGetData() - 列からデータを取得する
SQLGetData() は、結果セットの現在行の 1 つの列のデータを取り出します。また、SQLGetData() は、大きなデータ値を分割して取り出す場合にも使用できます。それぞれの列ごとに SQLGetData() を呼び出した後、SQLFetch() または SQLExtendedFetch() を 取り出す必要のある各行ごとに呼び出します。
SQLGetData() の前に SQLFetch() を呼び出す必要があります。 この関数を使用すると、SQLFetch() または SQLExtendedFetch() 呼び出しの 代わりに SQLBindCol() を使用して、アプリケーション変数または LOB ロケーターへデータを直接に転送します。
SQLGetData() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
31 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLGetData (SQLHSTMT hstmt,
SQLUSMALLINT icol,
SQLSMALLINT fCType,
SQLPOINTER rgbValue,
SQLINTEGER cbValueMax,
SQLINTEGER FAR *pcbValue);
64 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLGetData (SQLHSTMT hstmt,
SQLUSMALLINT icol,
SQLSMALLINT fCType,
SQLPOINTER rgbValue,
SQLLEN cbValueMax,
SQLLEN FAR *pcbValue);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | 結果セットが生成されるステートメント・ハンドル指定します。 |
| SQLUSMALLINT | icol | 入力 | データの取り出しが必要な結果セットの列番号を指定します。 |
| SQLSMALLINT | fCType | 入力 | icol が示す列の C データ・タイプを指定します。
引数 fCType には、以下のタイプを指定することができます。
|
| SQLPOINTER | rgbValue1 | 出力 | 取り出された列データを保管するバッファーを指します。 |
| SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 2 | cbValueMax | 入力 | 引数 rgbValue が指している バッファーの最大サイズを指定します。 |
| SQLINTEGER * (31 ビット) または SQLLEN * (64 ビット)2 | pcbValue1 | 出力 | 取り出そうとするデータの収容に必要なスペース量を
示す値を指しています。
データを分割して取り出す場合は、この値には、まだ残っているバイト数が入ります。
列のデータ値が NULL の場合、値は SQL_NULL_DATA です。 このポインターが NULL であり、SQLFetch() で NULL データを含む列を取得した場合、この関数は、データが NULL であることを報告する手段がないため、失敗します。
SQLFetch() がバイナリー・データを含んでいる列をフェッチする場合、引数 pcbValue が指定するポインターは NULL であってはなりません。NULL の場合に SQLGetData() は失敗する理由は、引数 rgbValue で指定したバッファーに戻す データ長に関して、アプリケーションに伝えらないからです。 |
| 注:
|
|||
使用法
- SQLFetch() を呼び出します。これは、カーソルを最初の行に進め、最初の行を取り出し、バインドされた列のデータを転送します。
- SQLGetData() を呼び出します。この関数により、指定された列のデータを転送します。
- 必要な各列ごとに、ステップ 2 を繰り返します。
- SQLFetch() を呼び出します。これは、カーソルを次の行に進め、次の行を取り出し、 バインドされた列のデータを転送します。
- 結果セットの各行ごとに、ステップ 2、3、および 4 を繰り返します。 あるいは、結果セットが必要なくなるまで、これを繰り返します。
また、C データ・タイプ (引数 fCType を用いて指定) が SQL_C_CHAR、SQL_C_BINARY、SQL_C_DBCHAR で あるか、あるいは fCType が SQL_C_DEFAULT 場合で、かつ、列タイプがバイナリーまたは 文字ストリングを示している場合、SQLGetData() を使用して長い列を取り出すこともできます。
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、EBCDIC データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = EBCDIC が初期設定ファイルで指定されているか、CURRENTAPPENSCH キーワードに指定された CCSID が EBCDIC CCSID であるか、あるいは、CURRENTAPPENSCH キーワードが初期設定ファイルで指定されていない。
- 引数 fCType が、SQLGetData() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
- ODBC ドライバーは、引数 fCType が、SQLGetData() 呼び出しで SQL_C_WCHAR を指定している場合は、ユニコード UCS-2 データをアプリケーション変数に入れます。
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ユニコード UTF-8 データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = UNICODE が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH キーワードに指定された CCSID がユニコード CCSID (1200、1208、13488 または 17584) である。
- 引数 fCType が、SQLGetData() 呼び出しで SQL_C_CHAR を指定している。
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ASCII データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = ASCII が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH キーワードに指定された CCSID が ASCII CCSID である。
- 引数 fCType が、SQLGetData() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
データ切り捨ての処理: 各 SQLGetData() 呼び出し後、戻しに使用可能なデータが cbValueMax 以上の場合は、 データは切り捨てられます。切り捨てが発生したことは、データ切り捨てを示す SQLSTATE とともに、関数戻りコード SQL_SUCCESS_WITH_INFO で 示されます。同じ列で SQLGetData() を再び呼び出して、切り捨てられたデータを引き続き 取り出すことができます。列全体を取得するには、SQLGetData() が SQL_SUCCESS を戻すまで、この呼び出しを繰り返します。SQL_SUCCESS が戻された後、SQLGetData() を呼び出すと、SQL_NO_DATA_FOUND が戻されます。
Db2 ODBC が数値データ・タイプで小数点の右側の桁を切り捨てた場合は、Db2 ODBC は警告を出します。 ただし、Db2 ODBC が小数点の左側の桁を切り捨てた場合には、Db2 ODBC はエラーを戻します。 (詳しくは 診断を参照してください。)
データ切り捨て時の警告を出力しないようにするには、SQL_ATTR_MAX_LENGTH 属性を最大長の値 に設定して SQLSetStmtAttr() を呼び出します。次に、SQL_ATTR_MAX_LENGTH で指定した値と同サイズ (NUL 終止符をプラス) である引数 rgbValue で バッファーを割り振ります。SQL_ATTR_MAX_LENGTH で指定した最大バイト数よりも列データの方が大きい場合 は、SQL_SUCCESS が戻されます。最大長を指定すると、Db2 ODBC は、実際の長さではなく、 指定した長さを引数 pcbValue に対して戻します。
アクティブな取り出しからデータを廃棄: 現在アクティブである取り出しからデータを廃棄するには、データを取り出す位置の次の列に 引数 icol を設定して、SQLGetData() を呼び出します。まだ取り出していないデータを廃棄するには、SQLFetch() を呼び出して、カーソルを 次の行に進めます。結果セットからのデータの取り出しが終了した場合 には、SQLFreeStmt() または SQLCloseCursor() を呼び出します。
バッファーの割り振り: fCType 入力引数により、rgbValue が指すバッファーに 列データを入れる前に発生するデータ変換のタイプ (その変換が発生する場合) が決まります。
- 引数 rgbValue が指定するバッファーのサイズは、2 バイトの倍数でなければなりません。(cbValueMax 値も、2 バイトの倍数としてこの値を指定する必要が あります。) SQLGetData() を呼び出す前に、SQLDescribeCol() または SQLColAttribute() を呼び出して、 結果セットのデータの SQL データ・タイプと長さ (バイト) を判別する必要があります。
- 引数 pcbValue は、NULL ポインターを指定してはなりま せん。Db2 ODBC は、引数 rgbValue が指しているバッファーに格納されている オクテットの数を保管します。
- データを分割して取り出す場合、Db2 ODBC は、引数 cbValueMax が指定する値以下で最も近い 2 オクテットの倍数に rgbValue を埋めようとします。cbValueMax が 2 の 倍数でない場合は、そのバッファーの最後のバイトは処理されません。Db2 ODBC が 2 バイト文字を分割することは ありません。
引数 rgbValue が指すバッファーには NUL 終了値が入りますが、例外として、 バイナリー・データを取り出す場合、またはその列の SQL データ・タイプが グラフィック (DBCS) および C バッファー・タイプが SQL_C_CHAR の場合を除きます。 データを分割して取り出す場合は、これらの分割された部分の再組み立て時に、 NUL 終止符を正しく調整する必要があります。(つまり、データの分割部分を連結する前に、NUL 終止符を 取り外す必要があります。)
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
SQLGetData() がゼロの長さのストリングを取り出した場合は、SQL_SUCCESS が戻されます。ゼロの長さのストリングの場合、pcbValue に 0 が入り、rgbValue には NUL 終止符が入ります。
直前の SQLGetData() 呼び出しでこの列のすべてのデータが 取り出されると、SQL_NO_DATA_FOUND が戻されます。
直前の SQLFetch() への呼び出しが失敗した場合は、SQLGetData() は呼び出さないでください。呼び出すと、SQLGetData() は不確定なデータを取り出します。
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 引数 icol で指定した列に対応して戻されたデータが切り捨てられました。 ストリングまたは数値は、右方切り捨てされます。(SQLGetData() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 07006 | 変換が無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 22002 | 無効な出力または標識バッファーが指定されました。 | 引数 pcbValue で指定されているポインターは NULL ポインターであり、 列の値も NULL です。この関数は、SQL_NULL_DATA を報告できません。 |
| 22008 | 日時形式が無効または日時フィールドがオーバーフローしました。 | 日時フィールドでオーバーフローが起こりました。 例: 日付またはタイム・スタンプの算術計算の結果が日付の有効範囲外であるか、あるいは、バインド済みの変数が小さすぎるため日時値を割り当てることができません。 |
| 22018 | 割り当てにエラーがありました。 | 戻された値は、引数 fCType で指示されたデータ・タイプと 互換性がありません。 |
| 24000 | カーソル状態が無効です。 | 直前の SQLFetch() の結果が SQL_ERROR であったか、 または SQL_NO_DATA が検出されました。その結果、カーソルが行に位置付けられていません。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY002 | 列番号が無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY003 | プログラム・タイプが範囲外です。 | 引数 fCType は、無効なデータ・タイプまたは SQL_C_DEFAULT を 指定しています。 |
| HY009 | NULL ポインターの使用は無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY010 | 関数シーケンス・エラーが発生しました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY019 | 数値が範囲外です。 | 列の数値が (数字またはストリングとして) 戻されたときに、 数値の整数部分は切り捨てられました。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 cbValueMax の値は 0 より小であり、引数 fCType は以下のいずれかの値を指定しています。
|
| HYC00 | ドライバーは使用できません。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
制約事項
ODBC は列 0 をブックマークとして定義しています。 Db2 ODBC はブックマークをサポートしていません。
例
/******************************************************************/
/* Populate BIOGRAPHY table from flat file text. Insert */
/* VITAE in 80-byte pieces via SQLPutData. Also retrieve */
/* NAME, UNIT and VITAE for all members. VITAE is retrieved*/
/* via SQLGetData. */
/******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
#define TEXT_SIZE 80
int insert_bio (SQLHSTMT hStmt, // insert_bio prototype
char *bio,
int bcount);
int main( )
{
SQLHENV hEnv = SQL_NULL_HENV;
SQLHDBC hDbc = SQL_NULL_HDBC;
SQLHSTMT hStmt = SQL_NULL_HSTMT, hStmt2 = SQL_NULL_HSTMT;
SQLRETURN rc = SQL_SUCCESS;
FILE *fp;
SQLINTEGER RETCODE = 0;
char pTable [200];
char *pDSN = "STLEC1";
UDWORD pirow;
SDWORD cbValue;
char *i_stmt = "INSERT INTO BIOGRAPHY VALUES (?, ?, ?)";
char *query = "SELECT NAME, UNIT, VITAE FROM BIOGRAPHY";
char text [TEXT_SIZE]; // file text
char vitae [3200]; // biography text
char Narrative [TEXT_SIZE];
SQLINTEGER vitae_ind = SQL_DATA_AT_EXEC; // bio data is
// passed at execute time
// via SQLPutData
SQLINTEGER vitae_cbValue = TEXT_SIZE;
char *t = NULL;
char *c = NULL;
char name [21];
SQLINTEGER name_ind = SQL_NTS;
SQLINTEGER name_cbValue = sizeof(name);
char unit [31];
SQLINTEGER unit_ind = SQL_NTS;
SQLINTEGER unit_cbValue = sizeof(unit);
char tmp [80];
char *token = NULL, *pbio = vitae;
char insert = SQL_FALSE;
int i, bcount = 0;
(void) printf ("**** Entering CLIP09.¥n¥n");
/*****************************************************************/
/* Allocate environment handle */
/*****************************************************************/
RETCODE = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, hEnv, &hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Allocate connection handle to DSN */
/*****************************************************************/
RETCODE = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
if( RETCODE != SQL_SUCCESS ) // Could not get a Connect Handle
goto dberror;
/*****************************************************************/
/* CONNECT TO data source (STLEC1) */
/*****************************************************************/
RETCODE = SQLConnect(hDbc, // Connect handle
(SQLCHAR *) pDSN, // DSN
SQL_NTS, // DSN is nul-terminated
NULL, // Null UID
0 ,
NULL, // Null Auth string
0);
if( RETCODE != SQL_SUCCESS ) // Connect failed
goto dberror;
/*****************************************************************/
/* Allocate statement handles */
/*****************************************************************/
rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Allocate statement handle failed.¥n");
goto dberror;
}
rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt2);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Allocate statement handle failed.¥n");
goto dberror;
}
/*****************************************************************/
/* Prepare INSERT statement. */
/*****************************************************************/
rc = SQLPrepare (hStmt,
(SQLCHAR *) i_stmt,
SQL_NTS);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Prepare of INSERT failed.¥n");
goto dberror;
}
/*****************************************************************/
/* Bind NAME and UNIT. Bind VITAE so that data can be passed */
/* via SQLPutData. */
/*****************************************************************/
rc = SQLBindParameter (hStmt, // bind NAME
1,
SQL_PARAM_INPUT,
SQL_C_CHAR,
SQL_CHAR,
sizeof(name),
0,
name,
sizeof(name),
&name_ind);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Bind of NAME failed.¥n");
goto dberror;
}
rc = SQLBindParameter (hStmt, // bind Branch
2,
SQL_PARAM_INPUT,
SQL_C_CHAR,
SQL_CHAR,
sizeof(unit),
0,
unit,
sizeof(unit),
&unit_ind);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Bind of UNIT failed.¥n");
goto dberror;
}
rc = SQLBindParameter (hStmt, // bind Rank
3,
SQL_PARAM_INPUT,
SQL_C_CHAR,
SQL_LONGVARCHAR,
3200,
0,
(SQLPOINTER) 3,
0,
&vitae_ind);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** Bind of VITAE failed.¥n");
goto dberror;
}
/*****************************************************************/
/* Read biographical text from flat file */
/*****************************************************************/
if ((fp = fopen ("DD:BIOGRAF", "r")) == NULL) // open command file
{
rc = SQL_ERROR; // open failed
goto exit;
}
/*****************************************************************/
/* Process file and insert biographical text */
/*****************************************************************/
while (((t = fgets (text, sizeof(text), fp)) != NULL) &&;
(rc == SQL_SUCCESS))
{
if (text[0] == #') // if commander data
{
if (insert) // if BIO data to be inserted
{
rc = insert_bio (hStmt,
vitae,
bcount); // insert row into BIOGRAPHY Table
bcount = 0; // reset text line count
pbio = vitae; // reset text pointer
}
token = strtok (text+1, ","); // get member NAME
(void) strcpy (name, token);
token = strtok (NULL, "#"); // extract UNIT
(void) strcpy (unit, token); // copy to local variable
// SQLPutData
insert = SQL_TRUE; // have row to insert
}
else
{
memset (pbio, ' ', sizeof(text));
strcpy (pbio, text); // populate text
i = strlen (pbio); // remove '¥n' and '¥0'
pbio [i--] =' ';
pbio [i] =' ';
pbio += sizeof (text); // advance pbio
bcount++; // one more text line
}
}
if (insert) // if BIO data to be inserted
{
rc = insert_bio (hStmt,
vitae,
bcount); // insert row into BIOGRAPHY Table
}
fclose (fp); // close text flat file
/*****************************************************************/
/* Commit insert of rows */
/*****************************************************************/
rc =SQLEndTran(SQL_HANDLE_DBC, hDbc, SQL_COMMIT);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** COMMIT FAILED.¥n");
goto dberror;
}
/*****************************************************************/
/* Open query to retrieve NAME, UNIT and VITAE. Bind NAME and */
/* UNIT but leave VITAE unbound. Retrieved using SQLGetData. */
/*****************************************************************/
RETCODE = SQLPrepare (hStmt2,
(SQLCHAR *)query,
strlen(query));
if (RETCODE != SQL_SUCCESS)
{
(void) printf ("**** Prepare of Query Failed.¥n");
goto dberror;
}
RETCODE = SQLExecute (hStmt2);
if (RETCODE != SQL_SUCCESS)
{
(void) printf ("**** Query Failed.¥n");
goto dberror;
}
RETCODE = SQLBindCol (hStmt2, // bind NAME
1,
SQL_C_DEFAULT,
name,
sizeof(name),
&name_cbValue);
if (RETCODE != SQL_SUCCESS)
{
(void) printf ("**** Bind of NAME Failed.¥n");
goto dberror;
}
RETCODE = SQLBindCol (hStmt2, // bind UNIT
2,
SQL_C_DEFAULT,
unit,
sizeof(unit),
&unit_cbValue);
if (RETCODE != SQL_SUCCESS)
{
(void) printf ("**** Bind of UNIT Failed.¥n");
goto dberror;
}
while ((RETCODE = SQLFetch (hStmt2)) != SQL_NO_DATA_FOUND)
{
(void) printf ("**** Name is
(void) printf ("**** Vitae follows:¥n¥n");
for (i = 0; (i < 3200 && RETCODE != SQL_NO_DATA_FOUND); i += TEXT_SIZE)
{
RETCODE = SQLGetData (hStmt2,
3,
SQL_C_CHAR,
Narrative,
sizeof(Narrative) + 1,
&vitae_cbValue);
if (RETCODE != SQL_NO_DATA_FOUND)
(void) printf ("
}
}
/*****************************************************************/
/* Deallocate statement handles */
/*****************************************************************/
rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, hStmt);
rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, hStmt2);
/*****************************************************************/
/* DISCONNECT from data source */
/*****************************************************************/
RETCODE = SQLDisconnect(hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Deallocate connection handle */
/*****************************************************************/
RETCODE = SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Free environment handle */
/*****************************************************************/
rc = SQLFreeHandle (SQL_HANDLE_ENV, hEnv);
if (RETCODE == SQL_SUCCESS)
goto exit;
dberror:
RETCODE=12;
exit:
(void) printf ("**** Exiting CLIP09.¥n¥n");
return RETCODE;
}
/*****************************************************************/
/* Function insert_bio is invoked to insert one row into the */
/* BIOGRAPHY Table. The biography text is inserted in sets of */
/* 80 bytes via SQLPutData. */
/*****************************************************************/
int insert_bio (SQLHSTMT hStmt,
char *vitae,
int bcount)
{
SQLINTEGER rc = SQL_SUCCESS;
SQLPOINTER prgbValue;
int i;
char *text;
/*****************************************************************/
/* NAME and UNIT are bound... VITAE is provided after execution */
/* of the INSERT using SQLPutData. */
/*****************************************************************/
rc = SQLExecute (hStmt);
if (rc != SQL_NEED_DATA) // expect SQL_NEED_DATA
{
rc = 12;
(void) printf ("**** NEED DATA not returned.¥n");
goto exit;
}
/*****************************************************************/
/* Invoke SQLParamData to position ODBC driver on input parameter*/
/*****************************************************************/
if ((rc = SQLParamData (hStmt,
&prgbValue)) != SQL_NEED_DATA)
{
rc = 12;
(void) printf ("**** NEED DATA not returned.¥n");
goto exit;
}
/*****************************************************************/
/* Iterate through VITAE in 80 byte increments.... pass to */
/* ODBC Driver via SQLPutData. */
/*****************************************************************/
for (i = 0, text = vitae, rc = SQL_SUCCESS;
(i < bcount) && (rc == SQL_SUCCESS);
i++, text += TEXT_SIZE)
{
rc = SQLPutData (hStmt,
text,
TEXT_SIZE);
}
/*****************************************************************/
/* Invoke SQLParamData to trigger ODBC driver to execute the */
/* statement. */
/*****************************************************************/
if ((rc = SQLParamData (hStmt,
&prgbValue)) != SQL_SUCCESS)
{
rc = 12;
(void) printf ("**** INSERT Failed.¥n");
}
exit:
return (rc);
}
SQL_C_TYPE_TIMESTAMP_EXT