IBCPSession::BCPColFmt (OLE DB)

Syntaxe

HRESULT BCPColFmt( 
      DBORDINAL idxUserDataCol,
      int eUserDataType,
      int cbIndicator,
      int cbUserData,
      BYTE *pbUserDataTerm,
      int cbUserDataTerm,
      DBORDINAL idxServerCol);

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 ;

• la 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, cbUserData et cbUserDataTerm. Cette procédure copie les cinq colonnes, trois avec votre format personnalisé et deux avec le format par défaut.

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 de SQL Server vers 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.

  Le fait d'attribuer BCP_LENGTH_NULL à cbUserData indique que toutes les valeurs dans les champs de fichier de données sont ou doivent être NULL. Le fait d'attribuer BCP_LENGTH_VARIABLE à cbUserData 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 les types de données caractères et binaires SQL Server, cbUserData peut ê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, s'il est présent, ou une séquence de marque de fin pour déterminer la longueur des données. Si un indicateur de longueur et une séquence de marque de fin sont fournis, la copie en bloc utilise celui qui entraîne le moins de données à copier. Si cbUserData est BCP_LENGTH_VARIABLE, le type de données est un type caractère ou binaire SQL Server ; et si aucun indicateur de longueur et aucune séquence de marque de fin 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 un indicateur de longueur ou une séquence de marque de fin est fourni en plus d'une valeur cbUserData positive, le système détermine la longueur de données en utilisant la méthode qui entraîne le moins de données à copier.

  La valeur cbUserData représente le nombre d'octets de données. Si des données caractères sont représentées par des caractères Unicode étendus, une valeur de paramètre cbUserData positive 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 principalement utile 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 correctement 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 de spécification de la longueur de colonne de fichier utilisateur sont utilisées (par exemple une marque de fin et un indicateur de longueur, ou une marque de fin et une longueur de colonne maximale), la copie en bloc choisit celle qui entraîne le moins de données à copier.

  L'API de copie en bloc effectue la conversion de caractères Unicode vers MBCS en fonction des besoins. Vous devez veiller à définir correctement la chaîne d'octet de marque de fin et la longueur de la chaîne d'octets.

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

Valeurs de code 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 n'était pas attendu. Par exemple, la méthode IBCPSession::BCPInit n'a pas été appelée avant l'appel de cette méthode.

• E_INVALIDARG
  L'argument n'était pas valide.

• E_OUTOFMEMORY
  Erreur de mémoire insuffisante.

Voir aussi

Concepts

Autres ressources