bcp_setcolfmt

Статья
01/10/2024

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

Функция 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 с поддержкой массового копирования.

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

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

Свойство	Значение	Описание
BCP_FMT_TYPE	BYTE	Тип данных этого столбца в файле пользователя. При отличии от типа данных соответствующего столбца в таблице базы данных массовое копирование преобразует данные, если это возможно. Параметр BCP_FMT_TYPE перечисляется в токенах типов данных SQL Server в файле sqlncli.h, а не в перечислении типов данных ODBC C. Например, можно указать символьную строку, тип ODBC SQL_C_CHAR, используя тип SQLCHARACTER, относящийся к SQL Server. Чтобы указать представление данных по умолчанию для типа данных SQL Server, задайте для этого параметра значение 0. Для массового копирования из SQL Server в файл, если BCP_FMT_TYPE имеет значение SQLDECIMAL или SQLNUMERIC, если исходный столбец не является десятичным или числовым, используются точность и масштаб по умолчанию. В противном случае, если исходный столбец является десятичным или числовым, используется точность и масштаб исходного столбца.
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 .

Поддержка функции bcp_setcolfmt для улучшенной даты и функций времени

Типы, используемые со свойством BCP_FMT_TYPE для типов даты и времени, указаны в разделе Изменения массового копирования для расширенных типов даты и времени (OLE DB и ODBC).

Дополнительные сведения см. в разделе Улучшения даты и времени (ODBC).

См. также:

Bulk Copy Functions

Share via