SQLGetConnectAttr-Funktion
Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92
Zusammenfassung
SQLGetConnectAttr gibt die aktuelle Einstellung eines Verbindungsattributs zurück.
Hinweis
Weitere Informationen dazu, was der Treiber-Manager diese Funktion ordnet, wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber funktioniert, finden Sie unter Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.
Syntax
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumente
ConnectionHandle
[Eingabe] Verbindungshandle.
Attribut
[Eingabe] Attribut, das abgerufen werden soll.
ValuePtr
[Ausgabe] Ein Zeiger auf den Arbeitsspeicher, in dem der aktuelle Wert des durch Attribut angegebenen Attributs zurückgegeben werden soll. Bei ganzzahligen Attributen schreiben einige Treiber möglicherweise nur die unteren 32-Bit- oder 16-Bit eines Puffers und lassen das Bit höherer Reihenfolge unverändert. Daher sollten Anwendungen einen Puffer von SQLULEN verwenden und den Wert auf 0 initialisieren, bevor diese Funktion aufgerufen wird.
Wenn ValuePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtanzahl der Bytes (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den ValuePtr verweist.
BufferLength
[Eingabe] Wenn Attribut ein odbc-definiertes Attribut ist und ValuePtr auf eine Zeichenfolge oder einen binären Puffer verweist, sollte dieses Argument die Länge von *ValuePtr haben. Wenn Attribut ein ODBC-definiertes Attribut und *ValuePtr eine ganze Zahl ist, wird BufferLength ignoriert. Wenn der Wert in *ValuePtr eine Unicode-Zeichenfolge ist (beim Aufrufen von SQLGetConnectAttrW), muss das BufferLength-Argument eine gerade Zahl sein.
Wenn Attribut ein vom Treiber definiertes Attribut ist, gibt die Anwendung die Art des Attributs für den Treiber-Manager an, indem das BufferLength-Argument festgelegt wird. BufferLength kann die folgenden Werte aufweisen:
Wenn *ValuePtr ein Zeiger auf eine Zeichenfolge ist, ist BufferLength die Länge der Zeichenfolge.
Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des Makros SQL_LEN_BINARY_ATTR(length) in BufferLength. Dadurch wird ein negativer Wert in BufferLength platziert.
Wenn *ValuePtr ein Zeiger auf einen anderen Wert als eine Zeichenfolge oder binäre Zeichenfolge ist, sollte BufferLength den Wert SQL_IS_POINTER haben.
Wenn *ValuePtr einen Datentyp mit fester Länge enthält, ist BufferLength entweder SQL_IS_INTEGER oder SQL_IS_UINTEGER.
StringLengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem die Gesamtanzahl von Bytes (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *ValuePtr zurückgegeben werden können. Wenn der Attributwert eine Zeichenfolge ist und die Anzahl der zurückzugebenden Bytes größer als BufferLength abzüglich der Länge des Null-Terminierungszeichens ist, werden die Daten in *ValuePtr in BufferLength abgeschnitten abzüglich der Länge des Null-Terminierungszeichens und vom Treiber null beendet.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLGetConnectAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert aus der Diagnosedatenstruktur abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle of ConnectionHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLGetConnectAttr zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Die in *ValuePtr zurückgegebenen Daten wurden als BufferLength abgeschnitten, abzüglich der Länge eines NULL-Terminierungszeichens. Die Länge des unwahren Zeichenfolgenwerts wird in *StringLengthPtr zurückgegeben. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08003 | Verbindung nicht geöffnet | (DM) Ein Attributwert , der eine offene Verbindung erforderte, wurde angegeben. |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden war, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die Fehlermeldung, die von der Diagnosedatenstruktur durch das Argument MessageText in SQLGetDiagField zurückgegeben wird, beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte arbeitsspeicher nicht zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) SQLBrowseConnect wurde für ConnectionHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor SQLBrowseConnect SQL_SUCCESS_WITH_INFO oder SQL_SUCCESS zurückgegeben hat. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für ConnectionHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) *ValuePtr ist eine Zeichenfolge, und BufferLength war kleiner als 00, aber nicht gleich SQL_NTS. |
| HY092 | Ungültiger Attribut-/Optionsbezeichner | Der für das Argument Attribut angegebene Wert war für die vom Treiber unterstützte ODBC-Version ungültig. |
| HY114 | Der Treiber unterstützt keine asynchrone Funktionsausführung auf Verbindungsebene. | (DM) Eine Anwendung hat versucht, die asynchrone Funktionsausführung mit SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE für einen Treiber zu aktivieren, der keine asynchronen Verbindungsvorgänge unterstützt. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYC00 | Optionale Funktion nicht implementiert | Der für das Argument Attribut angegebene Wert war ein gültiges ODBC-Verbindungsattribute für die vom Treiber unterstützte ODBC-Version, wurde aber vom Treiber nicht unterstützt. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der Treiber, der connectionHandle entspricht, unterstützt die Funktion nicht. |
Kommentare
Allgemeine Informationen zu Verbindungsattributen finden Sie unter Verbindungsattribute.
Eine Liste der Attribute, die festgelegt werden können, finden Sie unter SQLSetConnectAttr. Wenn Attribut ein Attribut angibt, das eine Zeichenfolge zurückgibt, muss ValuePtr ein Zeiger auf einen Puffer für die Zeichenfolge sein. Die maximale Länge der zurückgegebenen Zeichenfolge, einschließlich des NULL-Terminierungszeichens, ist BufferLength Bytes.
Abhängig vom Attribut muss eine Anwendung vor dem Aufrufen von SQLGetConnectAttr keine Verbindung herstellen. Wenn SQLGetConnectAttr jedoch aufgerufen wird und das angegebene Attribut keinen Standardwert aufweist und nicht durch einen vorherigen Aufruf von SQLSetConnectAttr festgelegt wurde, gibt SQLGetConnectAttr SQL_NO_DATA zurück.
Wenn Attribute SQL_ATTR_ TRACE oder SQL_ATTR_ TRACEFILE ist, muss ConnectionHandle nicht gültig sein, und SQLGetConnectAttr gibt SQL_ERROR oder SQL_INVALID_HANDLE nicht zurück, wenn ConnectionHandle ungültig ist. Diese Attribute gelten für alle Verbindungen. SQLGetConnectAttr gibt SQL_ERROR oder SQL_INVALID_HANDLE zurück, wenn ein anderes Argument ungültig ist.
Obwohl eine Anwendung Anweisungsattribute mithilfe von SQLSetConnectAttr festlegen kann, kann eine Anwendung SQLGetConnectAttr nicht verwenden, um Anweisungsattributwerte abzurufen. SqlGetStmtAttr muss aufgerufen werden, um die Einstellung der Anweisungsattribute abzurufen.
Sowohl SQL_ATTR_AUTO_IPD als auch SQL_ATTR_CONNECTION_DEAD Verbindungsattribute können durch einen Aufruf von SQLGetConnectAttr zurückgegeben, aber nicht durch einen Aufruf von SQLSetConnectAttr festgelegt werden.
Hinweis
SqlGetConnectAttr wird nicht asynchron unterstützt. Bei der Implementierung von SQLGetConnectAttr kann ein Treiber die Leistung verbessern, indem er die Anzahl der Vom Server gesendeten oder angeforderten Informationen minimiert.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Zurückgeben der Einstellung eines Anweisungsattributs | SQLGetStmtAttr-Funktion |
| Festlegen eines Verbindungsattributes | SQLSetConnectAttr-Funktion |
| Festlegen eines Umgebungsattributs | SQLSetEnvAttr-Funktion |
| Festlegen eines Anweisungsattributs | SQLSetStmtAttr-Funktion |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für