SQLSpecialColumns függvény

Megfelelőség
Bemutatott verzió: ODBC 1.0 Szabványoknak megfelelés: Open Group

Summary
Az SQLSpecialColumns a megadott táblázatban található oszlopokról származó alábbi információkat kéri:

• Az optimális oszlophalmaz, amely egyediben azonosítja a táblázat egy sorát.

• Olyan oszlopok, amelyek automatikusan frissülnek, amikor a sorban bármely érték tranzakcióval frissül.

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
[Bemenet] Utasításkezelő.

Azonosítótípus
[Bemenet] Milyen oszlop a visszaküldés. Az alábbi értékek egyikének kell lennie:

SQL_BEST_ROWID: Visszaadja az optimális oszlopot vagy oszlophalmazt, amely az oszlopból vagy oszlopokból származó értékek visszanyerésével lehetővé teszi, hogy a megadott táblázat bármely sora egyedien azonosítható legyen. Az oszlop lehet vagy egy kifejezetten erre a célra tervezett pszeudo-oszlop (mint az Oracle ROWID vagy az Ingres TID), vagy bármely táblázat egyedi indexének oszlopa vagy oszlopai.

SQL_ROWVER: Visszaadja a megadott táblában található oszlopot vagy oszlopokat, ha vannak, amelyeket az adatforrás automatikusan frissít, amikor a sorban bármely érték bármely tranzakcióval frissül (például SQLBase ROWID vagy Sybase TIMESTAMP).

CatalogName
[Bemenet] A táblázat katalógusneve. Ha egy illesztőprogram bizonyos táblákhoz katalógusokat támogat, másoknál nem, például amikor az illesztőprogram adatokat tölt be különböző adatbázisokból, akkor egy üres string ("") jelzi azokat a táblákat, amelyeknek nincs katalógus. A CatalogName nem tartalmazhat stringkereső mintát.

Ha a SQL_ATTR_METADATA_ID utasítás attribútuma SQL_TRUE-re van beállítva, a CatalogName azonosítóként kezelik, és az esete nem jelentős. Ha SQL_FALSE, akkor a CatalogName egy átlagos érv; szó szerint kezelik, és az esete jelentős. További információ: A Catalog Functions argumentumai.

NameLength1
[Bemenet] A *CatalogName karakterek hossza.

Séma neve
[Bemenet] Az asztal séma neve. Ha egy illesztőprogram támogatja a sémákat bizonyos táblákhoz, de másokhoz nem, például amikor az illeszőr adatokat tölt be különböző adatbázisokból, akkor egy üres string ("") jelzi azokat a táblákat, amelyeknek nincs sémájuk. A SchemaName nem tartalmazhat string keresési mintát.

Ha a SQL_ATTR_METADATA_ID állítás attribútuma SQL_TRUE-re van beállítva, akkor a SchemaName azonosítóként kezelik, és az esete nem jelentős. Ha SQL_FALSE, akkor a SchemaName egy hétköznapi érv; szó szerint kezelik, és az esete jelentős.

NameLength2
[Bemenet] Hossz a *SchemaName.

TáblaNév
[Bemenet] Tábla neve. Ez az érv nem lehet null pointer. A TableName nem tartalmazhat stringkereső mintát.

Ha a SQL_ATTR_METADATA_ID állítás attribútuma SQL_TRUE-re van beállítva, a TableName azonosítóként kezelik, és az eve nem jelentős. Ha SQL_FALSE, akkor a TableName egy hétköznapi érv; szó szerint kezelik, és az esete jelentős.

NameLength3
[Bemenet] Hosszúság a *TableName.

Scope
[Bemenet] A rovid minimum szükséges hatótávolsága. A visszatérő rovad nagyobb hatókörűek lehetnek. Az alábbiak egyikének kell lennie:

SQL_SCOPE_CURROW: A rowid garantáltan érvényes, ha azon a soron helyezkedik el. Későbbi rowid újraválasztás esetén nem feltétlenül adnak vissza sort, ha a sort egy másik tranzakció frissítette vagy törölte.

