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.

SQL_COPT_SS_AUTOBEGINTXN

Versione 17.6+ Quando il commit automatico è disattivato, controlla l'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.

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.

ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION

Controlla la crittografia di colonna trasparente (Always Encrypted). Per altre informazioni vedere Uso di Always Encrypted (ODBC).

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

ODBC Driver 17 e versioni precedenti

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.

UseFMTONLY

Controlla l'uso di SET FMTONLY per i metadati durante la connessione a SQL Server 2012 e versioni successive.

Replica

Specifica l'uso di un account di accesso per la replica in ODBC Driver 17.8 e versioni successive.

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:

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:

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.

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.

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.

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);

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.

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.