bcp_moretext
Посылает в SQL Server часть значения длинного типа данных переменной длины.
Синтаксис
RETCODE bcp_moretext ( HDBC hdbc, DBINT cbData, LPCBYTE pData);
Arguments
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 вызывается с параметром pData, не равным NULL, для типов данных, поддерживаемых функцией bcp_moretext, функция bcp_sendrow пересылает все значение целиком, независимо от его длины. Однако если функция bcp_bind вызывается с параметром pData, не равным NULL, для поддерживаемых типов данных, функцию 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.