Partager via

IBCPSession::BCPColFmt (OLE DB)

  • Article

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

Syntaxe

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

Notes

La méthode BCPColFmt permet de créer une liaison entre des champs de fichier de données BCP et des colonnes SQL Server. Il accepte la longueur, le type, la marque de fin et la longueur de préfixe d'une colonne en tant que paramètres et définit chacune de ces propriétés pour les 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 varient selon le type de la colonne serveur), et une fois pour définir le format en fonction du type de colonne du choix du client choisi lors du mode interactif pour chaque colonne.

Dans les modes non interactifs, elle est appelée uniquement une fois par colonne pour attribuer le type natif ou caractère à chaque colonne, et pour définir les marques 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 se compose des éléments suivants :

  • un mappage des champs de fichier utilisateur aux colonnes de base de données ;

  • le type de données de chaque champ de fichier utilisateur ;

  • la longueur de l'indicateur facultatif pour chaque champ ;

  • la longueur maximale des données par champ de fichier utilisateur ;

  • la 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 pour un champ de fichier utilisateur. Par exemple, pour modifier les paramètres par défaut pour trois champs dans un fichier de données utilisateur de cinq champs, appelez tout d'abord BCPColumns(5), puis BCPColFmt cinq fois, trois de ces appels définissant votre format personnalisé. Pour les deux appels restants, attribuez BCP_TYPE_DEFAULT à eUserDataType et, respectivement, 0, BCP_VARIABLE_LENGTH et 0 à cbIndicator, cbUserDataet cbUserDataTerm . Cette procédure copie les cinq colonnes, trois avec votre format personnalisé et deux avec le format par défaut.

Notes

La méthode IBCPSession::BCPColumns doit être appelée avant tout appel à BCPColFmt. Vous devez appeler BCPColFmt une fois pour chaque colonne dans le fichier utilisateur. Le fait d'appeler BCPColFmt plus d'une fois pour toute colonne de fichier utilisateur génère une erreur.

Vous n'êtes pas obligé de copier toutes les données dans un fichier utilisateur vers une table SQL Server . Pour ignorer une colonne, spécifiez le format des données pour la colonne en attribuant la valeur 0 au paramètre idxServerCol. Pour ignorer un champ, vous avez encore besoin de toutes les informations pour que la méthode fonctionne correctement.

Remarque La fonction IBCPSession::BCPWriteFmt peut être utilisée pour assurer la persistance de la spécification de format fournie par le biais de BCPColFmt.

Arguments

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

eUserDataType[in]
Type de données de 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 essaie d'utiliser le même type que la table ou la colonne de vue. Pour les opérations de copie en bloc hors 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 de préfixe pour le champ. La valeur par défaut est BCP_PREFIX_DEFAULT. Les longueurs valides pour le préfixe sont 0, 1, 2, 4 et 8. La taille de préfixe 8 est la plus souvent utilisée pour indiquer que le champ est segmenté. Elle permet d'effectuer des copies en bloc efficaces de colonnes de type valeur volumineuses.

cbUserData[in]
Longueur maximale, en octets, des données de ce champ dans le fichier utilisateur, sans compter la longueur de tout indicateur de longueur ou marque de fin.

La définition cbUserData de BCP_LENGTH_NULL indique que toutes les valeurs des champs de fichier de données sont ou doivent avoir la valeur NULL. La définition cbUserData de 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 sur une copie à partir de SQL Server, ou que l'indicateur est attendu dans les données copiées vers SQL Server.

Pour SQL Server caractères et les types de données binaires, cbUserData peuvent être BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 ou une valeur positive. Si cbUserData est BCP_LENGTH_VARIABLE, le système utilise l’indicateur de longueur, le cas échéant, ou une séquence de terminaison pour déterminer la longueur des données. Si un indicateur de longueur et une séquence de terminaison sont fournis, la copie en bloc utilise celui qui implique le volume de données à copier le plus faible. Si cbUserData est BCP_LENGTH_VARIABLE, le type de données est un caractère SQL Server ou un type binaire, et si ni un indicateur de longueur ni une séquence de terminaison n’est spécifié, le système retourne un message d’erreur.

Si cbUserData est 0 ou une valeur positive, le système utilise cbUserData comme longueur de données maximale. Toutefois, si, en plus d’un élément positif cbUserData, un indicateur de longueur ou une séquence de terminaison est fourni, le système détermine la longueur des données à l’aide de la méthode qui aboutit à la copie du moins grand nombre de donné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é par la taille, en octets, de chaque caractère.

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

Pour éviter de terminer des données extraites ou pour indiquer que les données dans un fichier utilisateur ne sont pas terminées, attribuez la valeur NULL à ce paramètre.

Si plusieurs méthodes sont employées pour définir la longueur des colonnes du fichier utilisateur (par exemple, un terminateur et un indicateur de longueur, ou un terminateur et une longueur de colonne maximale), la copie en bloc choisit celle qui implique le volume de données à copier le moins élevé.

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. Prenez soin de définir comme il se doit la chaîne d'octets de terminaison et la longueur de cette même chaîne.

cbUserDataTerm[in]
Longueur, en octets, de la séquence de marque de fin à utiliser pour la colonne. Si aucune marque de fin n'est présente ou désirée dans les données, attribuez 0 à cette valeur.

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 semblables. Si cette valeur est 0, la copie en bloc ignore le champ dans le fichier de données.

Codet de retour

S_OK
S_OK

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