SQLSpecialColumns, funkcja

Zgodność
Wprowadzona wersja: Zgodność standardów ODBC 1.0: Open Group

Podsumowanie
SQLSpecialColumns pobiera następujące informacje o kolumnach w określonej tabeli:

Optymalny zbiór kolumn, który jednoznacznie identyfikuje wiersz w tabeli.
Kolumny automatycznie aktualizowane, gdy jakakolwiek wartość w wierszu zostanie zaktualizowana przez transakcję.

Syntax

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

Arguments

StatementHandle
[Dane wejściowe] Uchwyt instrukcji.

IdentyfikatorType
[Input] Typ kolumny do zwrotu. Musi mieć jedną z następujących wartości:

SQL_BEST_ROWID: Zwraca optymalną kolumnę lub zbiór kolumn, które poprzez pobranie wartości z kolumny lub kolumn pozwalają na jednoznaczną identyfikację dowolnego wiersza w podanej tabeli. Kolumna może być albo pseudokolumną specjalnie zaprojektowaną do tego celu (jak w Oracle ROWID lub Ingres TID), albo kolumną lub kolumnami dowolnego unikalnego indeksu tabeli.

SQL_ROWVER: Zwraca kolumnę lub kolumny w określonej tabeli, jeśli takie istnieją, które są automatycznie aktualizowane przez źródło danych, gdy dowolna wartość w wierszu zostanie zaktualizowana przez dowolną transakcję (np. w SQLBase ROWID lub Sybase TIMESTAMP).

CatalogName
[Input] Katalogowa nazwa stołu. Jeśli sterownik obsługuje katalogi dla niektórych tabel, ale nie dla innych, na przykład gdy pobiera dane z różnych DBMS, pusty ciąg ("") oznacza te tabele, które nie mają katalogów. CatalogName nie może zawierać wzorca wyszukiwania w ciągu znaków.

Jeśli atrybut SQL_ATTR_METADATA_ID instrukcji jest ustawiony na SQL_TRUE, CatalogName jest traktowany jako identyfikator i jego przypadek nie jest istotny. Jeśli jest SQL_FALSE, CatalogName to zwykły argument; Jest traktowany dosłownie, a jego sprawa jest znacząca. Aby uzyskać więcej informacji, zobacz Argumenty w funkcjach wykazu.

NameLength1
[Input] Długość w znakach *KatalogNazwa.

NazwaSchematu
[Input] Nazwa schematu dla stołu. Jeśli sterownik obsługuje schematy dla niektórych tabel, ale nie dla innych, na przykład gdy pobiera dane z różnych DBMS, pusty ciąg ("") oznacza te tabele, które nie mają schematów. SchemaName nie może zawierać wzorca wyszukiwania w ciągu znaków.

Jeśli atrybut SQL_ATTR_METADATA_ID instrukcji jest ustawiony na SQL_TRUE, SchemaName jest traktowany jako identyfikator i jego przypadek nie jest istotny. Jeśli jest SQL_FALSE, SchemaName jest zwykłym argumentem; Jest traktowany dosłownie, a jego sprawa jest znacząca.

NameLength2
[Input] Długość w znakach *SchemaName.

TableName
[Dane wejściowe] Nazwa tabeli. Ten argument nie może być punktem zerowym. TableName nie może zawierać wzorca wyszukiwania w ciągu znaków.

Jeśli atrybut SQL_ATTR_METADATA_ID instrukcji jest ustawiony na SQL_TRUE, TableName traktowany jest jako identyfikator i jego przypadek nie jest istotny. Jeśli jest SQL_FALSE, TableName jest zwykłym argumentem; Jest traktowany dosłownie, a jego sprawa jest znacząca.

NameLength3
[Input] Długość w znakach *TableName.

Scope
[Input] Minimalny wymagany zakres rowid. Powracający ryczliwy może mieć większy zakres. Musi być jednym z następujących elementów:

