bcp_bind

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

Lie des données d’une variable de programme à une colonne de table pour la copie en bloc dans SQL Server.

Syntaxe

  
RETCODE bcp_bind (  
        HDBC hdbc,
        LPCBYTE pData,  
        INT cbIndicator,  
        DBINT cbData,  
        LPCBYTE pTerm,  
        INT cbTerm,  
        INT eDataType,  
        INT idxServerCol);  

Arguments

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

pData
Pointeur vers les données copiées. Si eDataType est SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR ou SQLIMAGE, pData peut être NULL. Un pData NULL indique que les valeurs de données longues sont envoyées à SQL Server en blocs à l’aide de bcp_moretext. L’utilisateur ne doit définir pData que sur NULL si la colonne correspondant au champ lié à l’utilisateur est une colonne BLOB sinon , bcp_bind échouera.

Si les indicateurs sont présents dans les données, ils apparaissent directement en mémoire avant les données. Le paramètre pData pointe vers la variable d’indicateur dans ce cas, et la largeur de l’indicateur, le paramètre cbIndicator , est utilisé par la copie en bloc pour traiter correctement les données utilisateur.

cbIndicator
Longueur, en octets, d'un indicateur de longueur ou d'un indicateur null pour les données de la colonne. Les valeurs de longueur d'indicateur valides sont 0 (quand aucun indicateur n'est utilisé), 1, 2, 4 ou 8. Les indicateurs apparaissent directement en mémoire avant les données. Par exemple, la définition de type de structure suivante peut être utilisée pour insérer des valeurs entières dans une table SQL Server à l’aide de la copie en bloc :

typedef struct tagBCPBOUNDINT  
    {  
    int iIndicator;  
    int Value;  
    } BCPBOUNDINT;  

Dans l’exemple, le paramètre pData est défini sur l’adresse d’une instance déclarée de la structure, l’adresse du membre de structure iIndicator BCPBOUNDINT. Le paramètre cbIndicator est défini sur la taille d’un entier (sizeof(int)), et le paramètre cbData est à nouveau défini sur la taille d’un entier (sizeof(int)). Pour copier en bloc une ligne sur le serveur contenant une valeur NULL pour la colonne liée, la valeur du membre iIndicator de l’instance doit être définie sur SQL_NULL_DATA.

cbData
Nombre d'octets de données dans la variable de programme, à l'exclusion de tout indicateur de longueur ou indicateur null ou terminateur.

La définition de cbData sur SQL_NULL_DATA signifie que toutes les lignes copiées sur le serveur contiennent une valeur NULL pour la colonne.

La définition de cbData sur SQL_VARLEN_DATA indique que le système utilisera une marque de fin de chaîne ou une autre méthode pour déterminer la longueur des données copiées.

Pour les types de données de longueur fixe, tels que les entiers, le type de données indique la longueur des données au système. Par conséquent, pour les types de données de longueur fixe, cbData peut être SQL_VARLEN_DATA ou la longueur des données en toute sécurité.

Pour les types de données binaires et caractères SQL Server, cbData peut être SQL_VARLEN_DATA, SQL_NULL_DATA, une valeur positive ou 0. Si cbData est SQL_VARLEN_DATA, le système utilise un indicateur de longueur/null (le cas échéant) ou une séquence de terminateur pour déterminer la longueur des données. Si les deux sont fournis, le système utilise celui qui se traduit par la quantité de données à copier la moins élevée. Si cbData est SQL_VARLEN_DATA, le type de données de la colonne est un caractère SQL Server ou un type binaire, et aucun indicateur de longueur ni séquence de fin n’est spécifié, le système retourne un message d’erreur.

Si cbData est égal à 0 ou à une valeur positive, le système utilise cbData comme longueur de données. Toutefois, si, en plus d’une valeur cbData positive, une séquence d’indicateur de longueur ou de fin est fournie, le système détermine la longueur des données à l’aide de la méthode qui entraîne la quantité minimale de données copiées.

