bcp_setcolfmt

Статья
05/07/2013

Функция bcp_setcolfmt заменяет функцию bcp_colfmt. При указании параметров сортировки столбца необходимо использовать функцию bcp_setcolfmt. С помощью bcp_setbulkmode можно задать формат нескольких столбцов.

Эта функция предоставляет гибкий подход к указанию формата столбцов в операции массового копирования. Она используется для установки атрибутов формата отдельного столбца. Каждый вызов функции bcp_setcolfmt устанавливает один атрибут формата столбца.

Функция bcp_setcolfmt указывает формат источника или целевой формат данных в пользовательском файле. При использовании с форматом источника функция bcp_setcolfmt указывает формат существующего файла данных, используемого как источник данных при массовом копировании в таблицу SQL Server. При использовании с целевым форматом создается файл данных с использованием форматов столбцов, указанных при помощи функции bcp_setcolfmt.

Синтаксис

RETCODE bcp_setcolfmt ( 
        HDBC hdbc, 
        INT field, 
        INT property, 
        void* pValue, 
        INT cbValue);

Аргументы

hdbc
Дескриптор соединения ODBC с поддержкой массового копирования.
поле
Это порядковый номер столбца, для которого устанавливается значение свойства.

свойство
Одна из констант свойства. В данной таблице определены константы свойства.

Свойство	Значение	Описание
BCP_FMT_TYPE	BYTE	Тип данных этого столбца в файле пользователя. При отличии от типа данных соответствующего столбца в таблице базы данных массовое копирование преобразует данные, если это возможно. Параметр BCP_FMT_TYPE перечисляется в токенах типов данных SQL Server в файле sqlncli.h, а не в перечислении типов данных ODBC C. Например, можно указать символьную строку типа SQL_C_CHAR ODBC при помощи типа SQLCHARACTER в SQL Server. Чтобы задать представление данных по умолчанию для типа данных SQL Server, установите этот параметр в значение 0. Для массового копирования из SQL Server в файл при BCP_FMT_TYPE, равном SQLDECIMAL или SQLNUMERIC: Если тип исходного столбца отличается от decimal и numeric, то используются точность и масштаб по умолчанию. Если исходный столбец имеет тип decimal или numeric, то используются точность и масштаб исходного столбца.
BCP_FMT_INDICATOR_LEN	INT	Задает длину признака (префикса) в байтах. Задает длину в байтах для признака длины или признака NULL в данных столбца. Допустимыми значениями длины признака являются 0 (если признак не используется), 1, 2 и 4. Чтобы задать для признака массового копирования использование по умолчанию, установите этот параметр в значение SQL_VARLEN_DATA. Признаки располагаются в памяти непосредственно перед данными, а в файле данных — непосредственно перед данными, к которым они применяются. Если для столбца файла данных используется несколько способов задания длины (например, признак и максимальная длина столбца или признак и последовательность-признак конца), то для массового копирования выбирается способ, применение которого вызовет копирование данных наименьшего объема. Если пользователь не изменяет формат данных, то создаваемые при массовом копировании файлы данных содержат признаки, которые определяют, когда столбец может принимать значение NULL или его данные имеют переменную длину.
BCP_FMT_DATA_LEN	DBINT	Задает длину данных (длину столбца) в байтах. Задает максимальную длину в байтах данных столбца в файле пользователя, не включая длину индикатора длины и признака конца. Установка для BCP_FMT_DATA_LEN значения SQL_NULL_DATA показывает, что для всех значений в столбце файла данных установлены или должны быть установлены значения NULL. Установка для BCP_FMT_DATA_LEN значения SQL_VARLEN_DATA показывает, что система должна определить длину данных для каждого столбца. Для некоторых столбцов это может означать, что создаваемые признаки длины и допустимости значений NULL предваряют данные при копировании из SQL Server, или ожидается их наличие в данных, копируемых в SQL Server. Для символьного и двоичного типов данных SQL Server значение BCP_FMT_DATA_LEN может быть равным SQL_VARLEN_DATA, SQL_NULL_DATA, 0 или любому положительному числу. Если значение BCP_FMT_DATA_LEN равно SQL_VARLEN_DATA, система использует либо признак длины при его наличии, либо признак конца для определения длины данных. Если задан и признак длины, и последовательность признака конца, то при массовом копировании используется значение, применение которого вызывает копирование данных наименьшего объема. Если значение BCP_FMT_DATA_LEN равно SQL_VARLEN_DATA, то тип данных представляет собой символьный или двоичный тип SQL Server, а если при этом ни признак длины, ни признака конца не указаны, то система возвращает сообщение об ошибке. Если значение BCP_FMT_DATA_LEN равно 0 или положительному числу, система использует значение BCP_FMT_DATA_LEN в качестве максимальной длины данных. Однако, если кроме того, что значение BCP_FMT_DATA_LEN является положительным числом, указан признак длины или признак конца, то система определяет длину данных при помощи метода, который вычисляет наименьший размер копируемых данных. Значение BCP_FMT_DATA_LEN показывает количество байтов данных. Если символьные данные представлены широкими символами Юникода, положительное значение параметра BCP_FMT_DATA_LEN обозначает число символов, умноженное на размер в байтах каждого символа.
BCP_FMT_TERMINATOR	LPCBYTE	Для этого столбца должен использоваться указатель на признак конца (соответственно ANSI или Юникода). Этот параметр предназначен главным образом для символьных типов данных, поскольку все другие типы имеют фиксированную длину или, как в случае с двоичными данными, требуют наличия признака длины, в котором записано точное число присутствующих байтов. Чтобы исключить обработку признака конца в извлекаемых данных или указать, что данные в файле пользователя не имеют признака конца, установите этот параметр в значение NULL. Если для столбца файла пользователя используется несколько способов задания длины (например, признак конца и признак длины или признак конца и максимальная длина столбца), то для массового копирования выбирается способ, применение которого вызывает копирование данных наименьшего объема. При необходимости API-интерфейс массового копирования выполнит преобразование символов из Юникода в многобайтовую кодировку (MBCS). Обратите особое внимание, правильно ли задана строка байтов, служащая признаком конца, а также ее длина.
BCP_FMT_SERVER_COL	INT	Порядковый номер столбца в базе данных
BCP_FMT_COLLATION	LPCSTR	Имя параметров сортировки.