SQL_SCOPE_TRANSACTION: A rowid garantáltan érvényes a jelenlegi tranzakció időtartamára.

SQL_SCOPE_SESSION: A rowid garantáltan érvényes lesz a játékmenet időtartamára (tranzakciós határokon át).

Nullable
[Bemenet] Meghatározza, hogy olyan speciális oszlopokat kell visszaadni, amelyek NULL értékkel rendelkezhetnek. Az alábbiak egyikének kell lennie:

SQL_NO_NULLS: Zárjuk ki azokat a speciális oszlopokat, amelyek NULL értékekkel rendelkeznek. Néhány illesztőprogram nem tudja támogatni az SQL_NO_NULLS, és ezek az illesztőprogramok üres eredményhalmazt adnak vissza, ha SQL_NO_NULLS meg van jelölve. A jelentkezéseket erre az esetre kell előkészíteni, és csak akkor kell kérni SQL_NO_NULLS ha feltétlenül szükséges.

SQL_NULLABLE: Térj vissza speciális oszlopokat, még akkor is, ha NULL értékük lehet.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR vagy SQL_INVALID_HANDLE.

Diagnostics

Amikor az SQLSpecialColumns SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad vissza, akkor egy hozzárendelt SQLSTATE értéket lehet elérni, ha az SQLGetDiagRec meghívása egy SQL_HANDLE_STMT HandleType és egy HandleType (StatementHandle) segítségével. Az alábbi táblázat felsorolja azokat az SQLSTATE értékeket, amelyeket az SQLSpecialColumns gyakran visszaad, és mindegyiket elmagyarázza ezen függvény kontextusában; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

