Freigeben über

SQLSetEnvAttr-Funktion

  • Artikel

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

Zusammenfassung
SQLSetEnvAttr legt Attribute fest, die Aspekte von Umgebungen steuern.

Syntax

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Argumente

EnvironmentHandle
[Eingabe] Umgebungshandle.

Attribut
[Eingabe] Festzulegende Attribut, aufgeführt in "Kommentare".

ValuePtr
[Eingabe] Zeiger auf den Wert, der dem Attribut zugeordnet werden soll. Abhängig vom Wert von Attribut ist ValuePtr ein ganzzahliger 32-Bit-Wert oder zeigt auf eine Zeichenfolge mit NULL-Beendigung.

StringLength
[Eingabe] Wenn ValuePtr auf eine Zeichenfolge oder einen binären Puffer zeigt, sollte dieses Argument die Länge von *ValuePtr sein. Für Zeichenfolgendaten sollte dieses Argument die Anzahl der Bytes in der Zeichenfolge enthalten.

Wenn ValuePtr eine ganze Zahl ist, wird StringLength ignoriert.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLSetEnvAttr 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 normalerweise von SQLSetEnvAttr 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. Wenn ein Treiber kein Umgebungsattribut unterstützt, kann der Fehler nur während der Verbindungszeit zurückgegeben werden.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01S02 Optionswert geändert Der Treiber unterstützte den in ValuePtr angegebenen Wert nicht und ersetzte einen ähnlichen Wert. (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.
HY009 Ungültige Verwendung von NULL-Zeiger Das Attributargument identifizierte ein Umgebungsattribut, das einen Zeichenfolgenwert erforderte, und das ValuePtr-Argument war ein NULL-Zeiger.
HY010 Funktionssequenzfehler (DM) Für EnvironmentHandle wurde ein Verbindungshandle zugewiesen.

(DM) SQL_ATTR_ODBC_VERSION nicht mit SQLSetEnvAttr festgelegt wurde, und Attribut ist nicht gleich SQL_ATTR_ODBC_VERSION. 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.
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 kleiner als 0, wurde aber nicht SQL_NTS.
HY092 Ungültiger Attribut-/Optionsbezeichner (DM) 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.

(DM) Das Attributargument wurde SQL_ATTR_OUTPUT_NTS und ValuePtr wurde SQL_FALSE.

Kommentare

Eine Anwendung kann SQLSetEnvAttr nur aufrufen, wenn kein Verbindungshandle für die Umgebung zugewiesen ist. Alle Umgebungsattribute, die erfolgreich von der Anwendung für die Umgebung festgelegt wurden, bleiben bestehen, bis SQLFreeHandle in der Umgebung aufgerufen wird. In ODBC 3.x können mehrere Umgebungshandle gleichzeitig zugeordnet werden.

Das Format der über ValuePtr festgelegten Informationen hängt vom angegebenen Attribut ab. SQLSetEnvAttr akzeptiert Attributinformationen in einem von zwei verschiedenen Formaten: eine NULL-Zeichenfolge oder einen 32-Bit-Ganzzahlwert. Das Format der Einzelnen wird in der Beschreibung des Attributs notiert.

Es gibt keine treiberspezifischen Umgebungsattribute.

Verbindungsattribute können nicht durch einen Aufruf von SQLSetEnvAttr festgelegt werden. Wenn Sie dies versuchen, wird SQLSTATE HY092 (Ungültiges Attribut/Optionsbezeichner) zurückgegeben.

Attribut ValuePtr-Inhalte
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) Ein 32-Bit-SQLUINTEGER-Wert, der verbindungspooling auf Umgebungsebene aktiviert oder deaktiviert. Die folgenden 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 einem Treiber zugeordnet.

SQL_CP_ONE_PER_HENV = Ein einzelner Verbindungspool wird für jede Umgebung unterstützt. Jede Verbindung in einem Pool ist einer Umgebung zugeordnet.

