Linee guida per la programmazione

Scaricare il driver ODBC

Questo articolo descrive considerazioni di programmazione per applicazioni che utilizzano il driver Microsoft ODBC per SQL Server in Linux o macOS. Alcuni link fanno riferimento a materiale di SQL Server Native Client. Queste pagine forniscono un contesto storico dell'API.

Scegli una versione del driver

Usa il driver ODBC 18 di Microsoft per SQL Server, l'attuale linea di driver, per nuovi sviluppi. Il driver ODBC 17 di Microsoft per SQL Server rimane supportato per applicazioni che già lo distribuiscono, come descritto nel ciclo di vita del supporto. ODBC Driver 13, fornito con SQL Server 2017, è idoneo per un supporto esteso fino al 12 ottobre 2027, solo in base a un accordo di supporto esteso.

Specifica il nome del driver installato nella tua stringa di connessione, tra parentesi graffe:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

In un nome di origine dati (DSN) in odbc.ini, usa il nome senza parentesi graffe, ad esempio Driver = ODBC Driver 18 for SQL Server. Per la sintassi DSN, vedi Parole chiave della stringa di connessione e nomi delle sorgenti dati (DSN).

Per le impostazioni di connessione specifiche della versione, vedi Differenze tra versioni principali. Per le date di supporto e la compatibilità del sistema operativo, vedi ciclo di vita del supporto e requisiti di sistema.

Costruisci un'applicazione

Per i percorsi dei file di intestazione, inclusi l'ordine, i comandi del compilatore, i nomi delle librerie e un esempio di C++, vedi Sviluppa applicazioni C e C++ con il driver ODBC e Connettersi ed eseguire query con C++ e ODBC.

Un'applicazione ODBC può utilizzare Multiple Active Result Sets (MARS) e altre funzionalità specifiche di SQL Server includendo msodbcsql.h dopo le intestazioni unixODBC (sql.h, sqlext.h, sqltypes.h, e sqlucode.h). Usa gli stessi nomi simbolici per gli elementi specifici di SQL Server che usi nelle applicazioni ODBC di Windows.

Trova le funzionalità del driver

Inizia con il ODBC Programmer's Reference per l'interfaccia standard di programmazione applicativa (API). Poi usa la documentazione attuale del driver per il comportamento specifico del driver.

La panoramica del driver Microsoft ODBC per SQL Server è collegata alla documentazione dei driver. I seguenti articoli SQL Server Native Client forniscono il contesto API per applicazioni che utilizzano il driver su Linux e macOS:

• Comunicazione con SQL Server (ODBC)
• Supporto per i timeout di connessione e delle query
• Cursori
• Miglioramenti data/ora (ODBC)
• Esecuzione di query (ODBC)
• Gestione di errori e messaggi
• Autenticazione Kerberos
• Grandi tipi definiti dall'utente Common Language Runtime (CLR) (ODBC)
• Eseguire transazioni (ODBC). Per le transazioni distribuite su Linux e macOS, usa le transazioni XA con DTC.
• Elaborazione dei risultati (ODBC)
• Esecuzione di stored procedure
• Supporto per colonne sparse (ODBC)
• Utilizzo della crittografia senza validazione
• Parametri con valori di tabella
• UTF-8 e UTF-16 per l'API di comandi e dati
• Utilizzo delle funzioni di catalogo

Limitazioni

Le seguenti funzionalità non sono state verificate come funzionanti correttamente nel driver ODBC su Linux e macOS:

• Connessione al cluster di failover.
• Risoluzione IP di rete trasparente precedente a ODBC Driver 17.
• Tracciamento Built-In Diagnostics (BID) del driver ODBC in Linux e macOS prima del driver ODBC 17.3.

Funzionalità non supportate

Le seguenti funzionalità non sono disponibili nel driver ODBC su Linux e macOS:

• Transazioni distribuite tramite l'attributo SQL_ATTR_ENLIST_IN_DTC . Il driver supporta transazioni XA tramite il Microsoft Distributed Transaction Coordinator (DTC). Per maggiori informazioni, vedi Usare le transazioni XA con DTC.

• Mirroring di database

• FILESTREAM.

• Profilazione delle prestazioni dei driver ODBC, discussa in SQLSetConnectAttr, e questi attributi di connessione correlati alle prestazioni:

  • SQL_COPT_SS_PERF_DATA
  • SQL_COPT_SS_PERF_DATA_LOG
  • SQL_COPT_SS_PERF_DATA_LOG_NOW
  • SQL_COPT_SS_PERF_QUERY
  • SQL_COPT_SS_PERF_QUERY_INTERVAL
  • SQL_COPT_SS_PERF_QUERY_LOG

