bcp_colfmt

Статья
01/10/2024

Применимо к:SQL Server Azure SQL DatabaseAzure Managed Instance Azure Synapse Analytics Analytics 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) представил поддержку маркеров типа данных SQLXML и SQLUDT в параметре eUserDataType .

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

Чтобы указать представление данных по умолчанию для типа данных 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 указывает, что система должна определить длину данных в каждом столбце. Для некоторых столбцов это может означать, что индикатор длины или 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).

См. также

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

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