Funkce SQLSetDescField

Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92

Shrnutí
SQLSetDescField nastavuje hodnotu jednoho pole deskriptorového záznamu.

Syntax

SQLRETURN SQLSetDescField(  
     SQLHDESC      DescriptorHandle,  
     SQLSMALLINT   RecNumber,  
     SQLSMALLINT   FieldIdentifier,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    BufferLength);

Arguments

DescriptorHandle
[Vstup] Handle popisu.

Přečíslovat
[Vstup] Označuje deskriptorový záznam obsahující pole, které aplikace chce nastavit. Descriptorové záznamy jsou číslovány od 0, přičemž číslo 0 je záznam záložek. Argument RecNumber je u hlavičkových polí ignorován.

FieldIdentifier
[Vstup] Označuje pole deskriptoru, jehož hodnota má být nastavena. Pro více informací viz "FieldIdentifier Argument" v sekci "Komentáře".

ValuePtr
[Vstup] Ukazatel na buffer obsahující informace o deskriptoru nebo na celočíselnou hodnotu. Typ dat závisí na hodnotě FieldIdentifier. Pokud je ValuePtr celočíselná hodnota, může být považována za 8 bajtů (SQLLEN), 4 bajty (SQLINTEGER) nebo 2 bajty (SQLSMALLINT), v závislosti na hodnotě argumentu FieldIdentifier .

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. Pro data řetězce znaků by tento argument měl obsahovat počet bajtů v řetězci.

Pokud je FieldIdentifier pole definované ODBC a ValuePtr je celé číslo, BufferLength se ignoruje .

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 řetězec znaků, 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 hodnotu pevné délky, pak BufferLength je buď SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, nebo SQL_IS_USMALLINT, podle potřeby.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostics

Když SQLSetDescField vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, pokud se vyvolá SQLGetDiagRec s HandleType SQL_HANDLE_DESC a HandleDescriptorHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLSetDescField 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.)
01S02 Změna hodnoty možnosti Ovladač nepodporoval hodnotu zadanou v *ValuePtr (pokud byl ukazatelem ValuePtr ) ani hodnotu v ValuePtr (pokud byla ValuePtr celočíselná hodnota), případně *ValuePtr byla neplatná kvůli pracovním podmínkám implementace, takže ovladač nahradil podobnou hodnotou. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
07009 Index neplatných deskriptorů Argument FieldIdentifier byl pole záznamu, argument RecNumber byl 0 a argument DescriptorHandle odkazoval na IPD handle.

Argument RecNumber byl menší než 0 a argument DescriptorHandle odkazoval na ARD nebo APD.

Argument RecNumber byl větší než maximální počet sloupců nebo parametrů, které zdroj dat může podpořit, a argument DescriptorHandle odkazoval na APD nebo ARD.

(DM) Argument FieldIdentifier byl SQL_DESC_COUNT a argument *ValuePtr byl menší než 0.

Argument RecNumber byl roven 0 a argument DescriptorHandle odkazoval na implicitně alokovaný APD. (Tato chyba se nevyskytuje u explitě přiděleného aplikačního deskriptoru, protože není známo, zda je explicitně přidělený aplikační deskriptor APD nebo ARD, dokud není čas vykonání.)
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.
22001 Řetězcová data, zkrácená vpravo Argument FieldIdentifier byl SQL_DESC_NAME a argument BufferLength měl hodnotu větší než SQL_MAX_IDENTIFIER_LEN.
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.
HY010 Chyba posloupnosti funkcí (DM) DescriptorHandle byl spojen s StatementHandlem , pro který byla volána asynchronně vykonávaná funkce (ne tato), která se stále spouštěla, když byla tato funkce vyvolána.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle , se kterým byl DescriptorHandle spojen, 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 SQLSetDescField .

(DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl vyvolán pro jeden z příkazových rukojeti přiřazených k DescriptorHandle a vrátil SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry.
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.
HY016 Nelze upravovat deskriptor řádku implementace Argument DescriptorHandle byl spojen s IRD a argument FieldIdentifier nebyl SQL_DESC_ARRAY_STATUS_PTR ani SQL_DESC_ROWS_PROCESSED_PTR.
HY021 Nekonzistentní informace o popisech Pole SQL_DESC_TYPE a SQL_DESC_DATETIME_INTERVAL_CODE netvoří platný SQL typ ODBC, SQL typ specifický pro ovladač (pro IPD) ani platný typ ODBC C (pro APD nebo ARDs).

Informace o popisech kontrolované během kontroly konzistence nebyly konzistentní. (Viz "Kontrola konzistence" v SQLSetDescRec.)
HY090 Neplatná délka řetězce nebo vyrovnávací paměti (DM) *ValuePtr je řetězec znaků a BufferLength byla menší než nula, ale nebyla rovna SQL_NTS.

(DM) Ovladač byl ODBC 2*.x* ovladač, deskriptor byl ARD, argument ColumnNumber byl nastaven na 0 a hodnota určená pro argument BufferLength nebyla roven 4.
HY091 Neplatný identifikátor pole deskriptoru Hodnota zadaná pro argument FieldIdentifier nebyla polem definovaným ODBC a nebyla definována implementací.

Argument FieldIdentifier byl neplatný pro argument DescriptorHandle .

Argument FieldIdentifier byl pole pouze pro čtení, definované ODBC.
HY092 Neplatný identifikátor atributu/opce Hodnota v *ValuePtr nebyla platná pro argument FieldIdentifier .

Argument FieldIdentifier byl SQL_DESC_UNNAMED a ValuePtr SQL_NAMED.
HY105 Neplatný typ parametru (DM) Hodnota uvedená pro pole SQL_DESC_PARAMETER_TYPE byla neplatná. (Pro více informací viz sekce "InputOutputType Argument" v SQLBindParameter.)
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 Co je nového v ODBC 3.8.
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 volat SQLSetDescField a nastavit libovolné pole popisu jedno po druhém. Jedno volání SQLSetDescField nastaví jedno pole v jednom deskriptoru. Tato funkce může být volána pro nastavení libovolného pole v libovolném typu popisovače, pokud lze toto pole nastavit. (Viz tabulka později v této části.)

Note

Pokud volání SQLSetDescField selže, obsah deskriptorového záznamu identifikovaného argumentem RecNumber není definován.

Další funkce lze volat k nastavení více deskriptorových polí jedním voláním funkce. Funkce SQLSetDescRec nastavuje různé pole, která ovlivňují datový typ a buffer vázaný na sloupec nebo parametr (pole SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR a SQL_DESC_INDICATOR_PTR). SQLBindCol nebo SQLBindParameter lze použít k vytvoření úplné specifikace pro vazbu sloupce nebo parametru. Tyto funkce nastavují konkrétní skupinu deskriptorových polí jedním voláním funkce.

SQLSetDescField lze volat ke změně bufferů pro vazby přidáním offsetu k ukazatelům vazby (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR nebo SQL_DESC_OCTET_LENGTH_PTR). Tím se mění buffery pro vazby bez nutnosti volat SQLBindCol nebo SQLBindParameter, což umožňuje aplikaci změnit SQL_DESC_DATA_PTR bez změny jiných polí, například SQL_DESC_DATA_TYPE.

Pokud aplikace zavolá SQLSetDescField k nastavení libovolného pole jiného než SQL_DESC_COUNT nebo odložených polí SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR nebo SQL_DESC_INDICATOR_PTR, záznam se stane nevázaným.

Pole hlaviček deskriptoru se nastavují voláním SQLSetDescField s příslušným FieldIdentifier. Mnoho hlavičkových polí jsou také atributy příkazů, takže je lze nastavit i voláním do SQLSetStmtAttr. To umožňuje aplikacím nastavit deskriptorové pole, aniž by nejprve získaly deskriptorovou rukojeť. Když je SQLSetDescField vyvolán k nastavení hlavičkového pole, argument RecNumber je ignorován.

K nastavení polí záložek se používá RecNumber 0.

Note

Příkazový atribut SQL_ATTR_USE_BOOKMARKS by měl být vždy nastaven před zavoláním SQLSetDescField pro nastavení polí záložek. I když to není povinné, důrazně se to doporučuje.

Sekvence polí deskriptorů nastavení

Při nastavování deskriptorových polí voláním SQLSetDescField musí aplikace dodržovat specifickou sekvenci:

  1. Aplikace musí nejprve nastavit pole SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE nebo SQL_DESC_DATETIME_INTERVAL_CODE.

  2. Po nastavení jednoho z těchto polí může aplikace nastavit atribut datového typu a ovladač nastaví pole atributu datového typu na odpovídající výchozí hodnoty pro daný datový typ. Automatické výchozí nastavení typů atributových polí zajišťuje, že deskriptor je vždy připraven k použití, jakmile aplikace zadá datový typ. Pokud aplikace explicitně nastaví atribut datového typu, přepisuje výchozí atribut.

  3. Po nastavení jednoho z polí uvedených v kroku 1 a atributech datových typů aplikace může nastavit SQL_DESC_DATA_PTR. To vyvolá kontrolu konzistence popisných polí. Pokud aplikace změní datový typ nebo atributy po nastavení pole SQL_DESC_DATA_PTR, ovladač SQL_DESC_DATA_PTR nastaví na nulový ukazatel, čímž záznam odpojí. To nutí aplikaci dokončit správné kroky v pořadí, než bude deskriptorový záznam použitelný.

Inicializace polí popisovače

Když je deskriptor alokován, pole v něm mohou být inicializována na výchozí hodnotu, inicializována bez výchozí hodnoty nebo nedefinovaná pro typ deskriptoru. Následující tabulky označují inicializaci každého pole pro každý typ deskriptoru, přičemž "D" označuje, že pole je inicializováno s výchozím nastavením, a "ND" označuje, že pole je inicializováno bez výchozího nastavení. Pokud je zobrazeno číslo, výchozí hodnota pole je právě toto číslo. Tabulky také ukazují, zda je pole čteno/zapisované (R/W) nebo pouze pro čtení (R).

Pole IRD mají výchozí hodnotu až poté, co byl příkaz připraven nebo vykonán a IRD naplněn, nikoli když je přiřazen handle nebo deskriptor příkazu. Dokud není IRD vyplněn, jakýkoli pokus o přístup k poli IRD vrátí chybu.

Některá deskriptorová pole jsou definována pro jeden nebo více, ale ne pro všechny typy deskriptorů (ARDs a IRD, APD a IPD). Pokud je pole nedefinované pro typ deskriptoru, není potřeba žádnou z funkcí, které tento deskriptor používají.

Pole, ke kterým lze přistupovat pomocí SQLGetDescField , nemusí nutně nastavit SQLSetDescField. Pole, která lze nastavit pomocí SQLSetDescField , jsou uvedena v následujících tabulkách.

Inicializace hlavičkových polí je popsána v následující tabulce.

Název hlavičkového pole Typ R/W Výchozí
SQL_DESC_ALLOC_TYPE SQLSMALLINT ARD: R APD: R IRD: R IPD: R ARD: SQL_DESC_ALLOC_AUTO pro implicitní nebo SQL_DESC_ALLOC_USER pro explicitní

APD: SQL_DESC_ALLOC_AUTO pro implicitní nebo SQL_DESC_ALLOC_USER pro explicitní

IRD: SQL_DESC_ALLOC_AUTO

IPD: SQL_DESC_ALLOC_AUTO
SQL_DESC_ARRAY_SIZE SQLULEN ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD:[1] APD:[1] IRD: Nepoužitý IPD: Nepoužitý
SQL_DESC_ARRAY_STATUS_PTR SQLUSMALLINT* ARD: R/W APD: R/W IRD: R/W IPD: R/W ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr
SQL_DESC_BIND_OFFSET_PTR SQLLEN* ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD: Null ptr APD: Null ptr IRD: Nepoužitý IPD: Nepoužitý
SQL_DESC_BIND_TYPE SQLINTEGER ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD: SQL_BIND_BY_COLUMN

APD: SQL_BIND_BY_COLUMN

IRD: Nepoužitý

IPD: Nepoužitý
SQL_DESC_COUNT SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: 0 APD: 0 IRD: D IPD: 0
SQL_DESC_ROWS_PROCESSED_PTR SQLULEN* ARD: Nepoužitý APD: Nepoužitý IRD: R/W IPD: R/W ARD: Nepoužitý APD: Nepoužitý IRD: Null ptr IPD: Null ptr

[1] Tato pole jsou definována pouze tehdy, když je IPD automaticky vyplněno ovladačem. Pokud ne, jsou nedefinované. Pokud se aplikace pokusí tato pole nastavit, vrátí se SQLSTATE HY091 (Invalid descriptor field identifier).

Inicializace polí záznamů je uvedena v následující tabulce.

Název záznamového pole Typ R/W Výchozí
SQL_DESC_AUTO_UNIQUE_VALUE SQLINTEGER ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_BASE_COLUMN_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_BASE_TABLE_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_ROZLIŠUJE_VELIKOST_PÍSMEN SQLINTEGER ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: D[1]
SQL_DESC_CATALOG_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_CONCISE_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: SQL_C_ DEFAULT APD: SQL_C_ DEFAULT IRD: D IPD: ND
SQL_DESC_DATA_PTR SQLPOINTER ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD: Null ptr APD: Null ptr IRD: Nepoužitý IPD: Nepoužitý[2]
SQL_DESC_DATETIME_INTERVAL_CODE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DATETIME_INTERVAL_PRECISION SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DISPLAY_SIZE SQLLEN ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_FIXED_PREC_SCALE SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: D[1]
SQL_DESC_INDICATOR_PTR SQLLEN * ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD: Null ptr APD: Null ptr IRD: Nepoužitý IPD: Nepoužitý
SQL_DESC_LABEL SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_LENGTH SQLULEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_LITERAL_PREFIX SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_LITERAL_SUFFIX SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_LOCAL_TYPE_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: D[1]
SQL_DESC_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NULLABLE (Určuje, zda může být hodnota sloupce NULL) SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NUM_PREC_RADIX SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH SQLLEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH_PTR SQLLEN * ARD: R/W APD: R/W IRD: Nepoužitý IPD: Nepoužitý ARD: Null ptr APD: Null ptr IRD: Nepoužitý IPD: Nepoužitý
SQL_DESC_PARAMETER_TYPE SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: Nepoužitý IPD: R/W ARD: Nepoužitý APD: Nepoužitý IRD: Nepoužitý IPD: D=SQL_PARAM_INPUT
SQL_DESC_PRECISION SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_ROWVER SQLSMALLINT ARD: Nepoužitý

APD: Nepoužitý

IRD: R

IPD: R		 ARD: Nepoužitý

APD: Nepoužitý

IRD: ND

IPD: ND
SQL_DESC_SCALE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_SCHEMA_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_SEARCHABLE SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_NÁZEV_TABULKY SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý
SQL_DESC_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND
SQL_DESC_TYPE_NAME SQLCHAR * ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: D[1]
SQL_DESC_UNNAMED SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_UNSIGNED SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: R ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: D[1]
SQL_DESC_UPDATABLE SQLSMALLINT ARD: Nepoužitý APD: Nepoužitý IRD: R IPD: Nepoužitý ARD: Nepoužitý APD: Nepoužitý IRD: D IPD: Nepoužitý

[1] Tato pole jsou definována pouze tehdy, když je IPD automaticky vyplněno ovladačem. Pokud ne, jsou nedefinované. Pokud se aplikace pokusí tato pole nastavit, vrátí se SQLSTATE HY091 (Invalid descriptor field identifier).

[2] Pole SQL_DESC_DATA_PTR v IPD lze nastavit tak, aby vynutilo kontrolu konzistence. Při následném volání do SQLGetDescField nebo SQLGetDescRec není ovladač povinen vracet hodnotu, na kterou byl SQL_DESC_DATA_PTR nastaven.

FieldIdentifier Argument

Argument FieldIdentifier označuje deskriptorové pole, které má být nastaveno. Descriptor obsahuje hlavičku deskriptoru, která se skládá z hlavičkových polí popsaných v následující sekci "Header Fields" a nula nebo více descriptorových záznamů, které obsahují pole záznamu popsaná v sekci po sekci "Header Fields".

Hlavičková pole

Každý deskriptor má hlavičku složenou z následujících polí:

SQL_DESC_ALLOC_TYPE [Všichni]
Toto pole hlavičky SQLSMALLINT, které je určeno pouze pro čtení, specifikuje, zda byl deskriptor automaticky přidělen ovladačem, nebo explicitně aplikací. Aplikace může toto pole získat, ale nemusí ho upravovat. Pole je nastaveno na SQL_DESC_ALLOC_AUTO ovladačem, pokud byl deskriptor automaticky přidělen ovladačem. Ovladač ho nastaví na SQL_DESC_ALLOC_USER, pokud byl deskriptor explicitně přidělen aplikací.

SQL_DESC_ARRAY_SIZE [Popisy žádostí]
V ARD toto pole hlavičky SQLULEN určuje počet řádků v sadě řádků. To je počet řádků, které má být vrácen voláním do SQLFetch nebo SQLFetchScroll , nebo aby byl operován voláním do SQLBulkOperations nebo SQLSetPos.

V APD toto pole hlavičky SQLULEN určuje počet hodnot pro každý parametr.

Výchozí hodnota tohoto pole je 1. Pokud je SQL_DESC_ARRAY_SIZE větší než 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR a SQL_DESC_OCTET_LENGTH_PTR APD nebo ARD ukazují na pole. Kardinálnost každého pole je rovna hodnotě tohoto pole.

Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROW_ARRAY_SIZE. Toto pole v APD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAMSET_SIZE.

SQL_DESC_ARRAY_STATUS_PTR [Všichni]
Pro každý typ deskriptoru toto pole hlavičky SQLUSMALLINT * ukazuje na pole hodnot SQLUSMALLINT. Tato pole jsou pojmenována následovně: řádkové stavové pole (IRD), parametrické stavové pole (IPD), řádkové operační pole (ARD) a parametrové operační pole (APD).

V IRD toto pole hlavičky ukazuje na řádkové stavové pole obsahující stavové hodnoty po volání do SQLBulkOperations, SQLFetch, SQLFetchScroll nebo SQLSetPos. Pole má tolik prvků, kolik je řádků v sadě řádků. Aplikace musí alokovat pole SQLUSMALLINTů a nastavit toto pole tak, aby ukazovalo na pole. Pole je ve výchozím nastavení nastaveno na nulový ukazatel. Ovladač pole vyplní – pokud pole SQL_DESC_ARRAY_STATUS_PTR není nastaveno na nulový ukazatel, v takovém případě nejsou generovány žádné stavové hodnoty a pole není vyplněno.

Caution

Chování ovladačů není definováno, pokud aplikace nastaví prvky řádkového stavového pole, na které ukazuje SQL_DESC_ARRAY_STATUS_PTR pole IRD.

Pole je zpočátku vyplněno voláním SQLBulkOperations, SQLFetch, SQLFetchScroll nebo SQLSetPos. Pokud volání nevrátilo SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO, obsah pole na které toto pole ukazuje není definován. Prvky v poli mohou obsahovat následující hodnoty:

  • SQL_ROW_SUCCESS: Řada byla úspěšně vyzvednuta a od posledního vyzvednutí se nezměnila.

  • SQL_ROW_SUCCESS_WITH_INFO: Řada byla úspěšně vyzvednuta a od posledního stažení se nezměnila. Avšak bylo vráceno upozornění o řádku.

  • SQL_ROW_ERROR: Při načítání řádku došlo k chybě.

  • SQL_ROW_UPDATED: Řádek byl úspěšně načten a od posledního načtení byl aktualizován. Pokud je řádek znovu načten, jeho stav je SQL_ROW_SUCCESS.

  • SQL_ROW_DELETED: Řádek byl smazán od posledního načtení.

  • SQL_ROW_ADDED: Řádek byl vložen pomocí SQLBulkOperations. Pokud je řádek znovu načten, jeho stav je SQL_ROW_SUCCESS.

  • SQL_ROW_NOROW: Řádková sada se překrývala s koncem výsledné množiny a nebyl vrácen žádný řádek, který by odpovídal tomuto prvku řádkového stavového pole.

Toto pole v IRD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROW_STATUS_PTR.

Pole SQL_DESC_ARRAY_STATUS_PTR IRD je platné až poté, co je SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO vrácen. Pokud return code není jedním z nich, místo, na které SQL_DESC_ROWS_PROCESSED_PTR ukazuje, není definováno.

V IPD toto pole hlavičky ukazuje na pole stavů parametrů obsahující informace o stavu pro každou sadu hodnot parametrů po volání do SQLExecute nebo SQLExecDirect. Pokud volání SQLExecute nebo SQLExecDirect nevrátilo SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO, obsah pole na toto pole je nedefinovaný. Aplikace musí alokovat pole SQLUSMALLINTů a nastavit toto pole tak, aby ukazovalo na pole. Ovladač pole vyplní – pokud pole SQL_DESC_ARRAY_STATUS_PTR není nastaveno na nulový ukazatel, v takovém případě nejsou generovány žádné stavové hodnoty a pole není vyplněno. Prvky v poli mohou obsahovat následující hodnoty:

  • SQL_PARAM_SUCCESS: SQL příkaz byl úspěšně vykonán pro tuto sadu parametrů.

  • SQL_PARAM_SUCCESS_WITH_INFO: SQL příkaz byl úspěšně vykonán pro tuto sadu parametrů; varovné informace jsou však dostupné v diagnostické datové struktuře.

  • SQL_PARAM_ERROR: Při zpracování této sady parametrů došlo k chybě. Další informace o chybách jsou dostupné v diagnostické datové struktuře.

  • SQL_PARAM_UNUSED: Tato sada parametrů nebyla použita, pravděpodobně proto, že nějaká předchozí sada parametrů způsobila chybu, která přerušila další zpracování, nebo protože SQL_PARAM_IGNORE byla nastavena pro tuto sadu parametrů v poli specifikovaném SQL_DESC_ARRAY_STATUS_PTR polem APD.

  • SQL_PARAM_DIAG_UNAVAILABLE: Diagnostické informace nejsou k dispozici. Příkladem je, když ovladač považuje pole parametrů za monolitickou jednotku a proto negeneruje tuto úroveň chybových informací.

Toto pole v IPD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAM_STATUS_PTR.

V ARD toto pole hlavičky ukazuje na pole řádkových operací hodnot, které může aplikace nastavit, aby určilo, zda má být tento řádek ignorován pro operace SQLSetPos . Prvky v poli mohou obsahovat následující hodnoty:

  • SQL_ROW_PROCEED: Řádek je zahrnut do hromadné operace pomocí SQLSetPos. (Toto nastavení nezaručuje, že operace proběhne na řádku. Pokud má řádek stavovou SQL_ROW_ERROR v IRD řádkovém stavovém poli, ovladač nemusí být schopen provést operaci v řádku.)

  • SQL_ROW_IGNORE: Řádek je vyloučen z hromadné operace pomocí SQLSetPos.

Pokud nejsou nastaveny žádné prvky pole, všechny řádky jsou zahrnuty do hromadné operace. Pokud je hodnota v SQL_DESC_ARRAY_STATUS_PTR poli ARD nulovým ukazatelem, všechny řádky jsou zahrnuty do hromadné operace; interpretace je stejná, jako kdyby ukazatel ukazoval na platné pole a všechny prvky pole byly SQL_ROW_PROCEED. Pokud je prvek v poli nastaven na SQL_ROW_IGNORE, hodnota v řádkovém stavovém poli pro ignorovaný řádek se nemění.

Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROW_OPERATION_PTR.

V APD toto pole hlavičky ukazuje na pole parametrů operací hodnot, které může aplikace nastavit, aby určila, zda má být tato sada parametrů ignorována při volání SQLExecute nebo SQLExecDirect . Prvky v poli mohou obsahovat následující hodnoty:

  • SQL_PARAM_PROCEED: Sada parametrů je zahrnuta ve volání SQLExecute nebo SQLExecDirect .

  • SQL_PARAM_IGNORE: Sada parametrů je vyloučena z volání SQLExecute nebo SQLExecDirect .

Pokud nejsou nastaveny žádné prvky pole, všechny sady parametrů v poli se použijí ve volaních SQLExecute nebo SQLExecDirect . Pokud je hodnota v SQL_DESC_ARRAY_STATUS_PTR poli APD nulovým ukazatelem, použijí se všechny sady parametrů; interpretace je stejná, jako kdyby ukazatel ukazoval na platné pole a všechny prvky pole byly SQL_PARAM_PROCEED.

Toto pole v APD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAM_OPERATION_PTR.

SQL_DESC_BIND_OFFSET_PTR [Popisy aplikací]
Toto pole hlavičky SQLLEN * ukazuje na offset pro vázání. Výchozí je nastaven na nulový ukazatel. Pokud toto pole není nulovým ukazatelem, ovladač při načítání odpojí ukazatel a přidá dereferencovanou hodnotu ke každému z odložených polí, která mají v descriptorovém záznamu nenulovou hodnotu (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR a SQL_DESC_OCTET_LENGTH_PTR), a při načítání použije nové hodnoty ukazatele.

Vazební offset se vždy přidává přímo k hodnotám v polích SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR a SQL_DESC_OCTET_LENGTH_PTR. Pokud je offset změněn na jinou hodnotu, nová hodnota se stále přidá přímo k hodnotě v každém descriptorovém poli. Nový posun se nepřidává k hodnotě pole plus k žádnému dřívějšímu posunu.

Toto pole je odložené pole: Není použito v době nastavení, ale později ho používá ovladač, když potřebuje určit adresy datových bufferů.

Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROW_BIND_OFFSET_PTR. Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAM_BIND_OFFSET_PTR.

Pro více informací viz popis řádkového přiřazení v SQLFetchScroll a SQLBindParameter.

SQL_DESC_BIND_TYPE [Popisy aplikací]
Toto pole hlavičky SQLUINTEGER nastavuje orientaci vazby, která se použije pro vazbu buď sloupců, nebo parametrů.

V ARD toto pole určuje orientaci vazby, když je na příslušném příkazovém handle vyvolán SQLFetchScroll nebo SQLFetch .

Pro výběr sloupcového přiřazení pro sloupce je toto pole nastaveno na SQL_BIND_BY_COLUMN (výchozí).

Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROW_BIND_TYPE.

V APD toto pole specifikuje orientaci vazby, která má být použita pro dynamické parametry.

Pro výběr sloupcového přiřazení parametrů se toto pole nastaví na SQL_BIND_BY_COLUMN (výchozí).

Toto pole v APD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAM_BIND_TYPE.

SQL_DESC_COUNT [Všichni]
Toto pole hlavičky SQLSMALLINT specifikuje index založený na 1 nejvyššího čísla záznamu, který obsahuje data. Když ovladač nastaví datovou strukturu pro deskriptor, musí také nastavit pole SQL_DESC_COUNT, které ukazuje, kolik záznamů je významných. Když aplikace přidělí instanci této datové struktury, nemusí specifikovat, pro kolik záznamů má rezervovat místo. Jakmile aplikace specifikuje obsah záznamů, ovladač podnikne všechny potřebné kroky, aby zajistil, že rukojeť deskriptoru odkazuje na datovou strukturu odpovídající velikosti.

SQL_DESC_COUNT není počet všech datových sloupců, které jsou vázané (pokud je pole v ARD), ani všech parametrů, které jsou omezeny (pokud je pole v APD), ale číslo nejvyššího číslovaného záznamu. Pokud je sloupec nebo parametr s nejvyšším číslem neomezený, SQL_DESC_COUNT se změní na číslo následujícího sloupce nebo parametru s nejvyšším číslem. Pokud je sloupec nebo parametr s číslem menším než číslo sloupce s nejvyšším číslem neomezený (voláním SQLBindCol s argumentem TargetValuePtr nastaveným na nulový ukazatel, nebo SQLBindParameter s argumentem ParameterValuePtr nastaveným na nullový ukazatel), SQL_DESC_COUNT se nemění. Pokud jsou další sloupce nebo parametry vázány na čísla větší než nejvýše číslovaný záznam obsahující data, ovladač automaticky zvýší hodnotu v poli SQL_DESC_COUNT. Pokud jsou všechny sloupce volány voláním SQLFreeStmt s možností SQL_UNBIND, SQL_DESC_COUNT polí v ARD a IRD jsou nastavena na 0. Pokud je SQLFreeStmt volán s možností SQL_RESET_PARAMS, SQL_DESC_COUNT polí v APD a IPD jsou nastavena na 0.

Hodnota v SQL_DESC_COUNT může být explicitně nastavena aplikací voláním SQLSetDescField. Pokud je hodnota v SQL_DESC_COUNT explicitně snížena, všechny záznamy s čísly vyššími než nová hodnota v SQL_DESC_COUNT jsou efektivně odstraněny. Pokud je hodnota v SQL_DESC_COUNT explicitně nastavena na 0 a pole je v ARD, všechny datové buffery kromě vázaného sloupce záložek jsou uvolněny.

Záznam v tomto poli ARD nezahrnuje svázaný sloupec záložek. Jediný způsob, jak odvázat sloupec záložek, je nastavit pole SQL_DESC_DATA_PTR na nulový ukazatel.

SQL_DESC_ROWS_PROCESSED_PTR [Popisy implementace]
V IRD toto pole hlavičky SQLULEN * ukazuje na buffer obsahující počet řádků získaných po volání do SQLFetch nebo SQLFetchScroll, tedy počet řádků ovlivněných hromadnou operací provedenou voláním SQLBulkOperations nebo SQLSetPos, včetně chybových řádků.

V IPD toto pole hlavičky SQLUINTEGER * ukazuje na buffer obsahující počet zpracovaných sad parametrů, včetně chybových sad. Pokud jde o nulový ukazatel, žádné číslo se nevrátí.

SQL_DESC_ROWS_PROCESSED_PTR je platné pouze poté, co SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO bylo vráceno po volání do SQLFetch nebo SQLFetchScroll (pro IRD pole) nebo SQLExecute, SQLExecDirect nebo SQLParamData (pro IPD pole). Pokud volání, které vyplní buffer odkazující tímto polem, nevrátí SQL_SUCCESS ani SQL_SUCCESS_WITH_INFO, obsah bufferu není definován, pokud nevrátí SQL_NO_DATA, v takovém případě je hodnota v bufferu nastavena na 0.

Toto pole v ARD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_ROWS_FETCHED_PTR. Toto pole v APD lze také nastavit voláním SQLSetStmtAttr s atributem SQL_ATTR_PARAMS_PROCESSED_PTR.

Buffer, na který toto pole ukazuje, je alokován aplikací. Jedná se o odložený výstupní buffer, který nastavuje ovladač. Výchozí je nastaven na nulový ukazatel.

Pole záznamů

Každý deskriptor obsahuje jeden nebo více záznamů složených z polí, která definují buď sloupcová data, nebo dynamické parametry, v závislosti na typu popisovače. Každý záznam je kompletní definicí jednoho sloupce nebo parametru.

SQL_DESC_AUTO_UNIQUE_VALUE [IRDs]
Toto pole záznamu SQLINTEGER, které je pouze pro čtení, obsahuje SQL_TRUE, pokud je sloupec automaticky inkrementující, nebo SQL_FALSE pokud sloupec není automaticky inkrementující. Toto pole je pouze pro čtení, ale základní sloupec automaticky inkrementující nemusí být nutně pouze pro čtení.

SQL_DESC_BASE_COLUMN_NAME [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje základní název sloupce pro sloupec výsledkové množiny. Pokud základní název sloupce neexistuje (jako u sloupců, které jsou výrazy), tato proměnná obsahuje prázdný řetězec.

SQL_DESC_BASE_TABLE_NAME [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje základní název tabulky pro sloupec výsledkové množiny. Pokud nelze definovat základní název tabulky nebo není použitelný, tato proměnná obsahuje prázdný řetězec.

SQL_DESC_CASE_SENSITIVE [Popisy implementace]
Toto pole záznamu SQLINTEGER, které je pouze pro čtení, obsahuje SQL_TRUE, zda je sloupec nebo parametr považován za citlivý na velká písmena pro kolace a porovnání, nebo SQL_FALSE pokud sloupec není považován za citlivý na velká písmena pro kolace a porovnání, nebo pokud je sloupcem bez znaků.

SQL_DESC_CATALOG_NAME [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje katalog základní tabulky, která sloupec obsahuje. Návratová hodnota závisí na ovladači, pokud je sloupec výrazem nebo pokud je sloupec součástí pohledu. Pokud datový zdroj nepodporuje katalogy nebo nelze katalog určit, tato proměnná obsahuje prázdný řetězec.

SQL_DESC_CONCISE_TYPE [Všichni]
Toto pole hlavičky SQLSMALLINT specifikuje stručný datový typ pro všechny datové typy, včetně datových a intervalových datových typů.

Hodnoty v poli SQL_DESC_CONCISE_TYPE, SQL_DESC_TYPE a SQL_DESC_DATETIME_INTERVAL_CODE jsou vzájemně závislé. Pokaždé, když je jedno z polí nastaveno, musí být nastaveno i druhé. SQL_DESC_CONCISE_TYPE lze nastavit voláním do SQLBindCol , SQLBindParameter nebo SQLSetDescField. SQL_DESC_TYPE lze nastavit voláním do SQLSetDescField nebo SQLSetDescRec.

Pokud je SQL_DESC_CONCISE_TYPE nastaveno na stručný datový typ jiný než intervalový nebo datový typ datového času, pole SQL_DESC_TYPE je nastaveno na stejnou hodnotu a pole SQL_DESC_DATETIME_INTERVAL_CODE na 0.

Pokud je SQL_DESC_CONCISE_TYPE nastaveno na stručný datový typ datového času nebo intervalu, pole SQL_DESC_TYPE se nastaví na odpovídající verbose typ (SQL_DATETIME nebo SQL_INTERVAL) a pole SQL_DESC_DATETIME_INTERVAL_CODE na příslušný podkód.

SQL_DESC_DATA_PTR [Popisy aplikací a IPD]
Toto pole záznamu SQLPOINTER ukazuje na proměnnou, která bude obsahovat hodnotu parametru (pro APD) nebo sloupec (pro ARD). Toto pole je odložené pole. Není použit v době nastavení, ale později ho používá ovladač k získání dat.

Sloupec specifikovaný SQL_DESC_DATA_PTR polem ARD není omezen, pokud je argument TargetValuePtr ve volání SQLBindCol nullovým ukazatelem, nebo pokud je SQL_DESC_DATA_PTR pole v ARD nastaveno voláním SQLSetDescField nebo SQLSetDescRec na nullový ukazatel. Ostatní pole nejsou ovlivněna, pokud je SQL_DESC_DATA_PTR pole nastaveno na nulový ukazatel.

Pokud volání SQLFetch nebo SQLFetchScroll , které vyplňuje buffer odkazující tímto polem, nevrátilo SQL_SUCCESS ani SQL_SUCCESS_WITH_INFO, obsah bufferu není definován.

Kdykoli je nastaveno SQL_DESC_DATA_PTR pole APD, ARD nebo IPD, ovladač kontroluje, že hodnota v poli SQL_DESC_TYPE obsahuje jeden z platných datových typů ODBC C nebo specifický datový typ a že všechna ostatní pole ovlivňující datové typy jsou konzistentní. Vyvolání kontroly konzistence je jediným využitím SQL_DESC_DATA_PTR pole IPD. Konkrétně, pokud aplikace nastaví SQL_DESC_DATA_PTR pole IPD a později na toto pole zavolá SQLGetDescField , nemusí být vrácena hodnota, kterou měla nastavenou. Pro více informací viz "Kontroly konzistence" v SQLSetDescRec.

SQL_DESC_DATETIME_INTERVAL_CODE [Všichni]
Toto pole záznamu SQLSMALLINT obsahuje podkód pro konkrétní datový typ datového času nebo intervalu, když je pole SQL_DESC_TYPE SQL_DATETIME nebo SQL_INTERVAL. To platí jak pro SQL tak pro C datové typy. Kód se skládá z názvu datového typu, kde "CODE" je nahrazeno buď "TYPE" nebo "C_TYPE" (pro typy datového času), nebo "CODE" místo "INTERVAL" nebo "C_INTERVAL" (pro typy intervalů).

Pokud jsou SQL_DESC_TYPE a SQL_DESC_CONCISE_TYPE v aplikačním deskriptoru nastaveny na SQL_C_DEFAULT a deskriptor není přiřazen k příkazovému handle, obsah SQL_DESC_DATETIME_INTERVAL_CODE není definován.

Toto pole lze nastavit pro datové typy datetime uvedené v následující tabulce.

Typy datového času DATETIME_INTERVAL_CODE
SQL_TYPE_DATE/SQL_C_TYPE_DATE SQL_CODE_DATE
SQL_TYPE_TIME/SQL_C_TYPE_TIME SQL_CODE_TIME
SQL_TYPE_TIMESTAMP/ SQL_C_TYPE_TIMESTAMP SQL_CODE_TIMESTAMP

Toto pole lze nastavit pro intervalové datové typy uvedené v následující tabulce.

Typ intervalu DATETIME_INTERVAL_CODE
SQL_INTERVAL_DAY/ SQL_C_INTERVAL_DAY SQL_CODE_DAY
SQL_INTERVAL_DAY_TO_HOUR/ SQL_C_INTERVAL_DAY_TO_HOUR SQL_CODE_DAY_TO_HOUR
SQL_INTERVAL_DAY_TO_MINUTE/ SQL_C_INTERVAL_DAY_TO_MINUTE SQL_CODE_DAY_TO_MINUTE
SQL_INTERVAL_DAY_TO_SECOND/ SQL_C_INTERVAL_DAY_TO_SECOND SQL_CODE_DAY_TO_SECOND
SQL_INTERVAL_HOUR/ SQL_C_INTERVAL_HOUR SQL_CODE_HOUR
SQL_INTERVAL_HOUR_TO_MINUTE/ SQL_C_INTERVAL_HOUR_TO_MINUTE SQL_CODE_HOUR_TO_MINUTE
SQL_INTERVAL_HOUR_TO_SECOND/ SQL_C_INTERVAL_HOUR_TO_SECOND SQL_CODE_HOUR_TO_SECOND
SQL_INTERVAL_MINUTE/ SQL_C_INTERVAL_MINUTE SQL_CODE_MINUTE
SQL_INTERVAL_MINUTE_TO_SECOND/ SQL_C_INTERVAL_MINUTE_TO_SECOND SQL_CODE_MINUTE_TO_SECOND
SQL_INTERVAL_MONTH/ SQL_C_INTERVAL_MONTH SQL_CODE_MONTH
SQL_INTERVAL_SECOND/ SQL_C_INTERVAL_SECOND SQL_CODE_SECOND
SQL_INTERVAL_YEAR/ SQL_C_INTERVAL_YEAR SQL_CODE_YEAR
SQL_INTERVAL_YEAR_TO_MONTH/ SQL_C_INTERVAL_YEAR_TO_MONTH SQL_CODE_YEAR_TO_MONTH

Pro více informací o datových intervalech a tomto poli viz Identifikátory datových typů a popisovače.

SQL_DESC_DATETIME_INTERVAL_PRECISION [Všichni]
Toto pole záznamu SQLINTEGER obsahuje přesnost vedoucí intervalu, pokud je pole SQL_DESC_TYPE SQL_INTERVAL. Když je pole SQL_DESC_DATETIME_INTERVAL_CODE nastaveno na intervalový datový typ, toto pole je nastaveno na výchozí intervalovou přesnost vedoucí.

SQL_DESC_DISPLAY_SIZE [IRDs]
Toto pole záznamu SQLINTEGER, které je pouze pro čtení, obsahuje maximální počet znaků potřebných k zobrazení dat z tohoto sloupce.

SQL_DESC_FIXED_PREC_SCALE [Popisy implementace]
Toto pole záznamu SQLSMALLINT pouze pro čtení je nastaveno na SQL_TRUE, pokud je sloupec přesný číselný sloupec a má pevnou přesnost a nenulovou škálu, nebo na SQL_FALSE, pokud sloupec není přesný číselný sloupec s pevnou přesností a měřítkem.

SQL_DESC_INDICATOR_PTR [Popisy aplikací]
V ARD toto pole záznamu SQLLEN * ukazuje na indikátorovou proměnnou. Tato proměnná obsahuje SQL_NULL_DATA pokud je sloupcová hodnota NULL. Pro APD je indikátorová proměnná nastavena na SQL_NULL_DATA pro specifikaci dynamických argumentů NULL. Jinak je proměnná nulová (pokud hodnoty v SQL_DESC_INDICATOR_PTR a SQL_DESC_OCTET_LENGTH_PTR nejsou stejné ukazatelem).

Pokud je pole SQL_DESC_INDICATOR_PTR v ARD nulovým ukazatelem, ovladač nemůže vrátit informaci, zda je sloupec nulový nebo ne. Pokud je sloupec NULL a SQL_DESC_INDICATOR_PTR null, vrátí se SQLSTATE 22002 (indikátorová proměnná požadovaná, ale neposkytnutá) při pokusu ovladače o naplnění bufferu po volání SQLFetch nebo SQLFetchScroll. Pokud volání na SQLFetch nebo SQLFetchScroll nevrátilo SQL_SUCCESS nebo SQL_SUCCESS_WITH_INFO, obsah bufferu není definován.

Pole SQL_DESC_INDICATOR_PTR určuje, zda je pole označené SQL_DESC_OCTET_LENGTH_PTR nastaveno. Pokud je hodnota dat pro sloupec NULL, ovladač nastaví indikátorovou proměnnou na SQL_NULL_DATA. Pole na SQL_DESC_OCTET_LENGTH_PTR pak není pevně nastaveno. Pokud během načítání není nalezena hodnota NULL, buffer na který ukazuje SQL_DESC_INDICATOR_PTR je nastaven na nulu a buffer na SQL_DESC_OCTET_LENGTH_PTR je nastaven na délku dat.

Pokud je pole SQL_DESC_INDICATOR_PTR v APD nullovým ukazatelem, aplikace nemůže použít tento descriptorový záznam k určení NULL argumentů.

Toto pole je odložené pole: Nepoužívá se v okamžiku nastavení, ale ovladač jej později použije k indikaci neplatnosti (pro ARD) nebo k určení neplatnosti (pro APD).

SQL_DESC_LABEL [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje štítek sloupce nebo název. Pokud sloupec nemá štítek, tato proměnná obsahuje název sloupce. Pokud je sloupec bezejmenný a neoznačený, tato proměnná obsahuje prázdný řetězec.

SQL_DESC_LENGTH [Všichni]
Toto pole záznamu SQLULEN je buď maximální nebo skutečná délka řetězce znaků v znacích, nebo binárního datového typu v bajtech. Je to maximální délka pro datový typ s pevnou délkou, nebo skutečná délka pro datový typ s proměnnou délkou. Jeho hodnota vždy vylučuje znak nulového ukončení, který končí řetězec znaků. Pro hodnoty, jejichž typ je SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP nebo některý z datových typů SQL intervalů, má toto pole délku znaků reprezentace řetězce znaků jako hodnota datetime nebo intervalu.

Hodnota v tomto poli se může lišit od hodnoty "délka" definované v ODBC 2*.x*. Pro více informací viz Příloha D: Typy dat.

SQL_DESC_LITERAL_PREFIX [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje znak nebo znaky, které ovladač rozpozná jako prefix pro literál tohoto datového typu. Tato proměnná obsahuje prázdný řetězec pro datový typ, pro který není použitelný literální prefix.

SQL_DESC_LITERAL_SUFFIX [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje znak nebo znaky, které ovladač rozpozná jako příponu pro literál tohoto datového typu. Tato proměnná obsahuje prázdný řetězec pro datový typ, pro který literální přípona není použitelná.

SQL_DESC_LOCAL_TYPE_NAME [Popisy implementace]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje jakýkoli lokalizovaný (v rodném jazyce) název datového typu, který se může lišit od běžného názvu datového typu. Pokud neexistuje lokalizovaný název, vrátí se prázdný řetězec. Toto pole slouží pouze k zobrazení.

SQL_DESC_NAME [Popisy implementace]
Toto pole záznamu SQLCHAR* v řádku obsahuje alias sloupce, pokud se na něj vztahuje. Pokud alias sloupce neplatí, je vrácen název sloupce. V obou případech řidič nastaví SQL_DESC_UNNAMED pole na SQL_NAMED při nastavení SQL_DESC_NAME pole. Pokud není uveden název sloupce ani alias sloupce, ovladač vrátí prázdný řetězec do pole SQL_DESC_NAME a nastaví pole SQL_DESC_UNNAMED na SQL_UNNAMED.

Aplikace může nastavit SQL_DESC_NAME pole IPD na název parametru nebo alias, aby specifikovala parametry uložených procedur podle jména. (Pro více informací viz Binding Parameters by Name (Named Parameters).) SQL_DESC_NAME pole IRD je pole pouze pro čtení; SQLSTATE HY091 (Neplatný identifikátor pole descriptor) se vrátí, pokud se aplikace pokusí jej nastavit.

V IPD je toto pole nedefinované, pokud ovladač nepodporuje pojmenované parametry. Pokud ovladač podporuje pojmenované parametry a je schopen je je popsat parametry, v tomto poli se vrací název parametru.

SQL_DESC_NULLABLE [Popisy implementace]
V IRD je toto pole záznamu SQLSMALLINT určeno pouze pro čtení SQL_NULLABLE, pokud sloupec může mít hodnoty NULL, SQL_NO_NULLS pokud sloupec nemá hodnoty NULL, nebo SQL_NULLABLE_UNKNOWN pokud není známo, zda sloupec přijímá hodnoty NULL. Toto pole se týká sloupce výsledkové množiny, nikoli základního sloupce.

V IPD je toto pole vždy nastaveno na SQL_NULLABLE, protože dynamické parametry jsou vždy nulovatelné a nelze je nastavit aplikací.

SQL_DESC_NUM_PREC_RADIX [Všichni]
Toto pole SQLINTEGER obsahuje hodnotu 2, pokud je datový typ v poli SQL_DESC_TYPE přibližný číselný datový typ, protože pole SQL_DESC_PRECISION obsahuje počet bitů. Toto pole obsahuje hodnotu 10, pokud je datový typ v poli SQL_DESC_TYPE přesný číselný datový typ, protože pole SQL_DESC_PRECISION obsahuje počet desetinných číslic. Toto pole je nastaveno na 0 pro všechny nenumerické datové typy.

SQL_DESC_OCTET_LENGTH [Všichni]
Toto pole záznamu SQLLEN obsahuje délku znakového řetězce nebo binárního datového typu v bajtech. Pro znaky s pevnou délkou nebo binární typy je to skutečná délka v bajtech. Pro proměnné délky znaků nebo binární typy je to maximální délka v bajtech. Tato hodnota vždy vylučuje místo pro znak null-termination pro implementační deskriptory a vždy zahrnuje místo pro znak null-termination pro aplikační deskriptory. Pro aplikační data toto pole obsahuje velikost bufferu. Pro APD je toto pole definováno pouze pro výstupní nebo vstupní/výstupní parametry.

SQL_DESC_OCTET_LENGTH_PTR [Popisy aplikací]
Toto pole SQLLEN * odkazuje na proměnnou, která bude obsahovat celkovou délku dynamického argumentu (pro parametrické deskriptory) nebo hodnotu bound column (pro řádkové deskriptory).

Pro APD je tato hodnota ignorována pro všechny argumenty kromě znakového řetězce a binárního souboru; pokud toto pole ukazuje na SQL_NTS, musí být dynamický argument ukončen null. Aby aplikace označila, že parametr bound bude parametrem data při vykonání, nastaví toto pole v příslušném záznamu APD na proměnnou, která při spuštění obsahuje hodnotu SQL_DATA_AT_EXEC nebo výsledek makra SQL_LEN_DATA_AT_EXEC. Pokud existuje více takových polí, lze SQL_DESC_DATA_PTR nastavit na hodnotu, která parametr jednoznačně identifikuje, aby aplikace pomohla určit, o který parametr se žádá.

Pokud je OCTET_LENGTH_PTR pole ARD nulovým ukazatelem, ovladač nevrátí informace o délce sloupce. Pokud je SQL_DESC_OCTET_LENGTH_PTR pole APD nulovým ukazatelem, ovladač předpokládá, že řetězce znaků a binární hodnoty jsou nulově ukončené. (Binární hodnoty by neměly být nulově ukončené, ale měly by mít délku, aby se předešlo ořezání.)

Pokud volání SQLFetch nebo SQLFetchScroll , které vyplňuje buffer odkazující tímto polem, nevrátilo SQL_SUCCESS ani SQL_SUCCESS_WITH_INFO, obsah bufferu není definován. Toto pole je odložené pole. Nepoužívá se v době nastavení, ale později ovladačem určuje nebo indikuje délku oktetových dat.

SQL_DESC_PARAMETER_TYPE [IPD]
Toto pole záznamu SQLSMALLINT je nastaveno tak, aby SQL_PARAM_INPUT pro vstupní parametr, SQL_PARAM_INPUT_OUTPUT pro vstupní/výstupní parametr, SQL_PARAM_OUTPUT pro výstupní parametr, SQL_PARAM_INPUT_OUTPUT_STREAM pro vstupně/výstupní streamovaný parametr nebo SQL_PARAM_OUTPUT_STREAM pro výstupní streamovaný parametr. Ve výchozím nastavení je nastaveno SQL_PARAM_INPUT.

Pro IPD je pole nastaveno na SQL_PARAM_INPUT ve výchozím nastavení, pokud IPD není automaticky vyplněno ovladačem (atribut SQL_ATTR_ENABLE_AUTO_IPD příkazu je SQL_FALSE). Aplikace by měla toto pole nastavit v IPD pro parametry, které nejsou vstupními parametry.

SQL_DESC_PRECISION [Všichni]
Toto pole záznamu SQLSMALLINT obsahuje počet číslic pro přesný číselný typ, počet bitů v mantise (binární přesnost) pro přibližný číselný typ nebo počet číslic v komponentě zlomkových sekund pro datový typ SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP nebo SQL_INTERVAL_SECOND. Toto pole není definováno pro všechny ostatní datové typy.

Hodnota v tomto poli se může lišit od hodnoty pro "přesnost" definovanou v ODBC 2*.x*. Pro více informací viz Příloha D: Typy dat.

SQL_DESC_ROWVER [Popisy implementace]
Toto pole SQLSMALLINTrecord ukazuje, zda je sloupec automaticky upraven DBMS při aktualizaci řádku (například sloupec typu "timestamp" v SQL Server). Hodnota tohoto pole záznamu je nastavena na SQL_TRUE, pokud je sloupec sloupec pro verzování řádku, a na SQL_FALSE jinak. Tento atribut sloupce je podobný volání SQLSpecialColumns s identifikátorem SQL_ROWVER pro určení, zda se sloupec automaticky aktualizuje.

SQL_DESC_SCALE [Všichni]
Toto pole záznamu SQLSMALLINT obsahuje definovanou škálu pro desetinné a číselné datové typy. Pole není definováno pro všechny ostatní datové typy.

Hodnota v tomto poli se může lišit od hodnoty pro "scale" definované v ODBC 2*.x*. Pro více informací viz Příloha D: Typy dat.

SQL_DESC_SCHEMA_NAME [IRD]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje název schématu základní tabulky, která sloupec obsahuje. Návratová hodnota závisí na ovladači, pokud je sloupec výrazem nebo pokud je sloupec součástí pohledu. Pokud datový zdroj schémata nepodporuje nebo nelze určit název schématu, tato proměnná obsahuje prázdný řetězec.

SQL_DESC_SEARCHABLE [IRDs]
Toto pole záznamu SQLSMALLINT, které je pouze pro čtení, je nastaveno na jednu z následujících hodnot:

  • SQL_PRED_NONE pokud sloupec nelze použít v klauzuli WHERE . (To je stejné jako hodnota SQL_UNSEARCHABLE v ODBC 2*.x*.)

  • SQL_PRED_CHAR pokud může být sloupec použit v klauzuli WHERE , ale pouze s predikátem LIKE . (To je stejné jako hodnota SQL_LIKE_ONLY v ODBC 2*.x*.)

  • SQL_PRED_BASIC pokud může být sloupec použit v klauzuli WHERE se všemi operátory srovnání kromě LIKE. (To je stejné jako SQL_EXCEPT_LIKE hodnota v ODBC 2*.x*.)

  • SQL_PRED_SEARCHABLE pokud může být sloupec použit v klauzuli WHERE s libovolným operátorem porovnání.

SQL_DESC_TABLE_NAME [IRDs]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje název základní tabulky, která tento sloupec obsahuje. Návratová hodnota závisí na ovladači, pokud je sloupec výrazem nebo pokud je sloupec součástí pohledu.

SQL_DESC_TYPE [Všichni]
Toto pole záznamu SQLSMALLINT specifikuje stručný typ dat SQL nebo C pro všechny datové typy kromě datových typů datetime a interval. Pro datové typy datetime a interval toto pole určuje verbose datový typ, který je SQL_DATETIME nebo SQL_INTERVAL.

Kdykoli toto pole obsahuje SQL_DATETIME nebo SQL_INTERVAL, musí pole SQL_DESC_DATETIME_INTERVAL_CODE obsahovat příslušný podkód pro typ stručné kategorie. Pro datové typy s datetime obsahuje SQL_DESC_TYPE SQL_DATETIME a pole SQL_DESC_DATETIME_INTERVAL_CODE obsahuje podkód pro konkrétní datový typ datetime. Pro intervalové datové typy obsahuje SQL_DESC_TYPE SQL_INTERVAL a pole SQL_DESC_DATETIME_INTERVAL_CODE obsahuje podkód pro konkrétní intervalový datový typ.

Hodnoty v poli SQL_DESC_TYPE a SQL_DESC_CONCISE_TYPE jsou vzájemně závislé. Pokaždé, když je jedno z polí nastaveno, musí být nastaveno i druhé. SQL_DESC_TYPE lze nastavit voláním do SQLSetDescField nebo SQLSetDescRec. SQL_DESC_CONCISE_TYPE lze nastavit voláním do SQLBindCol , SQLBindParameter nebo SQLSetDescField.

Pokud je SQL_DESC_TYPE nastaveno na stručný datový typ jiný než intervalový nebo datový datový typ, pole SQL_DESC_CONCISE_TYPE je nastaveno na stejnou hodnotu a pole SQL_DESC_DATETIME_INTERVAL_CODE na 0.

Pokud je SQL_DESC_TYPE nastaveno na verbose datetime nebo interval datového typu (SQL_DATETIME nebo SQL_INTERVAL) a pole SQL_DESC_DATETIME_INTERVAL_CODE je nastaveno na odpovídající podkód, pole SQL_DESC_CONCISE TYPE je nastaveno na odpovídající typ stručnosti. Pokud se pokusíte nastavit SQL_DESC_TYPE na jeden z konkrétních typů datetime nebo interval, vrátí se SQLSTATE HY021 (Inconsistent descriptor information).

Když je pole SQL_DESC_TYPE nastaveno voláním do SQLBindCol, SQLBindParameter nebo SQLSetDescField, následující pole jsou nastavena na výchozí hodnoty, jak je znázorněno v tabulce níže. Hodnoty zbývajících polí stejného záznamu nejsou definovány.

Hodnota SQL_DESC_TYPE Ostatní pole implicitně nastavená
SQL_CHAR, SQL_VARCHAR, SQL_C_CHAR, SQL_C_VARCHAR SQL_DESC_LENGTH je nastaveno na 1. SQL_DESC_PRECISION je nastaveno na 0.
SQL_DATETIME Když je SQL_DESC_DATETIME_INTERVAL_CODE nastaveno na SQL_CODE_DATE nebo SQL_CODE_TIME, SQL_DESC_PRECISION je nastaveno na 0. Když je nastavena na SQL_DESC_TIMESTAMP, SQL_DESC_PRECISION je nastavena na 6.
SQL_DECIMAL, SQL_NUMERIC, SQL_C_NUMERIC SQL_DESC_SCALE je nastaveno na 0. SQL_DESC_PRECISION je nastaveno na implementační přesnost pro daný datový typ.

Viz SQL to C: Numeric pro informace o tom, jak ručně navázat hodnotu SQL_C_NUMERIC.
SQL_FLOAT, SQL_C_FLOAT SQL_DESC_PRECISION je nastavena na implementací definovanou výchozí přesnost pro SQL_FLOAT.
SQL_INTERVAL Když je SQL_DESC_DATETIME_INTERVAL_CODE nastaveno na intervalový datový typ, SQL_DESC_DATETIME_INTERVAL_PRECISION je nastaveno na 2 (výchozí interval vedoucí přesností). Když má interval sekundovou složku, SQL_DESC_PRECISION je nastavena na 6 (výchozí přesnost intervalových sekund).

Když aplikace volá SQLSetDescField k nastavení polí deskriptoru místo volání SQLSetDescRec, musí nejprve deklarovat datový typ. Když se tak stane, ostatní pole uvedená v předchozí tabulce jsou implicitně nastavena. Pokud je některá z implicitně nastavených hodnot nepřijatelná, aplikace může pak zavolat SQLSetDescField nebo SQLSetDescRec a explicitně nastavit nepřijatelnou hodnotu.

SQL_DESC_TYPE_NAME [Popisy implementace]
Toto pole záznamu SQLCHAR * pouze pro čtení obsahuje název typu závislý na zdroji dat (například "CHAR", "VARCHAR" a podobně). Pokud je název datového typu neznámý, tato proměnná obsahuje prázdný řetězec.

SQL_DESC_UNNAMED [Popisy implementace]
Toto pole záznamu SQLSMALLINT v řádku nastavuje ovladač buď na SQL_NAMED, nebo SQL_UNNAMED při nastavení pole SQL_DESC_NAME. Pokud pole SQL_DESC_NAME obsahuje alias sloupce nebo pokud se alias sloupce neuplatňuje, ovladač nastaví pole SQL_DESC_UNNAMED na SQL_NAMED. Pokud aplikace nastaví SQL_DESC_NAME pole IPD na název parametru nebo alias, ovladač nastaví SQL_DESC_UNNAMED pole IPD na SQL_NAMED. Pokud není uveden název sloupce ani alias sloupce, ovladač nastaví pole SQL_DESC_UNNAMED na SQL_UNNAMED.

Aplikace může nastavit SQL_DESC_UNNAMED pole IPD na SQL_UNNAMED. Ovladač vrací SQLSTATE HY091 (identifikátor pole Invalid descriptor), pokud se aplikace pokusí nastavit pole SQL_DESC_UNNAMED IPD na SQL_NAMED. SQL_DESC_UNNAMED pole IRD je pouze pro čtení; SQLSTATE HY091 (Neplatný identifikátor pole descriptor) se vrátí, pokud se aplikace pokusí jej nastavit.

SQL_DESC_UNSIGNED [Popisy implementace]
Toto pole záznamu SQLSMALLINT pouze pro čtení je nastaveno na SQL_TRUE, pokud je typ sloupce bez znaménka nebo nečíselný, nebo SQL_FALSE, pokud je typ sloupce podepsán.

SQL_DESC_UPDATABLE [IRD]
Toto pole záznamu SQLSMALLINT, které je pouze pro čtení, je nastaveno na jednu z následujících hodnot:

  • SQL_ATTR_READ_ONLY, pokud je sloupec výsledkové množiny pouze pro čtení.

  • SQL_ATTR_WRITE pokud je sloupec výsledkové množiny čtení-zápis.

  • SQL_ATTR_READWRITE_UNKNOWN pokud není známo, zda je sloupec výsledků aktualizovatelný či nikoliv.

SQL_DESC_UPDATABLE popisuje aktualizovatelnost sloupce ve výsledné množině, nikoli sloupce v základní tabulce. Aktualizabilnost sloupce v základní tabulce, na které je sloupec založen na této výsledné množině, může být odlišná od hodnoty v tomto poli. To, zda je sloupec aktualizovatelný, může záviset na datovém typu, uživatelských oprávněních a samotné definici výsledné množiny. Pokud není jasné, zda je sloupec aktualizovatelný, měl by SQL_ATTR_READWRITE_UNKNOWN vrátit.

Kontroly konzistence

Kontrola konzistence je automaticky provedena ovladačem pokaždé, když aplikace zadá hodnotu pro pole SQL_DESC_DATA_PTR v ARD, APD nebo IPD. Pokud je některé z polí nekonzistentní s jinými poli, SQLSetDescField vrátí SQLSTATE HY021 (Inconsistent descriptor information). Pro více informací viz "Kontrola konzistence" v SQLSetDescRec.

Informace o Podívejte se
Vázání sloupce SQLBindCol – funkce
Vazba parametru Funkce SQLBindParameter
Získání popisného pole SQLGetDescField Function
Získání více deskriptorových polí SQLGetDescRec Function
Nastavení více deskriptorových polí SQLSetDescRec Function

Viz také

Soubory hlaviček ODBC
Referenční rozhraní ODBC API

  • Last updated on