SQLSpecialColumns-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: Open Group

Zusammenfassung
SQLSpecialColumns ruft die folgenden Informationen zu Spalten in einer angegebenen Tabelle ab:

• Der optimale Satz von Spalten, die eine Zeile in der Tabelle eindeutig identifiziert.

• Spalten, die automatisch aktualisiert werden, wenn ein Beliebiger Wert in der Zeile von einer 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] Spaltentyp, der zurückgegeben werden soll. Dies muss einer der folgenden Werte sein:

SQL_BEST_ROWID: Gibt die optimale Spalte oder einen Satz von Spalten zurück, die durch Abrufen von Werten aus der Spalte oder Spalten jede Zeile in der angegebenen Tabelle eindeutig identifiziert werden kann. Eine Spalte kann entweder eine pseudospalte sein, die speziell für diesen Zweck entwickelt wurde (wie in Oracle ROWID oder Ingres TID) oder die Spalte oder Spalten eines eindeutigen Indexes für die Tabelle.

SQL_ROWVER: Gibt die Spalte oder Spalten in der angegebenen Tabelle (sofern vorhanden) zurück, die automatisch von der Datenquelle aktualisiert werden, wenn ein beliebiger Wert in der Zeile von einer Transaktion aktualisiert wird (wie in 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, z. B. wenn der Treiber Daten aus verschiedenen DBMSs abruft, gibt eine leere Zeichenfolge ("") diese Tabellen an, die keine Kataloge enthalten. CatalogName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das attribut der SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird CatalogName als Bezeichner behandelt, und der Fall ist nicht relevant. Wenn es SQL_FALSE ist, ist CatalogName ein gewöhnliches Argument; es wird buchstäblich behandelt, und der Fall ist signifikant. Weitere Informationen finden Sie unter "Argumente in Katalogfunktionen".

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

Schemaname
[Eingabe] Schemaname für die Tabelle. Wenn ein Treiber Schemas für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen DBMSs abruft, gibt eine leere Zeichenfolge ("") diese Tabellen an, die keine Schemas besitzen. SchemaName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das attribut der SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird SchemaName als Bezeichner behandelt, und die Groß-/Kleinschreibung ist nicht relevant. Wenn es SQL_FALSE ist, ist SchemaName ein gewöhnliches Argument; es wird buchstäblich behandelt, und der Fall ist signifikant.

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

TableName
[Eingabe] Tabellenname. Dieses Argument kann kein Nullzeiger sein. TableName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das attribut der SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird TableName als Bezeichner behandelt, und der Fall ist nicht relevant. Wenn es SQL_FALSE ist, ist TableName ein gewöhnliches Argument; es wird buchstäblich behandelt, und der Fall ist signifikant.

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

Umfang
[Eingabe] Mindestens erforderlicher Bereich der Zeilen-ID. Die zurückgegebene Rowid kann einen größeren Bereich aufweisen. Dies muss eine der folgenden Ressourcen sein:

SQL_SCOPE_CURROW: Die Zeilen-ID ist garantiert nur gültig, wenn sie in dieser Zeile positioniert ist. Eine spätere erneute Auswahl mit rowid gibt möglicherweise keine Zeile zurück, wenn die Zeile von einer anderen Transaktion aktualisiert oder gelöscht wurde.

SQL_SCOPE_TRANSACTION: Die Zeilen-ID ist garantiert für die Dauer der aktuellen Transaktion gültig.

SQL_SCOPE_SESSION: Die Zeilen-ID ist garantiert für die Dauer der Sitzung gültig (über Transaktionsgrenzen hinweg).

NULL zulassen
[Eingabe] Bestimmt, ob spezielle Spalten zurückgegeben werden sollen, die einen NULL-Wert aufweisen können. Dies muss eine der folgenden Ressourcen sein:

SQL_NO_NULLS: Schließen Sie spezielle Spalten aus, die NULL-Werte enthalten können. Einige Treiber können SQL_NO_NULLS nicht unterstützen, und diese Treiber geben ein leeres Resultset zurück, wenn SQL_NO_NULLS angegeben wurde. Bewerbungen sollten für diesen Fall vorbereitet werden und SQL_NO_NULLS nur dann anfordern, wenn sie unbedingt erforderlich ist.

SQL_NULLABLE: Geben Sie spezielle Spalten zurück, auch wenn sie NULL-Werte aufweisen können.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLSpecialColumns SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLSpecialColumns 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.

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 Auswahlliste oder WHERE-Klausel verwendet werden. SQLColumns, die verwendet wird, um eine Vielzahl von Informationen zu 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 von einer Transaktion aktualisiert wird. Beispielsweise gibt SQLColumns möglicherweise nicht die Oracle-Pseudospalte ROWID zurück. Aus diesem Grund wird SQLSpecialColumns verwendet, um diese Spalten zurückzugeben. Weitere Informationen finden Sie unter Verwendung von Katalogdaten.

Wenn keine Spalten vorhanden sind, die jede Zeile in der Tabelle eindeutig identifizieren, gibt SQLSpecialColumns ein Rowset ohne Zeilen zurück; ein nachfolgender Aufruf von SQLFetch oder SQLFetchScroll für die Anweisung gibt SQL_NO_DATA zurück.

Wenn die Argumente IdentifierType, Scope oder Nullable Merkmale angeben, die von der Datenquelle nicht unterstützt werden, gibt SQLSpecialColumns einen leeren Resultset zurück.

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

SQLSpecialColumns gibt die Ergebnisse als Standardergebnissatz zurück, sortiert nach SCOPE.

Die folgenden Spalten wurden für ODBC 3.x umbenannt. Die Änderungen des Spaltennamens wirken sich nicht auf die Abwärtskompatibilität aus, da Anwendungen nach Spaltennummer gebunden sind.

Um die tatsächliche Länge der spalte COLUMN_NAME zu bestimmen, kann eine Anwendung SQLGetInfo mit der option SQL_MAX_COLUMN_NAME_LEN 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 Zugriff auf treiberspezifische Spalten erhalten, indem sie vom Ende des Resultsets heruntergezählt wird, anstatt eine explizite Ordnungsposition anzugeben. Weitere Informationen finden Sie unter "Von Katalogfunktionen zurückgegebene Daten".

Nachdem die Anwendung Werte für SQL_BEST_ROWID abgerufen hat, kann die Anwendung diese Werte verwenden, um diese Zeile im definierten Bereich erneut auszuwählen. Die SELECT-Anweisung kann garantiert weder Zeilen noch eine Zeile zurückgeben.

Wenn eine Anwendung eine Zeile basierend auf der Zeilen-ID-Spalte oder -Spalten erneut auswählen und die Zeile nicht gefunden wird, kann die Anwendung davon ausgehen, dass die Zeile gelöscht wurde oder die Zeilen-ID-Spalten geändert wurden. Das Gegenteil ist nicht wahr: Auch wenn sich die Zeilen-ID nicht geändert hat, haben sich die anderen Spalten in der Zeile möglicherweise geändert.

Spalten, die für den Spaltentyp SQL_BEST_ROWID zurückgegeben werden, sind nützlich für Anwendungen, die innerhalb eines Resultsets nach vorne und zurück scrollen müssen, um die aktuellsten Daten aus einer Reihe von Zeilen abzurufen. Die Spalte oder Spalten der Zeilen-ID werden garantiert nicht geändert, während sie in dieser Zeile positioniert sind.

Die Spalte oder Spalten der Zeilen-ID können neu Standard gültig sein, auch wenn der Cursor nicht in der Zeile positioniert ist. Die Anwendung kann dies ermitteln, indem die BEREICH-Spalte im Resultset überprüft wird.

Spalten, die für den Spaltentyp zurückgegeben werden SQL_ROWVER 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 mithilfe der Zeilen-ID erneut ausgewählt wurde. Beispielsweise kann die Anwendung nach der erneuten Auswahl einer Zeile mit rowid die vorherigen Werte in den SQL_ROWVER Spalten mit den soeben abgerufenen vergleichen. Wenn sich der Wert in einer SQL_ROWVER Spalte vom vorherigen Wert unterscheidet, kann die Anwendung den Benutzer darüber benachrichtigen, dass sich die Daten auf der Anzeige geändert haben.

Codebeispiel

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

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien