bcp_control

Статья
05/07/2013

Изменяет значения по умолчанию различных параметров управления для массового копирования между файлом и SQL Server.

Синтаксис

RETCODE bcp_control ( 
        HDBC hdbc, 
        INT eOption, 
        void* iValue);

Аргументы

hdbc
Дескриптор соединения ODBC с поддержкой массового копирования.
eOption
Принимает одно из следующих значений.
BCPABORT
Останавливает текущую операцию массового копирования. Вызовите функцию bcp_control с параметром eOption значения BCPABORT из другого потока, чтобы остановить выполняющуюся операцию массового копирования. Параметр iValue не учитывается.
BCPBATCH
Число строк в пакете. Значение по умолчанию — 0, что указывает либо все строки в таблице при извлечении данных, либо все строки в пользовательском файле данных, когда данные копируются в SQL Server. Если задать для этого параметра значение меньше 1, то значению BCPBATCH будет установлено значение по умолчанию.
BCPDELAYREADFMT
Логическое значение. Если оно имеет значение true, то bcp_readfmt будет читаться при выполнении. При значении false (по умолчанию) bcp_readfmt производит немедленное считывание файла форматирования. Если параметру BCPDELAYREADFMT задано значение true и вызывается bcp_columns или bcp_setcolfmt, то возникнет ошибка последовательности.

Ошибка последовательности также возникнет при вызове bcp_control(hdbc, BCPDELAYREADFMT, (void *)FALSE) после вызова bcp_control(hdbc, BCPDELAYREADFMT, (void *)TRUE) и bcp_writefmt.

Дополнительные сведения см. в разделе Обнаружение метаданных.
BCPFILECP
Параметр iValue содержит номер кодовой страницы для файла данных. Можно указать номер кодовой страницы, например 1252 или 850, либо одно из следующих значений.

BCPFILE_ACP: данные в файле имеют кодовую страницу Microsoft Windows® клиента.

BCPFILE_OEMCP: данные в файле имеют кодовую страницу OEM клиента (по умолчанию).

BCPFILE_RAW: данные в файле имеют кодовую страницу SQL Server.
BCPFILEFMT
Номер версии для формата файла данных. Может иметь значение 80 (SQL Server 2000), 90 (SQL Server 2005), 100 (SQL Server 2008 или SQL Server 2008 R2) или 110 (SQL Server 2012). 110 используется по умолчанию. Это может оказаться полезным при экспорте или импорте данных в форматах, которые поддерживались прежними версиями сервера. Например, чтобы импортировать данные, полученные из текстового столбца на сервере SQL Server 2000, в столбец типа varchar(max) на сервере SQL Server 2005 или более поздней версии, следует указать значение 80. Аналогично при указании значения 80 при экспорте данных из столбца типа varchar(max) данные столбца сохраняются точно так же, как сохраняются текстовые столбцы в формате SQL Server 2000, и их можно импортировать в текстовый столбец сервера SQL Server 2000.
BCPFIRST
Первая строка данных, копируемых в файл или таблицу. Значение по умолчанию равно 1. Если задать для этого параметра значение меньше 1, то будет установлено значение по умолчанию.
BCPFIRSTEX
В операциях bcp out задает первую строку таблицы базы данных для копирования в файл данных.

В операциях bcp in задает первую строку файла данных для копирования в таблицу базы данных.

Предполагается, что параметр iValue представляет собой адрес 64-разрядного целого числа со знаком, содержащего значение. Максимальное значение, передаваемое в BCPFIRSTEX, составляет 2^63-1.

BCPFMTXML
Указывает, что формируемый файл форматирования должен быть в формате XML. По умолчанию эта настройка отключена.

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

Примечание
XML-файлы форматирования поддерживаются только при установке SQL Server вместе с собственным клиентом SQL Server.

