bcp_colfmt

gäller för:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

Specificerar källan eller målformatet för datan i en användarfil. När den används som källformat specificerar bcp_colfmt formatet för en befintlig datafil som används som källa till data i en bulkkopia till en SQL Server tabell. När datafilen används som målformat skapas den med de kolumnformat som anges med bcp_colfmt.

Syntax

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

Arguments

hdbc
Är den masskopieringsaktiverade ODBC-anslutningshandtaget.

idxUserDataCol
Är det ordinala kolumnnumret i användardatafilen för vilken formatet specificeras. Den första kolumnen är 1.

eUserDataType
Är datatypen för denna kolumn i användarfilen. Om den skiljer sig från datatypen i motsvarande kolumn i databastabellen (idxServerColumn), konverterar masskopiering datan om möjligt.

SQL Server 2005 (9.x) introducerade stöd för SQLXML- och SQLUDT-datatyptokens i eUserDataType-parametern.

eUserDataType-parametern enumereras av SQL Server-datatyptokens i sqlncli.h, inte ODBC C:s datatyp-enumeratorer. Till exempel kan du ange en teckensträng, ODBC-typ SQL_C_CHAR, med den SQL Server-specifika typen SQLCHARACTER.

För att specificera standardrepresentationen för SQL Server-datatypen, sätt denna parameter till 0.

För en bulkkopiering från SQL Server till en fil, när eUserDataType är SQLDECIMAL eller SQLNUMERIC:

  • Om källkolumnen inte är decimal eller numerisk används standardprecision och skala.

  • Om källkolumnen är decimal eller numerisk används källkolumnens precision och skala.

cbIndicator
Är längden, i bytes, för en längd/noll-indikator i kolumndatan. Giltiga indikatorlängdvärden är 0 (utan indikator), 1, 2, 4 eller 8.

För att specificera användning av standardmasskopieringsindikatorn, ställ in denna parameter till SQL_VARLEN_DATA.

Indikatorer visas i minnet direkt före all data, och i datafilen direkt före den data de gäller för.

Om mer än ett sätt att specificera kolumnlängden i datafilen används (såsom en indikator och maximal kolumnlängd, eller en indikator och en terminatorsekvens), väljer bulkkopiering det som resulterar i minst mängd data som kopieras.

Datafiler som genereras genom masskopiering när ingen användarintervention justerar formatet på datan och innehåller indikatorer när kolumndata kan variera i längd eller när kolumnen kan acceptera NULL som värde.

cbUserData
Är den maximala längden, i bytes, av denna kolumns data i användarfilen, exklusive längden på någon längdindikator eller terminator.

Att ställa in cbUserData till SQL_NULL_DATA indikerar att alla värden i datafilkolumnen är, eller bör sättas till NULL.

Att sätta cbUserData till SQL_VARLEN_DATA indikerar att systemet ska bestämma längden på data i varje kolumn. För vissa kolumner kan detta innebära att en längd-/nollindikator genereras som föregår data på en kopia från SQL Server, eller att indikatorn förväntas i data som kopieras till SQL Server.

För SQL Server tecken- och binära datatyper kan cbUserData vara SQL_VARLEN_DATA, SQL_NULL_DATA, 0 eller något positivt värde. Om cbUserData är SQL_VARLEN_DATA använder systemet antingen längdindikatorn, om den finns, eller en terminatorsekvens för att bestämma datans längd. Om både en längdindikator och en terminatorsekvens tillhandahålls, använder bulkkopiering den som resulterar i minst mängd data som kopieras. Om cbUserData är SQL_VARLEN_DATA, datatypen är en SQL Server tecken- eller binär typ, och varken en längdindikator eller terminatorsekvens specificeras, returnerar systemet ett felmeddelande.

Om cbUserData är 0 eller ett positivt värde använder systemet cbUserData som maximal datalängde. Om däremot, utöver en positiv cbUserData, finns en längdindikator eller terminatorsekvens, bestämmer systemet datans längd genom att använda den metod som ger minst mängd data som kopieras.

