Funkce SQLSetStmtAttr

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

Shrnutí
SQLSetStmtAttr nastavuje atributy související s příkazem.

Syntax

  
SQLRETURN SQLSetStmtAttr(  
     SQLHSTMT      StatementHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);  

Arguments

StatementHandle
[Vstup] Popisovač příkazu

Atribut
[Vstup] Možnost nastavit, uvedená v "Komentářích."

ValuePtr
[Vstup] Hodnota je spojena s atributem. V závislosti na hodnotě atributubude hodnota Ptr jednou z následujících:

• Název s popisem ODBC.

• Hodnota SQLUINTEGER.

• Hodnota SQLULEN.

• Ukazatel na jednu z následujících oblastí:

  • Znakový řetězec s nulovým ukončením.

  • Binární buffer.

  • Hodnota nebo pole typu SQLLEN, SQLULEN nebo SQLUSMALLINT.

  • Hodnota definovaná ovladačem.

Pokud je argument Attribute hodnotou specifickou pro ovladač, může být ValuePtr podepsané celé číslo.

StringLength
[Vstup] Pokud je Attribute atribut definovaný ODBC a ValuePtr ukazuje na znakový řetězec nebo binární buffer, měl by být tento argument délka *ValuePtr. Pokud je Attribute atribut definovaný ODBC a ValuePtr je celé číslo, StringLength se ignoruje .

Pokud je Attribute atribut definovaný ovladačem, aplikace určuje povahu atributu Driver Manageru nastavením argumentu StringLength . StringLength může mít následující hodnoty:

• Pokud je ValuePtr ukazatelem na řetězec znaků, pak StringLength 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 StringLength. To umisťuje zápornou hodnotu v StringLength.

• Pokud je ValuePtr ukazatelem na hodnotu jinou než řetězec znaků nebo binární řetězec, pak by StringLength měla mít hodnotu SQL_IS_POINTER.

• Pokud ValuePtr obsahuje hodnotu pevné délky, pak je StringLength buď SQL_IS_INTEGER, nebo SQL_IS_UINTEGER, jak je vhodné.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostics

Když SQLSetStmtAttr vrátí 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é SQLSetStmtAttr 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.

Comments

Atributy příkazů pro příkaz zůstávají v platnosti, dokud nejsou změněny jiným voláním do SQLSetStmtAttr nebo dokud příkaz není vyřazen voláním SQLFreeHandle. Volání SQLFreeStmt pomocí SQL_CLOSE, SQL_UNBIND nebo SQL_RESET_PARAMS možnosti neresetuje atributy příkazů.

Některé atributy příkazů podporují substituci podobné hodnoty, pokud zdroj dat nepodporuje hodnotu zadanou v ValuePtr. V takových případech ovladač vrací SQL_SUCCESS_WITH_INFO a SQLSTATE 01S02 (změna hodnoty volitele). Například pokud je Attribute SQL_ATTR_CONCURRENCY a ValuePtr SQL_CONCUR_ROWVER, a pokud zdroj dat to nepodporuje, ovladač SQL_CONCUR_VALUES nahradí a vrátí SQL_SUCCESS_WITH_INFO. Pro určení substituované hodnoty aplikace volá SQLGetStmtAttr.

Formát informační množiny s ValuePtr závisí na specifikovaném atributu. SQLSetStmtAttr přijímá informace o atributech ve dvou různých formátech: jako znakový řetězec nebo celočíselnou hodnotu. Formát každého je uveden v popisu atributu. Tento formát se vztahuje na informace vrácené pro každý atribut v SQLGetStmtAttr. Znakové řetězce označené argumentem ValuePtr v SQLSetStmtAttr mají délku StringLength.

Atributy příkazů, které nastavují deskriptorová pole

Mnoho atributů příkazů odpovídá hlavičkovému poli deskriptoru. Nastavení těchto atributů ve skutečnosti vede k nastavení popisových polí. Nastavení polí voláním SQLSetStmtAttr místo SQLSetDescField má tu výhodu, že pro volání funkce není nutné získat handle deskriptoru.

Když je descriptorové pole nastaveno v důsledku nastavení odpovídajícího atributu příkazu, pole je nastaveno pouze pro příslušné deskriptory, které jsou aktuálně spojeny s tvrzením identifikovaným argumentem StatementHandle , a nastavení atributu neovlivňuje žádné deskriptory, které by mohly být s tímto tvrzením v budoucnu spojeny. Když je deskriptorové pole, které je zároveň atributem příkazu, nastaveno voláním SQLSetDescField, je nastaven odpovídající atribut příkazu. Pokud je explicitně přidělený deskriptor oddělen od příkazu, atribut příkazu odpovídající hlavičkovému poli se vrátí na hodnotu pole v implicitně alokovaném deskriptoru.

Když je příkaz alokován (viz SQLAllocHandle), čtyři popisovací handle jsou automaticky alokovány a přiřazeny k příkazu. Explicitně přidělené descriptorové handle lze s příkazem přiřadit vyvolání SQLAllocHandle pomocí fHandleType SQL_HANDLE_DESC pro přiřazení descriptorového handle a následným zavoláním SQLSetStmtAttr pro přiřazení descriptoru k příkazu.

Atributy příkazů v následující tabulce odpovídají polím hlaviček deskriptoru.

Atributy prohlášení

Aktuálně definované atributy a verze ODBC, ve které byly zavedeny, jsou uvedeny v následující tabulce; Očekává se, že ovladače budou definovány dalšími atributy, aby využily různé zdroje dat. ODBC vyrezervuje řadu atributů; vývojáři ovladačů si musí vyhradit hodnoty pro své vlastní použití specifické pro ovladače od Open Group. Další informace naleznete v tématu Driver-Specific datové typy, popisovače, typy informací, typy diagnostiky a atributy.

[1] Tyto funkce lze volat asynchronně pouze tehdy, pokud je deskriptor implementační, nikoli aplikační.

Viz Column-Wise Binding a Row-Wise Binding.

Související funkce

Viz také

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