SQLSetStmtAttr

Gilt für:SQL ServerAzure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

Der SQL Server Native Client ODBC-Treiber unterstützt das gemischte Cursormodell (Keyset/Dynamic) 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 fest, um die Anzahl der Zeilen zu deklarieren, die bei einem SQLFetch - oder SQLFetchScroll-Funktionsaufruf zurückgegeben werden. 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 verwendet werden, um SQL_SOPT_SS_PARAM_FOCUS im Anwendungsparameterdeskriptor (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 SQL_ERROR zurück, und ein Diagnosedatensatz wird 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 verwendet werden, um SQL_SOPT_SS_NAME_SCOPE festzulegen. Weitere Informationen finden Sie im Abschnitt zu SQL_SOPT_SS_NAME_SCOPE weiter unten in diesem Thema.

Weitere Informationen finden Sie unter Tabellenwertparametermetadaten 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 verwendet werden, um SQL_SOPT_SS_NAME_SCOPE festzulegen. Weitere Informationen finden Sie weiter unten in diesem Thema im Abschnitt SQL_SOPT_SS_NAME_SCOPE. Weitere Informationen zu Sparsespalten finden Sie unter Unterstützung von Sparsespalten (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 sind. Die Standardeinstellung ist SQL_CO_OFF. Der ValuePtr -Wert ist vom Typ SQLLEN.

ValuePtr-Wert	BESCHREIBUNG
SQL_CO_OFF	Standard. Deaktiviert schnelle vorwärtsgerichtete, schreibgeschützte Cursor und autofetch, aktiviert SQLGetData auf vorwärts gerichteten, schreibgeschützten Cursorn. 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 nun mithilfe von SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE einen anderen Cursortyp festlegen.
SQL_CO_FFO	Aktiviert schnelle vorwärtsgerichtete, schreibgeschützte Cursor und deaktiviert SQLGetData auf vorwärts gerichteten, schreibgeschützten Cursorn.
SQL_CO_AF	Aktiviert die automatische Abrufoption für jeden Cursortyp. Wenn diese Option für ein Anweisungshandle festgelegt ist, generiert SQLExecute oder SQLExecDirect einen impliziten 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 weiterhin SQLFreeStmt (SQL_CLOSE) oder SQLCloseCursor aufrufen, aber der Treiber muss die Benachrichtigung zum Schließen nicht an den Server senden.

Wenn die Auswahlliste eine Text-, ntext- oder Bildspalte enthält, wird der nur schnelle Vorwärtscursor in einen dynamischen Cursor konvertiert, und SQLGetData ist zulässig.

SQL_SOPT_SS_DEFER_PREPARE

Das attribut SQL_SOPT_SS_DEFER_PREPARE bestimmt, ob die Anweisung sofort vorbereitet oder verzögert wird, bis SQLExecute, SQLDescribeCol oder SQLDescribeParam ausgeführt wird. In SQL Server 7.0 und früheren Versionen wird diese Eigenschaft ignoriert (keine verzögerte Vorbereitung). Der ValuePtr -Wert ist vom Typ SQLLEN.

ValuePtr-Wert	BESCHREIBUNG
SQL_DP_ON	Standard. Nach dem Aufrufen der SQLPrepare-Funktion wird die Anweisungsvorbereitung verzögert, bis SQLExecute aufgerufen wird 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 aus SQL Server nativen Datentypen nur in Zeichenfolgen.

Der ValuePtr -Wert ist vom Typ SQLLEN.

ValuePtr-Wert	BESCHREIBUNG
SQL_RE_OFF	Standard. 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 das Gebietsschema des aktuellen Threads nicht, wenn die Anwendung es durch den Aufruf 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 die Protokollierung von Vorgängen für Spalten um, die Text - oder Bilddaten enthalten. Der ValuePtr -Wert ist vom Typ SQLLEN.

ValuePtr-Wert	BESCHREIBUNG
SQL_TL_OFF	Deaktiviert die Protokollierung von Vorgängen, die für Text - und Bilddaten ausgeführt werden.
SQL_TL_ON	Standard. Ermöglicht die Protokollierung von Vorgängen, die für Text - und Bilddaten ausgeführt werden.

SQL_SOPT_SS_HIDDEN_COLUMNS

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

ValuePtr-Wert	BESCHREIBUNG
SQL_HC_OFF	Standard. 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 Lesen von Benachrichtigungen von 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 432.000 Sekunden (5 Tage). Der ValuePtr -Wert ist vom Typ SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

Das attribut SQL_SOPT_SS_PARAM_FOCUS gibt den Fokus für nachfolgende SQLBindParameter-, SQLGetDescField-, SQLSetDescField-, SQLGetDescRec- und SQLSetDescRec-Aufrufe 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	Standard. Gibt bei Verwendung von Tabellenwertparametern an, dass Metadaten für tatsächliche Tabellen zurückgegeben werden sollen. Bei Verwendung des Features "Sparsespalten" gibt SQLColumns nur Spalten zurück, die keine Mitglieder des Sparse-column_set 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	Bei Verwendung des Features "Sparsespalten" gibt SQLColumns alle Spalten zurück, unabhängig von column_set Mitgliedschaft.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	Bei Verwendung des Features "Sparsespalten" gibt SQLColumns nur Spalten zurück, die Mitglieder der sparse-column_set sind.
SQL_SS_NAME_SCOPE_DEFAULT	Identisch mit SQL_SS_NAME_SCOPE_TABLE

SS_TYPE_CATALOG_NAME und SS_TYPE_SCHEMA_NAME werden mit den Parametern CatalogName bzw . SchemaName 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.

Wenn eine andere Katalogfunktion als SQLTables, SQLColumns oder SQLPrimaryKeys aufgerufen wird, wenn SQL_SOPT_SS_NAME_SCOPE einen anderen Wert als SQL_SS_NAME_SCOPE_TABLE hat, 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.

Weitere Informationen

SQLGetStmtAttr-Funktion
ODBC API Implementation Details