bcp_colfmt

Van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

Specificeert het bron- of doelformaat van de data in een gebruikersbestand. Wanneer het als bronformaat wordt gebruikt, specificeert bcp_colfmt het formaat van een bestaand databestand dat als bron van gegevens wordt gebruikt in een bulkkopie naar een SQL Server tabel. Wanneer het als doelformaat wordt gebruikt, wordt het databestand aangemaakt met de kolomformaten die met bcp_colfmt zijn gespecificeerd.

Syntax

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

Arguments

hdbc-
Is de ODBC-verbindingshandgreep waarvoor bulksgewijs kopiëren is ingeschakeld.

idxUserDataCol
Is het ordinaal kolomnummer in het gebruikersgegevensbestand waarvoor het formaat wordt opgegeven. De eerste kolom is 1.

eUserDataType
Is het datatype van deze kolom in het gebruikersbestand. Als het verschilt van het datatype van de overeenkomstige kolom in de databasetabel (idxServerColumn), wordt de data indien mogelijk in bulk gekopieerd.

SQL Server 2005 (9.x) introduceerde ondersteuning voor SQLXML- en SQLUDT-datatypetokens in de eUserDataType-parameter.

De eUserDataType-parameter wordt geënumereerd door de SQL Server-datatypetokens in sqlncli.h, niet door de ODBC C-datatype-enumerators. Je kunt bijvoorbeeld een tekenreeks specificeren, ODBC-type SQL_C_CHAR, met het SQL Server-specifieke type SQLCHARACTER.

Om de standaard gegevensrepresentatie voor het SQL Server-datatype te specificeren, zet deze parameter op 0.

Voor een bulkkopie uit SQL Server naar een bestand, wanneer eUserDataType SQLDECIMAL of SQLNUMERIC is:

  • Als de bronkolom niet decimaal of numeriek is, worden de standaardprecisie en schaal gebruikt.

  • Als de bronkolom decimaal of numeriek is, worden de precisie en schaal van de bronkolom gebruikt.

cbIndicator
Is de lengte, in bytes, van een lengte/nul-indicator binnen de kolomgegevens. Geldige indicatorlengtewaarden zijn 0 (zonder indicator), 1, 2, 4 of 8.

Om het gebruik van de standaard bulk copy indicator te specificeren, zet deze parameter op SQL_VARLEN_DATA.

Indicatoren verschijnen in het geheugen direct vóór alle data, en in het databestand direct vóór de data waarop ze van toepassing zijn.

Als meer dan één manier wordt gebruikt om de kolomlengte van een databestand te specificeren (zoals een indicator en een maximale kolomlengte, of een indicator en een terminatorsequentie), kiest de bulkkopie degene die resulteert in de minste hoeveelheid data.

Databestanden die door bulkkopieën worden gegenereerd wanneer geen gebruikersinterventie het formaat van de data aanpast, bevatten indicatoren wanneer de kolomgegevens in lengte kunnen variëren of wanneer de kolom NULL als waarde kan accepteren.

cbUserData
Is de maximale lengte, in bytes, van de gegevens van deze kolom in het gebruikersbestand, exclusief de lengte van een lengte-indicator of terminator.

Het instellen van cbUserData op SQL_NULL_DATA geeft aan dat alle waarden in de databestandkolom zijn, of moeten worden ingesteld op NULL.

Het instellen van cbUserData op SQL_VARLEN_DATA geeft aan dat het systeem de lengte van de gegevens in elke kolom moet bepalen. Voor sommige kolommen kan dit betekenen dat een lengte/nul-indicator wordt gegenereerd om data te voorafgaan aan een kopie van SQL Server, of dat de indicator wordt verwacht in data die naar SQL Server wordt gekopieerd.

Voor SQL Server teken- en binaire datatypes kan cbUserData SQL_VARLEN_DATA, SQL_NULL_DATA, 0 of een positieve waarde zijn. Als cbUserData SQL_VARLEN_DATA, gebruikt het systeem ofwel de lengte-indicator, indien aanwezig, of een terminatorsequentie om de lengte van de data te bepalen. Als zowel een lengte-indicator als een terminatorsequentie worden geleverd, gebruikt bulk copy de sequentie die resulteert in de minimale hoeveelheid data. Als cbUserData SQL_VARLEN_DATA is, het datatype een SQL Server teken of binair type is, en er noch een lengteindicator noch een terminatorsequentie is gespecificeerd, geeft het systeem een foutmelding terug.

Als cbUserData 0 of een positieve waarde is, gebruikt het systeem cbUserData als maximale datalengte. Als echter, naast een positieve cbUserData, een lengte-indicator of terminatorsequentie wordt geleverd, bepaalt het systeem de gegevenslengte door de methode te gebruiken die resulteert in de minimale hoeveelheid data.

