SQLGetConnectAttr-Funktion

Konformität
Eingeführte Version: ODBC 3.0 Normenkonformität: ISO 92

Summary
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 zum Abrufen.

ValuePtr
[Ausgabe] Ein Zeiger auf den Speicher, in dem der aktuelle Wert des von Attribut angegebenen Attributs zurückgegeben werden kann. Für ganzzahlige Attribute schreiben manche Treiber nur die unteren 32-Bit- oder 16-Bit-Elemente eines Puffers und lassen das höherwertige Bit unverändert. Daher sollten Anwendungen einen SQLULEN-Puffer verwenden und den Wert vor dem Aufruf dieser Funktion auf 0 initialisieren.

Wenn ValuePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtzahl der Bytes zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von ValuePtr gezeigten Puffer zurückgegeben werden können.

BufferLength
[Eingabe] Wenn attribut ein ODBC-definiertes Attribut ist und ValuePtr auf eine Zeichenfolge oder einen binären Puffer zeigt, sollte dieses Argument die Länge von *ValuePtr sein. Wenn Attribute ein ODBC-definiertes Attribut ist und *ValuePtr eine ganze Zahl, wird BufferLength ignoriert. Wenn der Wert in *ValuePtr eine Unicode-Zeichenkette ist (beim Aufruf von SQLGetConnectAttrW), muss das BufferLength-Argument eine gerade Zahl sein.

Wenn Attribute ein treiberdefiniertes Attribut ist, teilt die Anwendung die Natur des Attributs dem Driver Manager an, indem sie das BufferLength-Argument setzt. BufferLength kann folgende Werte haben:

• Wenn *ValuePtr ein Zeiger auf eine Zeichenkette ist, ist BufferLength die Länge der Zeichenkette.

• Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des Makros SQL_LEN_BINARY_ATTR(Länge) in BufferLength. Dies setzt einen negativen Wert in BufferLength.

• Wenn *ValuePtr ein Zeiger auf einen anderen Wert als eine Zeichenkette oder binäre Zeichenkette ist, sollte BufferLength den Wert SQL_IS_POINTER haben.

• Wenn *ValuePtr einen Datentyp mit fester Länge enthält, ist BufferLength je nach Bedarf entweder SQL_IS_INTEGER oder SQL_IS_UINTEGER.

StringLengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem die Gesamtzahl der Bytes (ohne das Null-Terminationszeichen) zurückgegeben werden kann, die in *ValuePtr zurückgegeben werden können. Wenn der Attributwert eine Zeichenkette ist und die Anzahl der zurückgegebenen Bytes größer ist als BufferLength minus die Länge des Null-Terminationszeichens, werden die Daten in *ValuePtr auf BufferLength minus die Länge des Null-Terminationszeichens abgeschnitten und vom Treiber null-terminiert.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLGetConnectAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert aus der diagnostischen Datenstruktur gewonnen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle von ConnectionHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die typischerweise von SQLGetConnectAttr zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. 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 von Attributen, die gesetzt werden können, finden Sie unter SQLSetConnectAttr. Beachte, dass, wenn Attribute ein Attribut angibt, das eine Zeichenkette zurückgibt, ValuePtr ein Zeiger auf einen Puffer für die Zeichenkette sein muss. Die maximale Länge der zurückgegebenen Zeichenkette, einschließlich des Null-Terminationszeichens, beträgt BufferLength-Bytes .

Je nach Attribut muss eine Anwendung keine Verbindung herstellen, bevor sie SQLGetConnectAttr aufruft. Wenn jedoch SQLGetConnectAttr aufgerufen wird und das angegebene Attribut keinen Standard hat und nicht durch einen vorherigen Aufruf von SQLSetConnectAttr gesetzt wurde, gibt SQLGetConnectAttr SQL_NO_DATA zurück.

Wenn das Attribut SQL_ATTR_ TRACE oder SQL_ATTR_ TRACEFILE ist, muss ConnectionHandle nicht gültig sein, und SQLGetConnectAttr wird weder SQL_ERROR noch SQL_INVALID_HANDLE zurückgeben, wenn ConnectionHandle ungültig ist. Diese Eigenschaften 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 mit SQLSetConnectAttr festlegen kann, kann eine Anwendung SQLGetConnectAttr nicht verwenden, um Ausweisungsattributwerte abzurufen; es muss SQLGetStmtAttr aufrufen, um die Einstellung der Anweisungsattribute abzurufen.

Sowohl SQL_ATTR_AUTO_IPD als auch SQL_ATTR_CONNECTION_DEAD Verbindungsattribute können durch einen Aufruf zu SQLGetConnectAttr zurückgegeben werden, können jedoch nicht durch einen Aufruf zu SQLSetConnectAttr gesetzt werden.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien