bcp_control

  • [アーティクル]

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

構文

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

引数

  • hdbc
    一括コピーが有効な ODBC 接続ハンドルです。
  • eOption
    次のいずれかを指定します。

  • BCP6xFILEFMT
    iValue が TRUE のときは、データ ファイルに格納されている列に、SQL Server 7.0 形式ではなく SQL Server 6.x 形式を使用することを指定します。

    SQL Server 7.0 データベースから一括コピー出力を行う場合、6.x 形式ではサポートされないデータ型があります。NULL 値を許容する bit 型の値は 0 に変換されます。char 型、varchar 型、binary 型、varbinary 型の 255 バイトを超える値は切り捨てられます。uniqueidentifier 型、nchar 型、nvarchar 型、および ntext 型の列はサポートされません。長さが 0 のデータは NULL に変換されます。

    文字形式のデータ ファイルの列から一括コピー入力を行うときに、iValue を FALSE に設定すると、空の入力値は NULL に変換されます。次の表に、iValue が TRUE のときの結果を示します。

    コピー先列のデータ型 コピー後の値

    numeric 型のカテゴリに属するデータ型

    0

    binary または varbinary

    0x00

    datetime または smalldatetime

    NULL

    uniqueidentifier

    NULL

    datetime 型の文字列を含む文字形式データ ファイルの列から一括コピー入力を行う場合、以前のバージョンの DB-Library の一括コピーでサポートされていたすべての datetime 型の文字列形式がサポートされます。

    iValue を TRUE に設定すると、キャラクタ モードのデータ ファイルでバイナリ値を示すプレフィックス 0x を指定できます。iValue が FALSE の場合、このプレフィックスを指定できません。

    iValue を FALSE に設定すると、長さが 0 の値は、キャラクタ モードのデータ ファイルでは 0x00 として格納され、BCPUNICODE ファイルでは 0x0000 として格納されます。

  • 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 のコード ページが使用されます。

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

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

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

    ms130996.note(ja-jp,SQL.90).gifメモ :
    XML フォーマット ファイルがサポートされるのは、SQL Server 2005 ツールを SQL 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 より小さい値を指定すると、このオプションは既定値にリセットされます。
  • 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'} と表されます。

  • BCPUNICODEFILE
    TRUE の場合、入力ファイルが Unicode ファイルであることを指定します。
  • FIRE_TRIGGERS
    コピー先のテーブルに定義された INSERT トリガと INSTEAD OF トリガが、一括コピー バッチごとに 1 回起動されることを指定します。各トリガに渡される inserted テーブルには、バッチによって挿入されるすべての行が含まれます。通常、一括コピー操作では最小のログ記録が行われますが、FIRE_TRIGGERS を指定すると完全なログ記録が行われます。このトリガによって生成される結果セットは、一括コピー操作を実行するクライアントには返されません。コピー先のテーブルのすべての INSERT トリガと INSTEAD OF トリガで複数行の挿入がサポートされる場合のみ、FIRE_TRIGGERS を指定します。iValue パラメータは無視されます。
  • iValue
    指定した eOption の値です。iValue は、後から 64 ビット値に拡張できるように void ポインタにキャストされた整数値です。

戻り値

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("%ld rows processed by bulk copy.", nRowsProcessed);

参照

関連項目

一括コピー関数

ヘルプおよび情報

SQL Server 2005 の参考資料の入手