IBCPSession::BCPColFmt (поставщик OLE DB собственного клиента)

  • Статья

Применимо к:SQL ServerAzure SQL DatabaseAzure Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)

Внимание

Собственный клиент SQL Server (часто сокращенный SNAC) был удален из SQL Server 2022 (16.x) и SQL Server Management Studio 19 (SSMS). Поставщик OLE DB собственного клиента SQL Server (SQLNCLI или SQLNCLI11) и устаревший поставщик Microsoft OLE DB для SQL Server (SQLOLEDB) не рекомендуется для новой разработки. Перейдите на новый драйвер Microsoft OLE DB (MSOLEDBSQL) для SQL Server .

Создает привязку между переменными программы и столбцами 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 соответственно. Эта процедура копирует все пять столбцов. Для трех применяется заданный измененный формат, а для двух оставшихся — формат по умолчанию.

Заметка

Необходимо вызывать метод IBCPSession::BCPColumns перед любым вызовом метода BCPColFmt. Метод 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 или должны быть установлены в 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)
Выполнение операций массового копирования