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

IBCPSession::BCPColFmt (OLE DB)

  • Статья

Создает привязку между переменными программы и столбцами SQL Server .

Синтаксис

  
HRESULT BCPColFmt(   
DBORDINALidxUserDataCol,  
inteUserDataType,  
intcbIndicator,  
intcbUserData,  
BYTE *pbUserDataTerm,  
intcbUserDataTerm,  
DBORDINALidxServerCol);

Remarks

Метод BCPColFmt используется для создания привязки между полями файла данных BCP и столбцами SQL Server. В качестве параметров он принимает длину, тип, признак конца и длину префикса столбца, а также задает каждое из этих свойств для отдельных полей.

Если пользователь работает в интерактивном режиме, этот метод вызывается дважды для каждого столбца: один раз, чтобы задать формат столбца согласно значениям по умолчанию (которые соответствуют типу столбца на сервере), а второй раз, чтобы задать формат согласно типу столбца, выбранному клиентом в интерактивном режиме.

В неинтерактивном режиме этот метод вызывается только один раз для каждого столбца, чтобы задать ему символьный или собственный тип, а также задать признаки конца столбца и строк.

При помощи метода BCPColFmt можно указывать формат файла пользователя для операций массового копирования. Формат для массового копирования состоит из следующих частей:

  • Сопоставление полей файла пользователя со столбцами базы данных.

  • Тип данных каждого поля в файле пользователя.

  • Длина дополнительного признака для каждого поля.

  • Максимальная длина данных в каждом поле файла пользователя.

  • Дополнительная последовательность байтов, служащая признаком конца для каждого поля.

  • длина дополнительной последовательности байт, служащей признаком конца.

При каждом вызове метода BCPColFmt задается формат для одного поля в файле пользователя. Например, чтобы изменить значения по умолчанию трех полей в файле данных пользователя, состоящем из пяти полей, сначала вызовите метод BCPColumns(5), а затем метод BCPColFmt пять раз и в трех из этих вызовов задайте нужный формат. При оставшихся двух вызовах для параметра eUserDataType установите значение BCP_TYPE_DEFAULT, а параметрам cbIndicator, cbUserDataи cbUserDataTerm присвойте значения 0, BCP_VARIABLE_LENGTH и 0 соответственно. Эта процедура копирует все пять столбцов. Для трех применяется заданный измененный формат, а для двух оставшихся — формат по умолчанию.

Примечание

Необходимо вызывать метод IBCPSession::BCPColumns перед любым вызовом метода BCPColFmt. Метод BCPColFmt необходимо вызывать по одному разу для каждого столбца из файла пользователя. При вызове метода BCPColFmt более одного раза для любого столбца из файла пользователя возникает ошибка.

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

Примечание. С помощью функции IBCPSession::BCPWriteFmt можно сохранить спецификацию формата, предоставленную с помощью метода BCPColFmt.

Аргументы

idxUserDataCol[in]
Индекс поля из файла данных пользователя.

eUserDataType[in]
Тип данных поля из файла данных пользователя. Доступные типы данных перечислены в файле заголовка SQL Server Native Client (sqlncli.h) в формате BCP_TYPE_XXX, например BCP_TYPE_SQLINT4. Если задано значение BCP_TYPE_DEFAULT, поставщик попытается использовать тот же тип, к которому принадлежит столбец таблицы или представления. Для операций массового копирования из SQL Server и в файл, если eUserDataType аргумент BCP_TYPE_SQLDECIMAL или BCP_TYPE_SQLNUMERIC:

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

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

cbIndicator[in]
Длина префикса поля. По умолчанию — BCP_PREFIX_DEFAULT. Допустимая длина префикса — 0, 1, 2, 4 или 8. Размер префикса 8 чаще всего используется для указания на то, что поле является фрагментированным. Фрагментация используется для повышения эффективности массового копирования столбцов типов с большими значениями.

cbUserData[in]
Максимальная длина в байтах данных этого поля в файле пользователя без учета длины любого признака длины или признака конца.

Значение cbUserData BCP_LENGTH_NULL указывает, что все значения в полях файла данных равны или должны иметь значение NULL. Значение cbUserData BCP_LENGTH_VARIABLE указывает, что система должна определить длину данных для каждого поля. Для некоторых полей это может означать, что создаваемые признаки длины и допустимости значений NULL предваряют данные при копировании из SQL Serverили ожидается наличие этих признаков в данных, копируемых в SQL Server.

Для SQL Server символьных и двоичных типов cbUserData данных может быть BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 или некоторое положительное значение. Если cbUserData параметр BCP_LENGTH_VARIABLE, то для определения длины данных система использует либо индикатор длины, если он имеется, либо последовательность признака конца. Если задан и признак длины, и последовательность признака конца, то при массовом копировании используется значение, применение которого вызывает копирование данных наименьшего объема. Если cbUserData параметр BCP_LENGTH_VARIABLE, то типом данных является символ SQL Server или двоичный тип, а если не указан ни индикатор длины, ни последовательность признака конца, система возвращает сообщение об ошибке.

Если cbUserData значение равно 0 или положительное значение, система использует cbUserData в качестве максимальной длины данных. Однако если в дополнение к положительному cbUserDataуказан индикатор длины или последовательность признака конца, система определяет длину данных с помощью метода , который приводит к минимальному объему копируемых данных.

Значение cbUserData представляет количество байтов данных. Если символьные данные представлены расширенными символами Юникода, положительное cbUserData значение параметра представляет количество символов, умноженное на размер каждого символа в байтах.

pbUserDataTerm[size_is][in]
Последовательность с признаком конца, которая должна использоваться для поля. Этот параметр предназначен главным образом для символьных типов данных, поскольку все другие типы имеют фиксированную длину или, как в случае с двоичными данными, требуют наличия признака длины, в котором записано точное число присутствующих байтов.

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

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

При необходимости API-интерфейс массового копирования выполнит преобразование символов из Юникода в многобайтовую кодировку (MBCS). Обратите особое внимание, правильно ли задана строка байтов, служащая признаком конца, а также ее длина.

cbUserDataTerm[in]
Длина в байтах последовательности с признаком конца, которая должна использоваться для столбца. Если в данных признак конца отсутствует или нежелателен, то установите это значение в 0.

idxServerCol[in]
Порядковый номер столбца в таблице базы данных. Первый столбец имеет номер 1. Порядковый номер столбца сообщается методом IColumnsInfo::GetColumnInfo либо подобными методами. Если это значение равно 0, то при массовом копировании это поле в файле данных будет пропущено.

Значения кода возврата

S_OK
Метод выполнен успешно.

E_FAIL
Произошла ошибка, связанная с поставщиком. Подробные сведения можно получить с помощью интерфейса ISQLServerErrorInfo.

E_UNEXPECTED
Непредвиденный вызов метода. Например, перед вызовом этого метода не был вызван метод IBCPSession::BCPInit.

E_INVALIDARG
Недопустимое значение аргумента.

E_OUTOFMEMORY
Ошибка, связанная с нехваткой памяти.

См. также:

Интерфейс IBCPSession (OLE DB)
Выполнение операций массового копирования