SQL_SCOPE_CURROW: Rowid jest gwarantowany jako ważny tylko wtedy, gdy jest ustawiony w tym rzędzie. Późniejsze ponowne zaznaczenie za pomocą rowid może nie zwrócić wiersza, jeśli wiersz został zaktualizowany lub usunięty przez inną transakcję.

SQL_SCOPE_TRANSACTION: Rowid jest gwarantowany jako ważny przez czas trwania bieżącej transakcji.

SQL_SCOPE_SESSION: Rowid jest gwarantowany jako ważny przez cały czas trwania sesji (ponad granicami transakcji).

Nullable
[Input] Określa, czy zwracać specjalne kolumny, które mogą mieć wartość NULL. Musi być jednym z następujących elementów:

SQL_NO_NULLS: Wyklucz specjalne kolumny, które mogą mieć wartości NULL. Niektóre sterowniki nie obsługują SQL_NO_NULLS, a jeśli SQL_NO_NULLS zostanie określony, zwrócą pusty zestaw wyników. Wnioski powinny być przygotowane w takiej sytuacji i składać wniosek o SQL_NO_NULLS tylko wtedy, gdy jest to absolutnie konieczne.

SQL_NULLABLE: Zwracaj specjalne kolumny, nawet jeśli mogą mieć wartości NULL.

Zwroty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy SQLSpecialColumns zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, można uzyskać powiązaną wartość SQLSTATE, wywołując SQLGetDiagRec z HandleType SQL_HANDLE_STMT oraz Handle z StatementHandle. Poniższa tabela przedstawia wartości SQLSTATE najczęściej zwracane przez SQLSpecialColumns i wyjaśnia każdą z nich w kontekście tej funkcji; notacja "(DM)" poprzedza opisy stanów SQL zwracanych przez Menedżera Sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.

