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.

SQL_COPT_SS_AUTOBEGINTXN

Wenn der Autocommitmodus deaktiviert ist, wird ab Version 17.6 die automatische BEGIN TRANSACTION nach ROLLBACK oder COMMIT gesteuert.

SQL_COPT_SS_FALLBACK_CONNECT

Steuert die Verwendung von SQL Server-Fallbackverbindungen. Wird nicht mehr unterstützt.

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.

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.

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

ODBC-Treiber 17 und älter

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.

UseFMTONLY

Steuert die Verwendung von „SET FMTONLY“ für Metadaten bei der Verbindung mit SQL Server 2012 und höheren Versionen.

Replikation

Gibt die Verwendung einer Replikationsanmeldung für ODBC Driver 17.8 oder höher an

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:

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:

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.

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.

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.

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

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.

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.