SQLGetEnvAttr-Funktion

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

Summary
SQLGetEnvAttr gibt die aktuelle Einstellung eines Umgebungsattributs zurück.

Syntax

  
SQLRETURN SQLGetEnvAttr(  
     SQLHENV        EnvironmentHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

Argumente

EnvironmentHandle
[Eingabe] Umwelt-Kontrolle.

Attribut
[Eingabe] Attribut zum Abrufen.

ValuePtr
[Ausgabe] Zeiger auf einen Puffer, in dem der aktuelle Wert des durch Attribut angegebenen Attributs zurückgegeben wird.

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 ValuePtr auf eine Zeichenkette zeigt, sollte dieses Argument die Länge von *ValuePtr sein. Wenn *ValuePtr eine ganze Zahl ist, wird BufferLength ignoriert. Wenn *ValuePtr eine Unicode-Zeichenkette ist (beim Aufruf von SQLGetEnvAttrW), muss das BufferLength-Argument eine gerade Zahl sein. Wenn der Attributwert keine Zeichenfolge ist, wird BufferLength nicht verwendet.

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 oder gleich BufferLength ist, werden die Daten in *ValuePtr auf BufferLength minus die Länge eines 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 SQLGetEnvAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_ENV und einem Handle von EnvironmentHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die häufig von SQLGetEnvAttr 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.

SQLSTATE Fehler Description
01000 Allgemeiner Warnhinweis Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01004 Zeichenfolgendaten, rechts abgeschnitten Die in *ValuePtr zurückgegebenen Daten wurden auf BufferLength minus das Null-Terminationszeichen abgeschnitten. Die Länge des untrunkierten Stringwerts wird in *StringLengthPTR zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache.
HY001 Speicherzuweisungsfehler Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY010 Funktionssequenzfehler (DM) SQL_ATTR_ODBC_VERSION wurde noch nicht über SQLSetEnvAttr eingestellt. Sie müssen SQL_ATTR_ODBC_VERSION nicht explizit festlegen, wenn Sie SQLAllocHandleStd verwenden.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY092 Ungültige Attribut-/Options-Identifikator Der für das Argument Attribut angegebene Wert war für die vom Treiber unterstützte Version von ODBC nicht gültig.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYC00 Optionales Feature wurde nicht implementiert Der für das Argument-Attribut angegebene Wert war ein gültiges ODBC-Umgebungsattribut für die vom Treiber unterstützte ODBC-Version, jedoch nicht vom Treiber.
IM001 Dieser Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der dem EnvironmentHandle entspricht, unterstützt diese Funktion nicht.

Kommentare

Eine Liste der Attribute finden Sie unter SQLSetEnvAttr. Es gibt keine fahrerspezifischen Umgebungsattribute. Wenn Attribute ein Attribut angibt, das eine Zeichenkette zurückgibt, muss ValuePtr ein Zeiger auf einen Puffer sein, in dem die Zeichenkette zurückgegeben wird. Die maximale Länge des Strings, einschließlich des Null-Terminierungsbytes, beträgt BufferLength-Bytes .

SQLGetEnvAttr kann jederzeit zwischen der Zuweisung und dem Freigeben eines Umgebungshandles aufgerufen werden. Alle von der Anwendung für die Umgebung erfolgreich gesetzten Umgebungsattribute bleiben bestehen, bis SQLFreeHandle auf dem EnvironmentHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird. In ODBC 3*.x* können gleichzeitig mehr als ein Umgebungshandle zugewiesen werden. Ein Umgebungsattribut in einer Umgebung wird nicht beeinflusst, wenn eine andere Umgebung zugewiesen wurde.

Note

Das Attribut SQL_ATTR_OUTPUT_NTS Umgebung wird von standardkonformen Anwendungen unterstützt. Wenn SQLGetEnvAttr aufgerufen wird, gibt der ODBC 3*.x* Driver Manager immer SQL_TRUE für dieses Attribut zurück. SQL_ATTR_OUTPUT_NTS kann nur durch einen Aufruf von SQLSetEnvAttr auf SQL_TRUE gesetzt werden.

Weitere Informationen zu Siehe
Zurückgeben der Einstellung eines Verbindungsattributes SQLGetConnectAttr-Funktion
Zurückgeben der Einstellung eines Anweisungsattributs SQLGetStmtAttr-Funktion
Festlegen eines Verbindungsattributes SQLSetConnectAttr-Funktion
Einstellung eines Umgebungsattributs SQLSetEnvAttr Funktion
Festlegen eines Anweisungsattributs SQLSetStmtAttr-Funktion

Verwandte Inhalte

  • Last updated on