Artikel
09/24/2010

SQLSetStmtAttr

Der SQL Server Native Client ODBC-Treiber unterstützt das gemischte Cursormodell (keysetgesteuert/dynamisch) nicht. Der Versuch, die Keysetgröße mit SQL_ATTR_KEYSET_SIZE festzulegen, schlägt fehl, wenn der festgelegte Wert ungleich 0 (null) ist.

Die Anwendung legt SQL_ATTR_ROW_ARRAY_SIZE für alle Anweisungen so fest, dass die Zahl der bei einem SQLFetch-Funktionsaufruf oder einem SQLFetchScroll-Funktionsaufruf zurückgegebenen Zeilen deklariert wird. Bei Anweisungen, die einen Servercursor angeben, verwendet der Treiber SQL_ATTR_ROW_ARRAY_SIZE, um die Größe des Zeilenblocks zu ermitteln, der vom Server als Reaktion auf eine Abrufanforderung des Cursors generiert wird. Innerhalb der Blockgröße eines dynamischen Cursors sind die Zeilenmitgliedschaft und -reihenfolge festgelegt, wenn die Isolationsstufe der Transaktion ausreichend ist, um wiederholbare Lesevorgänge von Transaktionen sicherzustellen, für die ein Commit ausgeführt wurde. Der Cursor ist außerhalb des von diesem Wert angegebenen Blocks vollkommen dynamisch. Die Blockgröße des Servercursors ist vollkommen dynamisch und kann zu jedem Zeitpunkt während der Abrufverarbeitung geändert werden.

'SQLSetStmtAttr' und Tabellenwertparameter

SQLSetStmtAttr kann dazu verwendet werden, SQL_SOPT_SS_PARAM_FOCUS im Anwendungsparameterdeskriptor (Application Parameter Descriptor, APD) festzulegen, bevor auf Deskriptorfelder für Tabellenwertparameterspalten zugegriffen wird.

Wenn versucht wird, SQL_SOPT_SS_PARAM_FOCUS auf die Ordnungszahl eines Parameters festzulegen, der kein Tabellenwertparameter ist, gibt SQLSetStmtAttr den Wert SQL_ERROR zurück, und es wird ein Diagnosedatensatz mit SQLSTATE = HY024 und der Meldung "Ungültiger Attributwert" erstellt. SQL_SOPT_SS_PARAM_FOCUS wird nicht geändert, wenn SQL_ERROR zurückgegeben wird.

Durch das Festlegen von SQL_SOPT_SS_PARAM_FOCUS auf 0 (null) wird der Zugriff auf Deskriptordatensätze für Parameter wiederhergestellt.

SQLSetStmtAttr kann auch zum Festlegen von SQL_SOPT_SS_NAME_SCOPE verwendet werden. Weitere Informationen finden Sie im Abschnitt zu SQL_SOPT_SS_NAME_SCOPE weiter unten in diesem Thema.

Weitere Informationen finden Sie unter Tabellenwertparameter-Metadaten für vorbereitete Anweisungen.

Weitere Informationen zu Tabellenwertparametern finden Sie unter Tabellenwertparameter (ODBC).

Unterstützung von 'SQLSetStmtAttr' für Spalten mit geringer Dichte

SQLSetStmtAttr kann zum Festlegen von SQL_SOPT_SS_NAME_SCOPE verwendet werden. Weitere Informationen finden Sie im Abschnitt zu SQL_SOPT_SS_NAME_SCOPE weiter unten in diesem Thema. Weitere Informationen über Spalten mit geringer Dichte finden Sie unter Unterstützung für Spalten mit geringer Dichte (ODBC).

Anweisungsattribute

Der SQL Server Native Client ODBC-Treiber unterstützt auch die folgenden treiberspezifischen Anweisungsattribute.

SQL_SOPT_SS_CURSOR_OPTIONS

Das SQL_SOPT_SS_CURSOR-Attribut gibt an, ob der Treiber treiberspezifische Leistungsoptionen für Cursor verwendet. SQLGetData ist nicht zulässig, wenn diese Optionen festgelegt werden. Die Standardeinstellung ist SQL_CO_OFF. Diese Optionen sind nur gültig in Verbindung mit einer Instanz von SQL Server Version 7.0 oder höher. Der ValuePtr-Wert ist vom Typ SQLLEN.

