IBCPSession::BCPColFmt (OLE DB)
Создает привязку между переменными программы и столбцами SQL Server.
Синтаксис
HRESULT BCPColFmt( DBORDINAL idxUserDataCol, int eUserDataType, int cbIndicator, int cbUserData, BYTE *pbUserDataTerm, int cbUserDataTerm, DBORDINAL idxServerCol);
Замечания
Метод BCPColFmt используется для создания привязки между полями файла данных BCP и столбцами SQL Server. В качестве параметров он принимает длину, тип, признак конца и длину префикса столбца, и задает каждое из этих свойств для отдельных полей.
Если пользователь работает в интерактивном режиме, этот метод вызывается дважды для каждого столбца; один раз, чтобы задать формат столбца согласно значениям по умолчанию (которые соответствуют типу столбца сервера), а второй раз, чтобы задать формат согласно типу столбца, выбранному клиентом в интерактивном режиме.
В неинтерактивном режиме этот метод вызывается только один раз для каждого столбца, чтобы задать ему символьный или собственный тип, а также чтобы задать признаки конца столбца и строк.
При помощи метода BCPColFmt можно указывать формат файла пользователя для операций массового копирования. Формат для массового копирования состоит из следующих частей:
Сопоставление полей файла пользователя со столбцами базы данных.
Тип данных каждого поля в файле пользователя.
Длина дополнительного признака для каждого поля.
Максимальная длина данных в каждом поле файла пользователя.
Дополнительная последовательность байт, служащая признаком конца для каждого поля.
Длина дополнительной последовательности байт, служащей признаком конца.
При каждом вызове метода BCPColFmt задается формат для одного поля в файле пользователя. Например, чтобы изменить значения по умолчанию трех полей в файле данных пользователя, состоящим из пяти полей, сначала вызовите метод BCPColumns(5), а затем метод BCPColFmt пять раз, и в трех из этих вызовов задайте нужный формат. При оставшихся двух вызовах параметру eUserDataType установите значение BCP_TYPE_DEFAULT, а параметрам cbIndicator, cbUserData и cbUserDataTerm — значения 0, BCP_VARIABLE_LENGTH и 0 соответственно. Эта процедура копирует все пять столбцов. Для трех применяется заданный измененный формат, а для двух оставшихся — формат по умолчанию.
.gif "Примечание") Примечание |
|---|
Перед любым вызовом метода BCPColFmt необходимо вызывать метод IBCPSession::BCPColumns. Метод BCPColFmt необходимо вызывать по одному разу для каждого столбца из файла пользователя. При вызове метода BCPColFmt более одного раза для любого столбца из файла пользователя возникает ошибка. |
Все данные из файла пользователя копировать в таблицу SQL Server необязательно. Чтобы пропустить столбец, укажите формат данных этого столбца, а параметру idxServerCol установите значение 0. Чтобы пропустить поле, для корректной работы метода потребуется все данные.
Примечание При помощи функции IBCPSession::BCPWriteFmt можно сохранить спецификацию формата, предоставленную с помощью метода BCPColFmt.
Аргументы
idxUserDataCol[in]
Индекс поля из файла данных пользователяeUserDataType[in]
Тип данных поля из файла данных пользователя Допустимые типы данных приведены в файле заголовка собственного клиента SQL Server (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
Ошибка, связанная с нехваткой памяти.
См. также