Värdet cbUserData representerar antalet bytes data. Om teckendata representeras av Unicode-breda tecken, representerar ett positivt cbUserData-parametervärde antalet tecken multiplicerat med storleken, i bytes, för varje tecken.

pUserDataTerm
Är terminatorsekvensen som ska användas för denna kolumn. Denna parameter är främst användbar för teckendatatyper eftersom alla andra typer har fast längd eller, i fallet med binär data, kräver en längdindikator för att korrekt registrera antalet byte som finns.

För att undvika att avsluta extraherad data, eller för att indikera att data i en användarfil inte termineras, sätt denna parameter till NULL.

Om mer än ett sätt att specificera en användarfils kolumnlängd används (såsom en terminator och en längdindikator, eller en terminator och maximal kolumnlängd), väljer bulkkopieringen det som resulterar i minst mängd data som kopieras.

Bulkkopierings-API:et utför Unicode-till-MBCS-teckenkonvertering vid behov. Man måste vara försiktig så att både terminatorbytesträngen och bytesträngens längd är korrekt inställda.

cbUserDataTerm
Är längden, i bytes, på terminatorsekvensen som ska användas för denna kolumn. Om ingen terminator finns eller önskas i datan, sätt detta värde till 0.

idxServerCol
Är kolumnens ordinala position i databastabellen. Det första kolumnnumret är 1. Kolumnens ordinala position rapporteras av SQLColumns.

Om detta värde är 0, ignorerar bulkkopiering kolumnen i datafilen.

Returns

SUCCEED eller FAIL.

Remarks

Funktionen bcp_colfmt låter dig ange användarfilformatet för masskopior. För bulkkopiering innehåller ett format följande delar:

  • En mappning från användarfilkolumner till databaskolumner.

  • Datatypen för varje användarfilkolumn.

  • Längden på den valfria indikatorn för varje kolumn.

  • Den maximala längden av data per användarfilkolumn.

  • Den valfria avslutningsbytesekvensen för varje kolumn.

  • Längden på den valfria terminerande bytesekvensen.

Varje anrop till bcp_colfmt specificerar formatet för en användarfilkolumn. Till exempel, för att ändra standardinställningarna för tre kolumner i en femkolumnig användardatafil, anropa först bcp_columns(5) och sedan bcp_colfmt fem gånger, där tre av dessa anrop sätter ditt anpassade format. För de återstående två anropen, sätt eUserDataType till 0, och ställ in cbIndicator, cbUserData och cbUserDataTerm till 0, SQL_VARLEN_DATA respektive 0. Denna procedur kopierar alla fem kolumner, tre med ditt anpassade format och två med standardformatet.

För cbIndicator är ett värde på 8 för att indikera en stor värdetyp nu giltigt. Om prefixet anges för ett fält vars motsvarande kolumn är en ny maxtyp, kan det endast sättas till 8. För detaljer, se bcp_bind.

Funktionen bcp_columns måste anropas innan några anrop till bcp_colfmt.

Du måste anropa bcp_colfmt en gång för varje kolumn i användarfilen.

Att anropa bcp_colfmt mer än en gång för någon användarfilkolumn orsakar ett fel.

Du behöver inte kopiera all data i en användarfil till SQL Server-tabellen. För att hoppa över en kolumn, ange formatet på datan för kolumnen och sätt idxServerCol-parametern till 0. Om du vill hoppa över en kolumn måste du ange dess typ.

Funktionen bcp_writefmt kan användas för att behålla formatspecifikationen.

bcp_colfmt Stöd för förbättrade datum- och tidsfunktioner

För information om vilka typer som används med parametern eUserDataType för datum/tid-typer, se Bulk Copy Changes for Enhanced Date and Time Types (OLE DB och ODBC).

Mer information finns i Förbättringar av datum och tid (ODBC).

Relaterat innehåll

  • Uppdaterades senast