ValuePtr-Wert	Beschreibung
SQL_CO_OFF	Standardwert. Deaktiviert schnelle Vorwärtscursor, schreibgeschützte Cursor und den automatischen Abruf, aktiviert SQLGetData für Vorwärtscursor und schreibgeschützte Cursor. Wenn SQL_SOPT_SS_CURSOR_OPTIONS auf SQL_CO_OFF festgelegt ist, ändert sich der Cursortyp nicht. Das heißt, ein schneller Vorwärtscursor bleibt ein schneller Vorwärtscursor. Um den Cursortyp zu ändern, muss die Anwendung jetzt mit SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE einen anderen Cursortyp festlegen.
SQL_CO_FFO	Aktiviert schnelle Vorwärtscursor, schreibgeschützte Cursor und deaktiviert SQLGetData für Vorwärtscursor und schreibgeschützte Cursor.
SQL_CO_AF	Aktiviert die automatische Abrufoption für jeden Cursortyp. Wenn diese Option für ein Anweisungshandle festgelegt ist, generiert SQLExecute oder SQLExecDirect implizit SQLFetchScroll (SQL_FIRST). Der Cursor wird geöffnet, und der erste Batch Zeilen wird mit einem einzigen Roundtrip an den Server zurückgegeben.
SQL_CO_FFO_AF	Aktiviert schnelle Vorwärtscursor mit der automatischen Abrufoption. Das entspricht der gleichzeitigen Angabe von SQL_CO_AF und SQL_CO_FFO.

Wenn diese Optionen festgelegt sind, schließt der Server den Cursor automatisch, wenn er erkennt, dass die letzte Zeile abgerufen wurde. Die Anwendung muss trotzdem SQLFreeStmt (SQL_CLOSE) oder SQLCloseCursor aufrufen, jedoch muss der Treiber dem Server keine Benachrichtigung zum Schließen senden.

Wenn die Auswahlliste eine text-Spalte, ntext-Spalte oder image-Spalte enthält, wird der schnelle Vorwärtscursor in einen dynamischen Cursor umgewandelt und SQLGetData zugelassen.

SQL_SOPT_SS_DEFER_PREPARE

Das SQL_SOPT_SS_DEFER_PREPARE-Attribut bestimmt, ob die Anweisung sofort vorbereitet oder bis zur Ausführung von SQLExecute, SQLDescribeCol oder SQLDescribeParam verzögert wird. In SQL Server 7.0 und früheren Versionen wird diese Eigenschaft ignoriert (die Vorbereitung nicht verzögert). Der ValuePtr-Wert ist vom Typ SQLLEN.

ValuePtr-Wert	Beschreibung
SQL_DP_ON	Standardwert. Nach Aufrufen von SQLPrepare wird die Anweisungsvorbereitung verzögert, bis SQLExecute aufgerufen oder der Metaeigenschaftsvorgang (SQLDescribeCol oder SQLDescribeParam) ausgeführt wird.
SQL_DP_OFF	Die Anweisung wird vorbereitet, sobald SQLPrepare ausgeführt wird.

SQL_SOPT_SS_REGIONALIZE

Das SQL_SOPT_SS_REGIONALIZE-Attribut wird verwendet, um die Datenkonvertierung auf Anweisungsebene zu bestimmen. Das Attribut bewirkt, dass der Treiber bei der Konvertierung von Datums-, Uhrzeit- und Währungswerten in Zeichenfolgen die Gebietsschemaeinstellung des Clients beachtet. Die Konvertierung erfolgt lediglich von systemeigenen SQL Server-Datentypen in Zeichenfolgen.

Der ValuePtr-Wert ist vom Typ SQLLEN.

ValuePtr-Wert	Beschreibung
SQL_RE_OFF	Standardwert. Der Treiber konvertiert Datums-, Uhrzeit- und Währungsdaten nicht gemäß der Gebietsschemaeinstellung des Clients in Zeichenfolgendaten.
SQL_RE_ON	Der Treiber konvertiert Datums-, Uhrzeit- und Währungsdaten gemäß der Gebietsschemaeinstellung des Clients in Zeichenfolgendaten.

