IBCPSession ::BCPColFmt (OLE DB)

Crée une liaison entre les variables de programme et les colonnes SQL Server.

Syntaxe

  
HRESULT BCPColFmt(   
DBORDINALidxUserDataCol,  
inteUserDataType,  
intcbIndicator,  
intcbUserData,  
BYTE *pbUserDataTerm,  
intcbUserDataTerm,  
DBORDINALidxServerCol);  

Remarques

La méthode BCPColFmt est utilisée pour créer une liaison entre les champs de fichier de données BCP et les colonnes SQL Server. Il prend la longueur, le type, le terminateur et la longueur de préfixe d’une colonne en tant que paramètres et définit chacune de ces propriétés pour des champs individuels.

Si l’utilisateur choisit le mode interactif, cette méthode est appelée deux fois ; une fois pour définir le format de colonne en fonction des valeurs par défaut (qui sont en fonction du type de la colonne serveur), et une fois pour définir le format en fonction du type de colonne du choix du client choisi pendant le mode interactif, pour chaque colonne.

Dans les modes non interactifs, il est appelé une seule fois par colonne pour définir le type de chaque colonne sur caractère ou type natif, et pour définir les indicateurs de fin de colonne et de ligne.

La méthode BCPColFmt vous permet de spécifier le format de fichier utilisateur pour les copies en bloc. Pour la copie en bloc, un format contient les parties suivantes :

• Mappage des champs de fichier utilisateur aux colonnes de base de données.

• Type de données de chaque champ de fichier utilisateur.

• Longueur de l’indicateur facultatif pour chaque champ.

• Longueur maximale des données par champ de fichier utilisateur.

• Séquence d’octets de fin facultative pour chaque champ.

• Longueur de la séquence d’octets de fin facultative.

Chaque appel à BCPColFmt spécifie le format d’un champ de fichier utilisateur. Par exemple, pour modifier les paramètres par défaut de trois champs dans un fichier de données utilisateur à cinq champs, tout d’abord appeler BCPColumns(5)BCPColFmt cinq fois, avec trois de ces appels définissant votre format personnalisé. Pour les deux appels restants, définissez eUserDataType sur BCP_TYPE_DEFAULT et définissez cbIndicator, cbUserData et cbUserDataTerm sur 0, BCP_VARIABLE_LENGTH et 0 respectivement. Cette procédure copie les cinq colonnes, trois avec votre format personnalisé et deux avec le format par défaut.

Vous n’avez pas besoin de copier toutes les données d’un fichier utilisateur dans une table SQL Server. Pour ignorer une colonne, spécifiez le format des données pour la colonne définissant le paramètre idxServerCol sur 0. Pour ignorer un champ, vous avez toujours besoin de toutes les informations pour que la méthode fonctionne correctement.

Note La fonction IBCPSession ::BCPWriteFmt peut être utilisée pour conserver la spécification de format fournie via BCPColFmt.

Les arguments

idxUserDataCol[in]
Index du champ dans le fichier de données de l’utilisateur.

eUserDataType[in]
Type de données du champ dans le fichier de données de l’utilisateur. Les types de données disponibles sont répertoriés dans le fichier d’en-tête SQL Server Native Client (sqlncli.h) au format BCP_TYPE_XXX, par exemple, BCP_TYPE_SQLINT4. Si la valeur BCP_TYPE_DEFAULT est spécifiée, le fournisseur tente d’utiliser le même type que le type de colonne de table ou d’affichage. Pour les opérations de copie en bloc hors de SQL Server et dans un fichier lorsque l’argument eUserDataType est BCP_TYPE_SQLDECIMAL ou BCP_TYPE_SQLNUMERIC :

• Si la colonne source n’est pas décimale ou numérique, la précision et l’échelle par défaut sont utilisées.

• Si la colonne source est décimale ou numérique, la précision et l’échelle de la colonne source sont utilisées.

cbIndicator[in]
Longueur du préfixe du champ. La valeur par défaut est BCP_PREFIX_DEFAULT. Les longueurs valides pour le préfixe sont 0, 1, 2, 4 et 8. Une taille de préfixe de 8 est la plus couramment utilisée pour indiquer que le champ est segmenté. Cela est utilisé pour copier efficacement des colonnes de type valeur volumineuses.

