SQLGetConnectAttr-Funktion

Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92

Zusammenfassung
SQLGetConnectAttr gibt die aktuelle Einstellung eines Verbindungsattributs zurück.

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.

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.

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien