通过

bcp_setcolfmt

  • 项目

bcp_setcolfmt 函数取代了 bcp_colfmt。 在指定列排序规则时，必须使用 bcp_setcolfmt 函数。 bcp_setbulkmode 可用于指定多个列格式。

该函数提供在大容量复制操作中指定列格式的灵活方法。 它用于设置单独的列格式属性。 对 bcp_setcolfmt 的每个调用都将设置一个列格式属性。

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

语法

RETCODE bcp_setcolfmt ( 
        HDBC hdbc, 
        INT field, 
        INT property, 
        void* pValue, 
        INT cbValue);

参数

  • hdbc
    支持大容量复制的 ODBC 连接句柄。

  • 字段
    要设置其属性的按一定顺序的列号。

  • 属性
    属性常量之一。 在下表中定义属性常量。

    属性

    值

    说明

    BCP_FMT_TYPE

    BYTE

    用户文件中此列的数据类型。 如果不同于数据库表中相应列的数据类型，则大容量复制将根据情况转换数据。

    BCP_FMT_TYPE 参数由 sqlncli.h 中的 SQL Server 数据类型标记枚举，而非采用 ODBC C 数据类型枚举器。 例如，您可以使用特定于 SQL Server 的 SQLCHARACTER 类型指定一个字符串：ODBC 类型 SQL_C_CHAR。

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

    对于从 SQL Server 大容量复制到某一文件，在 BCP_FMT_TYPE 为 SQLDECIMAL 或 SQLNUMERIC 时：

    • 如果源列不是 decimal 或 numeric，则使用默认的精度和小数位数。

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

    BCP_FMT_INDICATOR_LEN

    INT

    以字节表示的指示器（前缀）的长度。

    它是列数据中以字节表示的长度/空指示器的长度。 有效的指示器长度值是 0（在未使用指示器时）、1、2 或 4。

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

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

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

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

    BCP_FMT_DATA_LEN

    DBINT

    用字节表示的数据的长度（列长度）。

    它是用户文件中此列的数据的用字节表示的最大长度，不包括任何长度指示器或终止符的长度。

    如果将 BCP_FMT_DATA_LEN 设置为 SQL_NULL_DATA，则指示数据文件列中的所有值均为或应该设置为 NULL。

    如果将 BCP_FMT_DATA_LEN 设置为 SQL_VARLEN_DATA，则指示系统应确定各列中数据的长度。 对于某些列，这可能意味着生成长度/空指示符，以便置于来自 SQL Server 的副本的数据前，或者意味着该指示符应位于复制到 SQL Server 的数据中。

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

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

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

    BCP_FMT_TERMINATOR

    LPCBYTE

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

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

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

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

    BCP_FMT_SERVER_COL

    INT

    数据库中列的序号位置

    BCP_FMT_COLLATION

    LPCSTR

    排序规则名。

  • pValue
    指向要与 property 相关联的值的指针。 它允许单独设置每个列格式属性。

  • cbvalue
    以字节表示的属性缓冲区的长度。

返回值

SUCCEED 或 FAIL。

注释

此函数取代 bcp_colfmt 函数。 bcp_colfmt 的所有功能均在 bcp_setcolfmt 函数中提供。 此外，还提供对列排序规则的支持。 建议按照下面给出的顺序设置以下列格式属性：

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

bcp_setcolfmt 函数允许您为大容量复制指定用户文件格式。 对于大容量复制，格式包含以下部分：

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

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

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

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

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

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

对 bcp_setcolfmt 的每个调用都将为一个用户文件列指定格式。 例如，若要在由五个列构成的用户数据文件中更改其中三列的默认设置，请首先调用 bcp_columns(5)，然后调用 bcp_setcolfmt 五次，其中三次调用设置您的自定义格式。 对于其余两次调用，将 BCP_FMT_TYPE 设置为 0，将 BCP_FMT_INDICATOR_LENGTH、BCP_FMT_DATA_LEN 和 cbValue 分别设置为 0、SQL_VARLEN_DATA 和 0。 此过程复制全部五列，其中的三列采用您的自定义格式，另两列采用默认格式。

必须在调用 bcp_setcolfmt 前调用 bcp_columns 函数。

对于用户文件中每一列的每个属性，您必须调用 bcp_setcolfmt 一次。

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

bcp_writefmt 函数可用于维持格式规范。

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

用于日期/时间类型的 BCP_FMT_TYPE 属性的类型按照增强的日期/时间类型的大容量复制更改（OLE DB 和 ODBC）中的说明指定。

有关详细信息，请参阅 日期/时间的改进 (ODBC)。

请参阅

参考

大容量复制函数