bcp_moretext

Статья
01/10/2024

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

Отправляет часть длинного значения типа данных переменной длины в 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 вызывается с параметром pData, отличным от NULL, для типов данных, поддерживаемых 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 значение 4500, а затем вызывается bcp_moretext пять раз, указывая на каждом вызове, что длина буфера данных составила 1000 байтов.

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

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

Приложение обычно вызывает bcp_sendrow и bcp_moretext в циклах для отправки ряда строк данных. Ниже приведены сведения о том, как это сделать для таблицы, содержащей два текстовых столбца:

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.

См. также

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

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