SQL_CP_DRIVER_AWARE = Verwenden Sie die Verbindungspoolerkennungsfunktion des Treibers, sofern verfügbar. Wenn der Treiber die Verbindungspoolerkennung nicht unterstützt, wird SQL_CP_DRIVER_AWARE ignoriert und SQL_CP_ONE_PER_HENV verwendet. Weitere Informationen finden Sie unter Treiberfähiges Verbindungspooling. In einer Umgebung, in der einige Treiber und einige Treiber die Erkennung von Verbindungspools nicht unterstützen, können SQL_CP_DRIVER_AWARE die Verbindungspool-Sensibilisierungsfunktion für diese unterstützenden Treiber aktivieren. Dies entspricht jedoch der Einstellung auf SQL_CP_ONE_PER_HENV für die Treiber, die keine Verbindungspool-Sensibilisierungsfunktion unterstützen.

Das Verbindungspooling 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 festzulegen. Dieser Aufruf muss erfolgen, bevor die Anwendung die freigegebene Umgebung zuweist, für die das Verbindungspooling aktiviert werden soll. Das Umgebungshandle im Aufruf von SQLSetEnvAttr ist auf NULL festgelegt, wodurch SQL_ATTR_CONNECTION_POOLING ein Attribut auf Prozessebene wird. Nachdem das Verbindungspooling aktiviert wurde, ordnet die Anwendung eine implizite freigegebene Umgebung zu, indem SQLAllocHandle aufgerufen wird, wobei das Argument InputHandle auf SQL_HANDLE_ENV festgelegt ist.

Nachdem verbindungspooling aktiviert und eine freigegebene Umgebung für eine Anwendung ausgewählt wurde, kann SQL_ATTR_CONNECTION_POOLING für diese Umgebung nicht zurückgesetzt werden, da SQLSetEnvAttr beim Festlegen dieses Attributs mit einem NULL-Umgebungshandle aufgerufen wird. Wenn dieses Attribut festgelegt wird, während das Verbindungspooling bereits für eine freigegebene Umgebung aktiviert ist, wirkt sich das Attribut nur auf freigegebene Umgebungen aus, die anschließend zugeordnet werden.

Es ist auch möglich, Verbindungspools in einer Umgebung zu aktivieren. Beachten Sie Folgendes zum Pooling von Umgebungsverbindungen:

- Das Aktivieren von Verbindungspooling für ein NULL-Handle ist ein Attribut auf Prozessebene. Anschließend sind zugeordnete Umgebungen eine freigegebene Umgebung und erben die Einstellung für verbindungspooling auf Prozessebene.
– Nachdem eine Umgebung zugeordnet wurde, kann eine Anwendung ihre Verbindungspooleinstellung weiterhin ändern.
- Wenn das Verbindungspooling für die Umgebung aktiviert ist und der Treiber der Verbindung Treiberpooling verwendet, wird das Umgebungspooling bevorzugt.

SQL_ATTR_CONNECTION_POOLING wird im Treiber-Manager implementiert. Ein Treiber muss keine SQL_ATTR_CONNECTION_POOLING implementieren. ODBC 2.0- und 3.0-Anwendungen können dieses Umgebungsattribut 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 wird, bestimmt der Treiber-Manager, welche Verbindung aus dem Pool wiederverwendet wird. Der Treiber-Manager versucht, die Verbindungsoptionen im Aufruf und die von der Anwendung festgelegten Verbindungsattribute mit den Schlüsselwörtern und Verbindungsattributen der Verbindungen im Pool abzugleichen. Der Wert dieses Attributs bestimmt die Genauigkeit der Abgleichskriterien.

Die folgenden Werte werden verwendet, um den Wert dieses Attributs festzulegen:

SQL_CP_STRICT_MATCH = Nur Verbindungen, die genau den Verbindungsoptionen im Aufruf und den von der Anwendung festgelegten Verbindungsattributen entsprechen, werden wiederverwendet. Dies ist die Standardoption.

