bcp_moretext

Article
05/07/2013

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és 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, de longueur variable, pris en charge à envoyer à SQL Server.

Valeurs retournées

SUCCEED ou FAIL.

Notes

Cette fonction peut être utilisée avec bcp_bind et bcp_sendrow pour copier des valeurs de données longues, de longueur variable vers SQL Server en plusieurs petits segments. 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 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 les données immédiatement après un retour réussi de bcp_sendrow qui indique 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 vers la colonne SQL Server. Toute tentative visant à envoyer à SQL Server davantage d'octets que le nombre spécifié dans l'appel à bcp_bind ou bcp_collen génère une erreur. Cette erreur surviendrait par exemple dans une application ayant utilisé bcp_collen pour définir la longueur des données disponibles pour une colonne text SQL Server à 4500, puis ayant appelé bcp_moretext à cinq reprises en indiquant à chaque appel que la longueur du tampon de données était de 1000 octets.

Si une ligne copiée contient plusieurs colonnes longues, de longueur variable, bcp_moretext envoie d'abord ses données à la colonne de numéro inférieur, suivi de la colonne de numéro suivant, 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 bcp_moretext, il n'est pas nécessaire d'appeler bcp_collen pour définir la longueur de colonne. Au lieu de cela, pour ces types uniquement, la valeur est terminée en appelant bcp_sendrow avec une longueur de zéro.

Une application appelle normalement bcp_sendrow et bcp_moretext dans des boucles afin d'envoyer plusieurs lignes de données. Voici comment procéder pour une table qui contient deux colonnes 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);

}

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

Référence

Fonctions de copie en bloc

Partager via