IBCPSession::BCPColFmt (OLE DB)

Статья
05/23/2023

Применимо к: SQL Server Azure SQL Database Управляемый экземпляр SQL Azure Azure Synapse Analytics Analytics Platform System (PDW)

Скачать драйвер OLE DB

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

Синтаксис

  
HRESULT BCPColFmt(   
      DBORDINAL idxUserDataCol,  
      int eUserDataType,  
      int cbIndicator,  
      int cbUserData,  
      BYTE *pbUserDataTerm,  
      int cbUserDataTerm,  
      DBORDINAL idxServerCol);

Remarks

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

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

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

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

Сопоставление полей файла пользователя со столбцами базы данных.
Тип данных каждого поля в файле пользователя.
Длина дополнительного признака для каждого поля.
Максимальная длина данных в каждом поле файла пользователя.
Дополнительная последовательность байтов, служащая признаком конца для каждого поля ¹.
Длина дополнительной последовательности байт, служащей признаком конца ¹.

Важно!

[1]. Использование последовательности признака конца в сценариях, в которых в качестве кодовой страницы файла данных выбрано UTF-8, не поддерживается. В таких случаях параметр pbUserDataTerm должен быть установлен в значение nullptr, а cbUserDataTerm — в значение 0.

При каждом вызове метода 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]
Тип данных поля из файла данных пользователя. Допустимые типы данных перечислены в файле заголовка OLE DB Driver for SQL Server (msoledbsql.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 или должны быть установлены в 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). Обратите особое внимание, правильно ли задана строка байтов, служащая признаком конца, а также ее длина. Сведения об ограничениях кодировки UTF-8 см. в разделе Замечания выше.

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

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

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

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

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

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

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

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

См. также:

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