La valeur du paramètre cbData représente le nombre d’octets de données. Si les données de caractères sont représentées par des caractères larges Unicode, une valeur de paramètre cbData positive représente le nombre de caractères multiplié par la taille en octets de chaque caractère.

pTerm
Pointeur vers le modèle d'octet, s'il existe, qui marque la fin de cette variable de programme. Par exemple, les chaines C ANSI et MBCS ont habituellement un terminateur d'1 octet (\0).

S’il n’existe pas de terminateur pour la variable, définissez pTerm sur NULL.

Vous pouvez utiliser une chaîne vide ("") pour désigner l'indicateur de fin C null comme terminateur de variable de programme. Étant donné que la chaîne vide terminée par null constitue un octet unique (l’octet de fin lui-même), définissez cbTerm sur 1. Par exemple, pour indiquer que la chaîne dans szName est terminée par null et que le terminateur doit être utilisé pour indiquer la longueur :

bcp_bind(hdbc, szName, 0,  
   SQL_VARLEN_DATA, "", 1,  
   SQLCHARACTER, 2)  

Une forme non déterminée de cet exemple peut indiquer que 15 caractères doivent être copiés de la variable szName vers la deuxième colonne de la table liée :

bcp_bind(hdbc, szName, 0, 15,
   NULL, 0, SQLCHARACTER, 2)  

L'interface de programmation d'applications (API) de la copie en bloc procède à la conversion des caractères Unicode vers MBCS en fonction des besoins. Veillez à définir correctement la chaîne d'octet de marque de fin et la longueur de la chaîne d'octets. Par exemple, pour indiquer que la chaîne dans szName est une chaîne de caractères large Unicode, arrêtée par la valeur de fin null Unicode :

bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, L"",  
   sizeof(WCHAR), SQLNCHAR, 2)  

Si la colonne SQL Server liée est large, aucune conversion n’est effectuée sur bcp_sendrow. Si la colonne SQL Server est un type de caractère MBCS, une conversion de caractères large en caractères multioctets est effectuée à mesure que les données sont envoyées à SQL Server.

cbTerm
Nombre d'octets présents dans le terminateur de la variable de programme, s'il existe. S’il n’existe pas de terminateur pour la variable, définissez cbTerm sur 0.

eDataType est le type de données C de la variable de programme. Les données de la variable de programme sont converties dans le type de la colonne de base de données. Si ce paramètre est égal à 0, aucune conversion n'est effectuée.

Le paramètre eDataType est énuméré par les jetons de type de données SQL Server dans sqlncli.h, et non par les énumérateurs de type de données ODBC C. Par exemple, vous pouvez spécifier un entier à deux octets, un type ODBC SQL_C_SHORT, à l’aide du type spécifique à SQL Server SQLINT2.

SQL Server 2005 (9.x) a introduit la prise en charge des jetons de type de données SQLXML et SQLUDT dans le paramètre eDataType.

Le tableau suivant répertorie les types de données énumérées valides et les types de données ODBC C correspondants.

idxServerCol est la position ordinale de la colonne dans la table de base de données vers laquelle les données sont copiées. La première colonne d'une table est la colonne 1. La position ordinale d'une colonne est indiquée par SQLColumns.

Retours

SUCCEED ou FAIL.

Notes

Utilisez bcp_bind pour un moyen rapide et efficace de copier des données d’une variable de programme dans une table dans SQL Server.

Appelez bcp_init avant d’appeler cette fonction ou toute autre fonction de copie en bloc. L’appel bcp_init définit la table cible SQL Server pour la copie en bloc. Lors de l’appel de bcp_init à utiliser avec bcp_bind et bcp_sendrow, le paramètre bcp_init szDataFile, indiquant le fichier de données, a la valeur NULL ; le paramètre bcp_init eDirection est défini sur DB_IN.

Effectuez un appel bcp_bind distinct pour chaque colonne de la table SQL Server dans laquelle vous souhaitez copier. Une fois les appels bcp_bind nécessaires effectués, appelez bcp_sendrow pour envoyer une ligne de données de vos variables de programme à SQL Server. La reliaison des colonnes n'est pas prise en charge.