SQL_CP_RELAXED_MATCH = Verbindungen mit übereinstimmenden Schlüsselwörtern für Verbindungszeichenfolgen können verwendet werden. Schlüsselwörter müssen übereinstimmen, aber nicht alle Verbindungsattribute müssen übereinstimmen.

Weitere Informationen dazu, wie der Treiber-Manager die Übereinstimmung beim Herstellen einer Verbindung mit einer Poolverbindung ausführt, finden Sie unter 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 aufweisen. Die folgenden Werte werden verwendet, um den Wert dieses Attributs festzulegen:

SQL_OV_ODBC3_80 = Treiber-Manager und Treiber weisen das folgende ODBC 3.8-Verhalten auf:

– Der Treiber gibt ODBC 3.x-Codes für Datum, Uhrzeit und Zeitstempel zurück und erwartet diese.
– Der Treiber gibt ODBC 3.x SQLSTATE-Codes zurück, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen wird.
– Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert ein Suchmuster.
– Der Treiber-Manager unterstützt die Erweiterbarkeit des C-Datentyps. Weitere Informationen zur Erweiterbarkeit von C-Datentypen finden Sie unter C-Datentypen in ODBC.

Weitere Informationen finden Sie unter Neuerungen in ODBC 3.8.

SQL_OV_ODBC3 = Treiber-Manager und Treiber weisen das folgende ODBC 3.x-Verhalten auf:

– Der Treiber gibt ODBC 3.x-Codes für Datum, Uhrzeit und Zeitstempel zurück und erwartet diese.
– Der Treiber gibt ODBC 3.x SQLSTATE-Codes zurück, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen wird.
– Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert ein Suchmuster.
– Der Treiber-Manager unterstützt die Erweiterbarkeit des C-Datentyps nicht.

SQL_OV_ODBC2 = Treiber-Manager und Treiber weisen das folgende ODBC 2.x-Verhalten auf. Dies ist besonders nützlich für eine ODBC 2.x-Anwendung , die mit einem ODBC 3.x-Treiber arbeitet.

– Der Treiber gibt ODBC 2.x-Codes für Datum, Uhrzeit und Zeitstempel zurück und erwartet diese.
– Der Treiber gibt ODBC 2.x SQLSTATE-Codes zurück, wenn SQLError, SQLGetDiagField oder SQLGetDiagRec aufgerufen wird.
– Das CatalogName-Argument in einem Aufruf von SQLTables akzeptiert kein Suchmuster.
– Der Treiber-Manager unterstützt die Erweiterbarkeit des C-Datentyps nicht.

Eine Anwendung muss dieses Umgebungsattribut festlegen, bevor sie eine Funktion aufruft, die über ein SQLHENV-Argument verfügt, oder der Aufruf gibt SQLSTATE HY010 (Funktionssequenzfehler) zurück. Es ist treiberspezifisch, ob zusätzliches Verhalten für diese Umgebungsflags vorhanden ist.

– Weitere Informationen finden Sie unter Deklarieren der ODBC-Version und Verhaltensänderungen der Anwendung.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) Eine 32-Bit-Ganzzahl, die bestimmt, wie der Treiber Zeichenfolgendaten zurückgibt. Wenn SQL_TRUE, gibt der Treiber Zeichenfolgendaten mit NULL-Beendigung zurück. Wenn SQL_FALSE, gibt der Treiber keine NULL-endenden Zeichenfolgendaten zurück.

Dieses Attribut ist standardmäßig SQL_TRUE. Ein Aufruf von SQLSetEnvAttr , um es auf SQL_TRUE festzulegen, gibt SQL_SUCCESS zurück. Ein Aufruf von SQLSetEnvAttr , um es auf SQL_FALSE festzulegen, gibt SQL_ERROR und SQLSTATE HYC00 zurück (optionales Feature nicht implementiert).
Informationen über Finden Sie unter
Zuweisen eines Handles SQLAllocHandle-Funktion
Zurückgeben der Einstellung eines Umgebungsattributs SQLGetEnvAttr-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
Neuerungen in ODBC 3.8