Parole chiave e attributi per stringhe di connessione e DSN
Questa pagina elenca le parole chiave per le stringhe di connessione e i DSN e gli attributi di connessione per SQLSetConnectAttr e SQLGetConnectAttr, disponibili nel driver ODBC per SQL Server.
Parole chiave per DSN/stringa di connessione e attributi di connessione supportati
La tabella seguente elenca le parole chiave e gli attributi disponibili per ogni piattaforma (L: Linux ; M: macOS; W: Windows). Selezionare la parola chiave o l'attributo per altri dettagli.
Di seguito sono elencati alcuni attributi di connessione e parole chiave delle stringhe di connessione non documentati in Uso di parole chiave per le stringhe di connessione con SQL Server Native Client, SQLSetConnectAttr e Funzione SQLSetConnectAttr.
Descrizione
Consentono di descrivere l'origine dati.
SQL_COPT_SS_ANSI_OEM
Controlla la conversione dei dati da ANSI a OEM.
| Valore attributo | Descrizione |
|---|---|
| SQL_AO_OFF | (Impostazione predefinita) La conversione non viene eseguita. |
| SQL_AO_ON | La conversione viene eseguita. |
SQL_COPT_SS_AUTOBEGINTXN
Versione 17.6+ Quando il commit automatico è disattivato, controlla l'istruzione BEGIN TRANSACTION automatica dopo ROLLBACK o COMMIT.
| Valore attributo | Descrizione |
|---|---|
| SQL_AUTOBEGINTXN_ON | (Impostazione predefinita) Istruzione BEGIN TRANSACTION automatica dopo ROLLBACK o COMMIT. |
| SQL_AUTOBEGINTXN_OFF | Nessuna istruzione BEGIN TRANSACTION automatica dopo ROLLBACK o COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Controlla l'uso delle connessioni di fallback di SQL Server. Non è più supportata.
| Valore attributo | Descrizione |
|---|---|
| SQL_FB_OFF | (Impostazione predefinita) Le connessioni di fallback sono disabilitate. |
| SQL_FB_ON | Le connessioni di fallback sono abilitate. |
Nuove parole chiave delle stringhe di connessione e nuovi attributi di connessione
Authentication - SQL_COPT_SS_AUTHENTICATION
Imposta la modalità di autenticazione da usare durante la connessione a SQL Server. Per maggiori informazioni, vedere la sezione Come utilizzare Microsoft Entra ID.
| Valore della parola chiave | Valore attributo | Descrizione |
|---|---|---|
| SQL_AU_NONE | (Impostazione predefinita) Non impostata. La combinazione di altri attributi determina la modalità di autenticazione. | |
| SqlPassword | SQL_AU_PASSWORD | Autenticazione di SQL Server con nome utente e password. |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Autenticazione integrata di Microsoft Entra. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Autenticazione password di Microsoft Entra. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Autenticazione interattiva di Microsoft Entra. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Autenticazione di identità gestita di Microsoft Entra. Per l'identità assegnata dall'utente, UID è impostato sull'ID oggetto dell'identità utente. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Autenticazione dell’entità servizio di Microsoft Entra. UID è l'ID client dell'entità servizio. PWD è il segreto client. |
| SQL_AU_RESET | Non impostata. Esegue l'override di qualsiasi impostazione del DSN o della stringa di connessione. |
Nota
Quando si usa la parola chiave Authentication o l'attributo, impostare in modo esplicito l'impostazione Encrypt sul valore desiderato nella stringa di connessione, nel DSN o nell'attributo di connessione. Per informazioni dettagliate, vedere Uso delle parole chiave delle stringhe di connessione con SQL Server Native Client.
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
Controlla la crittografia di colonna trasparente (Always Encrypted). Per altre informazioni vedere Uso di Always Encrypted (ODBC).
| Valore della parola chiave | Valore attributo | Descrizione |
|---|---|---|
| Attivata | SQL_CE_ENABLED | Abilita Always Encrypted. |
| Disabilitata | SQL_CE_DISABLED | (Impostazione predefinita) Disabilita Always Encrypted. |
| SQL_CE_RESULTSETONLY | Abilita solo la decrittografia (risultati e valori restituiti). |
Encrypt
Specifica se le connessioni usano la crittografia TLS nella rete. I valori possibili sono yes/mandatory (18.0+), no/optional (18.0+) e strict (18.0+). Il valore predefinito è yes nella versione 18.0+ e no nelle versioni precedenti.
Indipendentemente dall'impostazione di Encrypt, le credenziali di accesso al server (nome utente e password) vengono sempre crittografate.
Le impostazioni Encrypt, TrustServerCertificate e Force Encryption (lato server) determinano se le connessioni sono crittografate nella rete. Le tabelle seguenti mostrano l'effetto di queste impostazioni.
ODBC Driver 18 e versioni successive
| Impostazione di crittografia | TrustServerCertificate | Crittografia richiesta dal server | Risultato |
|---|---|---|---|
| No | No | No | Il certificato del server non viene controllato. I dati inviati tra client e server non vengono crittografati. |
| No | Sì | No | Il certificato del server non viene controllato. I dati inviati tra client e server non vengono crittografati. |
| Sì | No | No | Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | Sì | No | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| No | No | Sì | Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
| No | Sì | Sì | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | No | Sì | Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | Sì | Sì | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Strict | - | - | L'opzione TrustServerCertificate viene ignorata. Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
Nota
L'impostazione Strict è disponibile solo per i server che supportano le connessioni TDS 8.0.
ODBC Driver 17 e versioni precedenti
| Impostazione di crittografia | TrustServerCertificate | Crittografia richiesta dal server | Risultato |
|---|---|---|---|
| No | No | No | Il certificato del server non viene controllato. I dati inviati tra client e server non vengono crittografati. |
| No | Sì | No | Il certificato del server non viene controllato. I dati inviati tra client e server non vengono crittografati. |
| Sì | No | No | Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | Sì | No | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| No | No | Sì | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| No | Sì | Sì | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | No | Sì | Il certificato del server viene verificato. I dati inviati dal client al server e viceversa vengono crittografati. |
| Sì | Sì | Sì | Il certificato del server non viene controllato. I dati inviati dal client al server e viceversa vengono crittografati. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
Controlla la funzionalità Risoluzione dell'IP di rete trasparente che interagisce con MultiSubnetFailover per consentire tentativi di riconnessione più rapidi. Per altre informazioni vedere Uso della risoluzione dell'IP di rete trasparente.
| Valore della parola chiave | Valore attributo | Descrizione |
|---|---|---|
| Attivata | SQL_IS_ON | (Impostazione predefinita) Abilita la risoluzione dell'IP di rete trasparente. |
| Disabilitata | SQL_IS_OFF | Disabilita la risoluzione dell'IP di rete trasparente. |
UseFMTONLY
Controlla l'uso di SET FMTONLY per i metadati durante la connessione a SQL Server 2012 e versioni successive.
| Valore della parola chiave | Descrizione |
|---|---|
| No | (Impostazione predefinita) Usare sp_describe_first_result_set per i metadati, se disponibili. |
| Sì | Usare SET FMTONLY per i metadati. |
Replica
Specifica l'uso di un account di accesso per la replica in ODBC Driver 17.8 e versioni successive.
| Valore della parola chiave | Descrizione |
|---|---|
| No | (Impostazione predefinita) L'account di accesso alla replica non viene usato. |
| Sì | I trigger con l'opzione NOT FOR REPLICATION non vengono attivati nella connessione. |
RetryExec
La logica di ripetizione dei tentativi configurabile è disponibile a partire dalla versione 18.1. Consente di ripetere automaticamente l'esecuzione di chiamate di funzione ODBC specifiche in base a condizioni configurabili. Questa funzionalità può essere abilitata tramite la stringa di connessione usando la parola chiave RetryExec insieme a un elenco di regole di ripetizione dei tentativi. Ogni regola di ripetizione dei tentativi include tre componenti separati da due punti: una corrispondenza di errore, criteri di ripetizione e una corrispondenza di query.
La corrispondenza di query determina la regola di ripetizione dei tentativi da usare per un'esecuzione specifica e la corrispondenza viene cercata confrontando il testo del comando in ingresso (SQLExecDirect) o il testo del comando preparato nell'oggetto istruzione (SQLExecute). Se viene trovata la corrispondenza con più di una regola, viene usata la prima corrispondenza nell'elenco. Questo comportamento consente alle regole di essere elencate in ordine crescente di genericità. Se non viene trovata la corrispondenza con nessuna regola, non viene applicata alcuna logica di ripetizione dei tentativi.
Quando l'esecuzione genera un errore ed è presente una regola di ripetizione dei tentativi applicabile, viene usata la corrispondenza di errore per determinare se è necessario riprovare l'esecuzione.
Il valore della parola chiave RetryExec è un elenco di regole di ripetizione dei tentativi separate da punti e virgola.
RetryExec={rule1;rule2}
Ecco un esempio di regola di ripetizione dei tentativi: <errormatch>:<retrypolicy>:<querymatch>
Corrispondenza di errore: elenco di codici errore separati da virgole. Specificando, ad esempio, 1000,2000, si indicano i codici di errore per i quali ripetere il tentativo.
Criteri di ripetizione: specificano il ritardo fino al tentativo successivo. Il primo parametro indica il numero di tentativi mentre il secondo il ritardo. Ad esempio, 3,10+7 indica 3 tentativi a partire da 10 secondi e ogni tentativo successivo eseguito a incrementi di 7 secondi. Se il valore +7 non viene specificato, il tempo per ogni tentativo successivo viene raddoppiato in modo esponenziale.
Corrispondenza di query: specifica la query con cui si vuole cercare la corrispondenza. Se non viene specificato alcun valore, si applica a tutte le query. Se si specifica SELECT, si applica a tutte le query che iniziano con select.
Combinando i tre componenti precedenti in una stringa di connessione si ottiene quanto segue:
RetryExec={1000,2000:3,10+7:SELECT}
Ciò indica gli errori 1000 e 2000 in una query che inizia con SELECT. Ripetere i tentativi due volte con un ritardo iniziale di 10 secondi e aggiungendo 7 secondi per ogni tentativo successivo"
Esempi
40501,40540:4,5
Per gli errori 40501 e 40540, ripetere i tentativi fino a quattro volte, con un ritardo iniziale di 5 secondi e raddoppiando il tempo in modo esponenziale tra ogni tentativo. Questa regola si applica a tutte le query.
49919:2,10+:CREATE
Per l'errore 49919 in una query che inizia con CREATE, ripetere i tentativi al massimo due volte, inizialmente dopo 10 secondi e quindi dopo 20 secondi.
49918,40501,10928:5,10+5:SELECT c1
Per gli errori 49918, 40501 e 10928 nelle query che iniziano con SELECT c1, ripetere i tentativi fino a cinque volte, attendendo 10 secondi per il primo tentativo e aumentando l'attesa di 5 secondi per i tentativi successivi.
Le tre regole precedenti possono essere specificate insieme nella stringa di connessione come indicato di seguito:
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
La regola più generale (con la ricerca della corrispondenza in tutte le query) è posizionata alla fine, per consentire di cercare la corrispondenza per le due regole precedenti più specifiche con le rispettive query.
ClientCertificate
Specifica il certificato utente da usare per l'autenticazione. Le opzioni sono:
| Valore opzione | Descrizione |
|---|---|
sha1:<hash_value> |
Il driver ODBC usa l'hash SHA1 per individuare un certificato nell'archivio certificati Windows |
subject:<subject> |
Il driver ODBC usa Subject per individuare un certificato nell'archivio certificati Windows |
file:<file_location>[,password:<password>] |
Il driver ODBC usa un file di certificato. |
Se il certificato è in formato PFX e la chiave privata all'interno del certificato PFX è protetta da password, è necessaria la parola chiave della password. Per i certificati nei formati PEM e DER è obbligatorio l'attributo ClientKey
ClientKey
Specifica il percorso di un file di chiave privata per i certificati PEM o DER specificati dall'attributo ClientCertificate. Formato:
| Valore opzione | Descrizione |
|---|---|
file:<file_location>[,password:<password>] |
Specifica il percorso del file di chiave privata. |
Se il file di chiave privata è protetto da password, è necessario specificare la parola chiave della password. Se la password contiene caratteri ,, viene aggiunto un ulteriore carattere , immediatamente dopo ognuno di essi. Se, ad esempio, la password è a,b,c, la password dopo l'applicazione della sequenza di escape nella stringa di connessione è a,,b,,c.
HostnameInCertificate
Specifica il nome host previsto nel certificato del server quando la crittografia viene negoziata, se è diverso dal valore predefinito derivato da Addr/Address/Server. L'opzione HostnameInCertificate viene ignorata quando viene usata l'opzione ServerCertificate.
IpAddressPreference
Disponibile a partire dalla versione 18.1, questa opzione consente all'utente di specificare il tipo di indirizzo IP a cui dare la priorità per le connessioni. Le opzioni possibili sono "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]". UsePlatformDefault consente di stabilire la connessione agli indirizzi nell'ordine in cui vengono forniti dalla chiamata di sistema per risolvere il nome del server. Il valore predefinito è IPv4First, che corrisponde al comportamento nelle versioni precedenti.
ServerCertificate
Disponibile a partire dalla versione 18.1, questa opzione può essere usata con la modalità di crittografia strict. La parola chiave ServerCertificate viene usata per specificare il percorso di un file di certificato per cui cercare la corrispondenza con il certificato TLS/SSL di SQL Server. Viene eseguita la corrispondenza invece della convalida standard dei certificati (scadenza, nome host, catena di attendibilità e così via) I formati di certificato accettati sono PEM, DER e CER. Se il valore viene specificato, il certificato di SQL Server viene controllato esaminando se il valore di ServerCertificate fornito è una corrispondenza esatta.
SQL_COPT_SS_ACCESS_TOKEN
Consente di usare un token di accesso Microsoft Entra per l'autenticazione. Per maggiori informazioni, vedere la sezione Come utilizzare Microsoft Entra ID.
| Valore attributo | Descrizione |
|---|---|
| NULL | (Impostazione predefinita) Non viene fornito alcun token di accesso. |
| ACCESSTOKEN* | Puntatore a un token di accesso. |
SQL_COPT_SS_CEKEYSTOREDATA
Comunica con una libreria del provider dell'archivio chiavi caricata. Controlla la crittografia di colonna trasparente (Always Encrypted). Questo attributo non ha un valore predefinito. Per altre informazioni vedere Provider di archivi chiavi personalizzati.
| Valore attributo | Descrizione |
|---|---|
| CEKEYSTOREDATA * | Struttura dei dati di comunicazione per la libreria del provider dell'archivio chiavi |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Carica una libreria del provider dell'archivio chiavi per Always Encrypted o recupera i nomi delle librerie del provider dell'archivio chiavi caricate. Per altre informazioni vedere Provider di archivi chiavi personalizzati. Questo attributo non ha un valore predefinito.
| Valore attributo | Descrizione |
|---|---|
| char * | Percorso di una libreria del provider dell'archivio chiavi |
SQL_COPT_SS_ENLIST_IN_XA
Per abilitare le transazioni XA con elaborazione delle transazioni (TP) conforme a XA, l'applicazione deve chiamare SQLSetConnectAttr con SQL_COPT_SS_ENLIST_IN_XA e un puntatore a un oggetto XACALLPARAM. Questa opzione è supportata in Windows (17.3+), Linux e macOS.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Per associare una transazione XA con una sola connessione ODBC, specificare VERO o FALSO con SQL_COPT_SS_ENLIST_IN_XA anziché con il puntatore nella chiamata a SQLSetConnectAttr. Questa impostazione è valida solo in Windows e non può essere usata per specificare operazioni XA attraverso un'applicazione client.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| valore | Descrizione | Piattaforme |
|---|---|---|
| Oggetto XACALLPARAM* | Puntatore all'oggetto XACALLPARAM. |
Windows, Linux e macOS |
| TRUE | Associa la transazione XA alla connessione ODBC. Tutte le attività del database correlate vengono eseguite sotto la protezione della transazione XA. | Finestre |
| FALSE | Annulla l'associazione della transazione XA alla connessione ODBC. | Finestre |
Per altre informazioni sulle transazioni XA, vedere Uso delle transazioni XA.
SQL_COPT_SS_LONGASMAX
Consente l'invio di dati di tipo long ai server come dati di tipo max.
| Valore attributo | Descrizione |
|---|---|
| No | (Impostazione predefinita) Non esegue la conversione dei tipi long in tipi max durante l'invio. |
| Sì | Converte i dati da tipi long a tipi max durante l'invio. |
SQL_COPT_SS_SPID
Recupera l'ID del processo server della connessione. Questa proprietà equivale alla variabile T-SQL @@SPID, ad eccezione del fatto che non comporta un round trip aggiuntivo al server.
| Valore attributo | Descrizione |
|---|---|
| DWORD | SPID |