bcp_bind

Lie les données d'une variable de programme à une colonne de table pour une 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 a pour type 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 de type Long sont envoyées à SQL Server par segments à l'aide de bcp_moretext. L'utilisateur doit seulement définir pData avec la valeur NULL si la colonne correspondant au champ dépendant de l'utilisateur est une colonne BLOB, sinon bcp_bind échoue.

  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, dans ce cas, vers la variable indicateur dans ce cas, et la largeur de l'indicateur, le paramètre cbIndicator, est utilisée par la copie en bloc pour adresser 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 les valeurs entières dans une table SQL Server à l'aide de la copie en bloc :

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

  Dans cet exemple, le paramètre pData sera défini avec l'adresse d'une instance déclarée de la structure, l'adresse du membre de structure iIndicator BCPBOUNDINT. Le paramètre cbIndicator sera défini avec la taille d'un entier (sizeof (int)), et le paramètre cbData sera de même défini avec la taille d'un entier (sizeof (int)). Pour copier en bloc une ligne vers le serveur contenant une valeur NULL pour la colonne dépendante, la valeur du membre iIndicator de l'instance doit être 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 avec la valeur SQL_NULL_DATA signifie que toutes les lignes copiées vers le serveur contiennent une valeur NULL pour la colonne.

  La définition de cbData avec la valeur SQL_VARLEN_DATA indique que le système utilise un indicateur 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 sans risque avoir comme valeur SQL_VARLEN_DATA ou la longueur des données.

  Pour les types de données SQL Server character et binary, cbData peut avoir comme valeur SQL_VARLEN_DATA, SQL_NULL_DATA, une valeur positive quelconque ou 0. Si cbData a la valeur SQL_VARLEN_DATA, le système utilise un indicateur de longueur ou un indicateur null, s'il est présent, ou une séquence de terminaison 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 a la valeur SQL_VARLEN_DATA, le type de données de la colonne est un type SQL Server character ou binary, et si aucun indicateur de longueur ou séquence de terminaison n'est spécifié, le système retourne un message d'erreur.

  Si cbData est égal à 0 ou possède une valeur positive, le système utilise cbData comme longueur de données. Toutefois, si un indicateur de longueur ou une séquence de terminaison est fournie en plus d'une valeur cbData positive, le système détermine la longueur de données en utilisant la méthode qui se traduit par la plus petite quantité de données à copier.

  La valeur du paramètre cbData représente le nombre d'octets de données. Si les données caractères sont représentées par des caractères Unicode étendus, 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 aucun terminateur pour la variable, définissez pTerm avec la valeur NULL.

  Vous pouvez utiliser une chaîne vide ("") pour désigner l'indicateur de fin C null comme terminateur de variable de programme. Comme la chaîne vide se terminant par null représente un seul octet unique (l'octet de terminaison lui-même), définissez cbTerm avec la valeur 1. Par exemple, pour indiquer que la chaîne de szName se termine 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 sans terminaison 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'application (API) de copie en bloc effectue la conversion de 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 de szName est une chaîne de caractères Unicode étendus terminée par la valeur de marque de fin null Unicode :

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

  Si la colonne liée SQL Server est composée de caractères larges, aucune conversion n'est effectuée sur bcp_sendrow. Si la colonne SQL Server possède MBCS comme type de caractère, la conversion des caractères larges en caractères multioctets s'effectue quand 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 aucun terminateur pour la variable, définissez cbTerm avec la valeur 0.

• eDataType
  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 C ODBC. Par exemple, vous pouvez spécifier un entier à deux octets, type ODBC SQL_C_SHORT, à l'aide du type SQLINT2 propre à SQL Server.

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

• idxServerCol
  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.

Valeurs retournées

SUCCEED ou FAIL.

Notes

Utilisez bcp_bind comme méthode rapide et efficace pour copier les données d'une variable de programme dans une table de SQL Server.

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

Établissez un appel de bcp_bind distinct pour chaque colonne de la table SQL Server dans laquelle vous souhaitez effectuer la copie. Une fois effectués les appels nécessaires de bcp_bind, appelez bcp_sendrow pour envoyer une ligne de données de vos variables de programme vers SQL Server.

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

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

Les valeurs des paramètres de contrôle, spécifiées avec bcp_control, n'ont aucun effet sur les transferts de ligne bcp_bind.

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

Pour les nouveaux types de valeur de grande taille, 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 égal à 0, n'importe quelle valeur (1, 2, 4 ou 8) est valide pour le préfixe (cbIndicator). Dans ce cas, SQL Server Native Client recherche le terminateur, calcule la longueur des données par rapport au terminateur (i) et définit cbData avec la plus petite valeur de i et la valeur du préfixe.

Si cbTerm est égal à 0 et que cbIndicator (le préfixe) est différent de 0, cbIndicator doit être égal à 8. Le préfixe de 8 octets peut prendre les valeurs suivantes :

• 0xFFFFFFFFFFFFFFFF signifie une valeur NULL pour le champ

• 0xFFFFFFFFFFFFFFFE est traité comme valeur de préfixe spéciale utilisée pour envoyer efficacement les données par segments 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 qui contient longueur du segment, suivi par les données effectives 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 (00000000) signifiant la fin des données.

• Toute autre longueur de 8 octets valide est traitée comme longueur de données normale.

L'appel de bcp_columns lors de l'utilisation de bcp_bind se traduit par 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/time, consultez Modifications de copie en bloc pour les types date/heure améliorés (OLE DB et ODBC).

Pour plus d'informations, consultez Améliorations de la date et de l'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

Référence

Fonctions de copie en bloc