bcp_init

Inizializza l'operazione di copia bulk.

Sintassi

RETCODE bcp_init ( 
        HDBC hdbc, 
        LPCTSTR szTable, 
        LPCTSTR szDataFile, 
        LPCTSTR szErrorFile, 
        INT eDirection);

Argomenti

  • hdbc
    Handle di connessione ODBC abilitato per la copia bulk.

  • szTable
    Nome della tabella di database per la copia interna o esterna. Il nome può includere anche il nome del database o del proprietario, ad esempio pubs.gracie.titles, pubs..titles, gracie.titles e titles sono tutti nomi di tabella validi.

    Se eDirection è DB_OUT, szTable può essere anche il nome di una vista di database.

    Se eDirection è DB_OUT e viene specificata un'istruzione SELECT utilizzando bcp_control prima che venga chiamato bcp_exec, bcp_init szTable deve essere impostato su NULL.

  • szDataFile
    Nome del file utente per la copia interna o esterna. Se i dati sono copiati direttamente dalle variabili tramite bcp_sendrow, impostare szDataFile su NULL.

  • szErrorFile
    Nome del file degli errori in cui inserire messaggi di stato, messaggi di errore e copie delle righe che per qualche motivo non è stato possibile copiare da un file utente in una tabella. Se NULL viene passato come szErrorFile, non viene utilizzato alcun file degli errori.

  • eDirection
    Direzione della copia, ovvero DB_IN oppure DB_OUT. DB_IN indica una copia da variabili di programma o da un file utente a una tabella. DB_OUT indica una copia da una tabella di database a un file utente. È necessario specificare un nome di file utente con DB_OUT.

Valori restituiti

SUCCEED o FAIL.

Osservazioni

Chiamare bcp_init prima di chiamare qualsiasi altra funzione di copia bulk. bcp_init esegue le inizializzazioni necessarie per una copia bulk dei dati tra la workstation e SQL Server.

La funzione bcp_init deve essere fornita con un handle di connessione ODBC abilitato per l'utilizzo con le funzioni di copia bulk. Per abilitare l'handle, utilizzare SQLSetConnectAttr con SQL_COPT_SS_BCP impostato su SQL_BCP_ON su un handle di connessione allocato ma non collegato. Il tentativo di assegnare l'attributo su un handle collegato comporta un errore.

Quando viene specificato un file di dati, bcp_init esamina la struttura dell'origine del database o della tabella di destinazione, non del file di dati. bcp_init specifica i valori relativi al formato dei dati per il file di dati in base a ogni colonna nella vista o nella tabella di database o nel set di risultati SELECT. Questa specifica include il tipo di dati di ogni colonna, la presenza o meno di un indicatore di lunghezza o Null e di stringhe di byte con carattere di terminazione nei dati e la larghezza dei tipi di dati a lunghezza fissa. bcp_init imposta questi valori nel modo seguente:

  • Il tipo di dati specificato è quello della colonna della vista o della tabella di database oppure del set di risultati SELECT. Il tipo di dati viene enumerato in base ai tipi di dati nativi di SQL Server specificati in sqlncli.h. I dati vengono rappresentati nel relativo formato elettronico, ovvero i dati di una colonna di un tipo di dati integer vengono rappresentati da una sequenza a quattro byte, di tipo big o little_endian a seconda del computer con il quale è stato creato il file di dati.

  • Se un tipo di dati del database ha una lunghezza fissa, anche i dati del file di dati presenteranno una lunghezza fissa. Le funzioni di copia bulk che elaborano dati, ad esempio bcp_exec, analizzano le righe di dati prevedendo che la lunghezza dei dati nel file di dati sia identica alla lunghezza dei dati specificata nella vista o nella tabella di database o nell'elenco di colonne SELECT. I dati di una colonna di database definiti come char(13) devono, ad esempio, essere rappresentati da 13 caratteri per ogni riga di dati presente nel file. I dati a lunghezza fissa possono essere preceduti da un indicatore Null se la colonna del database consente valori Null.

  • Quando viene definita la sequenza di byte con caratteri di terminazione, la lunghezza di tale sequenza è impostata su 0.

  • Quando si esegue la copia in SQL Server, il file di dati deve includere dati per ogni colonna della tabella di database. Quando si esegue la copia da SQL Server, i dati di tutte le colonne della vista o della tabella di database o del set di risultati SELECT vengono copiati nel file di dati.

  • Quando si esegue la copia dati di in SQL Server, la posizione ordinale di una colonna nel file di dati deve essere identica alla posizione ordinale della colonna nella tabella di database. Quando si esegue la copia da SQL Server, bcp_exec dispone i dati in base alla posizione ordinale della colonna nella tabella di database.

  • Se un tipo di dati del database ha una lunghezza variabile, ad esempio varbinary(22), o se una colonna del database può contenere valori Null, i dati nel file di dati sono preceduti da un indicatore di lunghezza o Null. La larghezza dell'indicatore varia in base al tipo di dati e alla versione della copia bulk.

