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

bcp_bind

  • Статья

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

Синтаксис

RETCODE bcp_bind ( 
        HDBC hdbc,  
        LPCBYTE pData, 
        INT cbIndicator, 
        DBINT cbData, 
        LPCBYTE pTerm, 
        INT cbTerm, 
        INT eDataType, 
        INT idxServerCol);

Аргументы

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

  • pData
    Указатель на копируемые данные. Если типом аргумента eDataType является SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR или SQLIMAGE, аргумент pData может иметь значение NULL. Значение NULL аргумента pData указывает, что данные большого размера будут отправляться в SQL Server частями с помощью функции bcp_moretext. Присвоить аргументу pData значение NULL можно только в случае, если столбец, соответствующий связанному полю, имеет тип BLOB, иначе функция bcp_bind завершится ошибкой.

    Если в данных присутствуют признаки, они размещаются в памяти непосредственно перед данными. Параметр pData в этом случае указывает на переменную признака, и ширина признака, параметр cbIndicator, используется массовым копированием для правильной адресации пользовательских данных.

  • cbIndicator
    Ширина индикатора в байтах или значение NULL для данных столбца. Допускаются следующие значения длины признака: 0 (если признак не используется), 1, 2, 4 или 8. Признаки размещаются в памяти непосредственно перед данными. Например, следующее определение типа структуры можно использовать для вставки целочисленных значений в таблицу SQL Server с помощью массового копирования:

    typedef struct tagBCPBOUNDINT
    {
    int iIndicator;
    int Value;
    } BCPBOUNDINT;

    В этом примере параметр pData будет иметь значение адреса объявленного экземпляра структуры, адреса элемента iIndicator структуры BCPBOUNDINT. Параметр cbIndicator будет иметь значение размера типа integer (sizeof(int)), параметр cbData также будет иметь значение размера типа integer (sizeof(int)). Чтобы выполнить массовое копирование строки на сервер, содержащий значение NULL для связанного столбца, значение элемента iIndicator экземпляра должно быть равным SQL_NULL_DATA.

  • cbData
    Количество байт данных в программной переменной, исключая любую длину, NULL-индикатор или признак конца.

    Присвоение параметру cbData значения SQL_NULL_DATA означает, что все строки копируются на сервер, содержащий значение NULL для столбца.

    Присвоение параметру cbData значения SQL_VARLEN_DATA указывает, что система должна использовать строковый признак конца или другой метод для определения длины копируемых данных.

    Для типов данных фиксированной длины, например для целых чисел, система определяет длину данных на основе типа. Поэтому для типов данных фиксированной длины параметр cbData может иметь значение SQL_VARLEN_DATA или значение длины данных.

    Для символьных и двоичных типов данных SQL Server параметр cbData может принимать значение SQL_VARLEN_DATA, SQL_NULL_DATA, любое положительное значение или 0. Если значение параметра cbData равно SQL_VARLEN_DATA, для определения длины данных система использует индикатор длины, NULL-индикатор (если таковой имеется) либо последовательность признаков конца. Если представлено и то, и другое, система использует то значение, которое приводит к наименьшему объему копируемых данных. Если параметр cbData равен SQL_VARLEN_DATA, столбец имеет символьный или двоичный тип SQL Server и не задан ни индикатор длины, ни последовательность признака конца, система возвращает сообщение об ошибке.

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

    Параметр cbData представляет количество данных в байтах. Если символьные данные представлены строкой знаков в Юникоде, то положительное значение параметра cbData представляет количество символов, умноженное на размер символа в байтах.

  • pTerm
    Указатель на байтовый шаблон, если таковой имеется, являющийся признаком конца программной переменной. Например, строки ANSI и MBCS C обычно имеют 1-байтовый признаки конца строки (\0).

    Если признак конца переменной отсутствует, присвойте параметру pTerm значение NULL.

    Для обозначения символа конца строки в качестве признака конца программной переменной в языке C можно использовать пустую строку (""). Поскольку длина пустой строки, оканчивающейся нулевым байтом, составляет один байт (байт признака конца строки), присвойте параметру cbTerm значение 1. Например, в следующем коде указывается, что строка szName оканчивается нулевым байтом, а для указания длины строки используется признак конца строки:

    bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, "", 1,
   SQLCHARACTER, 2)

    Вариант этого примера, не заканчивающийся нулевым символом, может указывать, что из переменной szName должны копироваться 15 символов во второй столбец связанной таблицы:

    bcp_bind(hdbc, szName, 0, 15, 
   NULL, 0, SQLCHARACTER, 2)

    При необходимости API-интерфейс массового копирования выполнит преобразование символов из Юникода в многобайтовую кодировку (MBCS). Убедитесь, что правильно задана строка байтов признака конца и количество байт в строке. Например, в следующем коде указано, что строка szName содержит расширенные символы Юникода и заканчивается значением нулевого символа Юникода:

    bcp_bind(hdbc, szName, 0, 
   SQL_VARLEN_DATA, L"",
   sizeof(WCHAR), SQLNCHAR, 2)

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

  • cbTerm
    Количество байт в признаке конца программной переменной, если такой имеется. Если признак конца переменной отсутствует, присвойте параметру cbTerm значение 0.

  • eDataType
    Тип данных языка C для программной переменной. Данные в программной переменной преобразуются в тип столбца базы данных. Если этот параметр равен 0, преобразование не выполняется.

    Параметр eDataType перечисляется токенами типов данных SQL Server в файле sqlncli.h, а не перечислителями ODBC типа данных C. Например, можно задать целое двухбайтовое значение ODBC типа SQL_C_SHORT с помощью типа SQL Server SQLINT2.

    В SQL Server 2005 в параметре eDataType была введена поддержка токенов типов данных SQLXML и SQLUDT.

  • idxServerCol
    Порядковый номер столбца в таблице базы данных, в которую копируются данные. Первый столбец в таблице имеет порядковый номер 1. Порядковый номер столбца возвращается функцией SQLColumns.

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

