bcp_control

Article
03/05/2024

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

Modifie les paramètres par défaut pour différents paramètres de contrôle pour une copie en bloc entre un fichier et SQL Server.

Syntaxe

  
RETCODE bcp_control (  
        HDBC hdbc,  
        INT eOption,  
        void* iValue);

Arguments

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

eOption
Prend l'une des valeurs suivantes :

BCPABORT
Arrête une opération de copie en bloc déjà en cours. Appelez bcp_control avec une option eOption de BCPABORT à partir d’un autre thread pour arrêter une opération de copie en bloc en cours d’exécution. Le paramètre iValue est ignoré.

BCPBATCH
Nombre de lignes par lot. La valeur par défaut est 0, qui indique toutes les lignes d’une table, lorsque les données sont extraites ou toutes les lignes du fichier de données utilisateur, lorsque les données sont copiées dans un serveur SQL Server. Une valeur inférieure à 1 rétablit la valeur par défaut de BCPBATCH.

BCPDELAYREADFMT
Une valeur booléenne, si elle est définie sur true, entraîne la lecture de bcp_readfmt lors de l’exécution. Si la valeur est false (valeur par défaut), bcp_readfmt lit immédiatement le fichier de format. Une erreur de séquence se produit si BCPDELAYREAD OGF a la valeur true et que vous appelez bcp_columns ou bcp_setcolfmt.

Une erreur de séquence se produit également si vous appelez bcp_control(hdbc, BCPDELAYREAD OGF, (void *)FALSE) après avoir appelé bcp_control(hdbc, BCPDELAYREAD OGF, (void *)TRUE) et bcp_writefmt.

Pour plus d’informations, consultez Découverte des métadonnées.

BCPFILECP
iValue contient le numéro de la page de codes du fichier de données. Vous pouvez spécifier le numéro de la page de codes, par exemple 1252 ou 850, ou l'une de ces valeurs :

BCPFILE_ACP : les données du fichier se trouve dans la page de codes Microsoft Windows du client.

BCPFILE_OEMCP : les données dans le fichier figurent dans la page de codes OEM du client (valeur par défaut).

BCPFILE_RAW : les données du fichier se trouve dans la page de codes de SQL Server.

BCPFILEFMT
Numéro de version du format de fichier de données. Cela peut être 80 ( SQL Server 2000 (8.x)), 90 ( SQL Server 2005 (9.x)), 100 ( SQL Server 2008 (10.0.x) ou SQL Server 2008 R2 (10.50.x)), 110 ( SQL Server 2012 (11.x)) ou 120 ( SQL Server 2014 (12.x)). 120 est la valeur par défaut. Cela s'avère utile pour exporter et importer des données dans des formats pris en charge par une version antérieure du serveur. Par exemple, pour importer des données obtenues à partir d’une colonne de texte dans un serveur SQL Server 2000 (8.x) dans une colonne varchar(max) dans un serveur SQL Server 2005 (9.x) ou version ultérieure, vous devez spécifier 80. De même, si vous spécifiez 80 lors de l’exportation de données à partir d’une colonne varchar(max), elle sera enregistrée comme les colonnes de texte sont enregistrées au format SQL Server 2000 (8.x) et peuvent être importées dans une colonne de texte d’un serveur SQL Server 2000 (8.x).

BCPFIRST
Première ligne du fichier de données ou de la table à copier. La valeur par défaut est 1 ; une valeur inférieure à 1 rétablit la valeur par défaut de cette option.

BCPFIRSTEX
Pour les opérations bcp out, spécifie la première ligne de la table de base de données à copier dans le fichier de données.

Pour les opérations bcp in, spécifie la première ligne du fichier de données à copier dans la table de base de données.

Le paramètre iValue doit être l’adresse d’un entier 64 bits signé contenant la valeur. La valeur maximale qui peut être passée à BCPFIRSTEX est 2^63-1.

BCPFMTXML
Spécifie que le fichier de format généré doit être au format XML. Il est désactivé par défaut.

Les fichiers au format XML offrent plus de souplesse, mais aussi quelques contraintes supplémentaires. Par exemple, vous ne pouvez pas spécifier simultanément le préfixe et la terminaison pour un champ, ce qui était possible dans les fichiers de format plus anciens.

Remarque

Les fichiers de format XML ne sont pris en charge que lorsque SQL Server est installé avec SQL Server Native Client.

BCPHINTS
iValue contient un pointeur de chaîne de caractères SQLTCHAR. La chaîne adressée spécifie des indicateurs de traitement de copie en bloc SQL Server ou une instruction Transact-SQL qui retourne un jeu de résultats. Si une instruction Transact-SQL est spécifiée qui retourne plusieurs jeux de résultats, tous les jeux de résultats après le premier sont ignorés. Pour plus d’informations sur les indicateurs de traitement de copie en bloc, consultez l’utilitaire bcp.

