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 格式化文件提供更大的灵活性,但具有某些额外约束。例如,不能同时为字段指定前缀和终止符,而在较早的格式化文件中则可以执行此操作。

    注意注意

    只有当 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,则指定以字符格式保存的 datetimesmalldatetime 值将使用 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);

请参阅

参考