Funkce SQLSpecialColumns

Soulad
Představená verze: ODBC 1.0 Soulad standardů: Open Group

Summary
SQLSpecialColumns získává následující informace o sloupcích ve specifikované tabulce:

Optimální sada sloupců, která jednoznačně identifikuje řádek v tabulce.
Sloupce, které se automaticky aktualizují, když je jakákoli hodnota v řádku aktualizována transakcí.

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
[Vstup] Popisovač příkazu

IdentifierType
[Vstup] Typ sloupce, který se vrací. Toto musí být jedna z následujících hodnot:

SQL_BEST_ROWID: Vrátí optimální sloupec nebo sadu sloupců, které získáním hodnot z tohoto sloupce nebo sloupců umožňují jednoznačnou identifikaci jakéhokoli řádku ve specifikované tabulce. Sloupec může být buď pseudosloupec speciálně navržený pro tento účel (například Oracle ROWID nebo Ingres TID), nebo sloupec či sloupce libovolného unikátního indexu tabulky.

SQL_ROWVER: Vrací sloupec nebo sloupce ve specifikované tabulce, pokud nějaké jsou, které jsou automaticky aktualizovány datovým zdrojem, když je jakákoli hodnota v řádku aktualizována jakoukoli transakcí (například v SQLBase ROWID nebo Sybase TIMESTAMP).

CatalogName
[Vstup] Katalogový název stolu. Pokud ovladač podporuje katalogy pro některé tabulky, ale ne pro jiné, například když ovladač získává data z různých DBMS, prázdný řetězec ("") označuje tabulky, které katalogy nemají. CatalogName nemůže obsahovat vzor vyhledávání řetězců.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, CatalogName je považován za identifikátor a jeho případ není významný. Pokud je to SQL_FALSE, CatalogName je běžný argument; Je brána doslovně a její případ je významný. Další informace naleznete v tématu Argumenty funkce katalogu.

NameLength1
[Vstup] Délka znaků *CatalogName.

Název schématu
[Vstup] Schéma pro stůl. Pokud ovladač podporuje schémata pro některé tabulky, ale ne pro jiné, například když ovladač získává data z různých DBMS, prázdný řetězec ("") označuje tabulky, které schémata nemají. SchemaName nemůže obsahovat vzor vyhledávání řetězců.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, SchemaName je považován za identifikátor a jeho případ není významný. Pokud je to SQL_FALSE, SchemaName je běžný argument; Je brána doslovně a její případ je významný.

NameLength2
[Vstup] Délka znaků *SchemaName.

TableName
[Vstup] Název tabulky Tento argument nemůže být nulovým ukazatelem. TableName nemůže obsahovat vzor vyhledávání řetězců.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, TableName je považován za identifikátor a jeho případ není významný. Pokud je to SQL_FALSE, TableName je běžný argument; Je brána doslovně a její případ je významný.

NameLength3
[Vstup] Délka znaků *TableName.

Scope
[Vstup] Minimální požadovaný rozsah rowid. Vrácený rowid může mít větší rozsah. Musí to být jedna z těchto věcí:

SQL_SCOPE_CURROW: Rowid je zaručeně platný pouze tehdy, když je umístěn v dané řadě. Pozdější opětovný výběr pomocí rowid nemusí vrátit řádek, pokud byl řádek aktualizován nebo smazán jinou transakcí.

SQL_SCOPE_TRANSACTION: Rowid je zaručeně platný po celou dobu trvání aktuální transakce.

SQL_SCOPE_SESSION: Rowid je zaručeně platný po celou dobu trvání relace (přes hranice transakcí).

Nullable
[Vstup] Určuje, zda vrátit speciální sloupce, které mohou mít hodnotu NULL. Musí to být jedna z těchto věcí:

SQL_NO_NULLS: Vylučujte speciální sloupce, které mohou mít hodnoty NULL. Některé ovladače nemohou podporovat SQL_NO_NULLS a pokud SQL_NO_NULLS bylo specifikováno, vrátí prázdnou sadu výsledků. Žádosti by měly být připraveny pro tento případ a žádat SQL_NO_NULLS pouze tehdy, pokud je to naprosto nezbytné.