BCPKEEPIDENTITY
Quand iValue a la valeur TRUE, spécifie que les fonctions de copie en bloc insèrent des valeurs de données fournies pour les colonnes SQL Server définies avec une contrainte d’identité. Le fichier d'entrée doit fournir des valeurs pour les colonnes d'identité. Si cela n'est pas défini, de nouvelles valeurs d'identités sont générées pour les lignes insérées. Toutes les données présentes dans le fichier pour les colonnes d'identité sont ignorées.

BCPKEEPNULLS
Spécifie si les valeurs de données vides dans le fichier sont converties en valeurs NULL dans la table SQL Server . Lorsque iValue a la valeur TRUE, les valeurs vides sont converties en valeurs NULL dans la table SQL Server. L'option par défaut consiste à convertir les valeurs vides en une valeur par défaut pour la colonne dans la table SQL Server si une valeur par défaut existe.

BCPLAST
Dernière ligne à copier. L'option par défaut consiste à copier toutes les lignes ; une valeur inférieure à 1 rétablit la valeur par défaut de cette option.

BCPLASTEX
Pour les opérations bcp out, spécifie la dernière ligne de la table de base de données à copier dans le fichier de données.

Pour les opérations bcp in, spécifie la dernière ligne du fichier de données à copier dans la table de base de données.

Le paramètre iValue doit être l’adresse d’un entier 64 bits signé contenant la valeur. La valeur maximale qui peut être passée à BCPLASTEX est 2^63-1.

BCPMAXERRS
Nombre d’erreurs autorisées avant l’échec de l’opération de copie en bloc. La valeur par défaut est 10 ; une valeur inférieure à 1 réinitialise cette option à sa valeur par défaut. La copie en bloc impose 65 535 erreurs au maximum. Toute tentative d'attribution d'une valeur supérieure à 65 535 à cette option entraîne l'attribution de la valeur 65 535 à l'option.

BCPODBC
Lorsque la valeur EST TRUE, spécifie que les valeurs datetime et smalldatetime enregistrées au format caractère utilisent le préfixe et le suffixe de séquence d’échappement ODBC. L’option BCPODBC s’applique uniquement à DB_OUT.

Lorsque la valeur EST FALSE, une valeur datetime représentant le 1er janvier 1997 est convertie en chaîne de caractères : 1997-01-01 00 :00 :00.000. Lorsque la valeur true, la même valeur datetime est représentée comme suit : {ts '1997-01-01-00 :00 :00.000'}.

BCPROWCOUNT
Retourne le nombre de lignes affectées par l'opération BCP en cours (ou la dernière).

BCPTEXTFILE
Lorsque la valeur est TRUE, spécifie que le fichier de données est un fichier texte et non un fichier binaire. Si le fichier est un fichier texte, BCP détermine s'il est ou non un fichier Unicode en vérifiant le marqueur d'octet Unicode dans les deux premiers octets du fichier de données.

BCPUNICODEFILE
Lorsque la valeur est TRUE, spécifie que le fichier d'entrée est un fichier Unicode.

iValue
Valeur de l’eOption spécifié. iValue est un cast de valeur entier (LONGLONG) en pointeur void pour permettre une extension future aux valeurs 64 bits.

Retours

SUCCEED ou FAIL.

Notes

Cette fonction définit différents paramètres de contrôle pour les opérations de copie en bloc, y compris le nombre d'erreurs autorisées avant l'annulation de la copie en bloc, les numéros des première et dernière lignes à copier à partir d'un fichier de données, et la taille du lot.

Cette fonction est également utilisée pour spécifier l’instruction SELECT lors de la copie en bloc à partir de SQL Server, le jeu de résultats d’un SELECT. Définissez eOption sur BCPHINTS et définissez iValue pour avoir un pointeur vers une chaîne SQLTCHAR contenant l’instruction SELECT.

Ces paramètres de contrôle sont significatifs uniquement lors de la copie entre un fichier utilisateur et une table SQL Server. Les paramètres de contrôle n’ont aucun effet sur les lignes copiées dans SQL Server avec bcp_sendrow.

Exemple

// Variables like henv not specified.  
SQLHDBC      hdbc;  
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, _T("address"), _T("address.add"), _T("addr.err"),  
   DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Set the number of rows per batch.   
if (bcp_control(hdbc, BCPBATCH, (void*) 1000) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Set file column count.   
if (bcp_columns(hdbc, 1) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Set the file format.   
if (bcp_colfmt(hdbc, 1, 0, 0, SQL_VARLEN_DATA, '\n', 1, 1)  
   == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Execute the bulk copy.   
if (bcp_exec(hdbc, &nRowsProcessed) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
printf_s("%ld rows processed by bulk copy.", nRowsProcessed);

Voir aussi

Fonctions de copie en bloc