De cbUserData-waarde geeft het aantal bytes aan data weer Als tekengegevens worden weergegeven door Unicode-brede tekens, dan geeft een positieve cbUserData-parameterwaarde het aantal tekens vermenigvuldigd met de grootte, in bytes, van elk teken weer.

pUserDataTerm
Is de terminatorreeks die voor deze kolom moet worden gebruikt. Deze parameter is vooral nuttig voor tekendatatypes omdat alle andere typen een vaste lengte hebben of, in het geval van binaire gegevens, een lengteindicator vereisen om het aantal aanwezige bytes nauwkeurig vast te leggen.

Om te voorkomen dat de geëxtraheerde data wordt beëindigd, of om aan te geven dat gegevens in een gebruikersbestand niet worden beëindigd, zet deze parameter op NULL.

Als er meer dan één manier wordt gebruikt om een kolomlengte van een gebruikersbestand te specificeren (zoals een terminator en een lengte-indicator, of een terminator en een maximale kolomlengte), kiest de bulkkopie degene die resulteert in de minste hoeveelheid data die wordt gekopieerd.

De bulk copy API voert Unicode-naar-MBCS tekenconversie uit waar nodig. Er moet zorgvuldig op worden gelet dat zowel de terminatorbytestring als de lengte van de bytestring correct zijn ingesteld.

cbUserDataTerm
Is de lengte, in bytes, van de terminatorreeks die voor deze kolom wordt gebruikt. Als er geen terminator aanwezig of gewenst is in de data, zet deze waarde dan op 0.

idxServerCol
Is de ordinaalpositie van de kolom in de databasetabel. Het eerste kolomnummer is 1. De ordinaalpositie van een kolom wordt gerapporteerd door SQLColumns.

Als deze waarde 0 is, negeert bulk copy de kolom in het databestand.

Returns

SLAGEN OF MISLUKKEN.

Remarks

De bcp_colfmt-functie stelt je in staat het gebruikersbestandsformaat voor bulkkopieën te specificeren. Voor bulkkopieën bevat een formaat de volgende onderdelen:

  • Een mapping van kolommen in gebruikersbestanden naar databasekolommen.

  • Het datatype van elke gebruikersbestandkolom.

  • De lengte van de optionele indicator voor elke kolom.

  • De maximale lengte van gegevens per kolom in het gebruikersbestand.

  • De optionele beëindigingsbyte-sequentie voor elke kolom.

  • De lengte van de optionele terminerende bytesequentie.

Elke aanroep naar bcp_colfmt specificeert het formaat voor één kolom in het gebruikersbestand. Om bijvoorbeeld de standaardinstellingen voor drie kolommen in een gebruikersdatabestand met vijf kolommen te wijzigen, roep je eerst bcp_columns(5) aan en roep je vervolgens bcp_colfmt vijf keer aan, waarbij drie van die aanroepen je aangepaste formaat bepalen. Voor de resterende twee aanroepen zet eUserDataType op 0, en stel cbIndicator, cbUserData en cbUserDataTerm respectievelijk op 0, SQL_VARLEN_DATA en 0. Deze procedure kopieert alle vijf kolommen, drie met je aangepaste formaat en twee met het standaardformaat.

Voor cbIndicator is een waarde van 8 om een type grote waarde aan te geven nu geldig. Als het voorvoegsel wordt opgegeven voor een veld waarvan de overeenkomstige kolom een nieuw max-type is, kan het alleen op 8 worden gezet. Voor details, zie bcp_bind.

De bcp_columns functie moet worden aangeroepen voordat er aanroepen naar bcp_colfmt zijn.

Je moet bcp_colfmt één keer aanroepen voor elke kolom in het gebruikersbestand.

Het aanroepen van bcp_colfmt meer dan eens voor een gebruikersbestandkolom veroorzaakt een fout.

Je hoeft niet alle data uit een gebruikersbestand te kopiëren naar de SQL Server-tabel. Om een kolom over te slaan, specificeer je het formaat van de data voor die kolom en zet je de idxServerCol-parameter op 0. Als je een kolom wilt overslaan, moet je het type specificeren.

De bcp_writefmt-functie kan worden gebruikt om de formaatspecificatie te behouden.

bcp_colfmt Ondersteuning voor verbeterde datum- en tijdfuncties

Voor informatie over de typen die worden gebruikt met de eUserDataType-parameter voor datum-/tijdtypes, zie Bulk Copy Changes for Enhanced Date and Time Types (OLE DB en ODBC).

Zie ODBC-(Datum- en tijdverbeteringen) voor meer informatie.

Verwante onderwerpen

  • Last updated on