SQLGetDescField függvény

Megfelelőség
Bemutatott verzió: ODBC 3.0 szabványoknak megfelelés: ISO 92

Summary
Az SQLGetDescField egyetlen descriptor rekord mezőjének aktuális beállításait vagy értékét adja vissza.

Syntax

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

Arguments

DescriptorHandle
[Bemenet] Leíró kilét.

RecNumber
[Bemenet] Jelzi azt a leíró rekordot, amelyből az alkalmazás információt keres. A leíró rekordokat 0-tól számozták, a 0-as rekord pedig a könyvjelző rekord. Ha a FieldIdentifier argumentus fejlécmezőt jelöl, akkor a RecNumber figyelmen kívül marad. Ha a RecNumber kisebb vagy egyenlő SQL_DESC_COUNT-vel, de a sor nem tartalmaz adatokat egy oszlophoz vagy paraméterhez, az SQLGetDescField hívása visszaadja a mezők alapértelmezett értékeit. (További információért lásd: "Inicializáció a leíró mezők" az SQLSetDescField területén.)

FieldIdentifier
[Bemenet] Jelzi a leíró mezőjét, amelynek értékét vissza kell adni. További információért lásd az SQLSetDescField "FieldIdentifier Argument" szakaszát.

ValuePtr
[Kimenet] Mutató egy pufferre, amelyben a leíró információt vissza lehet adni. Az adattípus a FieldIdentifier értékétől függ.

Ha a ValuePtr egész számtípusú, az alkalmazásoknak SQLULEN pufferét kell használniuk, és inicializálniuk kell az értéket 0-ra, mielőtt ezt a függvényt hívják, mivel egyes illesztőprogramok csak a puffer alsó 32 vagy 16 bites részét írják, és a magasabb rendű bitet változatlanul hagyják.

Ha a ValuePtr NULL, akkor a StringLengthPtr továbbra is visszaadja a ValuePtr által mutatott pufferben elérhető összes bájtszámot (kivéve a null-terminációs karaktert a karakteradatokhoz).

BufferLength
[Bemenet] Ha a FieldIdentifier egy ODBC-definiált mező, és a ValuePtr egy karakterláncszálra vagy bináris pufferre mutat, akkor ennek az argumentumnak a *ValuePtr hosszának kell lennie. Ha a FieldIdentifier ODBC-definiált mező, míg a *ValuePtr egy egész szám, akkor a BufferLength-et figyelmen kívül hagyjuk. Ha a *ValuePtr értéke Unicode adattípusú, (amikor az SQLGetDescFieldW hívása), akkor a BufferLength argumentusnak páros számnak kell lennie.

Ha a FieldIdentifier illesztőprogram-definiált mező, az alkalmazás a Driver Manager számára a BufferLength argumentus beállításával jelzi a mező természetét. A BufferLength a következő értékeket kaphatja:

• Ha a *ValuePtr egy karakterláncra mutató, akkor a BufferLength a lánc vagy SQL_NTS hossza.

• Ha a *ValuePtr egy bináris pufferre mutató, akkor az alkalmazás a SQL_LEN_BINARY_ATTR(hosszúság) makró eredményét a BufferLength mappába helyezi. Ez negatív értéket ad a BufferLength-ben.

• Ha a *ValuePtr egy másik értékre mutató, mint egy karakterlánc vagy bináris string, akkor a BufferLengthnek az értéke SQL_IS_POINTER.

• Ha a *ValuePtr fix hosszúságú adattípust tartalmaz, akkor a BufferLength vagy SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, vagy SQL_IS_USMALLINT, ahogy megfelelően.

StringLengthPtr
[Kimenet] Mutató arra a pufferre, amelyben vissza lehet adni a null-terminációs karakterhez szükséges bájtok teljes számát (kivéve a null-terminációs karakterhez szükséges bájtszámot), amelyek a *ValuePtr-ben vissza lehet térni.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA vagy SQL_INVALID_HANDLE.

SQL_NO_DATA akkor jelenik meg, ha a RecNumber nagyobb, mint a jelenlegi leíró rekordok száma.

SQL_NO_DATA akkor jelenik meg, ha a DescriptorHandle IRD handle, és az utasítás előkészített vagy futtatott állapotban van, de nem volt hozzá nyitott kurzor.

Diagnostics

