• [アーティクル]

bcp_control

ファイルと SQL Server の間の一括コピーに使用するさまざまな制御パラメーターの既定の設定を変更します。

構文

RETCODE bcp_control (
        HDBC hdbc,
        INT eOption,
        void* iValue);

引数

  • dbc
    一括コピーが有効な ODBC 接続ハンドルです。

  • eOption
    次のいずれかを指定します。

  • BCPABORT
    既に実行中の一括コピー操作を停止します。別のスレッドから eOption に BCPABORT を指定して bcp_control を呼び出すと、一括コピー操作の実行が停止されます。iValue パラメーターは無視されます。

  • BCPBATCH
    バッチごとの行数を指定します。既定値は 0 です。既定値を指定すると、データを抽出するときはテーブル内のすべての行が抽出されることを示し、データを SQL Server にコピーするときはユーザー データ ファイル内のすべての行がコピーされることを示します。1 より小さい値を指定すると、BCPBATCH は既定値にリセットされます。

  • BCPFILECP
    iValue には、データ ファイルのコード ページ番号を指定します。1252 や 850 などのコード ページ番号を指定するか、次のいずれかの値を指定できます。

    BCPFILE_ACP を指定すると、ファイル内のデータには、クライアントの Microsoft Windows® コード ページが使用されます。

    BCPFILE_OEMCP を指定すると、ファイル内のデータには、クライアントの OEM コード ページ (既定) が使用されます。

    BCPFILE_RAW を指定すると、ファイル内のデータには、SQL Server のコード ページが使用されます。

  • BCPFILEFMT
    データ ファイル形式のバージョン番号を指定します。80 (SQL Server 2000)、90 (SQL Server 2005)、または 100 (SQL Server 2008 または SQL Server 2008 R2) を指定できます。既定値は 100 です。このオプションは、以前のバージョンのサーバーでサポートされていた形式でデータをエクスポートおよびインポートする際に便利です。たとえば、SQL Server 2000 サーバーのテキスト列から取得したデータを、SQL Server 2005 以降のサーバーの varchar(max) 列にインポートするには、80 を指定する必要があります。同様に、データを varchar(max) 列からエクスポートするときに 80 を指定すると、データは、テキスト列が SQL Server 2000 形式で保存される場合と同じ形式で保存されるので、SQL Server 2000 サーバーのテキスト列にインポートできます。

  • BCPFIRST
    ファイルまたはテーブルにコピーする最初のデータ行を指定します。既定値は 1 です。1 より小さい値を指定すると、このオプションは既定値にリセットされます。

  • BCPFIRSTEX
    BCP out 操作の場合は、データ ファイルにコピーするための、データベース テーブルの最初の行を指定します。

    BCP in 操作の場合は、データベース テーブルにコピーするための、データ ファイルの最初の行を指定します。

    iValue パラメーターには、その値を含む 64 ビット符号付き整数のアドレスを指定する必要があります。BCPFIRSTEX に渡すことができる最大値は 2^63-1 です。

  • BCPFMTXML
    XML 形式のフォーマット ファイルが生成されることを指定します。既定では無効になっています。

    XML フォーマット ファイルにより柔軟性が向上しますが、いくつか制約も追加されます。たとえば、以前のフォーマット ファイルでは、1 つのフィールドにプレフィックスとターミネータを同時に指定できましたが、XML フォーマット ファイルでは指定できません。

    注意注

    XML フォーマット ファイルがサポートされるのは、SQL Server を SQL Server Native Client と共にインストールした場合だけです。

  • BCPHINTS
    iValue には、SQLTCHAR 文字列ポインターが含まれます。ポインターが指す文字列には、SQL Server 一括コピー処理ヒント、または結果セットを返す Transact-SQL ステートメントを指定します。複数の結果セットを返す Transact-SQL ステートメントを指定すると、1 つ目以外の結果セットはすべて無視されます。一括コピー処理ヒントの詳細については、「bcp ユーティリティ」を参照してください。

  • BCPKEEPIDENTITY
    iValue が TRUE のときは、一括コピー関数が指定されたデータ値を ID 制約で定義された SQL Server 列に挿入することを指定します。入力ファイルには ID 列の値を指定する必要があります。このオプションを設定しないと、挿入される行に対して新しい ID 値が生成されます。ファイル内に存在する ID 列用のデータはすべて無視されます。

  • BCPKEEPNULLS
    ファイル内の空のデータ値を SQL Server テーブルで NULL 値に変換するかどうかを指定します。iValue が TRUE のときは、空の値は SQL Server テーブルで NULL に変換されます。既定では、空の値は SQL Server テーブル内の列の既定値 (存在する場合) に変換されます。

  • BCPLAST
    コピーする最後の行を指定します。既定では、すべての行がコピーされます。1 より小さい値を指定すると、このオプションは既定値にリセットされます。

  • BCPLASTEX
    BCP out 操作の場合は、データ ファイルにコピーするための、データベース テーブルの最後の行を指定します。

    BCP in 操作の場合は、データベース テーブルにコピーするための、データ ファイルの最後の行を指定します。

    iValue パラメーターには、その値を含む 64 ビット符号付き整数のアドレスを指定する必要があります。BCPLASTEX に渡すことができる最大値は 2^63-1 です。

  • BCPMAXERRS
    一括コピー操作が失敗するまでに発生してもかまわないエラーの数です。既定値は 10 です。1 より小さい値を指定すると、このオプションは既定値にリセットされます。一括コピーでは、最大 65,535 個のエラーが許容されます。このオプションに 65,535 を超える値を設定しようとすると、65,535 が設定されます。

  • BCPODBC
    TRUE に設定した場合、文字形式で保存されている datetime 型の値と smalldatetime 型の値に、ODBC タイムスタンプ エスケープ シーケンスのプレフィックスとサフィックスが使用されることを示します。BCPODBC オプションは、BCP_OUT にのみ適用されます。

    FALSE の場合、1997 年 1 月 1 日を表す datetime 型の値は、1997-01-01 00:00:00.000 という文字列に変換されます。TRUE の場合、同じ datetime 型の値は {ts '1997-01-01 00:00:00.000'} と表されます。

  • BCPROWCOUNT
    現在 (または最後) の BCP 操作で処理された行数を返します。

  • BCPTEXTFILE
    TRUE の場合、データ ファイルがバイナリ ファイルではなくテキスト ファイルであることを示します。ファイルがテキスト ファイルの場合、BCP では、データ ファイルの先頭 2 バイトに含まれる Unicode バイト マーカーをチェックして、そのファイルが Unicode 形式かどうかを判断します。

  • BCPUNICODEFILE
    TRUE の場合、入力ファイルが Unicode ファイルであることを指定します。

  • iValue
    指定された eOption に対応する値です。iValue は、後から 64 ビット値に拡張できるように void ポインターにキャストされた整数値 (LONGLONG) です。

