bcp_setcolfmt

Article
01/10/2024

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

La fonction bcp_setcolfmt remplace le bcp_colfmt. Lors de la spécification du classement de colonne, la fonction bcp_setcolfmt doit être utilisée. bcp_setbulkmode pouvez être utilisé pour spécifier plusieurs formats de colonne.

Cette fonction propose une approche souple pour la définition du format des colonnes dans le cadre d'une opération de copie en bloc. Elle est employée pour définir des attributs de format de colonne individuels. Chaque appel à bcp_setcolfmt définit un attribut de format de colonne.

La fonction bcp_setcolfmt spécifie le format source ou cible des données dans un fichier utilisateur. Lorsqu’elle est utilisée comme format source, bcp_setcolfmt 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 dans 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_setcolfmt.

Syntaxe

  
RETCODE bcp_setcolfmt (  
        HDBC hdbc,  
        INT field,  
        INT property,  
        void* pValue,  
        INT cbValue);

Arguments

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

field
Numéro de colonne ordinal pour lequel la propriété est définie.

propriété
L'une des constantes de propriété. Les constantes de propriété sont définies dans le tableau qui suit.

Propriété	Valeur	Description
BCP_FMT_TYPE	BYTE	Type de données de la colonne dans le fichier utilisateur. Si le type de données est différent de celui de la colonne correspondante dans la table de base de données, la copie en bloc convertit, si possible, les données. Le paramètre BCP_FMT_TYPE 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 C ODBC. Par exemple, vous pouvez spécifier une chaîne de caractères, un type ODBC SQL_C_CHAR, à l’aide du type SQLCHARACTER spécifique à SQL Server. 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 BCP_FMT_TYPE 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. Sinon, si la colonne source est décimale ou numérique, la précision et l’échelle de la colonne source sont utilisées.
BCP_FMT_INDICATOR_LEN	INT	Longueur, en octets, de l'indicateur (préfixe). Longueur, en octets, d'un indicateur de longueur/null au sein des données de la 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 d'un indicateur de copie en bloc par défaut, définissez ce paramètre sur SQL_VARLEN_DATA. Les indicateurs apparaissent directement en mémoire avant les autres données et, dans le fichier de données, juste avant les données auxquelles ils s'appliquent. Si plusieurs méthodes de spécification de la longueur de colonne d'un fichier de données sont utilisées (par exemple, un indicateur et une longueur de colonne maximale, ou un indicateur et une séquence de terminaison), la copie en bloc choisit celle qui implique la quantité de données à copier la moins élevée. 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 si la longueur des données de la colonne est variable ou si la colonne peut accepter la valeur NULL.
BCP_FMT_DATA_LEN	DBINT	Longueur, en octets, des données (longueur de colonne). Longueur maximale, en octets, des données de cette colonne dans le fichier utilisateur, hormis la longueur d'un indicateur de longueur ou d'un terminateur. La définition de BCP_FMT_DATA_LEN sur SQL_NULL_DATA indique que toutes les valeurs de la colonne du fichier de données ont ou doivent avoir la valeur NULL. La définition de BCP_FMT_DATA_LEN 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, BCP_FMT_DATA_LEN peut être SQL_VARLEN_DATA, SQL_NULL_DATA, 0 ou une valeur positive. Si BCP_FMT_DATA_LEN a la valeur SQL_VARLEN_DATA, le système utilise l'indicateur de longueur (si disponible) ou une séquence de terminaison afin de 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 BCP_FMT_DATA_LEN est SQL_VARLEN_DATA, le type de données est un caractère SQL Server ou un type binaire, et aucun indicateur de longueur ni séquence de fin n’est spécifié, le système retourne un message d’erreur. Si BCP_FMT_DATA_LEN affiche une valeur égale à 0 ou une valeur positive, le système utilise BCP_FMT_DATA_LEN comme longueur de données maximale. Toutefois, si un indicateur de longueur ou une séquence de terminaison est fourni en plus d'une valeur BCP_FMT_DATA_LEN positive, le système détermine la longueur de données en utilisant la méthode qui implique le moins de données à copier. La valeur BCP_FMT_DATA_LEN représente le nombre d'octets de données. Si des données de caractères sont représentées par des caractères Unicode larges, une valeur de paramètre BCP_FMT_DATA_LEN positive représente le nombre de caractères multiplié par la taille, en octets, de chacun des caractères.
BCP_FMT_TERMINATOR	LPCBYTE	Pointeur vers la séquence de terminaison (ANSI ou Unicode, selon les besoins) à utiliser pour cette colonne. 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.
BCP_FMT_SERVER_COL	INT	Position ordinale de la colonne dans la base de données.
BCP_FMT_COLLATION	LPCSTR	Nom du classement.

pValue
Pointeur vers la valeur à associer à la propriété. Il permet de définir individuellement chaque propriété de format de colonne.

cbvalue
Taille de la mémoire tampon de propriété, en octets.

Retours

SUCCEED ou FAIL.

Notes

Cette fonction remplace la fonction bcp_colfmt . Toutes les fonctionnalités de bcp_colfmt sont fournies dans bcp_setcolfmt fonction. Le classement des colonnes est également pris en charge. Il est préférable de définir les attributs de format de colonne suivants dans l'ordre précisé ci-dessous :

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

La fonction bcp_setcolfmt 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 :

Mappage des colonnes du fichier utilisateur avec les colonnes de la base de données
Type de données de chaque colonne du fichier utilisateur
Longueur de l'indicateur facultatif pour chaque colonne
Longueur maximale des données par colonne du 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_setcolfmt 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_setcolfmt cinq fois, avec trois de ces appels définissant votre format personnalisé. Pour les deux appels restants, définissez BCP_FMT_TYPE sur 0 et définissez BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN et cbValue 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.

La fonction bcp_columns doit être appelée avant d’appeler bcp_setcolfmt.

Vous devez appeler bcp_setcolfmt une fois pour chaque propriété de chaque colonne du fichier utilisateur.

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 attribuant la valeur 0 au paramètre BCP_FMT_SERVER_COL. Pour ignorer une colonne, vous devez spécifier son type.

La fonction bcp_writefmt peut être utilisée pour garantir la persistance du format spécifié.

Prise en charge de la fonction bcp_setcolfmt pour les fonctionnalités de date et heure améliorées

Les types utilisés avec la propriété BCP_FMT_TYPE pour les types date/heure sont spécifiés dans les 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

Partager via