• Статья

bcp_control

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

Синтаксис

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

Аргументы

  • dbc
    Дескриптор соединения ODBC с поддержкой массового копирования.

  • eOption
    Принимает одно из следующих значений.

  • BCPABORT
    Останавливает текущую операцию массового копирования. Вызовите функцию bcp_control с параметром eOption значения BCPABORT из другого потока, чтобы остановить выполняющуюся операцию массового копирования. Параметр iValue не учитывается.

  • BCPBATCH
    Число строк в пакете. Значение по умолчанию — 0, что указывает либо все строки в таблице при извлечении данных, либо все строки в пользовательском файле данных, когда данные копируются в SQL Server. Если задать для этого параметра значение меньше 1, то значению BCPBATCH будет установлено значение по умолчанию.

  • 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). Значение по умолчанию — 100. Это может оказаться полезным при экспорте или импорте данных в форматах, которые поддерживались прежними версиями сервера. Например, чтобы импортировать данные, полученные из текстового столбца на сервере 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);

См. также

Справочник

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