SQLSetConnectAttr-Funktion
Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: ISO 92
Zusammenfassung
SQLSetConnectAttr legt Attribute fest, die Aspekte von Verbindungen steuern.
Hinweis
Weitere Informationen dazu, was der Treiber-Manager dieser Funktion zuordnet, wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber arbeitet, finden Sie unter Mapping Replacement Functions for Backward Compatibility of Applications.
Syntax
SQLRETURN SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumente
ConnectionHandle
[Eingabe] Verbindungshandle.
Attribut
[Eingabe] Attribut, das festgelegt werden soll, in "Kommentare" aufgeführt.
ValuePtr
[Eingabe] Zeigen Sie auf den Wert, der dem Attribut zugeordnet werden soll. Abhängig vom Wert des Attributs ist ValuePtr ein ganzzahliger Wert ohne Vorzeichen oder zeigt auf eine Zeichenfolge mit Nullen beendetes Zeichen. Beachten Sie, dass der integrale Typ des Attributarguments möglicherweise keine feste Länge aufweist, ausführliche Informationen finden Sie im Abschnitt "Kommentare".
StringLength
[Eingabe] Wenn attribut ein ODBC-definiertes Attribut ist und ValuePtr auf eine Zeichenfolge oder einen binären Puffer zeigt, sollte dieses Argument die Länge von *ValuePtr sein. Bei Zeichenfolgendaten sollte dieses Argument die Anzahl der Bytes in der Zeichenfolge enthalten.
Wenn das Attribut ein ODBC-definiertes Attribut ist und ValuePtr eine ganze Zahl ist, wird StringLength ignoriert.
Wenn Attribut ein treiberdefiniertes Attribut ist, gibt die Anwendung die Art des Attributs für den Treiber-Manager an, indem Das Argument StringLength festgelegt wird. StringLength kann die folgenden Werte haben:
Wenn ValuePtr ein Zeiger auf eine Zeichenfolge ist, ist StringLength die Länge der Zeichenfolge oder SQL_NTS.
Wenn ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des Makros SQL_LEN_BINARY_ATTR(länge) in StringLength. Dadurch wird ein negativer Wert in StringLength platziert.
Wenn ValuePtr ein Zeiger auf einen anderen Wert als eine Zeichenfolge oder eine binäre Zeichenfolge ist, sollte StringLength den Wert SQL_IS_POINTER haben.
Wenn ValuePtr einen Wert mit fester Länge enthält, ist StringLength entweder SQL_IS_INTEGER oder SQL_IS_UINTEGER, je nach Bedarf.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.
Diagnostik
Wenn SQLSetConnectAttr SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle of ConnectionHandle abgerufen werden. In der folgenden Tabelle sind die sqlSTATE-Werte aufgeführt, die häufig von SQLSetConnectAttr zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
Der Treiber kann SQL_SUCCESS_WITH_INFO zurückgeben, um Informationen zum Ergebnis der Einstellung einer Option bereitzustellen.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S02 | Optionswert geändert | Der Treiber unterstützt den in ValuePtr angegebenen Wert nicht und ersetzte einen ähnlichen Wert. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08002 | Verwendeter Verbindungsname | Das Argument "Attribut " wurde SQL_ATTR_ODBC_CURSORS, und der Treiber war bereits mit der Datenquelle verbunden. |
| 08003 | Verbindung nicht geöffnet | (DM) Es wurde ein Attributwert angegeben, der eine geöffnete Verbindung erforderte, aber das ConnectionHandle-Element war nicht in einem verbundenen Zustand. |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| 24.000 | Ungültiger Cursorstatus | Das Attributargument wurde SQL_ATTR_CURRENT_CATALOG, und ein Resultset steht aus. |
| 25000 | Unzulässiger Vorgang während einer lokalen Transaktion | Eine Verbindung befand sich in einer lokalen Transaktion, während versucht wurde, eine DTC (Distributed Transaction Connection) auflisten zu lassen, indem das Verbindungsattribute SQL_ATTR_ENLIST_IN_DTC festgelegt wurde. Eine Verbindung wird bereits in einem DTC aufgelistet. Eine Verbindung wurde in einer verteilten Transaktionsverbindung aufgelistet, und eine lokale Transaktion wurde gestartet, indem SQL_ATTR_AUTOCOMMIT auf SQL_AUTOCOMMIT_OFF festgelegt wurde. |
| 3D000 | Ungültiger Katalogname | Das Attributargument wurde SQL_CURRENT_CATALOG, und der angegebene Katalogname war ungültig. |
| 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. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für " ConnectionHandle" aktiviert. Die SQLSetConnectAttr-Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde die SQLCancelHandle-Funktion für connectionHandle aufgerufen, und dann wurde die SQLSetConnectAttr-Funktion erneut für die ConnectionHandle-Funktion aufgerufen. Oder die SQLSetConnectAttr-Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancelHandle für das ConnectionHandle von einem anderen Thread in einer Multithread-Anwendung aufgerufen. |
| HY009 | Ungültige Verwendung des Nullzeigers | Das Attributargument hat ein Verbindungsattribute identifiziert, das einen Zeichenfolgenwert erforderte, und das ValuePtr-Argument war ein Nullzeiger. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für ein StatementHandle aufgerufen, das dem ConnectionHandle zugeordnet ist und noch ausgeführt wurde, als SQLSetConnectAttr aufgerufen wurde. (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das ConnectionHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für eine der Anweisungshandles aufgerufen, die dem ConnectionHandle zugeordnet sind und SQL_PARAM_DATA_AVAILABLE zurückgegeben wurden. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für ein StatementHandle-Element aufgerufen, das dem ConnectionHandle zugeordnet ist und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. (DM) SQLBrowseConnect wurde für " ConnectionHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor SQLBrowseConnect SQL_SUCCESS_WITH_INFO oder SQL_SUCCESS zurückgegeben hat. |
| HY011 | Attribut kann jetzt nicht festgelegt werden | Das Attributargument wurde SQL_ATTR_TXN_ISOLATION, und eine Transaktion wurde geöffnet. |
| 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. (Der Treiber-Manager gibt diesen SQLSTATE-Wert nur für Verbindungs- und Anweisungsattribute zurück, die einen separaten Wertesatz akzeptieren, z. B. SQL_ATTR_ACCESS_MODE oder SQL_ATTR_ASYNC_ENABLE. Für alle anderen Verbindungs- und Anweisungsattribute muss der Treiber den in ValuePtr angegebenen Wert überprüfen.) Das Attributargument war SQL_ATTR_TRACEFILE oder SQL_ATTR_TRANSLATE_LIB, und ValuePtr war eine leere Zeichenfolge. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) *ValuePtr ist eine Zeichenfolge, und das Argument StringLength war kleiner als 0, aber nicht SQL_NTS. |
| HY092 | Ungültiger Attribut-/Optionsbezeichner | (DM) Der für das Argumentattribut angegebene Wert war für die vom Treiber unterstützte ODBC-Version ungültig. (DM) Der für das Argument Attribut angegebene Wert war ein schreibgeschütztes Attribut. |
| HY114 | Treiber unterstützt keine asynchrone Funktionsausführung auf Verbindungsebene | (DM) Eine Anwendung hat versucht, die asynchrone Funktionsausführung mit SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE für einen Treiber zu aktivieren, der keine asynchronen Verbindungsvorgänge unterstützt. |
| 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. |
| HY121 | Cursorbibliothek und Driver-Aware Pooling können nicht gleichzeitig aktiviert werden | Weitere Informationen finden Sie unter Driver-Aware Connection Pooling. |
| HYC00 | Optionales Feature wurde nicht implementiert | Der für das Argumentattribut angegebene Wert war ein gültiges ODBC-Verbindungs- oder Anweisungsattribut für die vom Treiber unterstützte ODBC-Version, wurde jedoch vom Treiber nicht unterstützt. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem ConnectionHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM009 | Die Übersetzungs-DLL kann nicht geladen werden. | Der Treiber konnte die Übersetzungs-DLL, die für die Verbindung angegeben wurde, nicht laden. Dieser Fehler kann nur zurückgegeben werden, wenn Attribut SQL_ATTR_TRANSLATE_LIB ist. |
| IM017 | Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. | Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung deaktiviert. |
| IM018 | SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. | Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachbearbeitung durchzuführen und den Vorgang abzuschließen. |
| S1118 | Der Treiber unterstützt keine asynchrone Benachrichtigung. | SQL_ATTR_ASYNC_DBC_EVENT wurde festgelegt (nachdem die Verbindung hergestellt wurde), asynchrone Benachrichtigung wird jedoch vom Treiber nicht unterstützt. |
Wenn "Attribute" ein Anweisungsattribut ist, kann SQLSetConnectAttr alle sqlSTATEs zurückgeben, die von SQLSetStmtAttr zurückgegeben werden.
Kommentare
Allgemeine Informationen zu Verbindungsattributen finden Sie unter "Verbindungsattribute".
Die derzeit definierten Attribute und die Version von ODBC, in der sie eingeführt wurden, werden in der Tabelle weiter unten in diesem Abschnitt gezeigt. es wird erwartet, dass mehr Attribute definiert werden, um verschiedene Datenquellen nutzen zu können. Ein Bereich von Attributen wird von ODBC reserviert; Treiberentwickler müssen Werte für ihre eigene treiberspezifische Verwendung aus Open Group reservieren.
Hinweis
Die Möglichkeit zum Festlegen von Anweisungsattributen auf Verbindungsebene durch Aufrufen von SQLSetConnectAttr ist in ODBC 3*.x* veraltet. ODBC 3*.x*-Anwendungen sollten niemals Anweisungsattribute auf Verbindungsebene festlegen. ODBC 3*.x*-Anweisungsattribute können nicht auf Verbindungsebene festgelegt werden, mit Ausnahme der attribute SQL_ATTR_METADATA_ID und SQL_ATTR_ASYNC_ENABLE Attribute, die sowohl Verbindungsattribute als auch Anweisungsattribute sind und entweder auf Verbindungsebene oder auf Anweisungsebene festgelegt werden können.
ODBC 3*.x*-Treiber müssen diese Funktionalität nur unterstützen, wenn sie mit ODBC 2*.x*-Anwendungen arbeiten sollten, die ODBC 2*.x*-Anweisungsoptionen auf Verbindungsebene festlegen. Weitere Informationen finden Sie unter SQLSetConnectOption-Zuordnung in Anhang G: Treiberrichtlinien für Abwärtskompatibilität.
Eine Anwendung kann SQLSetConnectAttr jederzeit zwischen der Zuordnung der Verbindung aufrufen und freigeben. Alle Verbindungs- und Anweisungsattribute wurden von der Anwendung für die Verbindung erfolgreich festgelegt, bis SQLFreeHandle für die Verbindung aufgerufen wird. Wenn eine Anwendung beispielsweise SQLSetConnectAttr aufruft, bevor eine Verbindung mit einer Datenquelle hergestellt wird, bleibt das Attribut auch dann erhalten, wenn sqlSetConnectAttr im Treiber fehlschlägt, wenn die Anwendung eine Verbindung mit der Datenquelle herstellt. Wenn eine Anwendung ein treiberspezifisches Attribut festlegt, bleibt das Attribut auch dann erhalten, wenn die Anwendung eine Verbindung mit einem anderen Treiber in der Verbindung herstellt.
Einige Verbindungsattribute können nur festgelegt werden, bevor eine Verbindung hergestellt wurde. andere können erst festgelegt werden, nachdem eine Verbindung hergestellt wurde. Die folgende Tabelle gibt die Verbindungsattribute an, die entweder vor oder nach dem Herstellen einer Verbindung festgelegt werden müssen. Gibt entweder an, dass das Attribut vor oder nach der Verbindung festgelegt werden kann.
| Attribut | Vor oder nach der Verbindung festlegen? |
|---|---|
| SQL_ATTR_ACCESS_MODE | Entweder[1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Sowohl als auch |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | Beides[4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Sowohl als auch |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Sowohl als auch |
| SQL_ATTR_ASYNC_ENABLE | Beides[2] |
| SQL_ATTR_AUTO_IPD | Sowohl als auch |
| SQL_ATTR_AUTOCOMMIT | Entweder[5] |
| SQL_ATTR_CONNECTION_DEAD | After |
| SQL_ATTR_CONNECTION_TIMEOUT | Sowohl als auch |
| SQL_ATTR_CURRENT_CATALOG | Entweder[1] |
| SQL_ATTR_DBC_INFO_TOKEN | After |
| SQL_ATTR_ENLIST_IN_DTC | After |
| SQL_ATTR_LOGIN_TIMEOUT | Vorher |
| SQL_ATTR_METADATA_ID | Sowohl als auch |
| SQL_ATTR_ODBC_CURSORS | Vorher |
| SQL_ATTR_PACKET_SIZE | Vorher |
| SQL_ATTR_QUIET_MODE | Sowohl als auch |
| SQL_ATTR_TRACE | Sowohl als auch |
| SQL_ATTR_TRACEFILE | Sowohl als auch |
| SQL_ATTR_TRANSLATE_LIB | After |
| SQL_ATTR_TRANSLATE_OPTION | After |
| SQL_ATTR_TXN_ISOLATION | Beides[3] |
[1] SQL_ATTR_ACCESS_MODE und SQL_ATTR_CURRENT_CATALOG können je nach Treiber vor oder nach dem Verbinden festgelegt werden. Interoperable Anwendungen legen sie jedoch vor dem Herstellen der Verbindung fest, da einige Treiber diese änderungen nach dem Herstellen der Verbindung nicht unterstützen.
[2] SQL_ATTR_ASYNC_ENABLE muss festgelegt werden, bevor eine aktive Anweisung vorhanden ist.
[3] SQL_ATTR_TXN_ISOLATION kann nur festgelegt werden, wenn keine offenen Transaktionen für die Verbindung vorhanden sind. Einige Verbindungsattribute unterstützen die Ersetzung eines ähnlichen Werts, wenn die Datenquelle den in *ValuePtr angegebenen Wert nicht unterstützt. In solchen Fällen gibt der Treiber SQL_SUCCESS_WITH_INFO und SQLSTATE 01S02 zurück (Optionswert geändert). Wenn das Attribut beispielsweise SQL_ATTR_PACKET_SIZE und *ValuePtr die maximale Paketgröße überschreitet, ersetzt der Treiber die maximale Größe. Um den ersetzten Wert zu ermitteln, ruft eine Anwendung SQLGetConnectAttr auf.
[4] Wenn SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE festgelegt ist, bevor eine Verbindung geöffnet wird, legt der Treiber-Manager das Attribut des Treibers fest, wenn der Treiber während eines Aufrufs von SQLBrowseConnect, SQLConnect oder SQLDriverConnect geladen wird. Vor einem Aufruf von SQLBrowseConnect, SQLConnect oder SQLDriverConnect weiß der Treiber-Manager nicht, mit welchem Treiber eine Verbindung hergestellt werden soll, und weiß nicht, ob der Treiber asynchrone Verbindungsvorgänge unterstützt. Daher gibt der Treiber-Manager immer SQL_SUCCESS zurück. Wenn der Treiber jedoch keine asynchronen Verbindungsvorgänge unterstützt, schlägt der Aufruf von SQLBrowseConnect, SQLConnect oder SQLDriverConnect fehl.
[5] Wenn SQL_ATTR_AUTOCOMMIT auf FALSE festgelegt ist, sollten Anwendungen SQLEndTran(SQL_ROLLBACK) aufrufen, wenn eine API SQL_ERROR zurückgibt, um die Transaktionskonsistenz sicherzustellen.
Das Format der im *ValuePtr-Puffer festgelegten Informationen hängt vom angegebenen Attribut ab. SQLSetConnectAttr akzeptiert Attributinformationen in einem von zwei verschiedenen Formaten: eine mit Null beendete Zeichenzeichenfolge oder einen ganzzahligen Wert. Das Format der einzelnen Wird in der Beschreibung des Attributs angegeben. Zeichenzeichenfolgen, auf die das ValuePtr-Argument von SQLSetConnectAttr verweist, weisen eine Länge von StringLength Bytes auf.
Das Argument StringLength wird ignoriert, wenn die Länge durch das Attribut definiert wird, wie bei allen Attributen, die in ODBC 2*.x* oder früher eingeführt wurden.
| Attribut | ValuePtr-Inhalt |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Ein SQLUINTEGER-Wert. SQL_MODE_READ_ONLY wird vom Treiber oder der Datenquelle als Indikator verwendet, dass die Verbindung nicht erforderlich ist, um SQL-Anweisungen zu unterstützen, die zu Aktualisierungen führen. Dieser Modus kann verwendet werden, um Sperrstrategien, Transaktionsverwaltung oder andere Bereiche entsprechend dem Treiber oder der Datenquelle zu optimieren. Der Treiber ist nicht erforderlich, um zu verhindern, dass solche Aussagen an die Datenquelle übermittelt werden. Das Verhalten des Treibers und der Datenquelle beim Verarbeiten von SQL-Anweisungen, die während einer schreibgeschützten Verbindung nicht schreibgeschützt sind, ist implementierungsdefiniert. SQL_MODE_READ_WRITE ist die Standardeinstellung. |
| SQL_ATTR_ASYNC_DBC_EVENT (ODBC 3.8) | Ein SQLPOINTER-Wert, der ein Ereignishandle ist. Die Benachrichtigung über den Abschluss asynchroner Funktionen wird durch Aufrufen von SQLSetConnectAttr mit dem attribut SQL_ATTR_ASYNC_STMT_EVENT aktiviert und das Ereignishandle angegeben. Hinweis: Die Benachrichtigungsmethode wird von der Cursorbibliothek nicht unterstützt. Eine Anwendung erhält eine Fehlermeldung, wenn versucht wird, die Cursorbibliothek über SQLSetConnectAttr zu aktivieren, wenn die Benachrichtigungsmethode aktiviert ist. |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) | Ein SQLUINTEGER-Wert, der die asynchrone Ausführung ausgewählter Funktionen im Verbindungshandle aktiviert oder deaktiviert. Weitere Informationen finden Sie unter Asynchrone Ausführung (Polling-Methode).For more information, see Asynchronous Execution (Polling Method). SQL_ASYNC_DBC_ENABLE_ON = Asynchroner Vorgang für angegebene verbindungsbezogene Funktionen aktivieren. SQL_ASYNC_DBC_ENABLE_OFF = (Standard) Deaktivieren Des asynchronen Vorgangs für angegebene verbindungsbezogene Funktionen. Das Festlegen SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE ist immer synchron (d. a. es wird nie SQL_STILL_EXECUTING zurückgegeben). Die asynchrone Ausführung von Anweisungsvorgängen ist mit SQL_ATTR_ASYNC_ENABLE aktiviert. |
| SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) | Ein SQLPOINTER-Wert, der auf die Kontextstruktur verweist. Nur der Treiber-Manager kann die SQLSetStmtAttr-Funktion eines Treibers mit diesem Attribut aufrufen. |
| SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) | Ein SQLPOINTER-Wert, der auf die Kontextstruktur verweist. Nur der Treiber-Manager kann die SQLSetStmtAttr-Funktion eines Treibers mit diesem Attribut aufrufen. |
| SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) | Ein SQLULEN-Wert, der angibt, ob eine Funktion, die mit einer Anweisung für die angegebene Verbindung aufgerufen wird, asynchron ausgeführt wird: SQL_ASYNC_ENABLE_OFF = Asynchrone Ausführungsunterstützung für Anweisungsvorgänge auf Verbindungsebene deaktivieren (Standardeinstellung). SQL_ASYNC_ENABLE_ON = Aktivieren der asynchronen Ausführungsebene für Anweisungsvorgänge. Dieses Attribut kann festgelegt werden, ob SQLGetInfo mit dem SQL_ASYNC_MODE Informationstyp SQL_AM_CONNECTION oder SQL_AM_STATEMENT zurückgibt. |
| SQL_ATTR_AUTO_IPD (ODBC 3.0) | Ein schreibgeschützter SQLUINTEGER-Wert, der angibt, ob die automatische Grundgesamtheit der IPD nach einem Aufruf von SQLPrepare unterstützt wird: SQL_TRUE = Automatische Grundpopulation der IPD, nachdem ein Aufruf von SQLPrepare vom Treiber unterstützt wird. SQL_FALSE = Automatische Population der IPD, nachdem ein Aufruf von SQLPrepare vom Treiber nicht unterstützt wird. Server, die vorbereitete Anweisungen nicht unterstützen, können die IPD nicht automatisch auffüllen. Wenn SQL_TRUE für das SQL_ATTR_AUTO_IPD-Verbindungsattribute zurückgegeben wird, kann das Attribut der Anweisung SQL_ATTR_ENABLE_AUTO_IPD so festgelegt werden, dass die automatische Grundgesamtheit der IPD aktiviert oder deaktiviert wird. Wenn SQL_ATTR_AUTO_IPD SQL_FALSE ist, kann SQL_ATTR_ENABLE_AUTO_IPD nicht auf SQL_TRUE festgelegt werden. Der Standardwert von SQL_ATTR_ENABLE_AUTO_IPD ist gleich dem Wert von SQL_ATTR_AUTO_IPD. Dieses Verbindungsattribut kann von SQLGetConnectAttr zurückgegeben, aber nicht von SQLSetConnectAttr festgelegt werden. |
| SQL_ATTR_AUTOCOMMIT (ODBC 1.0) | Ein SQLUINTEGER-Wert, der angibt, ob der Autocommit- oder manueller Commit-Modus verwendet werden soll: SQL_AUTOCOMMIT_OFF = Der Treiber verwendet den manuellen Commitmodus, und die Anwendung muss transaktionen mit SQLEndTran explizit commiten oder zurücksetzen. SQL_AUTOCOMMIT_ON = Der Treiber verwendet den Autocommit-Modus. Jede Anweisung wird unmittelbar nach der Ausführung zugesichert. Dies ist die Standardeinstellung. Alle geöffneten Transaktionen für die Verbindung werden zugesichert, wenn SQL_ATTR_AUTOCOMMIT auf SQL_AUTOCOMMIT_ON festgelegt ist, um vom manuellen Commit-Modus in den AutoCommit-Modus zu wechseln. Weitere Informationen finden Sie unter Commit-Modus. Wichtig: Einige Datenquellen löschen die Zugriffspläne und schließen die Cursor für alle Anweisungen für eine Verbindung jedes Mal, wenn eine Anweisung zugesichert wird. Der AutoCommit-Modus kann dazu führen, dass dies geschieht, nachdem jede nicht abfragefreie Anweisung ausgeführt wird oder wenn der Cursor für eine Abfrage geschlossen wird. Weitere Informationen finden Sie in den SQL_CURSOR_COMMIT_BEHAVIOR- und SQL_CURSOR_ROLLBACK_BEHAVIOR Informationstypen in SQLGetInfo und Auswirkungen von Transaktionen auf Cursor und vorbereitete Anweisungen. Wenn ein Batch im AutoCommit-Modus ausgeführt wird, sind zwei Dinge möglich. Der gesamte Batch kann als autokommitierbare Einheit behandelt werden, oder jede Anweisung in einem Batch wird als autokommitierbare Einheit behandelt. Bestimmte Datenquellen können sowohl diese Verhaltensweisen unterstützen als auch eine Möglichkeit bieten, eine oder die andere auszuwählen. Es wird vom Treiber definiert, ob ein Batch als automatisch verwendbare Einheit behandelt wird oder ob jede einzelne Anweisung innerhalb des Batches automatisch aussetzbar ist. |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
Ein schreibgeschützter SQLUINTEGER-Wert, der den Status der Verbindung angibt. Wenn SQL_CD_TRUE, geht die Verbindung verloren. Wenn SQL_CD_FALSE, ist die Verbindung noch aktiv. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Ein SQLUINTEGER-Wert, der der Anzahl von Sekunden entspricht, bis eine Anforderung für die Verbindung abgeschlossen ist, bevor sie zur Anwendung zurückkehrt. Der Treiber sollte SQLSTATE HYT00 (Timeout abgelaufen) jederzeit zurückgeben, wenn ein Timeout in einer Situation möglich ist, die nicht mit der Abfrageausführung oder Anmeldung verknüpft ist. Wenn ValuePtr gleich 0 (Standardeinstellung) ist, gibt es kein Timeout. |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | Eine Zeichenfolge mit dem Namen des Katalogs, die von der Datenquelle verwendet werden soll. In SQL Server ist der Katalog beispielsweise eine Datenbank, sodass der Treiber eine USE-Datenbank-Anweisung an die Datenquelle sendet, wobei die Datenbank die in *ValuePtr angegebene Datenbank ist. Bei einem einzelstufigen Treiber kann der Katalog ein Verzeichnis sein, sodass der Treiber sein aktuelles Verzeichnis in das verzeichnis ändert, das in *ValuePtr angegeben ist. |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8) | Ein SQLPOINTER-Wert, der verwendet wird, um das Verbindungsinformationstoken in das DBC-Handle zurückzustellen, wenn der Parameter "SQLRateConnection(* pRating") nicht gleich 100 ist. SQL_ATTR_DBC_INFO_TOKEN ist schreibgeschützt. Es ist nicht möglich, diesen Wert mithilfe von SQLGetConnectAttr oder SQLGetConnectOption abzurufen. Der SQLSetConnectAttr des Treiber-Managers akzeptiert SQL_ATTR_DBC_INFO_TOKEN nicht, da eine Anwendung dieses Attributs nicht festlegen sollte. Wenn ein Treiber nach dem Festlegen SQL_ATTR_DBC_INFO_TOKEN SQL_ERROR zurückgibt, wird die soeben aus dem Pool abgerufene Verbindung freigegeben. Der Treiber-Manager versucht dann, eine andere Verbindung vom Pool abzurufen. Weitere Informationen finden Sie unter Developing Connection-Pool Awareness in einem ODBC-Treiber . |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Ein SQLPOINTER-Wert, der angibt, ob der ODBC-Treiber in verteilten Transaktionen verwendet werden soll, die von Microsoft Component Services koordiniert werden. Übergeben Sie ein DTC OLE-Transaktionsobjekt, das die zu exportierende Transaktion in SQL Server angibt, oder SQL_DTC_DONE, um die DTC-Zuordnung der Verbindung zu beenden. Der Client ruft die OLE ITransactionDispenser::BeginTransaction-Methode von Microsoft Distributed Transaction Coordinator (MS DTC) auf, um eine MS DTC-Transaktion zu starten und ein MS DTC-Transaktionsobjekt zu erstellen, das die Transaktion darstellt. Die Anwendung ruft dann SQLSetConnectAttr mit der Option SQL_ATTR_ENLIST_IN_DTC auf, um das Transaktionsobjekt der ODBC-Verbindung zuzuordnen. Alle entsprechenden Datenbankaktivitäten werden unter dem Schutz der MS DTC-Transaktion durchgeführt. Die Anwendung ruft SQLSetConnectAttr mit SQL_DTC_DONE auf, um die DTC-Zuordnung der Verbindung zu beenden. Weitere Informationen finden Sie in der MS DTC-Dokumentation. |
| SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) | Ein SQLUINTEGER-Wert, der der Anzahl von Sekunden entspricht, bis eine Anmeldeanforderung abgeschlossen ist, bevor sie zur Anwendung zurückkehrt. Der Standardwert ist treiberabhängig. Wenn ValuePtr 0 ist, ist das Timeout deaktiviert, und ein Verbindungsversuch wartet auf unbestimmte Zeit. Wenn das angegebene Timeout das maximale Anmeldetimeout in der Datenquelle überschreitet, ersetzt der Treiber diesen Wert und gibt SQLSTATE 01S02 zurück (Optionswert geändert). |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | Ein SQLUINTEGER-Wert, der bestimmt, wie die Zeichenfolgenargumente von Katalogfunktionen behandelt werden. Wenn SQL_TRUE, werden das Zeichenfolgenargument von Katalogfunktionen als Bezeichner behandelt. Der Fall ist nicht von Bedeutung. Bei nicht getrennten Zeichenfolgen entfernt der Treiber alle nachfolgenden Leerzeichen, und die Zeichenfolge wird in Großbuchstaben gefaltet. Bei durch Trennzeichen getrennten Zeichenfolgen entfernt der Treiber alle führenden oder nachgestellten Leerzeichen und nimmt buchstäblich das, was zwischen den Trennzeichen liegt. Wenn eines dieser Argumente auf einen Nullzeiger festgelegt ist, gibt die Funktion SQL_ERROR und SQLSTATE HY009 zurück (Ungültige Verwendung des Nullzeigers). Wenn SQL_FALSE, werden die Zeichenfolgenargumente von Katalogfunktionen nicht als Bezeichner behandelt. Der Fall ist von Bedeutung. Sie können je nach Argument entweder ein Zeichenfolgensuchmuster enthalten oder nicht. Der Standardwert ist SQL_FALSE. Das TableType-Argument von SQLTables, das eine Liste von Werten akzeptiert, wird von diesem Attribut nicht beeinflusst. SQL_ATTR_METADATA_ID können auch auf Der Anweisungsebene festgelegt werden. (Es ist das einzige Verbindungsattribute, das auch ein Anweisungsattribut ist.) Weitere Informationen finden Sie unter Argumente in Katalogfunktionen. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Ein SQLULEN-Wert, der angibt, wie der Treiber-Manager die ODBC-Cursorbibliothek verwendet: SQL_CUR_USE_IF_NEEDED = Der Treiber-Manager verwendet die ODBC-Cursorbibliothek nur, wenn sie benötigt wird. Wenn der Treiber die option SQL_FETCH_PRIOR in SQLFetchScroll unterstützt, verwendet der Treiber-Manager die Bildlauffunktionen des Treibers. Andernfalls wird die ODBC-Cursorbibliothek verwendet. SQL_CUR_USE_ODBC = Der Treiber-Manager verwendet die ODBC-Cursorbibliothek. SQL_CUR_USE_DRIVER = Der Treiber-Manager verwendet die Bildlauffunktionen des Treibers. Dies ist die Standardeinstellung. Weitere Informationen zur ODBC-Cursorbibliothek finden Sie in Anhang F: ODBC Cursor Library. Warnung: Die Cursorbibliothek wird in einer zukünftigen Version von Windows entfernt. Vermeiden Sie die Verwendung dieses Features in neuer Entwicklungsarbeit, und planen Sie, Anwendungen zu ändern, die dieses Feature derzeit verwenden. Microsoft empfiehlt die Verwendung der Cursorfunktion des Treibers. |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | Ein SQLUINTEGER-Wert, der die Netzwerkpaketgröße in Byte angibt. Hinweis: Viele Datenquellen unterstützen diese Option nicht oder nur können zurückgegeben, aber nicht die Netzwerkpaketgröße festgelegt werden. Wenn die angegebene Größe die maximale Paketgröße überschreitet oder kleiner als die minimale Paketgröße ist, ersetzt der Treiber diesen Wert und gibt SQLSTATE 01S02 zurück (Optionswert geändert). Wenn die Anwendung die Paketgröße festlegt, nachdem bereits eine Verbindung hergestellt wurde, gibt der Treiber SQLSTATE HY011 zurück (Attribut kann jetzt nicht festgelegt werden). |
| SQL_ATTR_QUIET_MODE (ODBC 2.0) | Ein Fensterziehpunkt (HWND). Wenn das Fensterhandle ein NULL-Zeiger ist, zeigt der Treiber keine Dialogfelder an. Wenn das Fensterhandle kein NULL-Zeiger ist, sollte es sich um das übergeordnete Fensterhandle der Anwendung handeln. Dies ist die Standardeinstellung. Der Treiber verwendet dieses Handle zum Anzeigen von Dialogfeldern. Hinweis: Das SQL_ATTR_QUIET_MODE-Verbindungsattribute gilt nicht für Dialogfelder, die von SQLDriverConnect angezeigt werden. |
| SQL_ATTR_TRACE (ODBC 1.0) | Ein SQLUINTEGER-Wert, der dem Treiber-Manager mitteilt, ob die Ablaufverfolgung ausgeführt werden soll: SQL_OPT_TRACE_OFF = Ablaufverfolgung deaktiviert (Standardeinstellung) SQL_OPT_TRACE_ON = Ablaufverfolgung nach Wenn die Ablaufverfolgung aktiviert ist, schreibt der Treiber-Manager jeden ODBC-Funktionsaufruf in die Ablaufverfolgungsdatei. Hinweis: Wenn die Ablaufverfolgung aktiviert ist, kann der Treiber-Manager SQLSTATE IM013 (Ablaufverfolgungsdateifehler) von einer beliebigen Funktion zurückgeben. Eine Anwendung gibt eine Ablaufverfolgungsdatei mit der Option SQL_ATTR_TRACEFILE an. Wenn die Datei bereits vorhanden ist, fügt der Treiber-Manager an die Datei an. Andernfalls wird die Datei erstellt. Wenn die Ablaufverfolgung aktiviert ist und keine Ablaufverfolgungsdatei angegeben wurde, schreibt der Treiber-Manager in die Datei SQL. LOG im Stammverzeichnis. Eine Anwendung kann die Variable ODBCSharedTraceFlag so festlegen, dass die Ablaufverfolgung dynamisch aktiviert wird. Die Ablaufverfolgung wird dann für alle derzeit ausgeführten ODBC-Anwendungen aktiviert. Wenn eine Anwendung die Ablaufverfolgung deaktiviert, ist sie nur für diese Anwendung deaktiviert. Wenn das Trace-Schlüsselwort in den Systeminformationen auf 1 festgelegt ist, wenn eine Anwendung SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV aufruft, ist die Ablaufverfolgung für alle Handles aktiviert. Sie ist nur für die Anwendung aktiviert, die SQLAllocHandle aufgerufen hat. Das Aufrufen von SQLSetConnectAttr mit einem Attribut von SQL_ATTR_TRACE erfordert nicht, dass das Argument ConnectionHandle gültig ist und SQL_ERROR nicht zurückgegeben wird, wenn ConnectionHandle NULL ist. Dieses Attribut gilt für alle Verbindungen. |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | Eine mit Null beendete Zeichenfolge, die den Namen der Ablaufverfolgungsdatei enthält. Der Standardwert des attributs SQL_ATTR_TRACEFILE wird mit dem TraceFile-Schlüsselwort in den Systeminformationen angegeben. Weitere Informationen finden Sie unter ODBC-Unterschlüssel. Das Aufrufen von SQLSetConnectAttr mit einem Attribut von SQL_ATTR_TRACEFILE erfordert nicht, dass das Argument ConnectionHandle gültig ist und SQL_ERROR nicht zurückgegeben wird, wenn ConnectionHandle ungültig ist. Dieses Attribut gilt für alle Verbindungen. |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | Eine mit Null beendete Zeichenfolge mit dem Namen einer Bibliothek, die die Funktionen SQLDriverToDataSource und SQLDataSourceToDriver enthält, auf die der Treiber zugreift, um Aufgaben wie die Zeichensatzübersetzung auszuführen. Diese Option kann nur angegeben werden, wenn der Treiber mit der Datenquelle verbunden ist. Die Einstellung dieses Attributs wird über Verbindungen hinweg beibehalten. Weitere Informationen zum Übersetzen von Daten finden Sie unter Übersetzungs-DLLs und Übersetzungs-DLL-Funktionsreferenz. |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | Ein 32-Bit-Flagwert, der an die Übersetzungs-DLL übergeben wird. Dieses Attribut kann nur angegeben werden, wenn der Treiber mit der Datenquelle verbunden ist. Informationen zum Übersetzen von Daten finden Sie unter Übersetzungs-DLLs. |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | Eine 32-Bit-Bitmaske, die die Transaktionsisolationsstufe für die aktuelle Verbindung festlegt. Eine Anwendung muss SQLEndTran aufrufen, um alle geöffneten Transaktionen in einer Verbindung zu übernehmen oder zurückzurufen, bevor SQLSetConnectAttr mit dieser Option aufgerufen wird. Die gültigen Werte für ValuePtr können durch Aufrufen von SQLGetInfo mit InfoType gleich SQL_TXN_ISOLATION_OPTIONS bestimmt werden. Eine Beschreibung der Transaktionsisolationsstufen finden Sie in der Beschreibung des SQL_DEFAULT_TXN_ISOLATION Informationstyps in SQLGetInfo - und Transaktionsisolationsstufen. |
[1] Diese Funktionen können asynchron nur aufgerufen werden, wenn der Deskriptor ein Implementierungsdeskriptor ist, nicht ein Anwendungsdeskriptor.
Codebeispiel
Siehe SQLConnect.
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Zuordnen eines Handles | SQLAllocHandle-Funktion |
| Zurückgeben der Einstellung eines Verbindungsattributes | SQLGetConnectAttr-Funktion |