bcp_bind

Статья
01/10/2024

Применимо: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure azure Synapse Analytics Analytics Platform System (PDW)

Привязывает данные из переменной программы к столбцу таблицы для массового копирования в 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 (9.x) представил поддержку маркеров типа данных SQLXML и SQLUDT в параметре eDataType .

В приведенной ниже таблице перечислены допустимые перечисляемые типы данных и соответствующие типы данных C в ODBC.

eDataType	Тип C
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	INT
SQLINT8	_int64
SQLINTN	cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8
SQLFLT4	с плавающей запятой
SQLFLT8	с плавающей запятой
SQLFLTN	cbIndicator 4: SQLFLT4 8: SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4: SQLMONEY4 8: SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4: SQLDATETIM4 8: SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	Любой тип данных, кроме следующих: — text — ntext — image — varchar(max) — varbinary(max) — nvarchar(max) — xml — timestamp
SQLXML	Поддерживаемые типы данных C: — char * — wchar_t * — unsigned char *

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, SQLXTEXT, SQLXML, SQLUDT, SQLCHARER, SQLVARCHAR, 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. Префикс 8-байтов может принимать следующие значения:

0xFFFFFFFFFFFFFFFF означает значение NULL для поля.
0xFFFFFFFFFFFFFFFE рассматривается как специальное значение префикса, которое используется для эффективной отправки данных на сервер. Данные со специальным префиксом имеют следующий формат.
<><SPECIAL_PREFIX 0 или более блоков DATA CHUNKS><ZERO_CHUNK>, где:
СПЕЦИАЛЬНЫЙ_ПРЕФИКС имеет значение 0xFFFFFFFFFFFFFFFE.
DATA_CHUNK — это префикс 4-байтов, содержащий длину блока, а затем фактические данные, длина которых указана в префиксе 4-байтов.
ZERO_CHUNK — это 4-байтовое значение, содержащее все нули (000000000), указывающее конец данных.
Любая другая допустимая длина 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);

См. также

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

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