SQLGetEnvAttr-Funktion

  • Artikel

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

Zusammenfassung
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] Umgebungshandle.

Attribut
[Eingabe] Attribut, das abgerufen werden soll.

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

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 ValuePtr auf eine Zeichenfolge verweist, sollte dieses Argument die Länge von *ValuePtr aufweisen. Wenn *ValuePtr eine ganze Zahl ist, wird BufferLength ignoriert. Wenn *ValuePtr eine Unicode-Zeichenfolge ist (beim Aufrufen 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 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 oder gleich BufferLength ist, werden die Daten in *ValuePtr in BufferLength abgeschnitten abzüglich der Länge eines NULL-Beendigungszeichens 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 SQLGetEnvAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_ENV und einem Handle of EnvironmentHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLGetEnvAttr 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 minus null-Terminierungszeichen abgeschnitten. Die Länge des unwahren Zeichenfolgenwerts wird in *StringLengthPtr zurückgegeben. (Die 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 kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherbelegung Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist.
HY010 Funktionssequenzfehler (DM) SQL_ATTR_ODBC_VERSION wurde noch nicht über SQLSetEnvAttr festgelegt. Sie müssen SQL_ATTR_ODBC_VERSION nicht explizit festlegen, wenn Sie SQLAllocHandleStd verwenden.
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.
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.
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-Umgebungsattribut für die vom Treiber unterstützte ODBC-Version, wurde aber vom Treiber nicht unterstützt.
IM001 Der Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der dem EnvironmentHandle entspricht, unterstützt die Funktion nicht.

Kommentare

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

SQLGetEnvAttr kann jederzeit zwischen der Zuordnung und der Freigabe eines Umgebungshandles aufgerufen werden. Alle Umgebungsattribute, die erfolgreich von der Anwendung für die Umgebung festgelegt wurden, bleiben bestehen, bis SQLFreeHandle auf der EnvironmentHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird. In ODBC 3*.x* können mehrere Umgebungshandle gleichzeitig zugeordnet werden. Ein Umgebungsattribut für eine Umgebung ist nicht betroffen, wenn eine andere Umgebung zugewiesen wurde.

Hinweis

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

Informationen über Finden Sie unter
Zurückgeben der Einstellung eines Verbindungsattributes SQLGetConnectAttr-Funktion
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

ODBC-API-Referenz
ODBC-Headerdateien