SQLGetEnvAttr-Funktion
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.
Verwandte Funktionen
| 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 |