通过

bcp_colfmt

  • 项目

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics 平台系统（PDW）

指定用户文件中的数据的源或目标格式。 用作源格式时， bcp_colfmt 指定用作大容量复制到 SQL Server 表的数据源的现有数据文件的格式。 用作目标格式时，将使用通过bcp_colfmt指定的列格式创建数据文件。

语法

  
RETCODE bcp_colfmt (  
        HDBC hdbc,  
        INT idxUserDataCol,  
        BYTE eUserDataType,  
        INT cbIndicator,  
        DBINT cbUserData,  
        LPCBYTE pUserDataTerm,  
        INT cbUserDataTerm,  
        INT idxServerCol);

参数

hdbc
已启用大容量复制的 ODBC 连接句柄。

idxUserDataCol
正在为其指定格式的用户数据文件中的列序号。 第一列为 1。

eUserDataType
用户文件中此列的数据类型。 如果不同于数据库表中相应列的数据类型（idxServerColumn），则大容量复制可根据需要转换数据。

SQL Server 2005 （9.x） 引入了对 eUserDataType 参数中 SQLXML 和 SQLUDT 数据类型令牌的支持。

eUserDataType 参数由 sqlncli.h 中的 SQL Server 数据类型标记而不是 ODBC C 数据类型枚举器枚举。 例如，可以使用 SQL Server 特定的 SQLCHARACTER 类型指定字符串、ODBC 类型SQL_C_CHAR。

若要指定 SQL Server 数据类型的默认数据表示形式，请将此参数设置为 0。

对于从 SQL Server 大容量复制到文件中，当 eUserDataType 为 SQLDECIMAL 或 SQLNUMERIC 时：

  • 如果源列不是 十进制 列或 数字，则使用默认精度和小数位数。

  • 如果源列是 小数 或 数值，则使用源列的精度和小数位数。

cbIndicator
列数据中的长度/Null 指示器的长度（字节）。 有效指示器长度值是 0（不使用任何指示器时）、1、2、4 或 8。

若要指定默认的大容量复制指示器用法，请将此参数设置为 SQL_VARLEN_DATA。

指示器在内存中出现在任何数据的紧前面，在数据文件中出现在它们适用于的数据的紧前面。

如果使用多种方法来指定数据文件列长度（例如指示器和最大列长度，或者指示器和终止符序列），则大容量复制将选择导致数据复制量最少的方法。

如果列数据可能在长度上发生变化或列可能接受 NULL 作为值，则在没有调整数据格式的用户干预时，大容量复制生成的数据文件将包含指示器。

cbUserData
用户文件中该列数据的最大长度（字节），不包括任何长度指示器或终止符的长度。

将 cbUserData 设置为SQL_NULL_DATA表示数据文件列中的所有值都设置为 NULL，或者应设置为 NULL。

将 cbUserData 设置为SQL_VARLEN_DATA表示系统应确定每列中数据的长度。 对于某些列，这可能意味着在从 SQL Server 复制的副本之前生成长度/null 指示器，或指示符在复制到 SQL Server 的数据中预期。

对于 SQL Server 字符和二进制数据类型， cbUserData 可以SQL_VARLEN_DATA、SQL_NULL_DATA、0 或某些正值。 如果 cbUserData 是SQL_VARLEN_DATA，则系统会使用长度指示器（如果存在）或终止符序列来确定数据的长度。 如果长度指示符和终止符序列均提供，则大容量复制将采用导致数据复制量最少的方法。 如果 cbUserData 是SQL_VARLEN_DATA，则数据类型为 SQL Server 字符或二进制类型，并且未指定长度指示器或终止符序列，系统将返回错误消息。

如果 cbUserData 为 0 或正值，则系统使用 cbUserData 作为最大数据长度 。 但是，如果除了正的 cbUserData 以外，还提供了长度指示器或终止符序列，则系统使用导致数据复制量最少的方法来确定数据长度。

cbUserData 值表示数据的字节计数。 如果字符数据由 Unicode 宽字符表示，则正的 cbUserData 参数值表示字符数乘以每个字符大小（字节）。

pUserDataTerm
要用于该列的终止符序列。 此参数主要用于字符数据类型，因为所有其他类型均属于固定长度，或者在二进制数据的情况下，要求长度指示器以精确记录提供的字节数目。

为了避免终止提取的数据，或者指示用户文件中的数据不终止，可将此参数设置为 NULL。

如果使用多种方法指定用户文件列长度（例如终止符和长度指示器，或者终止符和最大列长度），则大容量复制选择导致数据复制量最少的方法。

大容量复制 API 根据需要执行 Unicode 到 MBCS 的字符转换。 执行此操作时请务必小心，以便确保终止符字节字符串和字节字符串的长度都正确设置。

cbUserDataTerm
要用于该列的终止符序列的长度（字节）。 如果终止符不存在或不希望其出现在数据中，请将该值设置为 0。

idxServerCol
列在数据库表中的序号位置。 第一个列编号为 1。 SQLColumns 报告列的序号位置。

如果该值是 0，则大容量复制将忽略数据文件中的该列。

返回

SUCCEED 或 FAIL。

注解

使用 bcp_colfmt 函数可以指定大容量副本的用户文件格式。 对于大容量复制，格式包含以下部分：

  • 从用户文件列到数据库列的映射。

  • 每个用户文件列的数据类型。

  • 每个列的可选指示符的长度。

  • 每个用户文件列的数据的最大长度。

  • 每个列的可选终止字节序列。

  • 可选终止字节序列的长度。

每次调用 bcp_colfmt 指定一个用户文件列的格式。 例如，若要更改五列用户数据文件中三列的默认设置，请先调用 bcp_columns（5），然后调用 bcp_colfmt 5 次，其中三个调用设置自定义格式。 对于其余两个调用，请将 eUserDataType 设置为 0，并将 cbIndicator、 cbUserData 和 cbUserDataTerm 分别设置为 0、SQL_VARLEN_DATA和 0。 此过程复制全部五列，其中的三列采用您的自定义格式，另两列采用默认格式。

对于 cbIndicator，值 8 表示大型值类型现在有效。 如果为其相应列是新的 max 类型的字段指定了前缀，则只能将它设置为 8。 有关详细信息，请参阅 bcp_bind。

在调用bcp_colfmt之前，必须调用bcp_columns函数。

必须为用户文件中的每一列调用 bcp_colfmt 一次。

对任何用户文件列多次调用 bcp_colfmt 会导致错误。

您不需要将用户文件中的所有数据都复制到 SQL Server 表中。 若要跳过列，请指定列的数据格式，将 idxServerCol 参数设置为 0。 如果您要跳过某一列，则必须指定其类型。

bcp_writefmt函数可用于保留格式规范。

对增强的日期和时间功能的 bcp_colfmt 支持

有关日期/时间类型的 eUserDataType 参数中使用的类型的信息，请参阅增强的日期和时间类型的大容量复制更改（OLE DB 和 ODBC）。

有关详细信息，请参阅日期和时间改进（ODBC）。

另请参阅

大容量复制函数