SQLSpecialColumns-Funktion

Konformität
Eingeführte Version: ODBC 1.0 Standards Compliance: Open Group

Summary
SQLSpecialColumns ruft folgende Informationen über Spalten innerhalb einer festgelegten Tabelle ab:

• Die optimale Menge von Spalten, die eindeutig eine Zeile in der Tabelle identifiziert.

• Spalten, die automatisch aktualisiert werden, wenn ein Wert in der Zeile durch eine Transaktion aktualisiert wird.

Syntax

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

IdentifierType
[Eingabe] Art der Spalte, die zurückgegeben werden soll. Dies muss einer der folgenden Werte sein:

SQL_BEST_ROWID: Gibt die optimale Spalte oder Spaltenmenge zurück, die durch das Abrufen von Werten aus der Spalte oder den Spalten jede Zeile in der angegebenen Tabelle eindeutig identifizieren lässt. Eine Spalte kann entweder eine speziell für diesen Zweck entwickelte Pseudo-Spalte sein (wie in Oracle ROWID oder Ingres TID) oder die Spalte oder mehrere Spalten eines eindeutigen Index für die Tabelle.

SQL_ROWVER: Gibt die Spalte oder Spalten in der angegebenen Tabelle, falls vorhanden, zurück, die automatisch von der Datenquelle aktualisiert werden, wenn ein Wert in der Zeile durch eine Transaktion aktualisiert wird (wie bei SQLBase ROWID oder Sybase TIMESTAMP).

Catalogname
[Eingabe] Katalogname für die Tabelle. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, etwa wenn der Treiber Daten aus verschiedenen DBMSs abruft, bezeichnet eine leere Zeichenkette ("") jene Tabellen, die keine Kataloge besitzen. CatalogName kann kein String-Suchmuster enthalten.

Wenn das Attribut SQL_ATTR_METADATA_ID Statement auf SQL_TRUE gesetzt ist, wird CatalogName als Identifikator behandelt und sein Fall ist nicht signifikant. Wenn es SQL_FALSE ist, ist CatalogName ein gewöhnliches Argument; Es wird wörtlich behandelt, und sein Fall ist bedeutsam. Weitere Informationen finden Sie unter Argumente in Katalogfunktionen.

NameLength1
[Eingabe] Länge in den Zeichen von *CatalogName.

SchemaName
[Eingabe] Schema-Name für die Tabelle. Wenn ein Treiber Schemata für einige Tabellen, aber für andere nicht unterstützt, etwa wenn der Treiber Daten aus verschiedenen DBMSs abruft, bezeichnet eine leere Zeichenkette ("") jene Tabellen, die keine Schemata enthalten. SchemaName kann kein Zeichenkettensuchmuster enthalten.

Wenn das Attribut SQL_ATTR_METADATA_ID Statement auf SQL_TRUE gesetzt ist, wird SchemaName als Identifikator behandelt und sein Fall ist nicht signifikant. Wenn es SQL_FALSE ist, ist SchemaName ein gewöhnliches Argument; Es wird wörtlich behandelt, und sein Fall ist bedeutsam.

NameLength2
[Eingabe] Länge in den Zeichen von *SchemaName.

Tabellenname
[Eingabe] Tabellenname. Dieses Argument kann kein Nullpointer sein. TableName kann kein Zeichenkettensuchmuster enthalten.

Wenn das Attribut SQL_ATTR_METADATA_ID Statement auf SQL_TRUE gesetzt ist, wird TableName als Identifikator behandelt und sein Fall ist nicht signifikant. Wenn es SQL_FALSE ist, ist TableName ein gewöhnliches Argument; Es wird wörtlich behandelt, und sein Fall ist bedeutsam.

NameLength3
[Eingabe] Länge in den Zeichen von *TableName.

Scope
[Eingabe] Mindestmaßnahme des Rowid. Das zurückgekommene Rowid könnte von größerem Umfang sein. Muss einer der folgenden Werte sein:

SQL_SCOPE_CURROW: Der Rowid ist garantiert nur gültig, solange er auf dieser Reihe steht. Eine spätere Neuauswahl mit Rowid kann eine Zeile nicht zurückgeben, wenn die Zeile durch eine andere Transaktion aktualisiert oder gelöscht wurde.

SQL_SCOPE_TRANSACTION: Das Rowid ist garantiert für die Dauer der aktuellen Transaktion gültig.

SQL_SCOPE_SESSION: Der Rowid ist für die Dauer der Sitzung (über Transaktionsgrenzen hinweg) garantiert gültig.

Nullable
[Eingabe] Bestimmt, ob spezielle Spalten zurückgegeben werden sollen, die einen NULL-Wert haben können. Muss einer der folgenden Werte sein:

SQL_NO_NULLS: Spezielle Spalten ausschließen, die NULL-Werte haben können. Einige Treiber können SQL_NO_NULLS nicht unterstützen und geben ein leeres Ergebnisset zurück, wenn SQL_NO_NULLS angegeben wurde. Bewerbungen sollten für diesen Fall vorbereitet werden und SQL_NO_NULLS nur dann beantragen, wenn es absolut erforderlich ist.