• SQLBrowseConnect prima della versione 17.2.

• Tipi di intervalli C come SQL_C_INTERVAL_YEAR_TO_MONTH, documentati in Data Type Identifiers and Descriptors.

• Il valore di SQL_CUR_USE_ODBC dell'attributo SQL_ATTR_ODBC_CURSORS di SQLSetConnectAttr.

Gestire i dati dei caratteri

Su Linux e macOS, usa buffer UTF-16 SQLWCHAR con API ODBC a carattere ampio invece del tipo nativo wchar_t . L'interfaccia driver utilizza unità di codice a 16 bit.

Codifiche dei caratteri

Per i driver ODBC 13 e 13.1, devi usare UTF-8 per i SQLCHAR dati. Queste versioni non supportano altre codifiche.

A partire dal driver ODBC 17, i set di caratteri e le codifiche supportate per SQLCHAR i dati includono:

Quando ti connetti, il driver rileva le impostazioni locali correnti del processo in cui è stato caricato. Se le impostazioni locali utilizzano una delle codifiche elencate, il driver utilizza quella codifica per i dati SQLCHAR (a caratteri stretti). Altrimenti, il predefinito è UTF-8. I processi iniziano di default nel C locale, il che fa sì che il driver passi di default a UTF-8. Se un'applicazione ha bisogno di una delle codifica elencate, chiama setlocale prima di connettersi. Specifica esplicitamente le impostazioni locali, oppure usa una stringa vuota (ad esempio, setlocale(LC_ALL, "")) per utilizzare le impostazioni locali dell'ambiente.

In un tipico ambiente Linux o macOS dove la codifica è UTF-8, gli utenti del driver ODBC 17 che aggiornano da 13 o 13.1 non noteranno differenze. Le applicazioni che utilizzano una codifica setlocale non UTF-8 elencata devono utilizzare quella codifica per i dati da e verso il driver invece di UTF-8.

Devi usare UTF-16LE (little endian) per i SQLWCHAR dati.

Quando associ i parametri di input usando SQLBindParameter, se specifichi un tipo SQL a caratteri stretti come SQL_VARCHAR, il driver converte i dati forniti dalla codifica client alla codifica lato server per quel parametro. La codifica dipende dalla collazione; non è sempre la tabella codici 1252. Per i parametri di output il driver esegue la conversione dalla codifica specificata nelle informazioni delle regole di confronto associate ai dati alla codifica del client. I caratteri nella codifica sorgente che non sono rappresentabili nella codifica target si convertono in un punto interrogativo (?).

Per evitare questa perdita di dati quando si legano i parametri di input, specificare un tipo di carattere Unicode SQL come SQL_WVARCHAR. Il driver converte la codifica client in UTF-16, che può rappresentare tutti i caratteri Unicode. La colonna o parametro di destinazione deve essere anche un tipo Unicode (nchar, nvarchar o ntext) o un tipo con collazione o codifica che possa rappresentare tutti i dati sorgente originali. Per i parametri di output, si specifica un tipo SQL Unicode e o un tipo C Unicode (SQL_C_WCHAR), che fa sì che il driver restituisca i dati come UTF-16, oppure un tipo C stretto con una codifica client che può rappresentare i dati sorgente. UTF-8 può sempre rappresentare questi dati.

Per maggiori informazioni su collation e codifica, vedi Collation e supporto Unicode.

Ci sono differenze di conversione tra le versioni di Windows e Linux o macOSiconv:

• Per la code page 1255, il byte 0xCA si converte in punto 0x05BA codice UTF-16 su Windows e 0x00CA su macOS e Linux con libiconv versioni precedenti alla 1.15.
• Le librerie Linux iconv senza la revisione del 2003 di Big5/CP950 (BIG5-2003) non convertono correttamente i caratteri aggiunti in quella revisione.
• Per la code page 932 (giapponese, Shift-JIS), la decodifica dei caratteri non definiti nello standard di codifica differisce. Ad esempio, byte 0x80 si converte in U+0080 su Windows e potrebbe diventare U+30FB su Linux e macOS, a seconda della iconv versione.

Nei driver ODBC 13 e 13.1, la divisione dei caratteri multibyte UTF-8 o dei surrogati UTF-16 tra SQLPutData i buffer provoca corruzione dei dati. Usa buffer di streaming che non terminino con codifiche parziali dei caratteri. Questa limitazione è stata rimossa nel Driver 17 di ODBC.

Per la codifica dei caratteri, la conversione, il binding dei parametri e le indicazioni sul buffer-size, vedi Problemi noti.

OpenSSL

A partire dal driver ODBC 17.4, il driver carica OpenSSL dinamicamente, il che gli consente di funzionare su sistemi con versione 1.0 o 1.1 senza file driver separati. A partire dalla versione 17.9, il driver supporta OpenSSL 3.0 oltre alle versioni precedenti. Quando sono presenti più versioni di OpenSSL, il driver tenta di caricare una versione supportata dai suoi percorsi di ricerca delle librerie.

OpenSSL 4 non è supportato. Su macOS, un collegamento homebrew openssl che punta a OpenSSL 4 può impedire al driver di caricare OpenSSL anche quando OpenSSL 3 è installato. Controlla il percorso della libreria così come le versioni installate.

Alpine Linux

La dimensione predefinita dello stack per i nuovi thread in musl è di 128 KB, a meno che l'eseguibile non richieda una dimensione predefinita dello stack maggiore. Un thread può superare questo limite quando viene chiamato dal driver. Collega un'applicazione ODBC su Alpine Linux con -Wl,-z,stack-size=<size_in_bytes> per richiedere uno stack di thread predefinito più grande. Le applicazioni che creano thread con una dimensione di stack esplicita devono anche scegliere una dimensione adeguata per quei thread.

Lo stack del thread principale e quello predefinito per i nuovi thread non sono la stessa impostazione. Nei glibc sistemi, il default per i nuovi thread normalmente segue il limite di risorse dello stack del processo, con un fallback specifico per architettura quando tale limite è illimitato. Non dare per scontato un valore predefinito fisso di 2 MB su sistemi Linux.

Note aggiuntive

Per creare una connessione amministratore dedicata (DAC) da un'applicazione ODBC, imposta Server=tcp:<server>,<dac_port> nella stringa di connessione. Usa la porta DAC scoperta, non la porta di connessione normale dell'istanza. Ad esempio, se la porta DAC è 33000, imposta Server=tcp:<server>,33000. Questi frammenti di stringa di connessione specificano solo l'endpoint, non l'autenticazione. Configurare l'autenticazione e la validazione del certificato server separatamente.

Il login deve essere un membro del sysadmin ruolo server. L'accesso remoto richiede che l'opzione di connessione amministrativa remota del server sia abilitata. Per i requisiti di accesso, la configurazione del server e le procedure di amministrazione in linea di comando, vedi Connessione diagnostica per amministratori di database. Per la scoperta delle porte, vedi la porta DAC.

Il driver manager unixODBC gestisce gli attributi dell'istruzione statement passati tramite SQLSetConnectAttr nello stesso modo del Windows Driver Manager. Le opzioni di statement ODBC 2.x, come SQL_ATTR_QUERY_TIMEOUT e SQL_ATTR_MAX_ROWS, si applicano sia agli statement esistenti che ai nuovi sulla connessione. Gli attributi ODBC 3.x solo per istruzioni, come SQL_ATTR_ROW_ARRAY_SIZE e SQL_ATTR_PARAMSET_SIZE, restituiscono SQLSTATE HY092. Gli attributi definiti sia a livello di connessione che di istruzione, come SQL_ATTR_METADATA_ID, possono essere impostati a entrambi i livelli. Impostare attributi validi solo per l'istruzione a livello di connessione è obsoleto in ODBC 3.x, quindi chiama SQLSetStmtAttr invece. Per ulteriori informazioni, vedi la funzione SQLSetConnectAttr.

In applicazioni altamente multithread, la validazione dei handle unixODBC potrebbe diventare un collo di bottiglia delle prestazioni. Compilare unixODBC con --enable-fastvalidate potrebbe migliorare le prestazioni. Tuttavia, questa opzione potrebbe causare il crash delle applicazioni che passano handle non validi alle API ODBC invece di restituire SQL_INVALID_HANDLE.

Per i passaggi di installazione e configurazione della piattaforma, vedi:

• Installa il driver ODBC su Linux.
• Installa il driver ODBC su macOS.
• Installa il gestore driver unixODBC.
• Configura stringhe di connessione e DSN.
• Rivedi i requisiti di sistema.

Contenuti correlati

• Domande frequenti su ODBC su Linux e macOS
• Note di rilascio per il driver Microsoft ODBC per SQL Server in Linux e macOS