bcp_moretext

Статья
05/07/2013

Отправляет в SQL Server часть значения длинного типа данных переменной длины.

Синтаксис

RETCODE bcp_moretext ( 
        HDBC hdbc, 
        DBINT cbData, 
        LPCBYTE pData);

Аргументы

hdbc
Дескриптор соединения ODBC с поддержкой массового копирования.
cbData
Представляет собой число байтов данных, копируемых в SQL Server из данных, на которые указывает pData. Значение SQL_NULL_DATA соответствует значению NULL.
pData
Представляет собой указатель на ту часть значения поддерживаемого длинного типа данных переменной длины, которую нужно переслать в SQL Server.

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

SUCCEED или FAIL.

Замечания

Эту функцию можно использовать совместно с функциями bcp_bind и bcp_sendrow для копирования значений длинного типа данных переменной длины на SQL Server в виде фрагментов меньшего размера. Функцию bcp_moretext можно использовать со столбцами следующих типов данных SQL Server: text, ntext, image, varchar(max), nvarchar(max), varbinary(max), определяемых пользователем типов (UDT) и XML. Функция bcp_moretext не поддерживает преобразование данных, поэтому тип передаваемых данных должен соответствовать типу столбца назначения.

Если функция bcp_bind вызывается с отличным от NULL параметром pData применительно к типам данных, поддерживаемых функцией bcp_moretext, то функция bcp_sendrow пересылает все значение целиком, независимо от его длины. Но если функция bcp_bind имеет отличный от NULL параметр pData применительно к поддерживаемым типам данных, то функцию bcp_moretext можно использовать для копирования данных непосредственно после успешного возврата из функции bcp_sendrow, указывающего на то, что все привязанные столбцы, в которых есть данные, обработаны успешно.

Если функция bcp_moretext используется в строке для передачи одного столбца с поддерживаемым типом данных, то в этой строке с помощью той же функции должны быть переданы все остальные столбцы с поддерживаемым типом данных. Ни один столбец не может быть пропущен. Поддерживаемыми типами данных являются SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT и SQLXML. То же относится к типам данных SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY и SQLVARBINARY, если столбец имеет тип varchar(max), nvarchar(max) или varbinary(max) соответственно.

Вызов любой из двух функций bcp_bind или bcp_collen задает общую длину всех фрагментов данных, подлежащих копированию в столбец SQL Server. Попытка передать в SQL Server большее количество байтов, чем указано в вызове функции bcp_bind или bcp_collen, приводит к возникновению ошибки. Например, ошибка возникает, если в приложении после использования функции bcp_collen для задания длины допустимых данных в столбце SQL Server типа text, равной 4500, происходит пятикратный вызов функции bcp_moretext, причем каждый раз с указанием длины буфера данных, равной 1000.

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

Когда значения var(max) передаются на сервер с помощью функций bcp_sendrow и bcp_moretext, необязательно вызывать функцию bcp_collen для задания длины столбца. Вместо этого (только для указанных типов) значение завершается вызовом bcp_sendrow с длиной, равной нулю.

Обычно в приложениях функции bcp_sendrow и bcp_moretext вызываются в циклах для пересылки нескольких строк данных. Далее показан пример для таблицы, содержащей два столбца типа text.

while (there are still rows to send)
{
bcp_sendrow(...);

for (all the data in the first varbinary(max) column)
bcp_moretext(...);
bcp_moretext(hdbc, 0, NULL);

for (all the data in the second varbinary(max) column)
bcp_moretext(...);
bcp_moretext(hdbc, 0, NULL);

}

Пример

Этот пример показывает совместное использование функций bcp_moretext, bcp_bind и bcp_sendrow.

// Variables like henv not specified.
HDBC      hdbc;
DBINT      idRow = 5;
char*      pPart1 = "This text value isn't very long,";
char*      pPart2 = " but it's broken into three parts";
char*      pPart3 = " anyhow.";
DBINT      cbAllParts;
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, "comdb..articles", NULL, NULL, DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Bind program variables to table columns. 
if (bcp_bind(hdbc, (LPCBYTE) &idRow, 0, SQL_VARLEN_DATA, NULL, 0,
   SQLINT4, 1)    == FAIL)
   {
   // Raise error and return.
   return;
   }

cbAllParts = (DBINT) (strnlen(pPart1, sizeof(pPart1) + 1) + strnlen(pPart2, sizeof(pPart2) + 1) + strnlen(pPart3, sizeof(pPart3) + 1));
if (bcp_bind(hdbc, NULL, 0, cbAllParts, NULL, 0, SQLTEXT, 2) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Send this row, with the text value broken into three chunks. 
if (bcp_sendrow(hdbc) == FAIL)
   {
   // Raise error and return.
   return;
   }

if (bcp_moretext(hdbc, (DBINT) strnlen(pPart1, sizeof(pPart1) + 1), pPart1) == FAIL)
   {
   // Raise error and return.
   return;
   }
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart2, sizeof(pPart2) + 1), pPart2) == FAIL)
   {
   // Raise error and return.
   return;
   }
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart3, sizeof(pPart3) + 1), pPart3) == FAIL)
   {
   // Raise error and return.
   return;
   }

// All done. Get the number of rows processed (should be one).
nRowsProcessed = bcp_done(hdbc);

// Carry on.

См. также

Справочник

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

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