BCPHINTS
Параметр iValue содержит указатель символьной строки SQLTCHAR. Адресуемая строка задает указания для обработки массового копирования SQL Server или инструкцию Transact-SQL, которая возвращает результирующий набор. Если задана инструкция Transact-SQL, которая возвращает несколько результирующих наборов, все результирующие наборы после первого пропускаются. Дополнительные сведения по указаниям для обработки массового копирования см. в разделе Программа bcp.
BCPKEEPIDENTITY
Когда параметр iValue установлен в значение TRUE, это указывает, что функции массового копирования будут вставлять значения данных, приведенные в столбцах SQL Server (которые определены при помощи ограничения IDENTITY). Входной файл должен содержать значения для столбцов идентификаторов. Если эти значения не заданы, то для вставляемых строк создаются новые значения идентификаторов. Данные в файле, предназначенные для столбцов идентификаторов, не учитываются.
BCPKEEPNULLS
Указывает, будут ли пустые значения данных в файле преобразовываться в значения NULL в таблице SQL Server. Когда параметр iValue установлен в значение TRUE, в таблице SQL Server пустые значение будут преобразованы в значение NULL. По умолчанию пустые значения преобразовываются в значения по умолчанию для столбца в таблице SQL Server, если значение по умолчанию существует.
BCPLAST
Последняя строка для копирования. По умолчанию установлено копирование всех строк; если задать для этого параметра значение меньше 1, то ему будет установлено значение по умолчанию.
BCPLASTEX
В операциях bcp out задает последнюю строку таблицы базы данных для копирования в файл данных.

В операциях bcp in задает последнюю строку файла данных для копирования в таблицу базы данных.

Предполагается, что параметр iValue представляет собой адрес 64-разрядного целого числа со знаком, содержащего значение. Максимальное значение, передаваемое в BCPLASTEX, составляет 2^63-1.
BCPMAXERRS
Число ошибок, после которого произойдет сбой операции массового копирования. Значение по умолчанию равно 10. Если задать для этого параметра значение меньше 1, то будет установлено значение по умолчанию. В операции массового копирования допускается не более 65 535 ошибок. Если выполнить попытку установить этот параметр в значение, превышающее 65 535, будет установлено значение 65 535.
BCPODBC
Значение TRUE указывает, что значения datetime и smalldatetime, сохраненные в символьном формате, будут использовать префикс и суффикс escape-последовательности отметок времени ODBC. Параметр BCPODBC применяется только к BCP_OUT.

В значении FALSE значение datetime, представляющее 1 января 1997 года, преобразуется в символьную строку: 1997-01-01 00:00:00.000. В значении TRUE это же значение datetime представлено в виде: {ts '1997-01-01 00:00:00.000'}.
BCPROWCOUNT
Возвращает число строк, на которые распространяется действие текущей (или последней) операции bcp.
BCPTEXTFILE
Значение TRUE указывает, что файл данных является текстовым, а не двоичным файлом. Если файл является текстовым, BCP определяет, является ли его кодировка кодировкой Юникод, путем проверки байтового маркера Юникода в первых двух байтах файла данных.
BCPUNICODEFILE
В значении TRUE указывает, что входной файл является файлом в кодировке Юникод.
iValue
Значение для указанного параметра eOption. iValue является целым значением (LONGLONG), приведенным к пустому указателю, чтобы обеспечить возможность расширения до 64-разрядных значений в будущем.

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

SUCCEED или FAIL.

Замечания

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

Эта функция также используется для указания инструкции SELECT при массовом копировании результирующего набора инструкции SELECT из SQL Server. Задайте параметру eOption значение BCPHINTS, а параметру iValue задайте указатель на строку SQLTCHAR, содержащую инструкцию SELECT.

Эти параметры управления имеют значение только при копировании между пользовательским файлом и таблицей SQL Server. Параметры управления никак не влияют на строки, копируемые в SQL Server функцией bcp_sendrow.

Пример

// Variables like henv not specified.
SQLHDBC      hdbc;
DBINT      nRowsProcessed;
 
// Application initiation, get an ODBC environment handle, allocate the
// hdbc, and so on.
... 

// Enable bulk copy prior to connecting on allocated hdbc.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,
   SQL_IS_INTEGER);

// Connect to the data source, return on error.
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,
   _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))
   {
   // Raise error and return.
   return;
   }

// Initialize bulk copy. 
if (bcp_init(hdbc, _T("address"), _T("address.add"), _T("addr.err"),
   DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set the number of rows per batch. 
if (bcp_control(hdbc, BCPBATCH, (void*) 1000) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set file column count. 
if (bcp_columns(hdbc, 1) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Set the file format. 
if (bcp_colfmt(hdbc, 1, 0, 0, SQL_VARLEN_DATA, '\n', 1, 1)
   == FAIL)
   {
   // Raise error and return.
   return;
   }

// Execute the bulk copy. 
if (bcp_exec(hdbc, &nRowsProcessed) == FAIL)
   {
   // Raise error and return.
   return;
   }

printf_s("%ld rows processed by bulk copy.", nRowsProcessed);

См. также

Справочник

Функции массового копирования

Поделиться через