bcp_colfmt

Spécifie le format source ou cible des données dans un fichier utilisateur. Lorsqu’elle est utilisée comme format source, bcp_colfmt spécifie le format d’un fichier de données existant utilisé comme source de données dans une copie en bloc dans une table SQL Server. Lorsqu’il est utilisé comme format cible, le fichier de données est créé à l’aide des formats de colonne spécifiés avec bcp_colfmt.

Syntaxe

  
RETCODE bcp_colfmt (  
HDBC   
hdbc  
,  
INT  
idxUserDataCol  
,  
BYTE   
eUserDataType  
,  
INT   
cbIndicator  
,  
DBINT   
cbUserData  
,  
LPCBYTE   
pUserDataTerm  
,  
INT   
cbUserDataTerm  
,  
INT   
idxServerCol  
);  
  

Les arguments

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

idxUserDataCol
Numéro de colonne ordinal dans le fichier de données utilisateur pour lequel le format est spécifié. La première colonne est 1.

eUserDataType
Type de données de cette colonne dans le fichier utilisateur. Si elle diffère du type de données de la colonne correspondante dans la table de base de données (idxServerColumn), la copie en bloc convertit les données si possible.

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

Le paramètre eUserDataType 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 ODBC C. Par exemple, vous pouvez spécifier une chaîne de caractères, un type ODBC SQL_C_CHAR, à l’aide du type SQL Server spécifique à SQLCHARACTER.

Pour spécifier la représentation de données par défaut pour le type de données SQL Server, définissez ce paramètre sur 0.

Pour une copie en bloc de SQL Server dans un fichier, lorsque eUserDataType est SQLDECIMAL ou 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
Longueur, en octets, d’un indicateur de longueur/null dans les données de colonne. Les valeurs de longueur d'indicateur valides sont 0 (quand aucun indicateur n'est utilisé), 1, 2, 4 ou 8.

Pour spécifier l’utilisation de l’indicateur de copie en bloc par défaut, définissez ce paramètre sur SQL_VARLEN_DATA.

Les indicateurs apparaissent en mémoire directement avant toutes les données, et dans le fichier de données directement avant les données auxquelles elles s’appliquent.

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

Les fichiers de données générés par la copie en bloc lorsqu’aucune intervention de l’utilisateur n’ajuste le format des données contiennent des indicateurs lorsque les données de colonne peuvent varier en longueur ou que la colonne peut accepter NULL comme valeur.

cbUserData
Longueur maximale, en octets, des données de cette colonne dans le fichier utilisateur, sans inclure la longueur d’un indicateur de longueur ou d’un indicateur de fin.

La définition de cbUserData sur SQL_NULL_DATA indique que toutes les valeurs de la colonne de fichier de données sont ou doivent être définies sur NULL.

La définition de cbUserData sur SQL_VARLEN_DATA indique que le système doit déterminer la longueur des données dans chaque colonne. Pour certaines colonnes, 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 peut être SQL_VARLEN_DATA, SQL_NULL_DATA, 0 ou une valeur positive. Si cbUserData est SQL_VARLEN_DATA, 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 est SQL_VARLEN_DATA, le type de données est un caractère SQL Server ou un type binaire, et ni un indicateur de longueur ni une séquence de fin n’est spécifié, le système retourne un message d’erreur.

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

pUserDataTerm
Séquence de fin à utiliser pour cette colonne. 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'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. Veillez à ce que la chaîne d’octet de fin et la longueur de la chaîne d’octets soient correctement définies.

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

idxServerCol
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 indiquée par SQLColumns.

Si cette valeur est 0, la copie en bloc ignore la colonne du fichier de données.

Retours

SUCCEED ou FAIL.

Remarques

La fonction bcp_colfmt 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 colonnes de fichier utilisateur aux colonnes de base de données.

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

• Longueur de l’indicateur facultatif pour chaque colonne.

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

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

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

Chaque appel à bcp_colfmt spécifie le format d’une colonne de fichier utilisateur. Par exemple, pour modifier les paramètres par défaut de trois colonnes dans un fichier de données utilisateur à cinq colonnes, appelez d’abord bcp_columns(5), puis appelez bcp_colfmt cinq fois, avec trois de ces appels définissant votre format personnalisé. Pour les deux appels restants, définissez eUserDataType sur 0 et définissez cbIndicator, cbUserData et cbUserDataTerm sur 0, SQL_VARLEN_DATA et 0 respectivement. Cette procédure copie les cinq colonnes, trois avec votre format personnalisé et deux avec le format par défaut.

Pour cbIndicator, une valeur de 8 pour indiquer qu’un type de valeur élevée est maintenant valide. Si le préfixe est spécifié pour un champ dont la colonne correspondante est un nouveau type max, il ne peut être défini que sur 8. Pour plus d’informations, consultez bcp_bind.

La fonction bcp_columns doit être appelée avant tout appel à bcp_colfmt.

Vous devez appeler bcp_colfmt une fois pour chaque colonne du fichier utilisateur.

L’appel de bcp_colfmt plusieurs fois pour n’importe quelle colonne de fichier utilisateur provoque une erreur.

Vous n’avez pas besoin de copier toutes les données d’un fichier utilisateur dans la table SQL Server. Pour ignorer une colonne, spécifiez le format des données de la colonne, en définissant le paramètre idxServerCol sur 0. Si vous souhaitez ignorer une colonne, vous devez spécifier son type.

La fonction bcp_writefmt peut être utilisée pour conserver la spécification de format.

prise en charge bcp_colfmt des fonctionnalités de date et d’heure améliorées

Pour plus d’informations sur les types he utilisés avec le paramètre eUserDataType pour les types date/heure, consultez Modifications de copie en bloc pour les types de date et d’heure améliorés (OLE DB et ODBC).

Pour plus d’informations, consultez Améliorations de date et d’heure (ODBC).

Voir aussi

Fonctions de copie en bloc