pValue
Является указателем на значение, связанное со свойством. Это позволяет установить отдельно каждое свойство формата столбца.
cbvalue
Длина буфера свойств, в байтах.

Возвращаемое значение

SUCCEED или FAIL.

Замечания

Эта функция заменяет функцию bcp_colfmt. Вся функциональность bcp_colfmt реализована в функции bcp_setcolfmt. Дополнительно реализована поддержка параметров сортировки столбца. Рекомендуется устанавливать следующие атрибуты формата столбца в данной последовательности:

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

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

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

Каждый вызов функции bcp_setcolfmt устанавливает формат для одного столбца пользовательского файла. Например, для изменения параметров по умолчанию для трех столбцов в пользовательском файле данных с пятью столбцами необходимо сначала вызвать функцию bcp_columns(5), а затем пять раз вызвать функцию bcp_setcolfmt, при этом три из этих вызовов должны устанавливать пользовательский формат. Для оставшихся двух вызовов необходимо установить для BCP_FMT_TYPE значение 0, а также установить для BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN и cbValue значения 0, SQL_VARLEN_DATA и 0 соответственно. Эта процедура копирует все пять столбцов. Для трех применяется заданный измененный формат, а для двух оставшихся — формат по умолчанию.

Функция bcp_columns должна быть вызвана перед вызовом функции bcp_setcolfmt.

Необходимо вызвать функцию bcp_setcolfmt один раз для каждого свойства каждого столбца пользовательского файла.

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

Для сохранения спецификации формата можно воспользоваться функцией bcp_writefmt.