SQLSTATE	Hiba	Description
01000	Általános figyelmeztetés	Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
08S01	Kommunikációs kapcsolat hibája	Az illesztőprogram és az adatforrás közötti kommunikációs kapcsolat, amelyhez az illesztőprogram csatlakoztatva volt, nem sikerült, mielőtt a függvény befejeződött a feldolgozás.
24000	Érvénytelen kurzorállapot	A StatementHandle kurzora nyitva volt, és az SQLFetch vagy SQLFetchScroll hívást kapta. Ezt a hibát a Driver Manager adja vissza, ha a SQLFetch vagy SQLFetchScroll nem SQL_NO_DATA vissza, és a driver, ha SQLFetch vagy SQLFetchScroll SQL_NO_DATA visszaadta. A kurzor nyitva volt a StatementHandle-en, de az SQLFetch vagy SQLFetchScroll nem volt meghívva.
40001	Szerializálási hiba	A tranzakció egy erőforrás holtpontja miatt lett visszaállítva egy másik tranzakcióval.
40003	Az utasítás befejezése ismeretlen	A társított kapcsolat a függvény végrehajtása során meghiúsult, és a tranzakció állapota nem határozható meg.
HY000	Általános hiba	Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *MessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát.
HY001	Memóriafoglalási hiba	Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát.
HY008	A műveletet megszakították	Az aszinkron feldolgozás engedélyezve lett a StatementHandle-ben. A függvény meghívása megtörtént, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle meghívása megtörtént az Utasításkezelőben. Ezután a függvény ismét meghívásra került az Utasításkezelőben. A függvény meghívása megtörtént, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle egy másik szálról lett meghívva a StatementHandle-ra egy többszálas alkalmazásból.
HY009	Érvénytelen null mutató használata	A TableName argumentum null mutató volt. A SQL_ATTR_METADATA_ID utasítás attribútumot SQL_TRUE-re állították, a CatalogName argument null mutató volt, és az SQL_CATALOG_NAME InfoType azt mutatja, hogy a katalógusnevek támogatottak. (DM) A SQL_ATTR_METADATA_ID állítás attribútuma SQL_TRUE-re volt beállítva, a SchemaName érve pedig null mutató volt.
HY010	Függvényütemezési hiba	(DM) A StatementHandle-hez társított kapcsolati leíróhoz aszinkron módon végrehajtó függvény lett meghívva. Ez a függvény még futott, amikor az SQLSpecialColumns hívást kapta. (DM) SQLExecute, SQLExecDirect vagy SQLMoreResults lett meghívva az Utasításkezelőhöz , és SQL_PARAM_DATA_AVAILABLE ad vissza. Ez a függvény az összes streamelt paraméter adatainak lekérése előtt lett meghívva. (DM) Egy aszinkron módon végrehajtó függvény (nem ez) lett meghívva az StatementHandle-hez , és a függvény meghívásakor továbbra is végrehajtó volt. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations vagy SQLSetPos lett meghívva az Utasításkezelőhöz , és SQL_NEED_DATA. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg.
HY013	Memóriakezelési hiba	A függvényhívás nem dolgozható fel, mert a mögöttes memóriaobjektumok nem érhetők el, esetleg a memóriahiány miatt.
HY090	Érvénytelen sztring vagy puffer hossza	(DM) Az egyik hosszúságú argumentum értéke kisebb volt 0-nál, de nem egyenlő SQL_NTS-vel. Az egyik hosszúsági argumentus értéke meghaladta a megfelelő név maximális hosszértékét. Minden név maximális hossza az SQLGetInfo hívásával érhető el az InfoType értékekkel: SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN vagy SQL_MAX_TABLE_NAME_LEN.
HY097	Oszlop típusa a hatótávolságon kívül	(DM) Érvénytelen IdentifierType értéket jelöltek meg.
HY098	Távcső típus a hatótávolságon kívül	(DM) Értelen Scope értéket adtak meg.
HY099	Nullable típus a hatótávolságon kívül	(DM) Érvénytelen nullable értéket határoztak meg.
HY117	A kapcsolat ismeretlen tranzakciós állapot miatt fel van függesztve. Csak a leválasztási és írásvédett függvények engedélyezettek.	(DM) A felfüggesztett állapotról további információt az SQLEndTran függvényben talál.
HYC00	A választható funkció nem implementálva	Kijelöltek egy katalógust, és az illesztőprogram vagy adatforrás nem támogatja a katalógusokat. Sémát határoztak meg, és az illesztőprogram vagy adatforrás nem támogatja a sémákat. Az illesztőprogram vagy az adatforrás nem támogatja a SQL_ATTR_CONCURRENCY és SQL_ATTR_CURSOR_TYPE utasításattribútumok aktuális beállításainak kombinációját. A SQL_ATTR_USE_BOOKMARKS utasítás attribútuma SQL_UB_VARIABLE lett beállítva, és a SQL_ATTR_CURSOR_TYPE utasítás attribútum olyan kurzortípusra lett beállítva, amelyhez az illesztőprogram nem támogatja a könyvjelzőket.
HYT00	Időtúllépés történt	A lekérdezés időtúllépési időtartama lejárt, mielőtt az adatforrás visszaadta a kért eredményhalmazt. Az időtúllépési időszak az SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT keresztül van beállítva.
HYT01	A kapcsolati időkorlát lejárt	A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka az SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT keresztül van beállítva.
IM001	Az illesztőprogram nem támogatja ezt a függvényt	(DM) Az StatementHandle-hez társított illesztőprogram nem támogatja a függvényt.
IM017	A lekérdezés aszinkron értesítési módban le van tiltva	Az értesítési modell használata esetén a lekérdezés le van tiltva.
IM018	Az SQLCompleteAsync nem lett meghívva az előző aszinkron művelet végrehajtásához ezen a leírón.	Ha a leíró előző függvényhívása SQL_STILL_EXECUTING ad vissza, és ha az értesítési mód engedélyezve van, az SQLCompleteAsync-et a leírón kell meghívni a művelet utófeldolgozásához és befejezéséhez.

Comments

