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] Typ der zurückzugebenden Spalte. 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 konzipiert ist (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 zurück, sofern vorhanden, die automatisch von der Datenquelle aktualisiert werden, wenn ein Beliebiger Wert in der Zeile von einer beliebigen 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 signifikant. Wenn es SQL_FALSE ist, ist CatalogName ein normales Argument; es wird buchstäblich behandelt, und sein Fall ist erheblich. 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 unterstützt, aber nicht für andere, z. B. wenn der Treiber Daten aus unterschiedlichen DBMSs abruft, gibt eine leere Zeichenfolge ("") diese Tabellen an, die keine Schemas aufweisen. SchemaName darf kein Zeichenfolgensuchmuster enthalten.

Wenn das Attribut der SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird SchemaName als Bezeichner behandelt und der Fall ist nicht signifikant. Wenn es SQL_FALSE ist, ist SchemaName ein normales Argument; es wird buchstäblich behandelt, und sein Fall ist erheblich.

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 signifikant. Wenn es SQL_FALSE ist, ist TableName ein normales Argument; es wird buchstäblich behandelt, und sein Fall ist erheblich.

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

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

SQL_SCOPE_CURROW: Die Rowid 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 Rowid ist garantiert für die Dauer der aktuellen Transaktion gültig.

SQL_SCOPE_SESSION: Die Rowid 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 aufweisen können. Einige Treiber können SQL_NO_NULLS nicht unterstützen, und diese Treiber geben einen leeren Resultset zurück, wenn SQL_NO_NULLS angegeben wurde. Anträge sollten für diesen Fall vorbereitet sein und SQL_NO_NULLS nur anfordern, wenn es unbedingt erforderlich ist.

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

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

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 die einzelnen werte im Kontext dieser Funktion erläutert werden; 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.

SQLSTATE Fehler Beschreibung
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08S01 Kommunikationslinkfehler Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, konnte nicht ausgeführt werden, bevor die Verarbeitung der Funktion abgeschlossen wurde.
24.000 Ungültiger Cursorstatus Ein Cursor wurde im StatementHandle geöffnet, und SQLFetch oder SQLFetchScroll wurde aufgerufen. Dieser Fehler wird vom Treiber-Manager zurückgegeben, wenn SQLFetch oder SQLFetchScroll nicht SQL_NO_DATA zurückgegeben wurde und vom Treiber zurückgegeben wird, wenn SQLFetch oder SQLFetchScroll SQL_NO_DATA zurückgegeben wurde.

Ein Cursor wurde im StatementHandle geöffnet, aber SQLFetch oder SQLFetchScroll wurde nicht aufgerufen.
40001 Serialisierungsfehler Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003 Abschluss der Anweisung unbekannt Die zugeordnete Verbindung ist während der Ausführung dieser Funktion fehlgeschlagen, und der Status der Transaktion kann nicht bestimmt werden.
HY000 Allgemeiner Fehler Fehler, für den keine spezifische SQLSTATE vorhanden war und für die keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherzuweisung Der Treiber konnte den 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 das StatementHandle aktiviert. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen. Anschließend wurde die Funktion erneut im StatementHandle aufgerufen.

Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY009 Ungültige Verwendung von Nullzeigern Das Argument "TableName " war ein Nullzeiger.

Das attribut "SQL_ATTR_METADATA_ID-Anweisung" wurde auf SQL_TRUE festgelegt, das Argument "CatalogName " war ein Nullzeiger, und der SQL_CATALOG_NAME InfoType gibt diese Katalognamen zurück.

(DM) Das SQL_ATTR_METADATA_ID-Anweisungsattribute wurde auf SQL_TRUE festgelegt, und das SchemaName-Argument war ein Nullzeiger.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese Funktion wurde noch ausgeführt, als SQLSpecialColumns aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für die AnweisungHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle streamierten Parameter abgerufen wurden.

(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für die AnweisungHandle aufgerufen und wurde weiterhin ausgeführt, wenn diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die AnweisungHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Datenausführungsparameter oder Spalten gesendet wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, da die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnten, möglicherweise aufgrund niedriger Speicherbedingungen.
HY090 Ungültige Zeichenfolge oder Pufferlänge (DM) Der Wert eines der Längenargumente war kleiner als 0, aber nicht gleich SQL_NTS.

Der Wert eines der Längenargumente überschreitet den maximalen Längenwert für den entsprechenden Namen. Die maximale Länge jedes Namens kann durch Aufrufen von SQLGetInfo mit den InfoType-Werten abgerufen werden: SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN oder SQL_MAX_TABLE_NAME_LEN.
HY097 Spaltentyp außerhalb des Bereichs (DM) Ein ungültiger IdType-Wert wurde angegeben.
HY098 Bereichstyp außerhalb des Bereichs (DM) Ein ungültiger Bereichswert wurde angegeben.
HY099 Nullable-Typ außerhalb des Bereichs (DM) Ein ungültiger Nullwert wurde angegeben.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Nur Trenn- und Schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYC00 Optionales Feature wurde nicht implementiert Ein Katalog wurde angegeben, und der Treiber oder die Datenquelle unterstützt keine Kataloge.

Ein Schema wurde angegeben, und die Treiber- oder Datenquelle unterstützt keine Schemas.

Die Kombination der aktuellen Einstellungen der SQL_ATTR_CONCURRENCY und SQL_ATTR_CURSOR_TYPE Anweisungsattribute wurde vom Treiber oder der Datenquelle nicht unterstützt.

Das SQL_ATTR_USE_BOOKMARKS-Anweisungsattribute wurde auf SQL_UB_VARIABLE festgelegt, und das SQL_ATTR_CURSOR_TYPE-Anweisungsattribute wurde auf einen Cursortyp festgelegt, für den der Treiber keine Textmarken unterstützt.
HYT00 Timeout abgelaufen Der Abfrage-Timeoutzeitraum ist abgelaufen, bevor die Datenquelle den angeforderten Ergebnissatz zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr festgelegt, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für die Verbindung ist abgelaufen, bevor die Datenquelle auf die Anforderung reagierte. Der Zeitoutzeitraum für die Verbindung wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der mit der AnweisungHandle verknüpfte Treiber unterstützt die Funktion nicht.
IM017 Die Abfrage ist im asynchronen Benachrichtigungsmodus deaktiviert. Wenn das Benachrichtigungsmodell verwendet wird, ist die Abfrage deaktiviert.
IM018 SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang auf diesem Handle abzuschließen. Wenn der vorherige Funktionsaufruf des Handles SQL_STILL_EXECUTING zurückgibt und wenn der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync zum Verarbeiten und Abschließen des Vorgangs aufgerufen werden.

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 über die 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-Pseudospalten-ROWID zurück. Deshalb wird SQLSpecialColumns verwendet, um diese Spalten zurückzugeben. Weitere Informationen finden Sie unter Verwendung von Katalogdaten.

Hinweis

Weitere Informationen zur allgemeinen Verwendung, Argumente und zurückgegebenen Daten von ODBC-Katalogfunktionen finden Sie unter Katalogfunktionen.

Wenn keine Spalten vorhanden sind, die jede Zeile in der Tabelle eindeutig identifizieren, gibt SQLSpecialColumns ein Zeilenet ohne Zeilen zurück; Ein nachfolgenden Aufruf von SQLFetch oder SQLFetchScroll auf der Anweisung gibt SQL_NO_DATA zurück.

Wenn die Argumente "IdentifierType", " Bereich" oder " Null " Merkmale angeben, die von der Datenquelle nicht unterstützt werden, gibt SQLSpecialColumns einen leeren Ergebnissatz zurück.

Wenn das SQL_ATTR_METADATA_ID-Anweisungsattribute 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 Spaltennamenänderungen wirken sich nicht auf die Abwärtskompatibilität aus, da Anwendungen nach Spaltennummer binden.

ODBC 2.0-Spalte ODBC 3.x-Spalte
PRECISION COLUMN_SIZE
LENGTH BUFFER_LENGTH
SCALE DECIMAL_DIGITS

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

In der folgenden Tabelle werden die Spalten im Ergebnissatz aufgelistet. Zusätzliche Spalten über Spalte 8 (PSEUDO_COLUMN) können vom Treiber definiert werden. Eine Anwendung sollte Zugriff auf treiberspezifische Spalten erhalten, indem Sie ab dem Ende des Ergebnissatzes zählen, anstatt eine explizite Ordinalposition anzugeben. Weitere Informationen finden Sie unter "Von Katalogfunktionen zurückgegebene Daten".

Spaltenname Spaltennummer Datentyp Kommentare
BEREICH (ODBC 1.0) 1 Smallint Tatsächlicher Bereich der Rowid. Enthält einen der folgenden Werte:

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION

NULL wird zurückgegeben, wenn IdentifierType SQL_ROWVER ist. Eine Beschreibung jedes Werts finden Sie in der Beschreibung des Bereichs in "Syntax" weiter oben in diesem Abschnitt.
COLUMN_NAME (ODBC 1.0) 2 Varchar nicht NULL Spaltenname. Der Treiber gibt eine leere Zeichenfolge für eine Spalte zurück, die keinen Namen hat.
DATA_TYPE (ODBC 1.0) 3 Smallint nicht NULL SQL Datentyp. Dies kann ein ODBC-SQL Datentyp oder ein treiberspezifischer SQL Datentyp sein. Eine Liste gültiger ODBC-SQL Datentypen finden Sie unter SQL Datentypen. Informationen zu treiberspezifischen SQL Datentypen finden Sie in der Dokumentation des Treibers.
TYPE_NAME (ODBC 1.0) 4 Varchar nicht NULL Datentypname der Datenquelle; Beispielsweise "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" oder "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 1.0) 5 Integer Die Größe der Spalte in der Datenquelle. Weitere Informationen zur Spaltengröße finden Sie unter "Spaltengröße", "Dezimalstellen", "Oktetlänge übertragen" und "Anzeigegröße".
BUFFER_LENGTH (ODBC 1.0) 6 Integer Die Länge in Bytes von Daten, die auf einem SQLGetData - oder SQLFetch-Vorgang übertragen werden, wenn SQL_C_DEFAULT angegeben wird. Bei numerischen Daten unterscheidet sich diese Größe möglicherweise von der Größe der auf der Datenquelle gespeicherten Daten. Dieser Wert entspricht der spalte COLUMN_SIZE für Zeichen- oder Binärdaten. Weitere Informationen finden Sie unter "Spaltengröße", "Dezimalstellen", "Oktetlänge übertragen" und "Anzeigegröße".
DECIMAL_DIGITS (ODBC 1.0) 7 Smallint Die Dezimalstellen der Spalte in der Datenquelle. NULL wird für Datentypen zurückgegeben, bei denen dezimale Ziffern nicht anwendbar sind. Weitere Informationen zu dezimalen Ziffern finden Sie unter Spaltengröße, Dezimalstellen, Länge des Oktettransfers und Anzeigegröße.
PSEUDO_COLUMN (ODBC 2.0) 8 Smallint Gibt an, ob die Spalte eine Pseudospalte ist, z. B. Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Hinweis: Bei maximaler Interoperabilität sollte pseudospalten nicht mit dem von SQLGetInfo zurückgegebenen Bezeichner-Anführungszeichen zitiert werden.

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

Wenn eine Anwendung eine Zeile basierend auf der Zeileid-Spalte oder -Spalten neu markiert und die Zeile nicht gefunden wird, kann die Anwendung davon ausgehen, dass die Zeile gelöscht wurde oder die Zeilenidspalten geändert wurden. Das Gegenteil ist nicht wahr: auch wenn sich die Rowid nicht geändert hat, haben sich die anderen Spalten in der Zeile möglicherweise geändert.

Spalten, die für den Spaltentyp zurückgegeben SQL_BEST_ROWID sind nützlich für Anwendungen, die in einem Ergebnissatz vorwärts und zurück scrollen müssen, um die neuesten Daten aus einer Reihe von Zeilen abzurufen. Die Spalte oder Spalten der Rowid werden garantiert nicht geändert, während sie in dieser Zeile positioniert sind.

Die Spalte oder Spalten der Rowid können auch dann gültig bleiben, wenn der Cursor nicht in der Zeile positioniert ist; die Anwendung kann dies bestimmen, indem Sie die BEREICHsspalte im Ergebnissatz überprüfen.

Spalten, die für den Spaltentyp zurückgegeben werden, SQL_ROWVER für Anwendungen nützlich sind, die die Möglichkeit benötigen, zu überprüfen, ob spalten in einer bestimmten Zeile aktualisiert wurden, während die Zeile mithilfe der Rowid geändert wurde. Nachdem Sie beispielsweise eine Zeile mithilfe von Rowid erneut ausgewählt haben, kann die Anwendung die vorherigen Werte in den SQL_ROWVER Spalten vergleichen, die gerade abgerufen wurden. Wenn sich der Wert in einer SQL_ROWVER Spalte vom vorherigen Wert unterscheidet, kann die Anwendung den Benutzer benachrichtigen, dass sich die Daten in der Anzeige geändert haben.

Codebeispiel

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

Informationen über Finden Sie unter
Binden eines Puffers an eine Spalte in einem Ergebnissatz SQLBindCol-Funktion
Abbrechen der Anweisungsverarbeitung SQLCancel-Funktion
Zurückgeben der Spalten in einer Tabelle oder Tabellen SQLColumns-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in einer vorwärtsgeschützten Richtung SQLFetch-Funktion
Abrufen eines Datenblocks oder Scrollen durch einen Ergebnissatz SQLFetchScroll-Funktion
Zurückgeben der Spalten eines Primärschlüssels SQLPrimaryKeys-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien