Condividi tramite


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.

Parola chiave DSN / stringa di connessione Attributo di connessione Piattaforma
Addr LMW
Indirizzo LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
Autenticazione SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
Database SQL_ATTR_CURRENT_CATALOG LMW
Descrizione LMW
Driver LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (v18.0+) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (v18.0+) LMW
IpAddressPreference (v18.1+) LMW
KeepAlive (v17.4+, DSN solo prima della versione 17.8) LMW
KeepAliveInterval (v17.4+, DSN solo prima della versione 17.8) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Lingua LMW
LongAsMax (v18.0+) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Rete LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
Replica LMW
RetryExec (18.1+) LMW
SaveFile LMW
Server LMW
ServerCertificate (v18.1+) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONCAT_NULL LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.4.2+) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v 17.5 e successive) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

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 No Il certificato del server non viene controllato.
I dati inviati tra client e server non vengono crittografati.
No No Il certificato del server viene verificato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server non viene controllato.
I dati inviati dal client al server e viceversa vengono crittografati.
No No Il certificato del server viene verificato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server non viene controllato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server viene verificato.
I dati inviati dal client al server e viceversa vengono crittografati.
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 No Il certificato del server non viene controllato.
I dati inviati tra client e server non vengono crittografati.
No No Il certificato del server viene verificato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server non viene controllato.
I dati inviati dal client al server e viceversa vengono crittografati.
No No Il certificato del server non viene controllato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server non viene controllato.
I dati inviati dal client al server e viceversa vengono crittografati.
No Il certificato del server viene verificato.
I dati inviati dal client al server e viceversa vengono crittografati.
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.
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 per la replica non viene usato.
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.
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