bcp_moretext

Article
01/10/2024

S’applique à :SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Envoie une partie d’une valeur de type de données longue et de longueur variable à SQL Server.

Syntaxe

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

Arguments

hdbc
Handle de connexion ODBC compatible avec la copie en bloc.

cbData
Nombre d’octets de données copiées vers SQL Server à partir des données référencées par pData. Une valeur de SQL_NULL_DATA indique NULL.

Pdata
Pointeur vers le segment de données long et de longueur variable pris en charge à envoyer à SQL Server.

Retours

SUCCEED ou FAIL.

Remarques

Cette fonction peut être utilisée conjointement avec bcp_bind et bcp_sendrow pour copier de longues valeurs de données de longueur variable pour SQL Server dans un certain nombre de segments plus petits. bcp_moretext peut être utilisé avec des colonnes qui ont les types de données SQL Server suivants : text, ntext, image, varchar(max), nvarchar(max), varbinary(max), type défini par l’utilisateur (UDT) et XML. bcp_moretext ne prend pas en charge les conversions de données, les données fournies doivent correspondre au type de données de la colonne cible.

Si bcp_bind est appelé avec un paramètre pData non NULL pour les types de données pris en charge par bcp_moretext, bcp_sendrow envoie la valeur de données entière, quelle que soit la longueur. Si, toutefois, bcp_bind a un paramètre pData NULL pour les types de données pris en charge, bcp_moretext peut être utilisé pour copier des données immédiatement après un retour réussi de bcp_sendrow indiquant que toutes les colonnes liées avec des données présentes ont été traitées.

Si vous utilisez bcp_moretext pour envoyer une colonne de type de données prise en charge dans une ligne, vous devez également l’utiliser pour envoyer toutes les autres colonnes de type de données prises en charge dans la ligne. Aucune colonne ne peut être ignorée. Les types de données pris en charge sont SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT et SQLXML. SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY et SQLVARBINARY appartiennent également à cette catégorie si la colonne est un varchar (max), nvarchar (max) ou varbinary (max), respectivement.

L’appel de bcp_bind ou bcp_collen définit la longueur totale de toutes les parties de données à copier dans la colonne SQL Server. Une tentative d’envoi d’SQL Server plus d’octets que spécifié dans l’appel à bcp_bind ou bcp_collen génère une erreur. Cette erreur se produit, par exemple, dans une application qui a utilisé bcp_collen pour définir la longueur des données disponibles pour une colonne de texte SQL Server sur 4500, puis appelée bcp_moretext cinq fois tout en indiquant à chaque appel que la longueur de la mémoire tampon de données était de 1 000 octets.

Si une ligne copiée contient plusieurs colonnes longues et de longueur variable, bcp_moretext envoie d’abord ses données à la colonne numérotée de manière orale la plus basse, suivie de la colonne numérotée ordinally suivante, et ainsi de suite. Il est important de définir correctement la longueur totale des données attendues. Il n'existe aucun moyen de signaler, en dehors du paramètre de longueur, que toutes les données pour une colonne ont été reçues par copie en bloc.

Lorsque des valeurs var(max) sont envoyées au serveur à l’aide de bcp_sendrow et de bcp_moretext, il n’est pas nécessaire d’appeler bcp_collen pour définir la longueur de la colonne. Au lieu de cela, pour ces types uniquement, la valeur est arrêtée en appelant bcp_sendrow d’une longueur égale à zéro.

Une application appelle normalement bcp_sendrow et bcp_moretext dans des boucles pour envoyer un certain nombre de lignes de données. Voici un aperçu de la procédure à suivre pour une table contenant deux colonnes de texte :

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);  
  
}

Exemple

Cet exemple montre comment utiliser bcp_moretext avec bcp_bind et 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.

Voir aussi

Bulk Copy Functions

Share via