cbUserData[in]
Longueur maximale, en octets, des données de ce champ dans le fichier utilisateur, sans inclure la longueur d’un indicateur de longueur ou d’un indicateur de fin.

La valeur cbUserData BCP_LENGTH_NULL indique que toutes les valeurs des champs du fichier de données sont ou doivent être définies sur NULL. La valeur cbUserData BCP_LENGTH_VARIABLE indique que le système doit déterminer la longueur des données pour chaque champ. Pour certains champs, cela peut signifier qu’un indicateur de longueur/null est généré pour précéder les données d’une copie à partir de SQL Server, ou que l’indicateur est attendu dans les données copiées vers SQL Server.

Pour les types de données binaires et caractères SQL Server, cbUserData il peut s’agir de BCP_LENGTH_VARIABLE, de BCP_LENGTH_NULL, de 0 ou d’une valeur positive. Si cbUserData elle est BCP_LENGTH_VARIABLE, le système utilise l’indicateur de longueur, le cas échéant, ou une séquence de terminateur pour déterminer la longueur des données. Si un indicateur de longueur et une séquence de fin sont fournis, la copie en bloc utilise celle qui entraîne la copie minimale des données. Si cbUserData la valeur est BCP_LENGTH_VARIABLE, le type de données est un caractère SQL Server ou un type binaire, et si aucun indicateur de longueur ni séquence de fin n’est spécifié, le système retourne un message d’erreur.

S’il cbUserData s’agit de 0 ou d’une valeur positive, le système utilise cbUserData la longueur maximale des données. Toutefois, si, en plus d’une séquence positive cbUserData, un indicateur de longueur ou une séquence de fin est fourni, 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 cbUserData valeur 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 positive cbUserData représente le nombre de caractères multipliés par la taille, en octets, de chaque caractère.

pbUserDataTerm[size_is][in]
Séquence de fin à utiliser pour le champ. Ce paramètre est utile principalement pour les types de données caractères, car tous les autres types sont de longueur fixe ou, dans le cas de données binaires, nécessitent un indicateur de longueur pour enregistrer avec précision le nombre d’octets présents.

Pour éviter la fin des données extraites ou pour indiquer que les données d’un fichier utilisateur ne sont pas arrêtées, définissez ce paramètre sur NULL.

Si plusieurs moyens de spécifier une longueur de colonne de fichier utilisateur sont utilisés (par exemple, un indicateur de fin et une longueur, ou un indicateur de fin et une longueur de colonne maximale), la copie en bloc choisit celle qui entraîne la copie minimale des données.

L’API de copie en bloc effectue la conversion de caractères Unicode vers MBCS en fonction des besoins. Veillez à ce que la chaîne d’octet de fin et la longueur de la chaîne d’octets soient correctement définies.

cbUserDataTerm[in]
Longueur, en octets, de la séquence de terminateur à utiliser pour la colonne. Si aucun terminateur n’est présent ou souhaité dans les données, définissez cette valeur sur 0.

idxServerCol[in]
Position ordinale de la colonne dans la table de base de données. Le premier numéro de colonne est 1. La position ordinale d’une colonne est signalée par IColumnsInfo ::GetColumnInfo ou des méthodes similaires. Si cette valeur est 0, la copie en bloc ignore le champ dans le fichier de données.

Codet de retour

S_OK
La méthode a réussi.

E_FAIL
Une erreur spécifique au fournisseur s’est produite, pour obtenir des informations détaillées, utilisez l’interface ISQLServerErrorInfo .

E_UNEXPECTED
L’appel à la méthode était inattendu. Par exemple, la méthode IBCPSession ::BCPInit n’a pas été appelée avant d’appeler cette méthode.

E_INVALIDARG
L’argument n’était pas valide.

E_OUTOFMEMORY
Erreur de mémoire insuffisante.

Voir aussi

IBCPSession (OLE DB)
Exécution d’opérations de copie en bloc