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.

SQLSTATE	Error	Beschreibung
01000	Allgemeiner Warnhinweis	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, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
24000	Ungültiger Cursorstatus	Ein Cursor wurde für " 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 und vom Treiber zurückgegeben wird, wenn SQLFetch oder SQLFetchScroll SQL_NO_DATA zurückgegeben wurde. Ein Cursor war für " StatementHandle" geöffnet, aber SQLFetch oder SQLFetchScroll wurden nicht aufgerufen.
40001	Serialisierungsfehler	Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003	Abschluss der Anweisung unbekannt	Fehler bei der zugehörigen Verbindung während der Ausführung dieser Funktion, und der Status der Transaktion kann nicht bestimmt werden.
HY000	Allgemeiner Fehler	Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache.
HY001	Speicherzuweisungsfehler	Der Treiber konnte 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 " StatementHandle" aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für die Anweisungshandle aufgerufen. Anschließend wurde die Funktion erneut für " StatementHandle" aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY009	Ungültige Verwendung des Nullzeigers	Das Argument "TableName " war ein Nullzeiger. Das attribut der SQL_ATTR_METADATA_ID-Anweisung wurde auf SQL_TRUE festgelegt, das CatalogName-Argument war ein NULL-Zeiger, und die SQL_CATALOG_NAME InfoType gibt zurück, dass Katalognamen unterstützt werden. (DM) Das attribut der SQL_ATTR_METADATA_ID-Anweisung 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 " StatementHandle " aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden.
HY013	Speicherverwaltungsfehler	Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY090	Ungültige Zeichenfolgen- 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 hat den maximal zulässigen Längenwert für den entsprechenden Namen überschritten. 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) Es wurde ein ungültiger IdentifierType-Wert angegeben.
HY098	Bereichstyp außerhalb des Bereichs	(DM) Es wurde ein ungültiger Bereichswert angegeben.
HY099	Nullabler Typ außerhalb des Bereichs	(DM) Es wurde ein ungültiger Nullwerte angegeben.
HY117	Verbinden ion wird aufgrund des unbekannten Transaktionszustands angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig.	(DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYC00	Optionales Feature wurde nicht implementiert	Ein Katalog wurde angegeben, und der Treiber oder die Datenquelle unterstützt keine Kataloge. Es wurde ein Schema angegeben, und der Treiber oder die 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 attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_VARIABLE festgelegt, und das Attribut der SQL_ATTR_CURSOR_TYPE-Anweisung wurde auf einen Cursortyp festgelegt, für den der Treiber keine Lesezeichen unterstützt.
HYT00	Timeout überschritten	Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT festgelegt.
HYT01	Verbindungstimeout abgelaufen	Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSet Verbinden Attr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001	Dieser Treiber unterstützt diese Funktion nicht.	(DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht.
IM017	Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert.	Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung deaktiviert.
IM018	SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen.	Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachbearbeitung durchzuführen und den Vorgang abzuschließen.

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.

Hinweis

Weitere Informationen zur allgemeinen Verwendung, zu Argumenten 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 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.

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

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".

Spaltenname	Column number	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 der einzelnen Werte 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	Datenquellenabhängiger Datentypname; Beispiel: "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", "Dezimalziffern", "Oktettlänge übertragen" und "Anzeigegröße".
BUFFER_LENGTH (ODBC 1.0)	6	Integer	Die Länge in Byte der in einem SQLGetData - oder SQLFetch-Vorgang übertragenen Daten, wenn SQL_C_DEFAULT angegeben ist. Bei numerischen Daten kann sich diese Größe von der Größe der in der Datenquelle gespeicherten Daten unterscheiden. Dieser Wert kann sich von COLUMN_SIZE Spalte für Zeichendaten unterscheiden. Weitere Informationen finden Sie unter "Spaltengröße", "Dezimalziffern", "Oktettlä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 Dezimalziffern finden Sie unter Spaltengröße, Dezimalziffern, Länge des Oktetts und Anzeigegröße.
PSEUDO_COLUMN (ODBC 2.0)	8	Smallint	Gibt an, ob es sich bei der Spalte um eine Pseudospalte handelt, z. B. Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Hinweis: Bei maximaler Interoperabilität sollten 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 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

Informationen über	Siehe
Binden eines Puffers an eine Spalte in einem Resultset	SQLBindCol-Funktion
Abbrechen der Verarbeitung von Anweisungen	SQLCancel-Funktion
Zurückgeben der Spalten in einer Tabelle oder Tabellen	SQLColumns-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in eine vorwärtsgerichtete Richtung	SQLFetch-Funktion
Abrufen eines Datenblocks oder Scrollen durch ein Resultset	SQLFetchScroll-Funktion
Zurückgeben der Spalten eines Primärschlüssels	SQLPrimaryKeys-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien