bcp_setcolfmt
La fonction bcp_setcolfmt remplace la fonction bcp_colfmt. Vous devez utiliser la fonction bcp_setcolfmt pour le classement des colonnes.
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 à la fonction 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. Dans le cas du format source, bcp_setcolfmt spécifie le format d'un fichier de données existant utilisé comme source de données lors d'une copie en bloc dans une table SQL Server. Au format cible, le fichier de données est créé à l'aide des formats de colonne définis à l'aide de la fonction 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.property
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 (type de données ODBC SQL_C_CHAR) à l'aide du type SQLCHARACTER propre à SQL Server.
Pour spécifier la représentation des données par défaut pour le type de données SQL Server, attribuez la valeur 0 à ce paramètre.
Pour une copie en bloc dans un fichier hors SQL Server, 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.
Si la colonne source est décimale ou numérique, sa précision et son échelle propres 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 dans 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 SQL Server character et binary, BCP_FMT_DATA_LEN peut avoir comme valeur SQL_VARLEN_DATA, SQL_NULL_DATA, 0 ou une valeur positive quelconque. 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 a la valeur SQL_VARLEN_DATA, si le type de données est un type SQL Server character ou binary et si aucun indicateur de longueur ou séquence de terminaison 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
Longueur, en octets, de la mémoire tampon de propriété.
Valeurs retournées
SUCCEED ou FAIL.
Notes
Cette fonction remplace la fonction bcp_colfmt. Toutes les fonctionnalités de bcp_colfmt sont proposées dans la fonction bcp_setcolfmt. 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 du 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 à la fonction bcp_setcolfmt spécifie le format d'une colonne du fichier utilisateur. Par exemple, pour modifier les paramètres par défaut de trois colonnes dans un fichier de données utilisateur de cinq colonnes, appelez d'abord bcp_columns(5), puis la fonction bcp_setcolfmt cinq fois, trois de ces appels définissant votre format personnalisé. Pour les deux appels restants, définissez BCP_FMT_TYPE sur 0, puis définissez respectivement BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN et cbValue sur 0, SQL_VARLEN_DATA et 0. Cette procédure copie les cinq colonnes, trois avec votre format personnalisé et deux avec le format par défaut.
Vous devez appeler la fonction bcp_columns avant d'appeler bcp_setcolfmt.
Vous devez appeler bcp_setcolfmt une fois pour chaque propriété de chaque colonne dans le 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 apparaissent tels qu'ils sont spécifiés dans Modifications de copie en bloc pour les types date/heure améliorés (OLE DB et ODBC).
Pour plus d'informations, consultez Améliorations de la date et de l'heure (ODBC).