SQLSetConnectAttr-funktion

Överensstämmelse
Version introducerad: ODBC 3.0 Standardsefterlevnad: ISO 92

Summary
SQLSetConnectAttr sätter attribut som styr aspekter av anslutningar.

Syntax

  
SQLRETURN SQLSetConnectAttr(  
     SQLHDBC       ConnectionHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);  

Arguments

ConnectionHandle
Indata: Anslutningshandtag.

Attribut
[Input] Attribut till set, listat i "Kommentarer."

ValuePtr
[Input] Peka på värdet som ska kopplas till Attribute. Beroende på värdet av Attribute kommer ValuePtr att vara ett osignerat heltalsvärde eller peka på en null-terminerad teckensträng. Observera att integraltypen av attributargumentet kanske inte har fast längd, se avsnittet Kommentarer för detaljer.

StringLength
[Input] Om Attribute är ett ODBC-definierat attribut och ValuePtr pekar på en teckensträng eller en binär buffert, bör detta argument vara längden på *ValuePtr. För teckensträngsdata bör detta argument innehålla antalet byte i strängen.

Om Attribut är ett ODBC-definierat attribut och ValuePtr är ett heltal, ignoreras StringLength .

Om Attribut är ett drivrutinsdefinierat attribut anger applikationen attributets natur till Driver Manager genom att sätta argumentet StringLength . StringLength kan ha följande värden:

• Om ValuePtr är en pekare till en teckensträng, så är StringLength längden på strängen eller SQL_NTS.

• Om ValuePtr är en pekare till en binär buffert, placerar applikationen resultatet av makrot SQL_LEN_BINARY_ATTR(längd) i StringLength. Detta placerar ett negativt värde i StringLength.

• Om ValuePtr är en pekare till ett annat värde än en teckensträng eller en binär sträng, så bör StringLength ha värdet SQL_IS_POINTER.

• Om ValuePtr innehåller ett fast längdvärde, är StringLength antingen SQL_IS_INTEGER eller SQL_IS_UINTEGER, beroende på vad som är lämpligt.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE eller SQL_STILL_EXECUTING.

Diagnostics

När SQLSetConnectAttr returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_DBC och ett Handle av ConnectionHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLSetConnectAttr och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Föraren kan återvända SQL_SUCCESS_WITH_INFO för att lämna information om resultatet av att sätta ett alternativ.

När Attribute är ett statement-attribut kan SQLSetConnectAttr returnera alla SQLSTATEs som returneras av SQLSetStmtAttr.

Comments

För allmän information om anslutningsattribut, se Anslutningsattribut.

De för närvarande definierade attributen och den version av ODBC där de introducerades visas i tabellen senare i detta avsnitt; Det förväntas att fler attribut kommer att definieras för att dra nytta av olika datakällor. Ett intervall av attribut reserveras av ODBC; drivrutinsutvecklare måste reservera värden för sin egen drivrutinsspecifika användning från Open Group.

En applikation kan anropa SQLSetConnectAttr när som helst mellan det att anslutningen tilldelas och frigörs. Alla anslutnings- och satsattribut som applikationen framgångsrikt sätter för anslutningen kvarstår tills SQLFreeHandle anropas på anslutningen. Till exempel, om en applikation anropar SQLSetConnectAttr innan den ansluter till en datakälla, kvarstår attributet även om SQLSetConnectAttr misslyckas i drivrutinen när applikationen ansluter till datakällan; Om en applikation sätter ett drivrutinsspecifikt attribut kvarstår attributet även om applikationen ansluter till en annan drivrutin på anslutningen.

Vissa anslutningsattribut kan endast sättas innan en koppling har gjorts; andra kan bara ställas in efter att en koppling har gjorts. Följande tabell visar de anslutningsattribut som måste sättas antingen före eller efter att en anslutning har gjorts. Antingen indikerar att attributet kan sättas antingen före eller efter anslutning.

[1] SQL_ATTR_ACCESS_MODE och SQL_ATTR_CURRENT_CATALOG kan ställas in före eller efter anslutning, beroende på drivrutinen. Men kompatibla program ställer in dem innan du ansluter eftersom vissa drivrutiner inte har stöd för att ändra dessa efter anslutning.

[2] SQL_ATTR_ASYNC_ENABLE måste sättas innan det finns ett aktivt uttalande.

[3] SQL_ATTR_TXN_ISOLATION kan endast ställas in om det inte finns några öppna transaktioner på anslutningen. Vissa anslutningsattribut stödjer substitution av ett liknande värde om datakällan inte stöder värdet specificerat i *ValuePtr. I sådana fall returnerar drivrutinen SQL_SUCCESS_WITH_INFO och SQLSTATE 01S02 (Optionsvärdet ändrats). Till exempel, om Attribute är SQL_ATTR_PACKET_SIZE och *ValuePtr överstiger den maximala paketstorleken, ersätter drivrutinen den maximala storleken. För att bestämma det substituerade värdet anropar en applikation SQLGetConnectAttr.

[4] Om SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE sätts innan en anslutning är öppen, kommer Driver Manager att sätta drivrutinens attribut när drivrutinen laddas under ett anrop till SQLBrowseConnect, SQLConnect eller SQLDriverConnect. Innan ett anrop till SQLBrowseConnect, SQLConnect eller SQLDriverConnect vet inte Driver Manager vilken drivrutin som ska ansluta till och vet inte om drivrutinen stödjer asynkrona anslutningsoperationer. Därför returnerar Driver Manager alltid SQL_SUCCESS. Men om drivrutinen inte stödjer asynkrona anslutningsoperationer kommer anropet till SQLBrowseConnect, SQLConnect eller SQLDriverConnect att misslyckas.

[5] När SQL_ATTR_AUTOCOMMIT är satt till FALSK bör applikationer anropa SQLEndTran(SQL_ROLLBACK) om något API returnerar SQL_ERROR för att säkerställa transaktionell konsistens.

Formatet på informationen som sätts i *ValuePtr-bufferten beror på det specificerade attributet. SQLSetConnectAttr accepterar attributinformation i ett av två olika format: en nullterminerad teckensträng eller ett heltalsvärde. Formatet för varje anges i attributets beskrivning. Teckensträngar som pekas på av ValuePtr-argumentet i SQLSetConnectAttr har en längd på StringLength-bytes .

StringLength-argumentet ignoreras om längden definieras av attributet, vilket är fallet för alla attribut som introduceras i ODBC 2*.x* eller tidigare.

[1] Dessa funktioner kan anropas asynkront endast om deskriptorn är en implementationsdeskriptor, inte en applikationsdeskriptor.

Kodexempel

Se SQLConnect.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler