Schlüsselwörter und Attribute von DNS- und Verbindungszeichenfolgen
Auf dieser Seite sind die Schlüsselwörter für Verbindungszeichenfolgen und für DSN sowie Verbindungsattribute für die Funktionen „SQLSetConnectAttr“ und „SQLGetConnectAttr“ aufgelistet, die im Rahmen des ODBC-Treibers für SQL Server verfügbar sind.
Unterstützte Schlüsselwörter für DSN/Verbindungszeichenfolgen und Verbindungsattribute
In der folgenden Tabelle sind die verfügbaren Schlüsselwörter und Attribute nach Plattform aufgelistet (L: Linux; M: macOS; W: Windows). Wählen Sie das Schlüsselwort oder Attribut aus, um detailliertere Informationen zu erhalten.
Nachstehend sind einige Schlüsselwörter für Verbindungszeichenfolgen und Verbindungsattribute aufgeführt, die nicht in den Artikeln Verwenden von Schlüsselwörtern für Verbindungszeichenfolgen mit SQL Server Native Client, SQLSetConnectAttr und SQLSetConnectAttr-Funktion dokumentiert sind.
BESCHREIBUNG
Wird zum Beschreiben der Datenquelle verwendet.
SQL_COPT_SS_ANSI_OEM
Steuert die ANSI-in-OEM-Konvertierung.
| Attributwert | BESCHREIBUNG |
|---|---|
| SQL_AO_OFF | (Standard) Es erfolgt keine Übersetzung. |
| SQL_AO_ON | Es erfolgt eine Übersetzung. |
SQL_COPT_SS_AUTOBEGINTXN
Wenn der Autocommitmodus deaktiviert ist, wird ab Version 17.6 die automatische BEGIN TRANSACTION nach ROLLBACK oder COMMIT gesteuert.
| Attributwert | BESCHREIBUNG |
|---|---|
| SQL_AUTOBEGINTXN_ON | (Standard) Automatische BEGIN TRANSACTION nach ROLLBACK oder COMMIT. |
| SQL_AUTOBEGINTXN_OFF | Keine automatische BEGIN TRANSACTION nach ROLLBACK oder COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Steuert die Verwendung von SQL Server-Fallbackverbindungen. Wird nicht mehr unterstützt.
| Attributwert | BESCHREIBUNG |
|---|---|
| SQL_FB_OFF | (Standard) Fallbackverbindungen sind deaktiviert. |
| SQL_FB_ON | Fallbackverbindungen sind aktiviert. |
Neue Schlüsselwörter für Verbindungszeichenfolgen sowie Verbindungsattribute
Authentifizierung – SQL_COPT_SS_AUTHENTICATION
Legt den Authentifizierungsmodus für die Verbindung mit SQL Server fest. Weitere Informationen finden Sie unter Verwendung von Microsoft Entra ID.
| Schlüsselwortwert | Attributwert | BESCHREIBUNG |
|---|---|---|
| SQL_AU_NONE | (Standard) Nicht festgelegt. Die Kombination anderer Attribute bestimmt den Authentifizierungsmodus. | |
| SqlPassword | SQL_AU_PASSWORD | SQL Server-Standardauthentifizierung mit Benutzername und Kennwort. |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Integrierte Microsoft Entra-Authentifizierung. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Microsoft Entra-Authentifizierung mit Kennwort. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Interaktive Microsoft Entra-Authentifizierung. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Microsoft Entra-Authentifizierung mit verwalteter Identität. Für die Identität, die dem Benutzer zugewiesen wurde, ist die Benutzer-ID auf die Objekt-ID der Benutzeridentität festgelegt. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Microsoft Entra-Authentifizierung mit Dienstprinzipal. UID wird auf die Client-ID des Dienstprinzipals festgelegt. PWD wird auf den geheimen Clientschlüssel festgelegt. |
| SQL_AU_RESET | Nicht festgelegt. Überschreibt jeglichen DSN oder jegliche Verbindungszeichenfolgeeinstellung. |
Hinweis
Wenn das Authentication-Schlüsselwort oder -Attribut verwendet werden, legen Sie die Encrypt-Einstellung für die Verbindungszeichenfolge, DSN bzw. das Verbindungsattribut explizit auf den gewünschten Wert fest. Weitere Informationen finden Sie unter Using Connection String Keywords with SQL Server Native Client (Verwenden von Schlüsselwörtern für Verbindungszeichenfolgen mit SQL Server Native Client).
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
Steuert transparente Spaltenverschlüsselung (Always Encrypted). Weitere Informationen finden Sie unter Verwenden von Always Encrypted mit dem ODBC-Treiber für SQL Server.
| Schlüsselwortwert | Attributwert | BESCHREIBUNG |
|---|---|---|
| Aktiviert | SQL_CE_ENABLED | Aktiviert Always Encrypted. |
| Disabled | SQL_CE_DISABLED | (Standard) Deaktiviert Always Encrypted. |
| SQL_CE_RESULTSETONLY | Aktiviert nur die Entschlüsselung (Ergebnisse und Rückgabewerte). |
Verschlüsseln
Gibt an, ob Verbindungen die TLS-Verschlüsselung über das Netzwerk verwenden. Mögliche Werte sind: yes/mandatory(18.0 und höher), no/optional(18.0 und höher) und strict(18.0 und höher). Der Standardwert ist yes in Version 18.0 und höher und no in früheren Versionen.
Unabhängig von der Einstellung für Encrypt werden die Anmeldeinformationen für den Server (Benutzername und Kennwort) immer verschlüsselt.
Encrypt, TrustServerCertificate und die serverseitige Einstellung Force Encryption spielen eine Rolle dabei, ob Verbindungen über das Netzwerk verschlüsselt werden. Die folgenden Tabellen zeigen die Auswirkungen dieser Einstellungen.
ODBC-Treiber 18 und neuer
| Verschlüsselungseinstellung | TrustServerCertificate | Erzwingen der Verschlüsselung durch Server | Ergebnis |
|---|---|---|---|
| Nein | Nr. | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind nicht verschlüsselt. |
| Nein | Ja | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind nicht verschlüsselt. |
| Ja | Nr. | Nein | Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Ja | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Nein | Nein | Ja | Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Nein | Ja | Ja | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Keine | Ja | Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Ja | Ja | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Strict | - | - | TrustServerCertificate wird ignoriert. Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
Hinweis
„Strict“ ist nur für Server verfügbar, die TDS 8.0-Verbindungen unterstützen.
ODBC-Treiber 17 und älter
| Verschlüsselungseinstellung | TrustServerCertificate | Erzwingen der Verschlüsselung durch Server | Ergebnis |
|---|---|---|---|
| Nein | Nr. | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind nicht verschlüsselt. |
| Nein | Ja | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind nicht verschlüsselt. |
| Ja | Nr. | Nein | Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Ja | Nein | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Nein | Nein | Ja | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Nein | Ja | Ja | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Keine | Ja | Serverzertifikat wird überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
| Ja | Ja | Ja | Das Serverzertifikat wird nicht überprüft. Zwischen dem Client und dem Server verschickte Daten sind verschlüsselt. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
Steuert das Feature zur transparenten Netzwerk-IP-Adressauflösung, das mit MultiSubnetFailover interagiert, um erneute Verbindungsversuche zu beschleunigen. Weitere Informationen finden Sie unter Verwenden der transparenten Netzwerk-IP-Adressauflösung.
| Schlüsselwortwert | Attributwert | BESCHREIBUNG |
|---|---|---|
| Aktiviert | SQL_IS_ON | (Standard) Aktiviert die transparente Netzwerk-IP-Adressauflösung. |
| Disabled | SQL_IS_OFF | Deaktiviert die transparente Netzwerk-IP-Adressauflösung. |
UseFMTONLY
Steuert die Verwendung von „SET FMTONLY“ für Metadaten bei der Verbindung mit SQL Server 2012 und höheren Versionen.
| Schlüsselwortwert | BESCHREIBUNG |
|---|---|
| Nein | (Standard) Verwenden von „sp_describe_first_result_set“ für Metadaten, wenn verfügbar. |
| Ja | Verwenden von „SET FMTONLY“ für Metadaten. |
Replikation
Gibt die Verwendung einer Replikationsanmeldung für ODBC Driver 17.8 oder höher an
| Schlüsselwortwert | BESCHREIBUNG |
|---|---|
| No | (Standard) Die Replikationsanmeldung wird nicht verwendet. |
| Ja | Trigger mit der Option NOT FOR REPLICATION werden bei dieser Verbindung nicht ausgelöst. |
RetryExec
Konfigurierbare Wiederholungslogik ist ab Version 18.1 verfügbar. Sie führt automatisch bestimmte ODBC-Funktionsaufrufe auf Grundlage konfigurierbarer Bedingungen erneut aus. Dieses Feature kann über die Verbindungszeichenfolge mithilfe des Schlüsselworts RetryExec zusammen mit einer Liste von Wiederholungsregeln aktiviert werden. Jede Wiederholungsregel enthält drei durch Doppelpunkte getrennte Komponenten: einen Fehlerabgleich, eine Wiederholungsrichtlinie und einen Abfrageabgleich.
Der Abfrageabgleich bestimmt die Wiederholungsregel, die für eine bestimmte Ausführung verwendet werden soll, und wird mit dem eingehenden Befehlstext (SQLExecDirect) oder dem vorbereiteten Befehlstext im Anweisungsobjekt (SQLExecute) abgeglichen. Wenn mehr als eine Regel übereinstimmt, wird die erste übereinstimmende in der Liste verwendet. Durch dieses Verhalten können Regeln in der Reihenfolge ihrer zunehmenden Allgemeinheit aufgeführt werden. Wenn keine Regel übereinstimmt, wird kein Wiederholungsversuch angewendet.
Wenn die Ausführung zu einem Fehler führt und es eine anwendbare Wiederholungsregel gibt, wird deren Fehlerabgleich verwendet, um festzustellen, ob die Ausführung erneut ausgeführt werden soll.
Der Wert des Schlüsselworts „RetryExec“ ist eine Liste aus durch Semikolons getrennten Wiederholungsregeln.
RetryExec={rule1;rule2}
Eine Wiederholungsregel lautet wie folgt: <errormatch>:<retrypolicy>:<querymatch>
Fehlerabgleich: Eine durch Kommas getrennte Liste von Fehlercodes. Beispielsweise stellt die Angabe von 1000,2000 die Fehlercodes dar, die Sie wiederholen möchten.
Wiederholungsrichtlinie: Gibt die Verzögerung bis zum nächsten Wiederholungsversuch an. Der erste Parameter wäre die Anzahl der Wiederholungsversuche, während der zweite die Verzögerung wäre. Beispielsweise gibt 3,10+7 3 Versuche, beginnend bei 10 an, wobei jeder folgende Wiederholungsversuch 7 Sekunden erhöht würde. Wenn +7 nicht angegeben ist, wird der Abstand zwischen jedem folgenden Wiederholungsversuch exponentiell verdoppelt.
Abfrageabgleich: Gibt die Abfrage an, mit der Sie abgleichen möchten. Wenn nichts angegeben wird, ist es für alle Abfragen gültig. Das Angeben von SELECT bedeutet Gültigkeit für alle Abfragen, die mit SELECT beginnen.
Die gemeinsame Kombination aller drei oben genannten Komponenten zur Verwendung in einer Verbindungszeichenfolge sähe wie folgt aus:
RetryExec={1000,2000:3,10+7:SELECT}
Was bedeuten würde: „Für die Fehler 1000 und 2000 bei einer Abfrage, die mit SELECT beginnt. Führen Sie zwei Wiederholungsversuche mit einer anfänglichen Verzögerung von 10 Sekunden aus, und fügen Sie für jeden folgenden Versuch 7 Sekunden hinzu.“
Beispiele
40501,40540:4,5
Für die Fehler 40501 und 40540 wiederhole bis zu vier Mal mit einer anfänglichen Verzögerung von 5 Sekunden und exponentieller Verdoppelung zwischen den einzelnen Wiederholungsversuchen. Diese Regel gilt für alle Abfragen.
49919:2,10+:CREATE
Für Fehler 49919 bei einer Abfrage, die mit CREATE beginnt, wiederhole maximal zweimal, anfangs nach 10 Sekunden und dann nach 20 Sekunden.
49918,40501,10928:5,10+5:SELECT c1
Für die Fehler 49918, 40501 und 10928 bei Abfragen, die mit „SELECT c1“ beginnen, wiederhole bis zu fünf Mal, warte dabei 10 Sekunden bis zum ersten Wiederholungsversuch, und erhöhe danach die Wartezeit um jeweils 5 Sekunden.
Die obigen drei Regeln können in der Verbindungszeichenfolge wie folgt zusammen angegeben werden:
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
Die allgemeinste Regel (stimmt mit allen überein) wurde am Ende platziert, damit die beiden spezifischeren Regeln vorher mit ihren jeweiligen Abfragen abgeglichen werden können.
ClientCertificate
Dieser Wert gibt das Zertifikat an, das für die Authentifizierung verwendet werden soll. Die Optionen sind:
| Optionswert | BESCHREIBUNG |
|---|---|
sha1:<hash_value> |
Der ODBC-Treiber verwendet den SHA1-Hash, um im Windows-Zertifikatspeicher nach einem Zertifikat zu suchen. |
subject:<subject> |
Der ODBC-Treiber verwendet „subject“, um im Windows-Zertifikatspeicher nach einem Zertifikat zu suchen. |
file:<file_location>[,password:<password>] |
Der ODBC-Treiber verwendet eine Zertifikatsdatei. |
Falls das Zertifikat im PFX-Format vorliegt und der private Schlüssel im PFX-Zertifikat kennwortgeschützt ist, wird das Schlüsselwort „password“ benötigt. Für Zertifikate im PEM- und DER-Format wird das ClientKey-Attribut benötigt.
ClientKey
Gibt den Speicherort des privaten Schlüssels für PEM- oder DER-Zertifikate an, die vom ClientCertificate-Attribut angegeben werden. Format:
| Optionswert | BESCHREIBUNG |
|---|---|
file:<file_location>[,password:<password>] |
Diese Zeichenfolge gibt den Speicherort der Datei mit dem privaten Schlüssel an. |
Wenn die Datei mit privatem Schlüssel kennwortgeschützt ist, wird das Schlüsselwort „password“ benötigt. Wenn das Kennwort ,-Zeichen enthält, wird direkt hinter jedem solchen Zeichen ein zusätzliches ,-Zeichen hinzugefügt. Wenn das Kennwort z. B. a,b,c ist, lautet das Kennwort mit Escapezeichen in der Verbindungszeichenfolge a,,b,,c.
HostnameInCertificate
Gibt den Hostnamen an, der beim Aushandeln der Verschlüsselung im Zertifikat des Servers zu erwarten ist, wenn er sich vom von Addr/Address/Server abgeleiteten Standardwert unterscheidet. Die Option HostnameInCertificate wird ignoriert, wenn die Option ServerCertificate verwendet wird.
IpAddressPreference
Mit dieser ab Version 18.1 verfügbaren Option kann der Benutzer den Typ der IP-Adresse angeben, den er für Verbindungen priorisieren möchte. Die möglichen Optionen sind „IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]“. „UsePlatformDefault“ stellt eine Verbindung mit Adressen in der Reihenfolge her, in der sie vom Systemaufruf bereitgestellt werden, um den Servernamen aufzulösen. Der Standardwert ist „IPv4First“, der dem Verhalten in früheren Versionen entspricht.
ServerCertificate
Diese ab Version 18.1 verfügbare Option kann mit dem strengen Verschlüsselungsmodus verwendet werden. Das Schlüsselwort ServerCertificate wird verwendet, um den Pfad zu einer Zertifikatdatei anzugeben, die mit dem TLS/SSL-Zertifikat von SQL Server abzugleichen ist. Die Übereinstimmung erfolgt anstelle der standardmäßigen Zertifikatüberprüfung (Ablauf, Hostname, Vertrauenskette usw.) Die akzeptierten Zertifikatformate sind PEM, DER und CER. Wenn angegeben, wird das SQL Server-Zertifikat überprüft, indem festgestellt wird, ob das bereitgestellte ServerCertificate eine exakte Übereinstimmung ist.
SQL_COPT_SS_ACCESS_TOKEN
Ermöglicht die Verwendung eines Microsoft Entra-Zugriffstokens für die Authentifizierung. Weitere Informationen finden Sie unter Verwendung von Microsoft Entra ID.
| Attributwert | BESCHREIBUNG |
|---|---|
| NULL | (Standard) Kein Zugriffstoken steht zur Verfügung. |
| ACCESSTOKEN* | Zeiger zu einem Zugriffstoken. |
SQL_COPT_SS_CEKEYSTOREDATA
Kommuniziert mit einer geladenen Keystore-Anbieterbibliothek. Steuert transparente Spaltenverschlüsselung (Always Encrypted). Dieses Attribut hat keinen Standardwert. Weitere Informationen finden Sie unter Benutzerdefinierte Keystore-Anbieter.
| Attributwert | BESCHREIBUNG |
|---|---|
| CEKEYSTOREDATA * | Kommunikationsdatenstruktur für die Keystore-Anbieterbibliothek |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Lädt eine Keystore-Anbieterbibliothek für Always Encrypted oder ruft die Namen der geladenen Keystore-Anbieterbibliotheken ab. Weitere Informationen finden Sie unter Benutzerdefinierte Keystore-Anbieter. Dieses Attribut hat keinen Standardwert.
| Attributwert | BESCHREIBUNG |
|---|---|
| char * | Pfad zur Keystore-Anbieterbibliothek |
SQL_COPT_SS_ENLIST_IN_XA
Wenn XA-Transaktionen mit einem XA-konformen Transaktionsprozessor (TP) aktiviert werden sollen, muss die Anwendung mit „SQL_COPT_SS_ENLIST_IN_XA“ die Funktion SQLSetConnectAttr sowie einen Zeiger zu einem XACALLPARAM-Objekt aufrufen. Diese Option wird unter Windows (17.3 oder höher), Linux und macOS unterstützt.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Wenn eine XA-Transaktion nur einer ODBC-Verbindung zugeordnet werden soll, stellen Sie mit „SQL_COPT_SS_ENLIST_IN_XA“ beim Aufrufen von SQLSetConnectAttr entweder TRUE oder FALSE statt des Zeigers bereit. Diese Einstellung ist nur unter Windows gültig und kann nicht dazu verwendet werden, um XA-Vorgänge über eine Clientanwendung anzugeben.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| Wert | BESCHREIBUNG | Plattformen |
|---|---|---|
| XACALLPARAM object* | Der Zeiger auf das XACALLPARAM-Objekt. |
Windows, Linux und macOS |
| TRUE | Ordnet die XA-Transaktion der ODBC-Verbindung zu. Alle entsprechenden Datenbankaktivitäten werden unter dem Schutz der XA-Transaktion durchgeführt. | Windows |
| FALSE | Hebt die Zuordnung der XA-Transaktion zur ODBC-Verbindung auf. | Windows |
Weitere Informationen zu XA-Transaktionen finden Sie unter Verwenden von XA-Transaktionen.
SQL_COPT_SS_LONGASMAX
Ermöglicht das Senden von Daten des long-Typs an Server als Daten des max-Typs.
| Attributwert | BESCHREIBUNG |
|---|---|
| Nein | (Standard) Konvertieren Sie long-Typen beim Senden nicht in max-Typen. |
| Ja | Konvertiert Daten beim Senden von long-Typen in max-Typen. |
SQL_COPT_SS_SPID
Dieser Wert ruft die Serverprozess-ID der Verbindung ab. Diese Eigenschaft entspricht der T-SQL-Variablen @@SPID, mit dem Unterschied, dass kein zusätzlicher Roundtrip zum Server erfolgt.
| Attributwert | BESCHREIBUNG |
|---|---|
| DWORD | SPID |