bcp_init

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_initszTable 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.

Restituisce

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 di 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 il file di dati. bcp_init specifica i valori del formato dati per il file di dati in base a ogni colonna della vista o della tabella di database oppure del 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, nonché la larghezza dei tipi di dati a lunghezza fissa. bcp_init imposta tali 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 Ottimizzazione delle prestazioni dell'importazione bulk e ALTER DATABASE.

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

Esempio

// compile with: odbc32.lib sqlncli10.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);
}

Cronologia modifiche

Vedere anche

Riferimento