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

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 будет иметь адрес объявленного экземпляра структуры, адрес элемента структуры BCPBOUNDINT iIndicator . Параметр cbIndicator будет иметь размер целого числа (sizeof(int)), а параметр cbData снова будет иметь размер целочисленного числа (sizeof(int)). Чтобы массового копирования строки на сервер, содержащий значение NULL для связанного столбца, необходимо задать значение SQL_NULL_DATA для элемента iIndicator экземпляра.

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 можно использовать пустую строку (""). Поскольку пустая строка, завершающаяся значением NULL, представляет собой один байт (сам байт конца), задайте для cbTerm значение 1. Например, чтобы указать, что строка в szName завершается значением NULL, а для указания длины следует использовать терминатор:

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

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

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

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

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, используя SQLINT2 конкретного типа SQL Server.

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

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

Возвраты

SUCCEED или FAIL.

Замечания

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

Вызовите bcp_init перед вызовом этой или любой другой функции массового копирования. Вызов bcp_init задает целевую таблицу SQL Server для массового копирования. При вызове bcp_init для использования с bcp_bind и bcp_sendrow параметр bcp_init szDataFile, указывающий на файл данных, имеет значение NULL; параметр bcp_init eDirection имеет значение 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 .

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

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

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

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

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

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

  • <><SPECIAL_PREFIX 0 или более блоков DATA CHUNKS><ZERO_CHUNK>, где:

  • СПЕЦИАЛЬНЫЙ_ПРЕФИКС имеет значение 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);

См. также

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