SQLSTATE	Error	Description
01000	Ostrzeżenie ogólne	Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).
08S01	Błąd połączenia komunikacyjnego	Połączenie komunikacyjne między sterownikiem a źródłem danych, z którym sterownik został połączony, nie powiodło się przed zakończeniem przetwarzania funkcji.
24000	Nieprawidłowy stan kursora	Na StatementHandle był otwarty kursor, a wywołano SQLFetch lub SQLFetchScroll . Ten błąd jest zwracany przez Menedżera sterowników, jeśli SQLFetch lub SQLFetchScroll nie zwróciły SQL_NO_DATA i jest zwracany przez sterownik, jeśli SQLFetch lub SQLFetchScroll zwróciły SQL_NO_DATA. Kursor był otwarty na StatementHandle, ale SQLFetch ani SQLFetchScroll nie były wywoływane.
40001	Niepowodzenie serializacji	Transakcja została wycofana z powodu zakleszczenia zasobu z inną transakcją.
40003	Ukończenie instrukcji nieznane	Skojarzone połączenie nie powiodło się podczas wykonywania tej funkcji, a nie można określić stanu transakcji.
HY000	Błąd ogólny	Wystąpił błąd, dla którego nie było określonego stanu SQLSTATE i dla którego nie zdefiniowano parametru SQLSTATE specyficznego dla implementacji. Komunikat o błędzie zwrócony przez element SQLGetDiagRec w buforze *MessageText opisuje błąd i jego przyczynę.
HY001	Błąd alokacji pamięci	Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji.
HY008	Operacja anulowana	Przetwarzanie asynchroniczne zostało włączone dla instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano metodę SQLCancel lub SQLCancelHandle w obiekcie StatementHandle. Następnie funkcja została ponownie wywołana w instrukcji StatementHandle. Wywołano funkcję , a przed zakończeniem wykonywania wywołano funkcję SQLCancel lub SQLCancelHandle na instrukcjiHandle z innego wątku w aplikacji wielowątku.
HY009	Nieprawidłowe użycie wskaźnika o wartości null	Argument TableName był wskaźnikiem o wartości null. Atrybut SQL_ATTR_METADATA_ID instrukcji był ustawiony na SQL_TRUE, argument CatalogName był wskaźnikiem zerowym, a SQL_CATALOG_NAME InfoType zwraca, że nazwy katalogów są obsługiwane. (DM) Atrybut SQL_ATTR_METADATA_ID instrukcji był ustawiony na SQL_TRUE, a argument SchemaName był wskaźnikiem zerowym.
HY010	Błąd sekwencji funkcji	(DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z instrukcją StatementHandle. Funkcja ta działała nadal, gdy wywoływano SQLSpecialColumns . (DM) SqlExecute, SQLExecDirect lub SQLMoreResults została wywołana dla instrukcji StatementHandle i zwrócona SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. (DM) Asynchronicznie wykonująca funkcję (a nie tę) została wywołana dla instrukcji StatementHandle i nadal była wykonywana, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations lub SQLSetPos został wywołany dla instrukcjiHandle i zwrócił SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn.
HY013	Błąd zarządzania pamięcią	Nie można przetworzyć wywołania funkcji, ponieważ nie można uzyskać dostępu do bazowych obiektów pamięci, prawdopodobnie z powodu niskich warunków pamięci.
HY090	Nieprawidłowa długość ciągu lub buforu	(DM) Wartość jednego z argumentów długości była mniejsza niż 0, ale nie równa SQL_NTS. Wartość jednego z argumentów długości przekroczyła maksymalną wartość długości odpowiadającej nazwy. Maksymalną długość każdej nazwy można uzyskać, wywołując SQLGetInfo z wartościami InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN lub SQL_MAX_TABLE_NAME_LEN.
HY097	Typ kolumny poza zasięgiem	(DM) Podano nieprawidłową wartość IdentyfikatorType .
HY098	Typ lunety poza zasięgiem	(DM) Podano nieprawidłową wartość zakresu .
HY099	Typ nullable poza zasięgiem	(DM) Określono nieprawidłową wartość Nullable .
HY117	Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu.	(DM) Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz SQLEndTran, funkcja.
HYC00	Opcjonalna funkcja nie zaimplementowana	Określono katalog, a sterownik lub źródło danych nie obsługuje katalogów. Schemat został określony, a sterownik lub źródło danych nie obsługuje schematów. Kombinacja bieżących ustawień SQL_ATTR_CONCURRENCY i atrybutów instrukcji SQL_ATTR_CURSOR_TYPE nie była obsługiwana przez sterownik lub źródło danych. Atrybut instrukcji SQL_ATTR_USE_BOOKMARKS został ustawiony na SQL_UB_VARIABLE, a atrybut instrukcji SQL_ATTR_CURSOR_TYPE został ustawiony na typ kursora, dla którego sterownik nie obsługuje zakładek.
HYT00	Upłynął limit czasu	Okres przekroczenia limitu czasu zapytania wygasł, zanim źródło danych zwróciło żądany zestaw wyników. Limit czasu jest ustawiany za pomocą metody SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Upłynął limit czasu połączenia	Okres przekroczenia limitu czasu połączenia wygasł, zanim źródło danych odpowiedziało na żądanie. Limit czasu połączenia jest ustawiany za pomocą parametru SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Sterownik nie obsługuje tej funkcji	(DM) Sterownik skojarzony z instrukcją StatementHandle nie obsługuje funkcji.
IM017	Sondowanie jest wyłączone w trybie powiadomień asynchronicznych	Za każdym razem, gdy jest używany model powiadomień, sondowanie jest wyłączone.
IM018	Funkcja SQLCompleteAsync nie została wywołana w celu ukończenia poprzedniej operacji asynchronicznej na tym dojściu.	Jeśli poprzednie wywołanie funkcji na dojściu zwraca SQL_STILL_EXECUTING i jeśli tryb powiadomień jest włączony, narzędzie SQLCompleteAsync musi być wywoływane na dojściu, aby wykonać przetwarzanie końcowe i zakończyć operację.

Comments

Gdy argument IdentifierType jest SQL_BEST_ROWID, SQLSpecialColumns zwraca kolumnę lub kolumny, które jednoznacznie identyfikują każdy wiersz w tabeli. Kolumny te zawsze można wykorzystać w klauzuli select-list lub WHERE . SQLColumns, który służy do zwracania różnych informacji o kolumnach tabeli, niekoniecznie zwraca kolumny jednoznacznie identyfikujące każdy wiersz ani kolumny automatycznie aktualizowane, gdy jakakolwiek wartość w wierszu zostanie zaktualizowana przez transakcję. Na przykład SQLColumns może nie zwracać pseudokolumnowego ROWID-u Oracle. Dlatego właśnie do zwracania tych kolumn używa się SQLSpecialColumns . Aby uzyskać więcej informacji, zobacz Użycie danych wykazu.

Note

Aby uzyskać więcej informacji na temat ogólnego użycia, argumentów i zwracanych danych funkcji wykazu ODBC, zobacz Funkcje wykazu.

Jeśli nie ma kolumn jednoznacznie identyfikujących każdy wiersz w tabeli, SQLSpecialColumns zwraca zbiór wierszy bez wierszy; kolejne wywołanie do SQLFetch lub SQLFetchScroll na polecenie zwraca SQL_NO_DATA.

Jeśli argumenty IdentifierType, Scope lub Nullable określają cechy, które nie są obsługiwane przez źródło danych, SQLSpecialColumns zwraca pusty zbiór wyników.

Jeśli atrybut SQL_ATTR_METADATA_ID instrukcji jest ustawiony na SQL_TRUE, argumenty CatalogName, SchemaName i TableName są traktowane jako identyfikatory, więc w niektórych sytuacjach nie można ich ustawić na wskaźnik null. (Więcej informacji można znaleźć w sekcji Argumenty w funkcjach katalogowych.)

SQLSpecialColumns zwraca wyniki jako standardowy zbiór wyników, uporządkowany według SCOPE.

Nazwa następujących kolumn została zmieniona na ODBC 3.x. Zmiany nazw kolumn nie wpływają na kompatybilność wsteczną, ponieważ aplikacje wiążą się według numeru kolumny.

Kolumna ODBC 2.0	Kolumna ODBC 3.x
PRECYZJA	ROZMIAR_KOLUMNY
DŁUGOŚĆ	BUFFER_LENGTH
SKALA	CYFRA DZIESIĘTNA

Aby określić rzeczywistą długość kolumny COLUMN_NAME, aplikacja może wywołać SQLGetInfo z opcją SQL_MAX_COLUMN_NAME_LEN.

W poniższej tabeli wymieniono kolumny w zestawie wyników. Dodatkowe kolumny poza kolumną 8 (PSEUDO_COLUMN) mogą być definiowane przez sterownik. Aplikacja powinna uzyskać dostęp do kolumn specyficznych dla sterownika, odliczając od końca zbioru wyników, zamiast określać wyraźną pozycję porządkową. Aby uzyskać więcej informacji, zobacz Dane zwrócone przez funkcje wykazu.

Nazwa kolumny	Numer kolumny	Typ danych	Comments
ZAKRES (ODBC 1.0)	1	Smallint	Rzeczywisty zakres rowid. Zawiera jedną z następujących wartości: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL jest zwracany, gdy IdentifierType jest SQL_ROWVER. Opis każdej wartości można znaleźć w opisie zakresu w sekcji "Składnia" wcześniej w tej sekcji.
COLUMN_NAME (ODBC 1.0)	2	Varchar, a nie NULL	Nazwa kolumny. Sterownik zwraca pusty ciąg znaków dla kolumny, która nie ma nazwy.
DATA_TYPE (ODBC 1.0)	3	Smallint, nie NULL	Typ danych SQL. Może to być typ danych SQL ODBC lub typ danych SQL specyficzny dla sterownika. Listę poprawnych typów danych SQL ODBC można znaleźć w artykule Typy danych SQL. Aby uzyskać informacje o typach danych SQL specyficznych dla sterownika, zobacz dokumentację sterownika.
TYPE_NAME (ODBC 1.0)	4	Varchar, a nie NULL	Nazwa typu danych zależnego od źródła danych; na przykład "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" lub "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 1.0)	5	Integer	Rozmiar kolumny na źródle danych. Więcej informacji na temat rozmiaru kolumny można znaleźć w Column Size, Decimal Digits, Transfer Octet Length oraz Display Size.
BUFFER_LENGTH (ODBC 1.0)	6	Integer	Długość bajtów danych przesyłanych w sqlGetData lub operacji SQLFetch, jeśli określono SQL_C_DEFAULT. W przypadku danych liczbowych rozmiar może być inny niż rozmiar danych przechowywanych w źródle danych. Ta wartość może się różnić od kolumny COLUMN_SIZE danych o postaci. Więcej informacji można znaleźć w artykule Column Size, Decimal Digits, Transfer Octet Length oraz Display Size.
DECIMAL_DIGITS (ODBC 1.0)	7	Smallint	Cyfry dziesiętne kolumny na źródle danych. NULL jest zwracany dla typów danych, w których cyfry dziesiętne nie mają zastosowania. Więcej informacji o cyfrach dziesiętnych można znaleźć w Column Size, Decimal Digits, Transfer Octet Length oraz Display Size.
PSEUDO_COLUMN (ODBC 2.0)	8	Smallint	Wskazuje, czy kolumna jest pseudokolumną, na przykład Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Uwaga: Dla maksymalnej interoperacyjności pseudokolumny nie powinny być cytowane z identyfikatorem cytowania zwróconym przez SQLGetInfo.

Po pobraniu wartości SQL_BEST_ROWID aplikacja może użyć tych wartości do ponownego wyboru danego wiersza w ramach zdefiniowanego zakresu. Instrukcja SELECT gwarantuje brak wierszy lub jeden wiersz.

Jeśli aplikacja ponownie wybierze wiersz na podstawie kolumny lub kolumn rowid i wiersz nie zostanie znaleziony, może założyć, że wiersz został usunięty lub kolumny rowid zostały zmodyfikowane. Odwrotnie nie jest: nawet jeśli rowid się nie zmienił, pozostałe kolumny w wierszu mogły się zmienić.

Kolumny zwracane dla typu SQL_BEST_ROWID kolumn są przydatne w aplikacjach, które muszą przewijać do przodu i z powrotem w obrębie zbioru wyników, aby pobrać najnowsze dane z zestawu wierszy. Kolumna lub kolumny rowida gwarantują brak zmian podczas umieszczenia w tym wierszu.

Kolumna lub kolumny rowida mogą pozostać ważne nawet wtedy, gdy kursor nie jest umieszczony na wierszu; aplikacja może to określić, sprawdzając kolumnę SCOPE w zbiorze wyników.

Kolumny zwracane dla typu kolumny SQL_ROWVER są przydatne w aplikacjach, które muszą sprawdzić, czy któreś kolumny w danym wierszu zostały zaktualizowane podczas ponownego wyboru wiersza za pomocą rowidu. Na przykład po ponownym zaznaczeniu wiersza za pomocą rowid aplikacja może porównać poprzednie wartości w kolumnach SQL_ROWVER z tymi, które właśnie pobrano. Jeśli wartość w kolumnie SQL_ROWVER różni się od poprzedniej, aplikacja może powiadomić użytkownika o zmianie danych na wyświetlaczu.

Przykład kodu

Przykład kodu podobnej funkcji można znaleźć w SQLColumns.

Aby uzyskać informacje o	Zobacz
Wiązanie buforu z kolumną w zestawie wyników	SQLBindCol, funkcja
Anulowanie przetwarzania instrukcji	SQLCancel, funkcja
Zwracanie kolumn w tabeli lub tabelach	Funkcja SQLColumns
Pobieranie pojedynczego wiersza lub bloku danych w kierunku tylko do przodu	SQLFetch, funkcja
Pobieranie bloku danych lub przewijanie zestawu wyników	SQLFetchScroll, funkcja
Zwracanie kolumn klucza podstawowego	SQLPrimaryKeys, funkcja

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-24