Regionale Konvertierungseinstellungen gelten für Währungs-, Zahlen-, Datums- und Uhrzeitdatentypen. Die Konvertierungseinstellungen gelten nur für Ausgabekonvertierungen, wenn Währungs-, Zahlen-, Datums- oder Uhrzeitwerte in Zeichenfolgen konvertiert werden.

Hinweis
Wenn die SQL_SOPT_SS_REGIONALIZE-Anweisungsoption aktiviert ist, verwendet der Treiber die lokalen Registrierungseinstellungen für den aktuellen Benutzer. Der Treiber berücksichtigt die lokale Einstellung des aktuellen Threads nicht, wenn die Anwendung sie beispielsweise durch Aufrufen von SetThreadLocale festlegt.

Das Verändern des regionalen Verhaltens einer Datenquelle kann Anwendungsfehler verursachen. Eine Anwendung, die Datumszeichenfolgen analysiert und erwartet, dass sie der ODBC-Definition entsprechen, wird durch die Änderung dieses Werts möglicherweise beeinträchtigt.

SQL_SOPT_SS_TEXTPTR_LOGGING

Das SQL_SOPT_SS_TEXTPTR_LOGGING-Attribut schaltet zwischen der Protokollierung und Nichtprotokollierung von Vorgängen für Spalten um, die text-Daten oder image-Daten enthalten. Der ValuePtr-Wert ist vom Typ SQLLEN.

ValuePtr-Wert	Beschreibung
SQL_TL_OFF	Deaktiviert die Protokollierung von Vorgängen, die für text-Daten und image-Daten ausgeführt werden.
SQL_TL_ON	Standardwert. Aktiviert die Protokollierung von Vorgängen, die für text-Daten und image-Daten ausgeführt werden.

SQL_SOPT_SS_HIDDEN_COLUMNS

Das SQL_SOPT_SS_HIDDEN_COLUMNS-Attribut macht Spalten im Resultset verfügbar, die in einer SQL Server-SELECT FOR BROWSE-Anweisung verborgen sind. Der Treiber macht diese Spalten standardmäßig nicht verfügbar. Der ValuePtr-Wert ist vom Typ SQLLEN.

ValuePtr-Wert	Beschreibung
SQL_HC_OFF	Standardwert. FOR BROWSE-Spalten werden aus dem Resultset ausgeblendet.
SQL_HC_ON	Macht FOR BROWSE-Spalten verfügbar.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

Das SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT-Attribut gibt den Meldungstext für die Abfragebenachrichtigungsanforderung zurück.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

Das SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS-Attribut gibt die Optionen an, die für die Abfragebenachrichtigungsanforderung verwendet werden. Diese werden in einer Zeichenfolge mit der Syntax name=value angegeben (siehe Code weiter unten). Die Anwendung ist für das Erstellen des Diensts und das Lesen von Benachrichtigungen aus der Warteschlange verantwortlich.

Die Syntax der Zeichenfolge für die Abfragebenachrichtigungsoptionen lautet:

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

Beispiel:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

Das SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT-Attribut gibt die Dauer (in Sekunden) an, für die die Abfragebenachrichtigung aktiv bleiben soll. Der Standardwert lautet 432000 Sekunden (5 Tage). Der ValuePtr-Wert ist vom Typ SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

Das SQL_SOPT_SS_PARAM_FOCUS-Attribut gibt den Fokus für nachfolgende Aufrufe vom Typ SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec und SQLSetDescRec an.

Der Typ für SQL_SOPT_SS_PARAM_FOCUS lautet SQLULEN.

Der Standardwert ist 0 (null). Das bedeutet, dass diese Aufrufe sich an Parameter richten, die Parametermarkierungen in der SQL-Anweisung entsprechen. Wenn diese Aufrufe auf die Parameternummer eines Tabellenwertparameters festgelegt sind, adressieren sie Spalten dieses Tabellenwertparameters. Wenn sie auf einen anderen Wert als die Parameternummer eines Tabellenwertparameters festgelegt sind, geben diese Aufrufe den Fehler IM020 zurück: "Parameterfokus verweist nicht auf einen Tabellenwertparameter."

SQL_SOPT_SS_NAME_SCOPE

Das SQL_SOPT_SS_NAME_SCOPE-Attribut gibt den Namensbereich für nachfolgende Katalogfunktionsaufrufe an. Das von SQLColumns zurückgegebene Resultset hängt von der Einstellung von SQL_SOPT_SS_NAME_SCOPE ab.

Der Typ für SQL_SOPT_SS_NAME_SCOPE lautet SQLULEN.

ValuePtr-Wert	Beschreibung
SQL_SS_NAME_SCOPE_TABLE	Standardwert. Gibt bei Verwendung von Tabellenwertparametern an, dass Metadaten für tatsächliche Tabellen zurückgegeben werden sollen. Wenn das Feature für Spalten mit geringer Dichte verwendet wird, gibt SQLColumns nur Spalten zurück, die keine Elemente von column_set mit geringer Dichte sind.
SQL_SS_NAME_SCOPE_TABLE_TYPE	Gibt an, dass die Anwendung Metadaten für einen Tabellentyp anstatt einer tatsächlichen Tabelle erfordert (Katalogfunktionen sollten Metadaten für Tabellentypen zurückgeben). Die Anwendung übergibt dann den TYPE_NAME des Tabellenwertparameters als TableName-Parameter.
SQL_SS_NAME_SCOPE_EXTENDED	Wenn das Feature für Spalten mit geringer Dichte verwendet wird, gibt SQLColumns alle Spalten zurück, unabhängig davon, ob sie Elemente von column_set sind.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	Wenn das Feature für Spalten mit geringer Dichte verwendet wird, gibt SQLColumns nur Spalten zurück, die Elemente von column_set mit geringer Dichte sind.
SQL_SS_NAME_SCOPE_DEFAULT	Identisch mit SQL_SS_NAME_SCOPE_TABLE

SS_TYPE_CATALOG_NAME bzw. SS_TYPE_SCHEMA_NAME wird mit dem CatalogName-Parameter bzw. dem SchemaName-Parameter verwendet, um den Katalog und das Schema für den Tabellenwertparameter zu identifizieren. Wenn eine Anwendung das Abrufen von Metadaten für Tabellenwertparameter abgeschlossen hat, muss sie SQL_SOPT_SS_NAME_SCOPE wieder auf den Standardwert SQL_SS_NAME_SCOPE_TABLE festlegen.

Wenn SQL_SOPT_SS_NAME_SCOPE auf SQL_SS_NAME_SCOPE_TABLE festgelegt ist, schlagen Abfragen von Verbindungsservern fehl. Aufrufe von SQLColumns oder SQLPrimaryKeys mit einem Katalog, der eine Serverkomponente enthält, schlagen fehl.

Wenn Sie versuchen, SQL_SOPT_SS_NAME_SCOPE auf einen ungültigen Wert festzulegen, wird SQL_ERROR zurückgegeben. Zudem wird ein Diagnosedatensatz mit SQLSTATE HY024 und der Meldung "Ungültiger Attributwert" generiert.

Wird eine andere Katalogfunktion als SQLTables, SQLColumns oder SQLPrimaryKeys aufgerufen, wenn SQL_SOPT_SS_NAME_SCOPE einen anderen Wert als SQL_SS_NAME_SCOPE_TABLE aufweist, wird SQL_ERROR zurückgegeben. Ein Diagnosedatensatz mit SQLSTATE HY010 und der Meldung "Fehler in der Funktionsreihenfolge (SQL_SOPT_SS_NAME_SCOPE ist nicht auf SQL_SS_NAME_SCOPE_TABLE festgelegt)" wird generiert.

Änderungsverlauf

Aktualisierter Inhalt
Der Typ für SQL_SOPT_SS_NAME_SCOPE und SQL_SOPT_SS_PARAM_FOCUS wurde auf SQLULEN aktualisiert.