戻り値

SUCCEED または FAIL を返します。

説明

この関数では、一括コピー操作のさまざまな制御パラメーターを設定します。たとえば、一括コピーが取り消されるまでに発生してもかまわないエラーの数、データ ファイルから最初にコピーする行番号や最後にコピーする行番号、バッチ サイズなどを設定します。

また、この関数は、SQL Server から SELECT ステートメントの結果セットを一括コピーするときに、その SELECT ステートメントを指定するためにも使用します。この場合、eOption に BCPHINTS を設定し、iValue に SELECT ステートメントを含む SQLTCHAR 文字列へのポインターを設定します。

これらの制御パラメーターは、ユーザー ファイルと SQL Server テーブルの間でコピーを行う場合のみ意味があります。bcp_sendrow により SQL Server にコピーされる行が、制御パラメーターの設定の影響を受けることはありません。

例

// Variables like henv not specified.
SQLHDBC      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("address"), _T("address.add"), _T("addr.err"),
   DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set the number of rows per batch. 
if (bcp_control(hdbc, BCPBATCH, (void*) 1000) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set file column count. 
if (bcp_columns(hdbc, 1) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set the file format. 
if (bcp_colfmt(hdbc, 1, 0, 0, SQL_VARLEN_DATA, '\n', 1, 1)
   == FAIL)
   {
   // Raise error and return.
   return;
   }

// Execute the bulk copy. 
if (bcp_exec(hdbc, &nRowsProcessed) == FAIL)
   {
   // Raise error and return.
   return;
   }

printf_s("%ld rows processed by bulk copy.", nRowsProcessed);

関連項目

参照

一括コピー関数