Amikor az IdentifierType érve SQL_BEST_ROWID, az SQLSpecialColumns azt az oszlopot vagy oszlopokat adja vissza, amelyek egyedien azonosítják a táblázat minden sorát. Ezek az oszlopok mindig használhatók egy select-list vagy WHERE klauzuládban. Az SQLColumns, amelyet egy táblázat oszlopaiban található különféle információk visszaadására használnak, nem feltétlenül adja meg azokat az oszlopokat, amelyek egyedien azonosítják az egyes sorokat, vagy azokat az oszlopokat, amelyek automatikusan frissülnek, amikor bármely értéket egy tranzakció frissít. Például az SQLColumns nem feltétlenül adja vissza az Oracle pszeudo-oszlopos ROWID-et. Ezért használják az SQLSpecialColumns-t ezeknek az oszlopoknak a visszaadásához. További információ: A katalógusadatok felhasználása.

Note

Az ODBC-katalógusfüggvények általános használatáról, argumentumairól és visszaadott adatairól további információt a Catalog Functions című témakörben talál.

Ha nincs olyan oszlop, amely egyediben azonosítaná az egyes sorokat a táblában, akkor az SQLSpecialColumns egy sorhalmazt ad vissza, amelyben nincs sor; a következő hívás az SQLFetch-re vagy SQLFetchScroll-re az állításon SQL_NO_DATA-et ad.

Ha az IdentifierType, Scope vagy Nullable argumentumok olyan jellemzőket adnak meg, amelyeket az adatforrás nem támogat, az SQLSpecialColumns üres eredményhalmazt ad vissza.

Ha a SQL_ATTR_METADATA_ID utasítás attribútuma SQL_TRUE-re van beállítva, a CatalogName, SchemaName és TableName argumentumokat azonosítóként kezelik, így bizonyos helyzetekben nem állíthatók null mutatóra. (További információért lásd: Argumentok a Katalógus függvényekben.)

Az SQLSpecialColumns standard eredményhalmazként adja vissza az eredményeket, SCOPE szerint sorrendben.

A következő oszlopok átnevezve lettek az ODBC 3.x-re. Az oszlopnév változása nem befolyásolja a visszafelé kompatibilitást, mivel az alkalmazások oszlopszám alapján kötnek hozzá.

ODBC 2.0 oszlop	ODBC 3.x oszlop
PRECIZITÁS	Oszlop_méret
HOSSZ	Puffer_hossza
SKÁLA	TIZEDESJEGYEK

Az COLUMN_NAME oszlop tényleges hosszának meghatározásához egy alkalmazás az SQLGetInfo-t hívhatja a SQL_MAX_COLUMN_NAME_LEN opcióval.

Az alábbi táblázat az eredményhalmaz oszlopait sorolja fel. A 8. oszlop (PSEUDO_COLUMN) mögött további oszlopokat a meghajtó definiálhat. Az alkalmazásnak az illesztőgép-specifikus oszlopokhoz úgy kell hozzáférnie, hogy az eredményhalmaz végétől visszaszámol, nem pedig explicit ordinalpozíciót jelölne meg. További információ: Catalog Functions által visszaadott adatok.