SQL_NULLABLE: Spezielle Spalten zurückgeben, selbst wenn sie NULL-Werte haben können.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLSpecialColumns 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_STMT und einem Handle von StatementHandle aufgerufen wird. Die folgende Tabelle listet die von SQLSpecialColumns häufig zurückgegebenen SQLSTATE-Werte 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.

Kommentare

Wenn das IdentifierType-Argument SQL_BEST_ROWID ist, gibt SQLSpecialColumns die Spalte oder Spalten zurück, die jede Zeile in der Tabelle eindeutig identifizieren. Diese Spalten können immer in einer Select-List- oder WHERE-Klausel verwendet werden. SQLColumns, das verwendet wird, um eine Vielzahl von Informationen in den Spalten einer Tabelle zurückzugeben, gibt nicht unbedingt die Spalten zurück, die jede Zeile eindeutig identifizieren, oder Spalten, die automatisch aktualisiert werden, wenn ein Wert in der Zeile durch eine Transaktion aktualisiert wird. Zum Beispiel geben SQLColumns möglicherweise nicht das Oracle-Pseudo-Spalten-ROWID zurück. Deshalb wird SQLSpecialColumns verwendet, um diese Spalten zurückzugeben. Weitere Informationen finden Sie unter Verwendung von Katalogdaten.

Gibt es keine Spalten, die jede Zeile in der Tabelle eindeutig identifizieren, gibt SQLSpecialColumns eine Zeilenmenge ohne Zeilen zurück; ein anschließender Aufruf von SQLFetch oder SQLFetchScroll auf der Anweisung liefert SQL_NO_DATA.

Wenn die IdentifierType-, Scope- oder Nullable-Argumente Eigenschaften angeben, die von der Datenquelle nicht unterstützt werden, liefert SQLSpecialColumns eine leere Ergebnismenge zurück.

Wenn das Attribut SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE gesetzt ist, werden die Argumente CatalogName,SchemaName und TableName als Identifikatoren behandelt, sodass sie in bestimmten Situationen nicht auf einen Nullzeiger gesetzt werden können. (Weitere Informationen finden Sie unter Argumente in Katalogfunktionen.)

SQLSpecialColumns liefert die Ergebnisse als Standardergebnisset, geordnet nach SCOPE.

Die folgenden Spalten wurden für ODBC 3.x umbenannt. Die Änderungen des Spaltennamens beeinflussen die Abwärtskompatibilität nicht, da Anwendungen nach Spaltennummer binden.

Um die tatsächliche Länge der COLUMN_NAME-Spalte zu bestimmen, kann eine Anwendung SQLGetInfo mit der SQL_MAX_COLUMN_NAME_LEN-Option aufrufen.

In der folgenden Tabelle sind die Spalten im Resultset aufgeführt. Zusätzliche Spalten über Spalte 8 (PSEUDO_COLUMN) hinaus können vom Treiber definiert werden. Eine Anwendung sollte auf treiberspezifische Spalten zuzugreifen, indem sie vom Ende der Ergebnismenge herunterzählt, anstatt eine explizite Ordinalposition anzugeben. Weitere Informationen finden Sie unter "Von Katalogfunktionen zurückgegebene Daten".

Nachdem die Anwendung Werte für SQL_BEST_ROWID abgerufen hat, kann sie diese Werte verwenden, um diese Zeile innerhalb des definierten Umfangs erneut auszuwählen. Die SELECT-Anweisung gibt garantiert entweder keine Zeilen oder nur eine Zeile zurück.

Wenn eine Anwendung eine Zeile basierend auf der Rowid-Spalte oder den Spalten erneut auswählt und die Zeile nicht gefunden wird, kann die Anwendung davon ausgehen, dass die Zeile gelöscht oder die Rowid-Spalten geändert wurden. Das Gegenteil ist nicht der Fall: Selbst wenn sich das Rowid nicht geändert hat, könnten sich die anderen Spalten in der Zeile verändert haben.

Spalten, die für Spaltentyp SQL_BEST_ROWID zurückgegeben werden, sind nützlich für Anwendungen, die innerhalb eines Ergebnissets vor- und zurückscrollen müssen, um die aktuellsten Daten aus einer Reihe von Zeilen abzurufen. Die Spalte oder Spalten des Rowid ändern sich garantiert nicht, während sie auf dieser Zeile positioniert sind.

Die Spalte oder Spalten des Rowid können auch dann gültig bleiben, wenn der Cursor nicht auf der Zeile positioniert ist; die Anwendung kann dies bestimmen, indem sie die Spalte SCOPE im Ergebnisset überprüft.

Für Spaltentyp SQL_ROWVER zurückgegebene Spalten sind nützlich für Anwendungen, die die Möglichkeit benötigen, zu überprüfen, ob Spalten in einer bestimmten Zeile aktualisiert wurden, während die Zeile mit der Rowid neu ausgewählt wurde. Zum Beispiel kann die Anwendung nach der erneuten Auswahl einer Zeile mit rowid die vorherigen Werte in den SQL_ROWVER Spalten mit den gerade abgerufenen vergleichen. Wenn der Wert in einer SQL_ROWVER-Spalte vom vorherigen abweicht, kann die Anwendung den Benutzer darauf hinweisen, dass sich die Daten auf der Anzeige geändert haben.

Codebeispiel

Ein Codebeispiel für eine ähnliche Funktion finden Sie unter SQLColumns.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien