bcp_colfmt

  • 项目

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure Synapse AnalyticsAnalytics Platform System (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。

如果 eUserDataType 为 SQLDECIMAL 或 SQLNUMERIC，则从 SQL Server 大容量复制到文件中：

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

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

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

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

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

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

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

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

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

将 cbUserData 设置为 SQL_VARLEN_DATA 表示系统应确定每列中的数据长度。 对于某些列，这可能意味着生成一个长度/null 指示符，以在SQL Server副本上的数据之前，或者指示符预期在复制到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 五次，其中三个调用将设置自定义格式。 对于其余两个调用，请将 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) (日期和时间改进 。

另请参阅

大容量复制函数