SUCCEED или FAIL.

Замечания

Для быстрого эффективного копирования данных из программной переменной в таблицу SQL Server используется функция bcp_bind.

Функция bcp_init вызывается перед вызовом этой или любой другой функции массового копирования. Вызов функции bcp_init определяет целевую таблицу SQL Server для массового копирования. При вызове функции bcp_init с функциями bcp_bind и bcp_sendrow параметру szDataFile функции bcp_init, задающему файл данных, присваивается значение NULL, а параметру eDirection — значение DB_IN.

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

Если нужно, чтобы SQL Server зафиксировал уже полученные строки, вызовите функцию bcp_batch. Например, вызывайте функцию bcp_batch для каждых 1 000 вставленных строк или через любой другой интервал.

Когда строк для вставки больше не останется, вызовите функцию bcp_done. Несоблюдение этого правила приведет к ошибке.

Настройки параметров управления, заданные функцией bcp_control, не влияют на передачу строк функцией bcp_bind.

Если параметр pData для столбца имеет значение NULL, поскольку его значение будет предоставлено вызовами функции bcp_moretext, любой последующий столбец со значением параметра eDataType SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR или SQLIMAGE должен быть также связан с параметром pData, имеющим значение NULL, а их значения должны быть тоже предоставлены с помощью функции bcp_moretext.

Для новых типов больших значений, таких как varchar(max), varbinary(max) и nvarchar(max), в качестве индикаторов типа в параметре eDataType можно использовать значения SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY и SQLNCHAR.

Если параметр cbTerm не равен 0, для префикса (cbIndicator) допускается любое значение (1, 2, 4, or 8). В этой ситуации собственный клиент SQL Server будет искать признак конца, вычислять его длину данных (i) и присваивать параметру cbData наименьшее значение i и префикса.

Если параметр cbTerm равен 0, а cbIndicator (префикс) не равен 0, значение cbIndicator должно быть равным 8. Восьмибайтовый префикс может принимать следующие значения.

  • 0xFFFFFFFFFFFFFFFF означает значение NULL для поля.

  • 0xFFFFFFFFFFFFFFFE рассматривается как специальное значение префикса, которое используется для эффективной отправки на сервер данных, разбитых на фрагменты. Данные со специальным префиксом имеют следующий формат.

  • <СПЕЦИАЛЬНЫЙ_ПРЕФИКС> <0 или больше ФРАГМЕНТОВ_ДАННЫХ> <НУЛЕВОЙ_ФРАГМЕНТ>, где:

  • СПЕЦИАЛЬНЫЙ_ПРЕФИКС имеет значение 0xFFFFFFFFFFFFFFFE.

  • ФРАГМЕНТ_ДАННЫХ является 4-байтовым префиксом, содержащим длину фрагмента, за которым следуют фактические данные, длина которых задана 4-байтовым префиксом.

  • НУЛЕВОЙ_ФРАГМЕНТ является 4-байтовым значением, содержащим все нули (00000000), которое указывает конец данных.

  • Любая другая 8-байтовая длина рассматривается как длина обычных данных.

Вызов функции bcp_columns при использовании функции bcp_bind приводит к ошибке.

Поддержка функцией bcp_bind улучшенных возможностей даты и времени

Сведения о типах, используемых в параметре eDataType для даты и времени см. в разделе Изменения в функции массового копирования для работы с улучшенными типами даты-времени (OLE DB и ODBC).

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

Пример

#include sql.h
#include sqlext.h
#include odbcss.h
// Variables like henv not specified.
HDBC      hdbc;
char         szCompanyName[MAXNAME];
DBINT      idCompany;
DBINT      nRowsProcessed;
DBBOOL      bMoreData;
char*      pTerm = "\t\t";

// 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 bcp. 
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL
   DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Bind program variables to table columns. 
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,
   SQLINT4, 1)    == FAIL)
   {
   // Raise error and return.
   return;
   }
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)
   {
   // Raise error and return.
   return;
   }

while (TRUE)
   {
   // Retrieve and process program data. 
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)
      {
      // Send the data. 
      if (bcp_sendrow(hdbc) == FAIL)
         {
         // Raise error and return.
         return;
         }
      }
   else
      {
      // Break out of loop.
      break;
      }
   }

// Terminate the bulk copy operation.
if ((nRowsProcessed = bcp_done(hdbc)) == -1)
   {
   printf_s("Bulk-copy unsuccessful.\n");
   return;
   }

printf_s("%ld rows copied.\n", nRowsProcessed);

См. также

Справочник

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