Oszlop név	Oszlopszám	Adattípus	Comments
HATÓKÖR (ODBC 1.0)	1	Smallint	A rovad tényleges kiterjedése. Az alábbi értékek egyikét tartalmazza: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION A NULL értéket akkor adjuk vissza, amikor az IdentifierType SQL_ROWVER. Az egyes értékek leírásáért lásd a Scope leírását a "Szintaxis" című részben, amely korábban ebben a szakaszban található.
COLUMN_NAME (ODBC 1.0)	2	Varchar nem NULL	Oszlop neve. Az illesztőprogram üres stringet ad vissza egy olyan oszlophoz, amelynek nincs neve.
DATA_TYPE (ODBC 1.0)	3	Smallint nem NULL	SQL adattípus. Ez lehet ODBC SQL-adattípus vagy illesztőprogram-specifikus SQL-adattípus. Az érvényes ODBC SQL adattípusok listájáért lásd: SQL Data Types. Az illesztőprogram-specifikus SQL-adattípusokkal kapcsolatos információkért tekintse meg az illesztőprogram dokumentációját.
TYPE_NAME (ODBC 1.0)	4	Varchar nem NULL	Adatforrástól függő adattípus neve; például: "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY", vagy "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 1.0)	5	Egész szám	Az adatforrás oszlopának mérete. További információért az oszlopméretről lásd : Oszlopméret, tizedes számjegyek, átviteli oktett hossz és megjelenítés méret.
BUFFER_LENGTH (ODBC 1.0)	6	Egész szám	A SQLGetData vagy SQLFetch műveleten átvitt adatok bájtban megadott hossza, ha SQL_C_DEFAULT van megadva. Numerikus adatok esetén ez a méret eltérhet az adatforrásban tárolt adatok méretétől. Ez az érték eltérhet COLUMN_SIZE karakteradatok oszlopától. További információért lásd: Oszlopméret, tizedes számjegyek, átviteli oktet hossza és megjelenítés mérete.
DECIMAL_DIGITS (ODBC 1.0)	7	Smallint	Az adatforrás oszlopának tizedes számjegyei. A NULL olyan adattípusok esetén jelenik meg, ahol a tizedes számjegyek nem alkalmazhatók. További információért a tizedes számjegyekről lásd: Oszlopméret, tizedes számjegyek, átviteli oktet hossz és megjelenítés mérete.
PSEUDO_COLUMN (ODBC 2.0)	8	Smallint	Jelzi, hogy az oszlop pszeudo-oszlop-e, például az Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Megjegyzés: A maximális interoperabilitás érdekében a pszeudo-oszlopokat nem szabad idézőjellel idézni, amelyet az SQLGetInfo adott vissza.

Miután az alkalmazás lekéri az SQL_BEST_ROWID értékeit, ezekkel az értékekkel újra kiválaszthatja a sort a meghatározott tartományon belül. A SELECT utasítás garantáltan vagy sorok nélkül, vagy egy sort ad vissza.

Ha egy alkalmazás újra kiválaszt egy sort a soroszlop vagy oszlopok alapján, és a sor nem található, az alkalmazás feltételezheti, hogy a sort törölték, vagy a sorszám oszlopait módosították. Az ellenkezője nem igaz: még ha a rowid nem is változott, a sorban lévő többi oszlop is megváltozhatott.

A SQL_BEST_ROWID oszloptípushoz visszaadott oszlopok hasznosak azoknak az alkalmazásoknak, amelyeknek előre-hátra görgetniük kell az eredményhalmazon belül, hogy a sorokból származó legfrissebb adatokat visszanyerjenek. A rowid oszlopai vagy oszlopai garantáltan nem változnak, ha ezen a soron helyezkednek el.

A rowid oszlopa vagy oszlopai akkor is érvényesek maradhatnak, ha a kurzor nincs a sorban; az alkalmazás ezt az eredményhalmazban lévő SCOPE oszlop ellenőrzésével állapíthatja meg.

Az oszloptípushoz visszaadott oszlopok SQL_ROWVER hasznosak azoknak az alkalmazásoknak, amelyek ellenőrizni, frissítettek-e egy adott sorban az oszlopokat, miközben a sort újraválasztották a rowiddel. Például, miután egy sort újraválasztottunk a rowiddal, az alkalmazás összehasonlíthatja a SQL_ROWVER oszlop korábbi értékeit az épp most lehozott értékekkel. Ha egy SQL_ROWVER oszlop értéke eltér az előzőtől, az alkalmazás figyelmeztetheti a felhasználót, hogy a kijelzőn lévő adatok megváltoztak.

Kódpélda

Hasonló függvény kód példáját lásd: SQLColumns.

Kapcsolódó funkciók

Információ erről:	Nézze
Puffer kötése egy eredményhalmaz oszlopához	SQLBindCol függvény
Utasításfeldolgozás megszakítása	SQLCancel függvény
A táblázat vagy táblák oszlopainak visszaküldése	SQLColumns függvény
Egy sor vagy adatblokk előrelépési irányban történő lekérése	SQLFetch függvény
Adatblokk beolvasása vagy egy eredményhalmaz görgetése	SQLFetchScroll függvény
Elsődleges kulcs oszlopainak visszaadása	SQLPrimaryKeys függvény

Kapcsolódó tartalom

• ODBC API referencia
• ODBC-fejlécfájlok