Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92
Summary
SQLGetDescField vrací aktuální nastavení nebo hodnotu jednoho pole deskriptorového záznamu.
Syntax
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
DescriptorHandle
[Vstup] Handle popisu.
Přečíslovat
[Vstup] Označuje deskriptorový záznam, ze kterého žádost hledá informace. Descriptorové záznamy jsou číslovány od 0, přičemž číslo 0 je záznam záložek. Pokud argument FieldIdentifier označuje pole hlavičky, RecNumber se ignoruje. Pokud je RecNumber menší nebo rovno SQL_DESC_COUNT, ale řádek neobsahuje data pro sloupec nebo parametr, volání SQLGetDescField vrátí výchozí hodnoty polí. (Pro více informací viz "Inicializace deskriptorových polí" v SQLSetDescField.)
FieldIdentifier
[Vstup] Označuje pole popisovače, jehož hodnota má být vrácena. Pro více informací viz sekce "FieldIdentifier Argument" v SQLSetDescField.
ValuePtr
[Výstup] Ukazatel na buffer, do kterého se vrátí informace o popisu. Typ dat závisí na hodnotě FieldIdentifier.
Pokud je ValuePtr celočíselný typ, aplikace by měly použít buffer SQLULEN a inicializovat hodnotu na 0 před vyvoláním této funkce, protože některé ovladače mohou zapisovat pouze dolní 32bitový nebo 16bitový buffer a vyšší bit ponechat beze změny.
Pokud je ValuePtr NULL, StringLengthPtr stále vrátí celkový počet bajtů (bez znaku null-termination pro znaková data), které lze vrátit v bufferu na který ukazuje ValuePtr.
BufferLength
[Vstup] Pokud je FieldIdentifier pole definované ODBC a ValuePtr ukazuje na znakový řetězec nebo binární buffer, tento argument by měl být délka *ValuePtr. Pokud je FieldIdentifier pole definované ODBC a *ValuePtr je celé číslo, BufferLength se ignoruje. Pokud je hodnota v *ValuePtr z datového typu Unicode (při volání SQLGetDescFieldW), musí být argument BufferLength sudé číslo.
Pokud je FieldIdentifier pole definované ovladačem, aplikace určuje povahu pole Driver Manageru nastavením argumentu BufferLength . BufferLength může mít následující hodnoty:
Pokud je *ValuePtr ukazatelem na znakový řetězec, pak BufferLength je délka řetězce nebo SQL_NTS.
Pokud je *ValuePtr ukazatelem na binární buffer, aplikace umístí výsledek makra SQL_LEN_BINARY_ATTR(length) do BufferLength. To umístí zápornou hodnotu v BufferLength.
Pokud je *ValuePtr ukazatelem na hodnotu jinou než znakový řetězec nebo binární řetězec, pak by BufferLength měl mít hodnotu SQL_IS_POINTER.
Pokud *ValuePtr obsahuje datový typ s pevnou délkou, pak BufferLength je buď SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT nebo SQL_IS_USMALLINT, podle potřeby.
StringLengthPtr
[Výstup] Ukazatel na buffer, do kterého se vrací celkový počet bajtů (bez počtu bajtů potřebných pro znak null-terminace), které lze vrátit v *ValuePtr.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA nebo SQL_INVALID_HANDLE.
SQL_NO_DATA se vrátí, pokud je RecNumber větší než aktuální počet descriptorových záznamů.
SQL_NO_DATA se vrátí, pokud je DescriptorHandle IRD handle a příkaz je ve stavu připravený nebo vykonáný, ale nebyl k němu přiřazen otevřený kurzor.
Diagnostika
Když SQLGetDescField vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, kterou lze získat voláním SQLGetDiagRec pomocí HandleType SQL_HANDLE_STMT a HandleCommandHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLGetDescField 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.) |
| 01004 | Řetězcová data, zkrácená vpravo | Buffer *ValuePtr nebyl dostatečně velký na to, aby vrátil celé deskriptorové pole, takže pole bylo zkráceno. Délka neomezeného deskriptorového pole se vrací v *StringLengthPtr. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 07009 | Index neplatných deskriptorů | (DM) Argument RecNumber byl roven 0, atribut SQL_ATTR_USE_BOOKMARK příkazu byl SQL_UB_OFF a argument DescriptorHandle byl IRD handle. (Tuto chybu lze vrátit pro explicitně přidělený deskriptor pouze tehdy, pokud je deskriptor spojen s příkazovou rukojetí.) Argument FieldIdentifier byl pole záznamu, argument RecNumber byl 0 a argument DescriptorHandle byl IPD handle. Argument RecNumber byl menší než 0. |
| 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. |
| 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č nebyl schopen přidělit paměť potřebnou k podpoře nebo dokončení funkce. |
| HY007 | Související prohlášení není připraveno | DescriptorHandle byl spojen s StatementHandle jako IRD a příslušný příkazový handle nebyl připraven ani vykonán. |
| HY010 | Chyba posloupnosti funkcí | (DM) DescriptorHandle byl spojen s StatementHandle , pro který byla volána asynchronně vykonávající funkce (ne tato), která se stále spouštěla, když byla tato funkce vyvolána. (DM) DescriptorHandle byl spojen s StatementHandle , pro který byly volány SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos a vracely SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. (DM) Pro connection handle, který je spojen s DescriptorHandle, byla volána asynchronně vykonávající funkce. Tato asynchronní funkce se stále vykonávala, když byla volána funkce SQLGetDescField . |
| 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. |
| HY021 | Nekonzistentní informace o popisech | Pole SQL_DESC_TYPE a SQL_DESC_DATETIME_INTERVAL_CODE netvoří platný ODBC SQL typ, platný SQL typ specifický pro ovladač (pro IPD) ani platný ODBC C typ (pro APD nebo ARD). |
| HY090 | Neplatná délka řetězce nebo vyrovnávací paměti | (DM) *ValuePtr byl znakový řetězec a BufferLength byl menší než nula. |
| HY091 | Neplatný identifikátor pole deskriptoru |
FieldIdentifier nebyl pole definované ODBC a nebyl to hodnota definovaná implementací. FieldIdentifier nebyl definován pro DescriptorHandle. |
| HY117 | Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. | (DM) Pro více informací o pozastaveném stavu viz SQLEndTran Function. |
| 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řiřazený k DescriptorHandle tuto funkci nepodporuje. |
Comments
Aplikace může zavolat SQLGetDescField a vrátit hodnotu jednoho pole deskriptorového záznamu. Volání SQLGetDescField může vrátit nastavení libovolného pole v jakémkoli typu deskriptoru, včetně hlavičkových polí, záznamových polí a záložek. Aplikace může získat nastavení více polí ve stejném nebo různém deskriptore, v libovolném pořadí, opakovaným voláním do SQLGetDescField. SQLGetDescField lze také volat pro vrácení deskriptorových polí definovaných ovladačem.
Z důvodů výkonu by aplikace neměla volat SQLGetDescField pro IRD před vykonáním příkazu.
Nastavení více polí, která popisují název, datový typ a úložiště sloupců nebo parametrů, lze také získat v jednom volání do SQLGetDescRec. SQLGetStmtAttr lze volat tak, aby vrátil nastavení jednoho pole v hlavičce deskriptoru, které je zároveň atributem příkazu. SQLColAttribute, SQLDescribeCol a SQLDescribeParam return record nebo záložková pole.
Když aplikace volá SQLGetDescField k získání hodnoty pole, které není definováno pro konkrétní typ popisovače, funkce vrátí SQL_SUCCESS, ale hodnota vrácená pro toto pole je nedefinovaná. Například volání SQLGetDescField pro pole SQL_DESC_NAME nebo SQL_DESC_NULLABLE v APD nebo ARD vrátí SQL_SUCCESS, ale nedefinovanou hodnotu pro toto pole.
Když aplikace zavolá SQLGetDescField k získání hodnoty pole, které je definováno pro určitý typ deskriptoru, ale nemá výchozí hodnotu a ještě nebylo nastaveno, funkce vrátí SQL_SUCCESS, ale hodnota vrácená pro toto pole není definována. Pro více informací o inicializaci deskriptorových polí a popisech polí viz "Inicializace deskriptorových polí" v SQLSetDescField. Pro více informací o popisech viz Descriptors.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Získání více deskriptorových polí | SQLGetDescRec Function |
| Nastavení jednoho deskriptorového pole | SQLSetDescField Function |
| Nastavení více deskriptorových polí | SQLSetDescRec Function |