bcp_exec
データベース テーブルとユーザー ファイル間でデータの完全な一括コピーを実行します。
構文
RETCODE bcp_exec (
HDBC hdbc,
LPDBINT pnRowsProcessed);
引数
- hdbc
一括コピーが有効な ODBC 接続ハンドルです。
- pnRowsProcessed
DBINT へのポインタです。bcp_exec 関数は、この DBINT に正常にコピーされた行数を設定します。pnRowsProcessed が NULL の場合、bcp_exec はこの引数を無視します。
戻り値
SUCCEED、SUCCEED_ASYNC、または FAIL のいずれかを返します。すべての行がコピーされた場合、bcp_exec 関数は SUCCEED を返します。非同期の一括コピー操作が完了していない場合、bcp_exec は SUCCEED_ASYNC を返します。完了時エラーが発生した場合、またはエラーが発生した行数が、bcp_control を使用して BCPMAXERRS に指定した値に達した場合、bcp_exec は FAIL を返します。BCPMAXERRS の既定値は 10 です。BCPMAXERRS オプションの影響を受けるのは、データ ファイルの行 (サーバーに送信される行以外) を読み取る間にプロバイダで検出される構文エラーのみです。ある行でエラーが検出されると、サーバーはバッチを中止します。正常にコピーされた行数については、pnRowsProcessed パラメータをチェックしてください。
解説
この関数は、bcp_init の eDirection パラメータの値に応じてユーザーファイルからデータベース テーブルへ、またはデータベースからユーザー ファイルへデータをコピーします。
bcp_exec を呼び出す前に、有効なユーザー ファイル名を指定して bcp_init を呼び出してください。この操作を行わないと、エラーが発生します。
bcp_exec は、短時間に優れた結果を得られる唯一の一括コピー関数です。そのため、非同期モードをサポートする唯一の一括コピー関数でもあります。非同期モードを設定するには、bcp_exec を呼び出す前に、SQLSetConnectAttr を使用して SQL_ATTR_ASYNC_ENABLE を SQL_ASYNC_ENABLE_ON に設定します。完了したかどうかを確認するには、同じパラメータを指定して bcp_exec を呼び出します。一括コピーが完了していない場合、bcp_exec は SUCCEED_ASYNC を返します。また、pnRowsProcessed には、サーバーに送信された行の進行状況を表す行数も返されます。サーバーに送信された行は、バッチの終わりに到達するまではコミットされません。
例
次の例では、bcp_exec の使用方法を示します。
// Variables like henv not specified.
HDBC hdbc;
DBINT nRowsProcessed;
// Application initiation, get an ODBC environment handle, allocate the
// hdbc, and so on.
...
// Enable bulk copy prior to connecting on allocated hdbc.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,
SQL_IS_INTEGER);
// Connect to the data source, return on error.
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,
_T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))
{
// Raise error and return.
return;
}
// Initialize bulk copy.
if (bcp_init(hdbc, _T("pubs..authors"), _T("authors.sav"), NULL, DB_OUT)
== FAIL)
{
// Raise error and return.
return;
}
// Now, execute the bulk copy.
if (bcp_exec(dbproc, &nRowsProcessed) == FAIL)
{
if (nRowsProcessed == -1)
{
printf("No rows processed on bulk copy execution.\n");
}
else
{
printf("Incomplete bulk copy. Only %ld row%s copied.\n",
nRowsProcessed, (nRowsProcessed == 1) ? "": "s");
}
return;
}
printf("%ld rows processed.\n", nRowsProcessed);
// Carry on.