Amikor az SQLGetDescField SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad vissza, egy hozzárendelt SQLSTATE értéket lehet elérni, ha az SQLGetDiagRec hívása egy SQL_HANDLE_STMT HandleType és egy HandleType of StatementHandle (Handle) segítségével érhető el. Az alábbi táblázat felsorolja az SQLGetDescField által gyakran visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; 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.)
01004	Sztringadatok, jobb csonkolt	A *ValuePtr puffer nem volt elég nagy ahhoz, hogy az egész leíró mezőt visszaadja, ezért a mezőt lerövidítették. A csonkítatlan leíró mező hosszát a *StringLengthPtr-ben adjuk vissza. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
07009	Érvénytelen descriptor index	(DM) A RecNumber érvelés 0-val egyenlő volt, az SQL_ATTR_USE_BOOKMARK állítás attribútuma SQL_UB_OFF, a DescriptorHandle érve pedig IRD név volt. (Ez a hiba csak akkor tér vissza egy explicit módon kijelölt leíró esetén, ha a leíró egy utasításkezelőhöz van kötve.) A FieldIdentifier argumenta egy rekordmező volt, a RecNumber argumenta 0, a DescriptorHandle érve pedig egy IPD név. A RecNumber érv kevesebb volt, mint 0.
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.
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 illeszőr nem tudta lefoglalni a szükséges memóriát a funkció végrehajtásához vagy befejezéséhez.
HY007	A kapcsolódó nyilatkozat nincs elkészítve	A DescriptorHandle IRD-ként egy StatementHandle-hez volt kötve, és a hozzá tartozó utasításkezelőt nem készítették elő vagy hajtották végre.
HY010	Függvényütemezési hiba	(DM) A DescriptorHandle egy StatementHandle eszközhöz volt kapcsolva, amelyhez egy aszinkron futó függvényt hívtak (nem ezt), és még akkor futott, amikor ezt a függvényt hívták. (DM) A DescriptorHandle egy StatementHandle-hez volt kapcsolva, amelyhez az SQLExecute, SQLExecDirect, SQLBulkOperations vagy SQLSetPos meghívást és vissza SQL_NEED_DATA visszaadtak. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg. (DM) Egy aszinkron futóképességű függvényt hívtak a DescriptorHandle kapcsolati handle-hez. Ez az aszinkron függvény még akkor futott, amikor az SQLGetDescField függvényt hívták.
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.
HY021	Következetlen leíró információk	A SQL_DESC_TYPE és SQL_DESC_DATETIME_INTERVAL_CODE mezők nem alkotnak érvényes ODBC SQL típust, nem érvényes illesztőgép-specifikus SQL típust (IPD-k esetén), sem érvényes ODBC C típust (APD-k vagy ARD-k esetén).
HY090	Érvénytelen sztring vagy puffer hossza	(DM) *ValuePtr egy karakterlánc volt, a BufferLength pedig nullánál kisebb volt.
HY091	Érvénytelen deskriptor mezőazonosító	A FieldIdentifier nem ODBC által definiált mező volt, és nem is implementáció által definiált érték. A FieldIdentifier a DescriptorHandle számára definiálatlan volt.
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) További információért a felfüggesztett állapotról lásd : SQLEndTran függvény.
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) A DescriptorHandle hozzátartozó illesztőprogram nem támogatja ezt a funkciót.

Comments

Egy alkalmazás hívhatja az SQLGetDescField alkalmazást, hogy visszaadja egy leíró rekord egyetlen mező értékét. Az SQLGetDescField hívása bármely mező beállításait visszaadhatja bármely leíró típusban, beleértve a fejléceket, rekordmezőket és könyvjelző mezőket. Egy alkalmazás több mező beállításait ugyanazon vagy különböző leírókban tetszőleges sorrendben szerezheti meg, ismételt hívásokkal az SQLGetDescField-re. Az SQLGetDescField hívható arra is, hogy visszaadja az illesztőprogram-definiált leíró mezőket.

Teljesítmény miatt egy alkalmazásnak nem szabad SQLGetDescFieldet IRD-hez hívnia egy utasítás végrehajtása előtt.

Több mező beállításai, amelyek leírják az oszlop- vagy paraméteradatok nevét, adattípusát és tárolását, szintén egyetlen hívással letölthető SQLGetDescRec-hez. Az SQLGetStmtAttr meghívható, hogy visszaadja egyetlen mező beállítását a leíró fejlécben, amely egyben egy utasítás attribútum. SQLColAttribute, SQLDescribeCol és SQLDescribeParam visszaadják a rekord- vagy könyvjelző mezőket.

Amikor egy alkalmazás az SQLGetDescField-et hívja egy adott leíró típusra definiálatlan mező értékének lekérdezésére, a függvény SQL_SUCCESS ad, de a mező értéke nem definiál. Például, ha az APD vagy ARD SQL_DESC_NAME vagy SQL_DESC_NULLABLE mezőjére az SQLGetDescField hívása SQL_SUCCESS de egy meghatározatlan értéket ad vissza.

Amikor egy alkalmazás az SQLGetDescField-et hívja, hogy visszanyerje egy adott leíró típusra definiált, de alapértelmezett értéke nincs és még nem állították be, a függvény SQL_SUCCESS értéket ad vissza, de a mező értéke nem definiált. További információért a leíró mezők inicializációjáról és a mezők leírásáról lásd: "Inicializáció a leíró mezők inicializálása" az SQLSetDescField oldalon. További információért a leírókról lásd: Descriptors.

Kapcsolódó funkciók

Információ erről:	Nézze
Több leíró mező megszerzése	SQLGetDescRec Function
Egyetlen leíró mező beállítása	SQLSetDescField függvény
Több leíró mező beállítása	SQLSetDescRec Function

Kapcsolódó tartalom

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