SQL_NULLABLE: Vraťte speciální sloupce, i když mohou mít hodnoty NULL.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLSpecialColumns vrací SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLSTATE voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a handleCommandHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLSpecialColumns běžně vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

SQLSTATE	Error	Description
01000	Obecné upozornění	Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
08S01	Selhání komunikačního propojení	Komunikační propojení mezi ovladačem a zdrojem dat, ke kterému byl ovladač připojen, selhalo před dokončením zpracování funkce.
24000	Neplatný stav kurzoru	Na StatementHandle byl otevřený kurzor a byly volány SQLFetch nebo SQLFetchScroll . Tuto chybu vrátí správce ovladačů, pokud SQLFetch nebo SQLFetchScroll nevrátil SQL_NO_DATA, a ovladač ji vrátí, pokud SQLFetch nebo SQLFetchScroll vrátily SQL_NO_DATA. Na StatementHandle byl otevřený kurzor, ale SQLFetch nebo SQLFetchScroll nebyly volány.
40001	Selhání serializace	Transakce byla vrácena zpět kvůli vzájemnému zablokování prostředku s jinou transakcí.
40003	Neznámé dokončování příkazů	Přidružené připojení se nezdařilo během provádění této funkce a stav transakce nelze určit.
HY000	Obecná chyba	Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená nástrojem SQLGetDiagRec v vyrovnávací paměti MessageText* popisuje chybu a její příčinu.
HY001	Chyba přidělení paměti	Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce.
HY008	Operace byla zrušena.	Asynchronní zpracování bylo povoleno pro StatementHandle. Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel nebo SQLCancelHandle pro PříkazHandle. Pak byla funkce znovu volána v StatementHandle. Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel neboSQLCancelHandlez jiného vlákna v aplikaci s více vlákny.
HY009	Neplatné použití ukazatele null	Argument TableName byl ukazatel null. Atribut SQL_ATTR_METADATA_ID příkazu byl nastaven na SQL_TRUE, argument CatalogName byl nulový ukazatel a SQL_CATALOG_NAME InfoType vrací, že jsou podporována jména katalogů. (DM) Atribut SQL_ATTR_METADATA_ID příkazu byl nastaven na SQL_TRUE a argument SchemaName byl nulový ukazatel.
HY010	Chyba posloupnosti funkcí	(DM) Byla volána asynchronně spuštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato funkce se stále vykonávala, když byl vyvolán SQLSpecialColumns . (DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl volána pro StatementHandle a vrácena SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. (DM) Pro PříkazHandle byla volána asynchronně spuštěná funkce (ne tato) a při zavolání této funkce se stále spouštěla. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle a vráceny SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce.
HY013	Chyba správy paměti	Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti.
HY090	Neplatná délka řetězce nebo vyrovnávací paměti	(DM) Hodnota jednoho z argumentů délky byla menší než 0, ale nebyla rovna SQL_NTS. Hodnota jednoho z argumentů délky překročila maximální hodnotu délky pro odpovídající název. Maximální délku každého názvu lze získat voláním SQLGetInfo s hodnotami InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN nebo SQL_MAX_TABLE_NAME_LEN.
HY097	Typ sloupce mimo dosah	(DM) Byla určena neplatná hodnota IdentifierType .
HY098	Typ zaměřovače mimo dosah	(DM) Byla uvedena neplatná hodnota Scope .
HY099	Nullable typ mimo dosah	(DM) Byla určena neplatná hodnota Nullable .
HY117	Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení.	(DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran.
HYC00	Nepovinná funkce není implementována.	Byl specifikován katalog, ale ovladač nebo datový zdroj katalogy nepodporuje. Bylo specifikováno schéma a ovladač nebo zdroj dat schémata nepodporuje. Ovladač ani zdroj dat nepodporuje kombinaci aktuálních nastavení atributů SQL_ATTR_CONCURRENCY a SQL_ATTR_CURSOR_TYPE příkazu. Atribut příkazu SQL_ATTR_USE_BOOKMARKS byl nastaven na SQL_UB_VARIABLE a atribut příkazu SQL_ATTR_CURSOR_TYPE byl nastaven na typ kurzoru, pro který ovladač nepodporuje záložky.
HYT00	Vypršel časový limit.	Vypršení časového limitu dotazu vypršelo, než zdroj dat vrátil požadovanou sadu výsledků. Časový limit je nastavený prostřednictvím sqlSetStmtAttr SQL_ATTR_QUERY_TIMEOUT.
HYT01	Vypršel časový limit připojení	Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Časový limit připojení je nastavený prostřednictvím sqlSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Ovladač tuto funkci nepodporuje.	(DM) Ovladač přidružený k StatementHandle nepodporuje funkci.
IM017	Dotazování je zakázané v asynchronním režimu oznámení.	Při každém použití modelu oznámení je dotazování zakázané.
IM018	K dokončení předchozí asynchronní operace na tomto popisovači nebyla volána funkce SQLCompleteAsync.	Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolen režim oznámení, musí být sqlCompleteAsync volán na popisovači, aby bylo možné provést následné zpracování a dokončit operaci.

Comments

Když je argument IdentifierType SQL_BEST_ROWID, SQLSpecialColumns vrátí sloupec nebo sloupce, které jednoznačně identifikují každý řádek v tabulce. Tyto sloupce lze vždy použít v klauzuli select-list nebo WHERE . SQLColumns, který se používá k vrácení různých informací ve sloupcích tabulky, nemusí nutně vracet sloupce, které jednoznačně identifikují každý řádek, ani sloupce, které se automaticky aktualizují, když je jakákoli hodnota v řádku aktualizována transakcí. Například SQLColumns nemusí vracet Oracle pseudosloupec ROWID. Proto se k vrácení těchto sloupců používá SQLSpecialColumns . Další informace naleznete v tématu Použití dat katalogu.

Note

Další informace o obecném použití, argumentech a vrácených datech funkcí katalogu ODBC naleznete v tématu Funkce katalogu.

Pokud nejsou žádné sloupce, které by jednoznačně identifikovaly každý řádek v tabulce, SQLSpecialColumns vrací sadu řádků bez řádků; následné volání na SQLFetch nebo SQLFetchScroll na příkaz vrátí SQL_NO_DATA.

Pokud argumenty IdentifierType, Scope nebo Nullable specifikují charakteristiky, které nejsou zdrojem dat podporovány, SQLSpecialColumns vrátí prázdnou sadu výsledků.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, argumenty CatalogName, SchemaName a TableName jsou považovány za identifikátory, takže je nelze v určitých situacích nastavit na nulový ukazatel. (Pro více informací viz Argumenty v katalogových funkcích.)

SQLSpecialColumns vrací výsledky jako standardní množinu výsledků, seřazenou podle SCOPE.

Následující sloupce byly přejmenovány pro ROZHRANÍ ODBC 3.x. Změny názvů sloupců neovlivňují zpětnou kompatibilitu, protože aplikace se vážou podle čísla sloupce.

Sloupec ODBC 2.0	Sloupec ODBC 3.x
PŘESNOST	COLUMN_SIZE
Délka	DÉLKA_BUFFERU
ŠKÁLA	Desetinné číslice

Pro určení skutečné délky sloupce COLUMN_NAME může aplikace volat SQLGetInfo s možností SQL_MAX_COLUMN_NAME_LEN.

Následující tabulka uvádí sloupce v sadě výsledků. Další sloupce za sloupcem 8 (PSEUDO_COLUMN) může ovladač definovat. Aplikace by měla získat přístup ke sloupcům specifickým pro ovladač odpočítáváním od konce výsledné množiny místo explicitního určení ordinální pozice. Další informace naleznete v tématu Data vrácená funkcemi katalogu.

Název sloupce	Číslo sloupce	Datový typ	Comments
SCOPE (ODBC 1.0)	1	Smallint	Skutečný rozsah rowidu. Obsahuje jednu z následujících hodnot: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL se vrací, když je IdentifierType SQL_ROWVER. Popis každé hodnoty najdete v popisu Scope v "Syntaxi" dříve v této části.
COLUMN_NAME (ODBC 1.0)	2	Varchar, ne NULL	Název sloupce Ovladač vrací prázdný řetězec pro sloupec, který nemá jméno.
DATA_TYPE (ODBC 1.0)	3	Smallint, ne NULL	Datový typ SQL Může se jednat o datový typ ODBC SQL nebo datový typ SQL specifický pro ovladač. Pro seznam platných ODBC SQL datových typů viz SQL datové typy. Informace o datových typech SQL specifických pro ovladače najdete v dokumentaci ovladače.
TYPE_NAME (ODBC 1.0)	4	Varchar, ne NULL	Název datového typu závislý na zdroji dat; Například "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" nebo "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 1.0)	5	Integer	Velikost sloupce na datovém zdroji. Pro více informací o velikosti sloupců viz Velikost sloupce, Desetinné číslice, Délka přenosového oktetu a Velikost displeje.
BUFFER_LENGTH (ODBC 1.0)	6	Integer	Délka bajtů dat přenášených v SQLGetData nebo operace SQLFetch, pokud je zadána SQL_C_DEFAULT. U číselných dat se tato velikost může lišit od velikosti dat uložených ve zdroji dat. Tato hodnota se může lišit od sloupce COLUMN_SIZE pro data o postavě. Pro více informací viz Velikost sloupce, Desetinné číslice, Délka přenosového oktetu a Velikost displeje.
DECIMAL_DIGITS (ODBC 1.0)	7	Smallint	Desetinné číslice sloupce na datovém zdroji. NULL se vrací pro datové typy, kde desetinné číslice nejsou použitelné. Pro více informací o desetinných číslicích viz Velikost sloupce, Desetinné číslice, Délka přenosového oktetu a Velikost displeje.
PSEUDO_COLUMN (ODBC 2.0)	8	Smallint	Označuje, zda je sloupec pseudosloupcem, například Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Poznámka: Pro maximální interoperabilitu by pseudo-sloupce neměly být citovány identifikátorem vráceným SQLGetInfo.

Po získání hodnot pro SQL_BEST_ROWID může aplikace tyto hodnoty použít k opětovnému výběru daného řádku v definovaném rozsahu. Příkaz SELECT zaručeně vrátí buď žádné řádky, nebo jeden řádek.

Pokud aplikace znovu vybere řádek na základě sloupce nebo sloupců řádku a řádek není nalezen, může předpokládat, že řádek byl smazán nebo byly sloupce s řádky upraveny. Opak neplatí: i když se rowid nezměnil, ostatní sloupce v řádku se mohly změnit.

Sloupce vrácené pro typ sloupce SQL_BEST_ROWID jsou užitečné pro aplikace, které potřebují posouvat dopředu a zpět v rámci sady výsledků, aby získaly nejnovější data ze sady řádků. Sloupec nebo sloupce rowida se zaručeně nezmění, když jsou umístěny v tomto řádku.

Sloupec nebo sloupce rowidu mohou zůstat platné i tehdy, když kurzor není umístěn na řádku; aplikace to může určit kontrolou sloupce SCOPE ve výsledné množině.

Sloupce vrácené pro typ sloupce SQL_ROWVER jsou užitečné pro aplikace, které potřebují možnost zkontrolovat, zda byly některé sloupce v daném řádku aktualizovány během opětovného výběru řádku pomocí rowidu. Například po opětovném výběru řádku pomocí rowida může aplikace porovnat předchozí hodnoty ve sloupcích SQL_ROWVER s těmi, které právě načetla. Pokud se hodnota ve sloupci SQL_ROWVER liší od předchozí, aplikace může uživatele upozornit, že se data na displeji změnila.

Příklad kódu

Pro příklad kódu podobné funkce viz SQLColumns.

Informace o	Podívejte se
Vytvoření vazby vyrovnávací paměti ke sloupci v sadě výsledků	SQLBindCol – funkce
Zrušení zpracování příkazů	SQLCancel – funkce
Vrácení sloupců v tabulce nebo tabulkách	SQLColumns Function
Načítání jednoho řádku nebo bloku dat pouze ve směru dopředu	Funkce SQLFetch
Načtení bloku dat nebo procházení sady výsledků	SQLFetchScroll – funkce
Vrácení sloupců primárního klíče	FUNKCE SQLPrimaryKeys

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-24