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

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. Например, можно указать строку символов, тип 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_columns должна вызываться перед вызовами bcp_colfmt.

Необходимо вызвать bcp_colfmt один раз для каждого столбца в пользовательском файле.

Вызов bcp_colfmt несколько раз для любого столбца пользовательского файла приводит к ошибке.

Нет необходимости копировать все данные из файла пользователя в таблицу SQL Server. Чтобы пропустить столбец, укажите формат данных для столбца, задав для параметра idxServerCol значение 0. Если требуется пропустить столбец, необходимо указать его тип.

Для сохранения спецификации формата можно воспользоваться функцией bcp_writefmt .

Поддержка функцией bcp_colfmt улучшенных возможностей даты и времени

Сведения о типах, используемых с параметром eUserDataType для типов даты и времени, см. в разделе Изменения массового копирования для расширенных типов даты и времени (OLE DB и ODBC).

Дополнительные сведения см. в разделе Улучшения даты и времени (ODBC).

См. также:

Bulk Copy Functions