Share via

  • 项目

bcp_control

更改用于在文件和 SQL Server 之间进行大容量复制的各种控制参数的默认设置。

语法

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

参数

  • hdbc
    支持大容量复制的 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
    数据文件格式的版本号。该选项可以为 70 (SQL Server 7.0)、80 (SQL Server 2000)、90 (SQL Server 2005) 或 100 (SQL Server 2008)。默认值是 100，指示文件采用 SQL Server 2008 格式。对于采用服务器的早期版本所支持的格式的数据，该选项对导出和导入这样的数据非常有用。例如，若要将从 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 格式化文件提供更大的灵活性，但具有某些额外约束。例如，不能同时为字段指定前缀和终止符，而在较早的格式化文件中则可以执行此操作。

    注意注意

    只有当 SQL Server 和 SQL Server Native Client 一起安装后，才支持 XML 格式化文件。

  • BCPHINTS
    iValue 包含 SQLTCHAR 字符字符串指针。寻址的字符串指定 SQL Server 大容量复制处理提示或返回结果集的 Transact-SQL 语句。如果指定的 Transact-SQL 语句返回多个结果集，则忽略第一个结果集之后的所有结果集。有关大容量复制处理提示的详细信息，请参阅 bcp 实用工具。

  • BCPKEEPIDENTITY
    当 iValue 为 TRUE 时，该选项指定大容量复制函数插入为 SQL Server 列（使用标识约束定义）提供的数据值。输入文件必须提供标识列的值。如果未进行设置，则为插入的行生成新标识值。忽略文件的标识列中所存在的任何数据。

  • 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 将通过检查数据文件的前两个字节中的 Unicode 字节标记来确定该文件是否是 Unicode 文件。

  • BCPUNICODEFILE
    如果为 TRUE，则指定输入文件是 Unicode 文件。

  • iValue
    指定的 eOption 的值。iValue 是转换为 void 指针的整数值 (LONGLONG)，允许将来扩展到 64 位值。

返回值

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);

请参阅

参考

大容量复制函数