Per modificare i valori del formato di dati specificati per un file di dati, chiamare bcp_columns e bcp_colfmt.

Le copie bulk eseguite in SQL Server possono essere ottimizzate per le tabelle che non contengono indici impostando il modello di recupero del database su SIMPLE o BULK_LOGGED. Per ulteriori informazioni, vedere Prerequisiti per la registrazione minima nell'importazione bulk e ALTER DATABASE.

Se non viene utilizzato alcun file di dati, è necessario chiamare bcp_bind per specificare il formato e il percorso in memoria dei dati per ogni colonna, quindi copiare le righe di dati in SQL Server utilizzando bcp_sendrow.

Esempio

In questo esempio viene illustrato come utilizzare la funzione ODBC bcp_init con un file di formato.

Prima di compilare ed esegue il codice C++, è necessario effettuare le operazioni seguenti:

  • Creare un'origine dati ODBC denominata Test. È possibile associare questa origine dati a qualsiasi database.

  • Eseguire sul database l'istruzione Transact-SQL seguente:

    CREATE TABLE BCPDate (cola int, colb datetime);
    
  • Nella directory in cui verrà eseguita l'applicazione aggiungere un file denominato Bcpfmt.fmt e aggiungervi il codice seguente:

    8.0
    2
    1SQLCHAR04"\t"1colaSQL_Latin1_General_Cp437_Bin
    2SQLCHAR08"\r\n"2colbSQL_Latin1_General_Cp437_Bin
    
  • Nella directory in cui verrà eseguita l'applicazione aggiungere un file denominato Bcpodbc.bcp e aggiungervi il codice seguente:

    1
    2
    

A questo punto è possibile compilare ed eseguire il codice C++.

// compile with: odbc32.lib sqlncli11.lib
#include <stdio.h>
#include <windows.h>
#include <sql.h>
#include <sqlext.h>
#include <odbcss.h>

SQLHENV henv = SQL_NULL_HENV;
HDBC hdbc1 = SQL_NULL_HDBC; 

void Cleanup() {
   if (hdbc1 != SQL_NULL_HDBC) {
      SQLDisconnect(hdbc1);
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
   }

   if (henv != SQL_NULL_HENV)
      SQLFreeHandle(SQL_HANDLE_ENV, henv);
}

int main() {
   RETCODE retcode;
   SDWORD cRows;

   // Allocate the ODBC environment and save handle.
   retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
      printf("SQLAllocHandle(Env) Failed\n\n");
      Cleanup();
      return(9);
   }

   // Notify ODBC that this is an ODBC 3.0 app.
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
      printf("SQLSetEnvAttr(ODBC version) Failed\n\n");
      Cleanup();
      return(9);    
   }

   // Allocate ODBC connection handle, set BCP mode, and connect.
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
      printf("SQLAllocHandle(hdbc1) Failed\n\n");
      Cleanup();
      return(9);
   }

   retcode = SQLSetConnectAttr(hdbc1, SQL_COPT_SS_BCP, (void *)SQL_BCP_ON, SQL_IS_INTEGER);
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
      printf("SQLSetConnectAttr(hdbc1) Failed\n\n");
      Cleanup();
      return(9);
   }

   // Sample uses Integrated Security. Create SQL Server DSN using Windows NT authentication.
   retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"", SQL_NTS, (UCHAR*)"", SQL_NTS);
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
      printf("SQLConnect() Failed\n\n");
      Cleanup();
      return(9);
   }

   // Initialize the bulk copy.
   retcode = bcp_init(hdbc1, "BCPDate", "BCPODBC.bcp", NULL, DB_IN);
   if ( (retcode != SUCCEED) ) {
      printf("bcp_init(hdbc1) Failed\n\n");
      Cleanup();
      return(9);
   }

   // Read the format file.
   retcode = bcp_readfmt(hdbc1, "BCPFMT.fmt");
   if ( (retcode != SUCCEED) ) {
      printf("bcp_readfmt(hdbc1) Failed\n\n");
      Cleanup();
      return(9);
   }

   // Execute the bulk copy.
   retcode = bcp_exec(hdbc1, &cRows);
   if ( (retcode != SUCCEED) ) {
      printf("bcp_exec(hdbc1) Failed\n\n");
      Cleanup();
      return(9);
   }

   printf("Number of rows bulk copied in = %d.\n", cRows);

   // Cleanup
   SQLDisconnect(hdbc1);
   SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
   SQLFreeHandle(SQL_HANDLE_ENV, henv);
}

Vedere anche

Riferimento

Funzioni di copia bulk