Chaque fois que vous souhaitez que SQL Server valide les lignes déjà reçues, appelez bcp_batch. Par exemple, appelez bcp_batch une fois pour toutes les 1 000 lignes insérées ou à tout autre intervalle.

Lorsqu’il n’y a plus de lignes à insérer, appelez bcp_done. L'échec de cette opération entraîne une erreur.

Les paramètres de contrôle, spécifiés avec bcp_control, n’ont aucun effet sur les transferts de lignes bcp_bind .

Si pData pour une colonne a la valeur NULL, car sa valeur est fournie par des appels à bcp_moretext, toutes les colonnes suivantes avec eDataType définies sur SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR ou SQLIMAGE doivent également être liées avec pData défini sur NULL, et leurs valeurs doivent également être fournies par des appels à bcp_moretext.

Pour les nouveaux types de valeurs volumineuses, tels que varchar(max), varbinary(max)ou nvarchar(max), vous pouvez utiliser SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY et SQLNCHAR comme indicateurs de type dans le paramètre eDataType .

Si cbTerm n’est pas 0, une valeur (1, 2, 4 ou 8) est valide pour le préfixe (cbIndicator). Dans ce cas, SQL Server Native Client recherche la fin, calcule la longueur des données par rapport à la marque de fin (i) et définit la valeur cbData sur la plus petite valeur i et la valeur du préfixe.

Si cbTerm est 0 et cbIndicator (le préfixe) n’est pas 0, cbIndicator doit être 8. Le préfixe de 8 octets peut prendre les valeurs suivantes :

• 0xFFFFFFFFFFFFFFFF signifie une valeur NULL pour le champ

• 0xFFFFFFFFFFFFFFFE est traitée comme une valeur de préfixe spéciale, utilisée pour envoyer efficacement des données en blocs au serveur. Le format des données avec ce préfixe particulier est :

• <><SPECIAL_PREFIX 0 ou plus DATA CHUNKS><ZERO_CHUNK> où :

• SPECIAL_PREFIX est 0xFFFFFFFFFFFFFFFE

• DATA_CHUNK est un préfixe de 4 octets contenant la longueur du bloc, suivi des données réelles dont la longueur est spécifiée dans le préfixe de 4 octets.

• ZERO_CHUNK est une valeur de 4 octets contenant tous les zéros (000000000) indiquant la fin des données.

• Toute autre longueur de 8 octets valide est traitée comme une longueur de données régulière.

L’appel de bcp_columns lors de l’utilisation de bcp_bind entraîne une erreur.

Prise en charge de bcp_bind pour les fonctionnalités Date et Heure améliorées

Pour plus d’informations sur les types utilisés avec le paramètre eDataType pour les types date/heure, consultez Modifications de copie en bloc pour les types de date et d’heure améliorés (OLE DB et ODBC).

Pour plus d’informations, consultez Améliorations de date et d’heure (ODBC).

Exemple

#include sql.h  
#include sqlext.h  
#include odbcss.h  
// Variables like henv not specified.  
HDBC      hdbc;  
char         szCompanyName[MAXNAME];  
DBINT      idCompany;  
DBINT      nRowsProcessed;  
DBBOOL      bMoreData;  
char*      pTerm = "\t\t";  
  
// 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 bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL  
   DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,  
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
while (TRUE)  
   {  
   // Retrieve and process program data.
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)  
      {  
      // Send the data.
      if (bcp_sendrow(hdbc) == FAIL)  
         {  
         // Raise error and return.  
         return;  
         }  
      }  
   else  
      {  
      // Break out of loop.  
      break;  
      }  
   }  
  
// Terminate the bulk copy operation.  
if ((nRowsProcessed = bcp_done(hdbc)) == -1)  
   {  
   printf_s("Bulk-copy unsuccessful.\n");  
   return;  
   }  
  
printf_s("%ld rows copied.\n", nRowsProcessed);  

Voir aussi

Fonctions de copie en bloc