Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Konformität
Eingeführte Version: ODBC 3.0 Normenkonformität: ISO 92
Summary
SQLSetEnvAttr setzt Attribute , die Aspekte von Umgebungen steuern.
Syntax
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumente
EnvironmentHandle
[Eingabe] Umwelt-Kontrolle.
Attribut
[Eingabe] Attribut zur Menge, aufgeführt in "Kommentare".
ValuePtr
[Eingabe] Zeiger auf den Wert, der mit Attribut verknüpft werden soll. Je nach Wert des Attributs ist ValuePtr ein 32-Bit-Ganzzahlwert oder weist auf eine null-terminierte Zeichenfolge.
StringLength
[Eingabe] Wenn ValuePtr auf eine Zeichenkette oder einen Binärpuffer zeigt, sollte dieses Argument die Länge von *ValuePtr haben. Für Zeichenstring-Daten sollte dieses Argument die Anzahl der Bytes in der Zeichenkette enthalten.
Ist ValuePtr eine ganze Zahl, wird StringLength ignoriert.
Rücklieferungen
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnostics
Wenn SQLSetEnvAttr 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 SQLSetEnvAttr typischerweise zurückgegebenen SQLSetEnvAttr auf 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. Wenn ein Treiber kein Umgebungsattribut unterstützt, kann der Fehler nur während der Verbindungszeit zurückgegeben werden.
| SQLSTATE | Fehler | Description |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S02 | Optionswert geändert | Der Treiber unterstützte den in ValuePtr angegebenen Wert nicht und setzte einen ähnlichen Wert ein. (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. |
| HY009 | Ungültige Verwendung des Nullzeigers | Das Attribut-Argument identifizierte ein Umgebungsattribut, das einen String-Wert erforderte, und das ValuePtr-Argument war ein Nullzeiger. |
| HY010 | Funktionssequenzfehler | (DM) Ein Verbindungshandle wurde auf EnvironmentHandle zugewiesen. (DM) SQL_ATTR_ODBC_VERSION wurde nicht mit SQLSetEnvAttr gesetzt und das Attribut ist nicht gleich SQL_ATTR_ODBC_VERSION. 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. |
| HY024 | Ungültiger Attributwert | Aufgrund des angegebenen Attributwerts wurde in ValuePtr ein ungültiger Wert angegeben. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | Das StringLength-Argument war weniger als 0, aber nicht SQL_NTS. |
| HY092 | Ungültige Attribut-/Options-Identifikator | (DM) Der für das Argumentattribut angegebene Wert war für die vom Treiber unterstützte ODBC-Version ungü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. (DM) Das Attribut-Argument war SQL_ATTR_OUTPUT_NTS, und ValuePtr war SQL_FALSE. |
Kommentare
Eine Anwendung kann SQLSetEnvAttr nur aufrufen , wenn kein Verbindungshandle in der Umgebung zugewiesen ist. Alle von der Anwendung für die Umgebung erfolgreich gesetzten Umgebungsattribute bleiben bestehen, bis SQLFreeHandle in der Umgebung aufgerufen wird. In ODBC 3.x können in ODBC 3.x mehr als ein Umgebungshandle gleichzeitig zugewiesen werden.
Das Format der über ValuePtr gesetzten Informationen hängt vom angegebenen Attribut ab. SQLSetEnvAttr akzeptiert Attributinformationen in einem von zwei verschiedenen Formaten: einer null-terminierten Zeichenkette oder einem 32-Bit-Ganzzahlwert. Das Format der einzelnen Wird in der Beschreibung des Attributs angegeben.
Es gibt keine fahrerspezifischen Umgebungsattribute.
Verbindungsattribute können nicht durch einen Aufruf von SQLSetEnvAttr gesetzt werden. Wenn ich das versuche, wird SQLSTATE HY092 (Ungültiges Attribut/Options-Identifikator) zurückgegeben.
| Attribut | ValuePtr-Inhalt |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3,8) | Ein 32-Bit-SQLUINTEGER-Wert, der das Connection Pooling auf Umgebungsebene aktiviert oder deaktiviert. Folgende Werte werden verwendet: SQL_CP_OFF = Verbindungspooling ist deaktiviert. Dies ist die Standardoption. SQL_CP_ONE_PER_DRIVER = Für jeden Treiber wird ein einzelner Verbindungspool unterstützt. Jede Verbindung in einem Pool ist mit einem Treiber verknüpft. SQL_CP_ONE_PER_HENV = Für jede Umgebung wird ein einzelner Verbindungspool unterstützt. Jede Verbindung in einem Pool ist mit einer Umgebung verbunden. SQL_CP_DRIVER_AWARE = Verwenden Sie die Verbindungspool-Bewusstseinsfunktion des Treibers, sofern diese verfügbar ist. Wenn der Treiber keine Verbindungspool-Bewusstsein unterstützt, wird SQL_CP_DRIVER_AWARE ignoriert und SQL_CP_ONE_PER_HENV verwendet. Weitere Informationen finden Sie unter Driver-Aware Connection Pooling. In einer Umgebung, in der einige Treiber das Verbindungspool-Bewusstsein unterstützen und andere nicht, kann SQL_CP_DRIVER_AWARE die Verbindungspool-Bewusstseinsfunktion bei diesen unterstützenden Treibern aktivieren, aber es ist gleichbedeutend damit, auf jene Treiber zu SQL_CP_ONE_PER_HENV, die keine Verbindungspool-Bewusstseinsfunktion unterstützen. Connection Pooling wird aktiviert, indem SQLSetEnvAttr aufgerufen wird, um das Attribut SQL_ATTR_CONNECTION_POOLING auf SQL_CP_ONE_PER_DRIVER oder SQL_CP_ONE_PER_HENV zu setzen. Dieser Aufruf muss erfolgen, bevor die Anwendung die freigegebene Umgebung zuweist, für die Verbindungspooling aktiviert werden soll. Der Umgebungshandle im Aufruf zu SQLSetEnvAttr ist auf null gesetzt, was SQL_ATTR_CONNECTION_POOLING zu einem Prozessattribut macht. Nachdem das Connection Pooling aktiviert ist, weist die Anwendung eine implizite gemeinsame Umgebung zu, indem sie SQLAllocHandle mit dem InputHandle-Argument auf SQL_HANDLE_ENV aufruft. Nachdem das Connection Pooling aktiviert und eine gemeinsame Umgebung für eine Anwendung ausgewählt wurde, kann SQL_ATTR_CONNECTION_POOLING für diese Umgebung nicht zurückgesetzt werden, da SQLSetEnvAttr beim Setzen dieses Attributs mit einem Null-Umgebungshandle aufgerufen wird. Wenn dieses Attribut gesetzt wird, während Connection Pooling in einer gemeinsamen Umgebung bereits aktiviert ist, betrifft das Attribut nur die anschließend zugewiesenen gemeinsamen Umgebungen. Es ist auch möglich, Verbindungspooling in einer Umgebung zu aktivieren. Beachten Sie Folgendes zum Environment Connection Pooling: - Das Aktivieren von Connection Pooling auf einem NULL-Handle ist ein Prozess-Attribut. Anschließend werden zugewiesene Umgebungen eine gemeinsame Umgebung sein und übernehmen die Prozessebene Connection Pooling-Einstellung. - Nachdem eine Umgebung zugewiesen wurde, kann eine Anwendung weiterhin ihre Verbindungspool-Einstellung ändern. - Wenn Environment Connection Pooling aktiviert ist und der Treiber der Verbindung Driver Pooling verwendet, bevorzugt Environment Pooling. SQL_ATTR_CONNECTION_POOLING wird im Driver Manager implementiert. Ein Treiber muss SQL_ATTR_CONNECTION_POOLING nicht implementieren. ODBC 2.0- und 3.0-Anwendungen können dieses Umweltattribut festlegen. Weitere Informationen finden Sie unter ODBC-Verbindungspooling. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | Ein 32-Bit-SQLUINTEGER-Wert, der bestimmt, wie eine Verbindung aus einem Verbindungspool ausgewählt wird. Wenn SQLConnect oder SQLDriverConnect aufgerufen werden, bestimmt der Driver Manager, welche Verbindung aus dem Pool wiederverwendet wird. Der Driver Manager versucht, die Verbindungsoptionen im Anruf und die von der Anwendung gesetzten Verbindungsattribute mit den Schlüsselwörtern und Verbindungsattributen der Verbindungen im Pool abzugleichen. Der Wert dieses Attributs bestimmt das Maß an Genauigkeit der Matching-Kriterien. Die folgenden Werte werden verwendet, um den Wert dieses Attributs festzulegen: SQL_CP_STRICT_MATCH = Nur Verbindungen, die exakt den Verbindungsoptionen im Anruf und den von der Anwendung gesetzten Verbindungsattributen entsprechen, werden wiederverwendet. Dies ist die Standardoption. SQL_CP_RELAXED_MATCH = Verbindungen mit übereinstimmenden Verbindungszeichenfolge Schlüsselwörtern können verwendet werden. Schlüsselwörter müssen übereinstimmen, aber nicht alle Verbindungsattribute müssen übereinstimmen. Für weitere Informationen darüber, wie der Driver Manager das Matching bei der Verbindung zu einer gepoolten Verbindung durchführt, siehe SQLConnect. Weitere Informationen zum Verbindungspooling finden Sie unter ODBC-Verbindungspooling. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Eine 32-Bit-Ganzzahl, die bestimmt, ob bestimmte Funktionen ODBC 2.x oder ODBC 3.x Verhalten zeigen. Die folgenden Werte werden verwendet, um den Wert dieses Attributs festzulegen: SQL_OV_ODBC3_80 = Der Driver Manager und der Driver zeigen folgendes ODBC 3.8-Verhalten: - Der Fahrer liefert und erwartet ODBC 3.x-Codes für Datum, Uhrzeit und Zeitstempel. - Der Treiber liefert ODBC 3.x SQLSTATE-Codes, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen werden. - Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert ein Suchmuster. - Der Driver Manager unterstützt die Erweiterbarkeit des C-Datentyps. Weitere Informationen zur Erweiterbarkeit von C-Datentypen finden Sie unter C Data Types in ODBC. Weitere Informationen finden Sie unter Was ist neu in ODBC 3.8. SQL_OV_ODBC3 = Der Driver Manager und der Driver zeigen folgendes ODBC 3.x-Verhalten : - Der Fahrer liefert und erwartet ODBC 3.x-Codes für Datum, Uhrzeit und Zeitstempel. - Der Treiber liefert ODBC 3.x SQLSTATE-Codes, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen werden. - Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert ein Suchmuster. - Der Driver Manager unterstützt keine C-Datentyp-Erweiterbarkeit. SQL_OV_ODBC2 = Der Treiber-Manager und der Treiber zeigen folgendes ODBC 2.x-Verhalten . Dies ist besonders nützlich für eine ODBC 2.x-Anwendung , die mit einem ODBC 3.x-Treiber arbeitet. - Der Fahrer gibt ODBC 2.x-Codes für Datum, Uhrzeit und Zeitstempel zurück und erwartet. - Der Treiber gibt ODBC 2.x SQLSTATE-Codes zurück, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen werden. - Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert kein Suchmuster. - Der Driver Manager unterstützt keine C-Datentyp-Erweiterbarkeit. Eine Anwendung muss dieses Umgebungsattribut setzen, bevor sie eine Funktion mit einem SQLHENV-Argument aufruft, sonst gibt der Aufruf SQLSTATE HY010 (Funktionssequenzfehler) zurück. Es ist treiberspezifisch, ob für diese Umweltflaggen zusätzliches Verhalten vorhanden ist. - Weitere Informationen finden Sie unter Declaring the Application (ODBC-Version und Verhaltensänderungen). |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Eine 32-Bit-Ganzzahl, die bestimmt, wie der Treiber String-Daten zurückgibt. Wenn SQL_TRUE, gibt der Treiber String-Daten null-terminiert zurück. Wenn SQL_FALSE, gibt der Treiber keine String-Daten null-terminiert zurück. Dieses Attribut steht standardmäßig auf SQL_TRUE. Ein Aufruf von SQLSetEnvAttr, um es auf SQL_TRUE zu setzen, gibt SQL_SUCCESS zurück. Ein Aufruf von SQLSetEnvAttr, um es auf SQL_FALSE zu setzen, gibt SQL_ERROR und SQLSTATE HYC00 zurück (optionale Funktion nicht implementiert). |
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Zuweisung eines Handles | SQLAllocHandle-Funktion |
| Rückgabe der Einstellung eines Umgebungsattributs | SQLGetEnvAttr Funktion |