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

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).

См. также

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