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

  • Статья

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 будет иметь целочисленное значение размера (sizeof(int)), а параметр cbData– то же значение размера (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 была введена поддержка маркеров типов данных SQLXML и SQLUDT в параметре eDataType.

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

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

SUCCEED или FAIL.

Замечания

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

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

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

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

Когда строк для вставки больше не останется, вызовите функцию 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), можно использовать SQLCHARACTER,SQLVARCHAR,SQLVARBINARY,SQLBINARY и SQLNCHAR в качестве индикаторов типа в параметре eDataType.

Если параметр 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);

См. также

Справочник

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