bcp_colfmt
Указывает исходный или целевой формат данных в пользовательском файле. В случае исходного формата bcp_colfmt указывает формат существующего файла данных, используемого в качестве источника данных при массовом копировании в таблицу SQL Server. В случае целевого формата файл данных создается на основе форматов столбцов, указанных с помощью bcp_colfmt.
Синтаксис
RETCODE bcp_colfmt ( HDBC hdbc, INT idxUserDataCol, BYTE eUserDataType, INT cbIndicator, DBINT cbUserData, LPCBYTE pUserDataTerm, INT cbUserDataTerm, INT idxServerCol);
Arguments
hdbc
Дескриптор соединения ODBC с поддержкой массового копирования.idxUserDataCol
Порядковый номер столбца в пользовательском файле данных, для которого указывается формат. Первый столбец имеет номер 1.eUserDataType
Тип данных этого столбца в файле пользователя. Если тип данных отличается от типа соответствующего столбца в таблице базы данных (idxServerColumn), операция массового копирования преобразует данные, если это возможно.В SQL Server 2005 введена поддержка меток типа данных SQLXML и SQLUDT в параметре eUserDataType.
Параметр eUserDataType перечисляется метками типа данных SQL Server в sqlncli.h, а не в перечислителях типов данных ODBC C. Например, можно указать символьную строку SQL_C_CHAR типа ODBC с помощью специфического для SQL Server типа SQLCHARACTER.
Чтобы задать представление данных по умолчанию для типа данных SQL Server, установите этот параметр в значение 0.
Для массового копирования из SQL Server в файл, когда параметр eUserDataType имеет значение SQLDECIMAL или SQLNUMERIC:
Если тип исходного столбца отличается от decimal и numeric, то используются точность и масштаб по умолчанию.
Если исходный столбец имеет тип decimal или numeric, то используются точность и масштаб исходного столбца.
cbIndicator
Длина в байтах индикатора длины и допустимости значений NULL в данных столбца. Допускаются следующие значения длины индикатора: 0 (если индикатор не используется), 1, 2, 4 или 8.Чтобы задать для признака массового копирования использование по умолчанию, установите этот параметр в значение SQL_VARLEN_DATA.
Признаки располагаются в памяти непосредственно перед данными, а в файле данных — непосредственно перед данными, к которым они применяются.
Если для столбца файла данных используется несколько способов задания длины (например, признак и максимальная длина столбца или признак и последовательность-признак конца), то для массового копирования выбирается способ, применение которого вызовет копирование данных наименьшего объема.
Если пользователь не изменяет формат данных, то создаваемые при массовом копировании файлы данных содержат признаки, которые определяют, когда столбец может принимать значение NULL или его данные имеют переменную длину.
cbUserData
Максимальная длина в байтах данных в столбце пользовательского файла, не включая длину индикатора длины или терминатора.Если параметр cbUserData имеет значение SQL_NULL_DATA, это означает, что все значения в столбце файла данных равны или должны быть равны NULL.
Если параметр cbUserData имеет значение SQL_VARLEN_DATA, это означает, что система должна определить длину данных в каждом столбце. Для некоторых столбцов это может означать, что создаваемые признаки длины и допустимости значений NULL предваряют данные при копировании из SQL Server, или ожидается их наличие в данных, копируемых в SQL Server.
Для символьных и двоичных типов данных SQL Server параметр cbUserData может иметь значения SQL_VARLEN_DATA, SQL_NULL_DATA, 0 или другое положительное значение. Если параметр cbUserData имеет значение SQL_VARLEN_DATA, система использует для определения длины данных либо индикатор длины, если он есть, или последовательность-признак конца. Если задан и признак длины, и последовательность признака конца, то при массовом копировании используется значение, применение которого вызывает копирование данных наименьшего объема. Если параметр cbUserData имеет значение SQL_VARLEN_DATA, тип данных – символьный или двоичный тип SQL Server, и не указаны ни индикатор длины, ни последовательность признака конца, система возвращает сообщение об ошибке.
Если значение cbUserData больше или равно 0, то система рассматривает значение cbUserData как максимальную длину данных. Но если в дополнение к положительному значению для cbUserData указан признак длины или последовательность признака конца, то система определяет объем данных методом, который приведет к копированию наименьшего объема данных.
Значение cbUserData представляет объем данных в байтах. Если символьные данные представлены строкой знаков в Юникоде, то положительное значение параметра cbUserData представляет количество символов, умноженное на размер символа в байтах.
pUserDataTerm
Последовательность признака конца, используемая для этого столбца. Этот параметр предназначен главным образом для символьных типов данных, поскольку все другие типы имеют фиксированную длину или, как в случае с двоичными данными, требуют наличия признака длины, в котором записано точное число присутствующих байтов.Чтобы исключить обработку признака конца в извлекаемых данных или указать, что данные в файле пользователя не имеют признака конца, установите этот параметр в значение NULL.
Если для столбца файла пользователя используется несколько способов задания длины (например, признак конца и признак длины или признак конца и максимальная длина столбца), то для массового копирования выбирается способ, применение которого вызывает копирование данных наименьшего объема.
При необходимости API-интерфейс массового копирования выполнит преобразование символов из Юникода в многобайтовую кодировку (MBCS). Обратите особое внимание, правильно ли задана строка байтов, служащая признаком конца, а также ее длина.
cbUserDataTerm
Длина в байтах последовательности признака конца, используемой для этого столбца. Если в данных признак конца отсутствует или нежелателен, то установите это значение в 0.idxServerCol
Расположение по порядку столбца в таблице базы данных. Первый столбец имеет номер 1. Номер столбца по порядку сообщается функцией SQLColumns.Если значение равно 0, операция массового копирования игнорирует столбце в файле данных.
Возвращаемое значение
SUCCEED или FAIL.
Замечания
Функция bcp_colfmt позволяет указать формат пользовательского файла для массового копирования. Формат для массового копирования состоит из следующих частей:
сопоставление столбцов файла пользователя со столбцами базы данных;
тип данных каждого столбца в файле пользователя;
длина дополнительного признака для каждого столбца;
максимальная длина данных в каждом столбце файла пользователя;
дополнительная последовательность байт, служащая признаком конца для каждого столбца;
длина дополнительной последовательности байт, служащей признаком конца.
Каждый вызов функции bcp_colfmt определяет формат одного столбца в пользовательском файле. Например, чтобы изменить значение по умолчанию для трех столбцов в пользовательском файле данных, содержащем пять столбцов, сначала вызовите bcp_columns(5), а затем вызовите bcp_colfmt пять раз, при трех из этих вызовов указывая пользовательский формат. При остальных двух вызовах установите для eUserDataType значение 0, а для cbIndicator, cbUserData и cbUserDataTerm значения 0, SQL_VARLEN_DATA и 0 соответственно. Эта процедура копирует все пять столбцов. Для трех применяется заданный измененный формат, а для двух оставшихся — формат по умолчанию.
Для параметра cbIndicator не допускается значение 8, указывающее тип больших значений. Если для для поля, которому соответствует столбец с новым максимальным типом, указан префикс, его значение может быть равным только 8. Дополнительные сведения см. в разделе bcp_bind.
Прежде чем вызывать функцию bcp_colfmt, необходимо сначала вызвать функцию bcp_columns.
Функцию bcp_colfmt необходимо вызывать один раз для каждого столбца в пользовательском файле.
При вызове функции bcp_colfmt более одного раза для одного столбца пользовательского файла возникает ошибка.
Нет необходимости копировать все данные из пользовательского файла в таблицу SQL Server. Чтобы пропустить столбец, укажите формат данных для столбца, задав для параметра idxServerCol значение 0. Если нужно пропустить столбец, необходимо указать его тип.
Для сохранения спецификации формата можно воспользоваться функцией bcp_writefmt.
Поддержка функции bcp_colfmt для усовершенствованных функций даты и времени
Дополнительные сведения о типах, используемых в параметре eUserDataType для типов данных даты и времени, см. в разделе Изменения в функции массового копирования для работы с улучшенными типами даты-времени (OLE DB и ODBC).
Дополнительные сведения см. в разделе Улучшенная обработка даты и времени (ODBC).