Поделиться через

bcp_colfmt

  • Статья

Указывает исходный или целевой формат данных в пользовательском файле. В случае исходного формата функция 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 введена поддержка токенов типа данных SQLXML и SQLUDT в параметре eUserDataType.

    Параметр eUserDataType перечисляется токенами типов данных SQL Server в sqlncli.h, а не в перечислителях типов данных ODBC C. Например, можно указать символьную строку SQL_C_CHAR типа ODBC с помощью специфического для SQL Server типа SQLCHARACTER.

    Чтобы задать представление данных по умолчанию для типа данных SQL Server, установите этот параметр в значение 0.

    Для массового копирования из SQL Server в файл, когда параметр eUserDataType имеет значение SQLDECIMAL или SQLNUMERIC:

    • Если тип исходного столбца отличается от decimal и numeric, то используются точность и масштаб по умолчанию.

    • Если исходный столбец имеет тип decimal или numeric, то используются точность и масштаб исходного столбца.

  • 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 представляет объем данных в байтах. Если символьные данные представлены строкой знаков в Юникоде, то положительное значение параметра cbUserData представляет количество символов, умноженное на размер символа в байтах.

  • pUserDataTerm
    Последовательность-признак конца, используемая для этого столбца. Этот параметр предназначен главным образом для символьных типов данных, поскольку все другие типы имеют фиксированную длину или, как в случае с двоичными данными, требуют наличия признака длины, в котором записано точное число присутствующих байтов.

    Чтобы исключить обработку признака конца в извлекаемых данных или указать, что данные в файле пользователя не имеют признака конца, установите этот параметр в значение NULL.

    Если для столбца файла пользователя используется несколько способов задания длины (например, признак конца и признак длины или признак конца и максимальная длина столбца), то для массового копирования выбирается способ, применение которого вызывает копирование данных наименьшего объема.

    При необходимости API-интерфейс массового копирования выполнит преобразование символов из Юникода в многобайтовую кодировку (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).

См. также

Справочник

Функции массового копирования