SQLAllocHandle-funktion

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

Summary
SQLAllocHandle tilldelar en miljö, anslutning, sats eller deskriptorhandtag.

Syntax

  
SQLRETURN SQLAllocHandle(  
      SQLSMALLINT   HandleType,  
      SQLHANDLE     InputHandle,  
      SQLHANDLE *   OutputHandlePtr);  

Arguments

HandleType
[Input] Typen av handtag som ska tilldelas av SQLAllocHandle. Måste vara något av följande värden:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handtag används endast av Drivrutinshanteraren och drivrutinen. Program bör inte använda den här referenstypen. För mer information om SQL_HANDLE_DBC_INFO_TOKEN, se Utveckling av Connection-Pool medvetenhet i en ODBC-drivrutin.

InputHandle
[Input] Det indatahandtag i vars kontext det nya handtaget ska allokeras. Om HandleType är SQL_HANDLE_ENV är detta SQL_NULL_HANDLE. Om HandleType är SQL_HANDLE_DBC måste detta vara ett miljöhandtag, och om det är SQL_HANDLE_STMT eller SQL_HANDLE_DESC måste det vara ett anslutningshandtag.

OutputHandlePtr
[Utdata] Peka på en buffert där man ska returnera handtaget till den nyallokerade datastrukturen.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE eller SQL_ERROR.

När man allokerar ett annat handtag än ett miljöhandtag, om SQLAllocHandle returnerar SQL_ERROR, sätter det OutputHandlePtr till SQL_NULL_HDBC, SQL_NULL_HSTMT eller SQL_NULL_HDESC, beroende på värdet på HandleType, om inte utgångsargumentet är en nullpekare. Applikationen kan sedan hämta ytterligare information från den diagnostiska datastrukturen som är kopplad till handtaget i argumentet InputHandle .

Miljöhanteringsfel i allokering

Miljöallokering sker både inom Driver Manager och inom varje drivrutin. Felet som returneras av SQLAllocHandle med en HandleType SQL_HANDLE_ENV beror på vilken nivå felet inträffade.

Om Driver Manager inte kan allokera minne för *OutputHandlePtr när SQLAllocHandle med en HandleType av SQL_HANDLE_ENV anropas, eller om applikationen tillhandahåller en nullpekare för OutputHandlePtr, returnerar SQLAllocHandle SQL_ERROR. Driver Manager sätter *OutputHandlePtr till SQL_NULL_HENV (om inte applikationen tillhandtagit en nullpekare som returnerar SQL_ERROR). Det finns inget handtag för att koppla ytterligare diagnostisk information.

Driver Manager anropar inte drivrutinsnivåmiljöns hanteringsfunktion förrän applikationen anropar SQLConnect, SQLBrowseConnect eller SQLDriverConnect. Om ett fel uppstår i drivrutinsnivån SQLAllocHandle , returnerar funktionen Driver Manager-nivå SQLConnect, SQLBrowseConnect eller SQLDriverConnect SQL_ERROR. Den diagnostiska datastrukturen innehåller SQLSTATE IM004 (drivrutinens SQLAllocHandle misslyckades). Felet returneras på ett anslutningshandtag.

För mer information om flödet av funktionsanrop mellan Driver Manager och en drivrutin, se SQLConnect Function.

Diagnostics

När SQLAllocHandle returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med rätt HandleType och Handle satt till värdet InputHandle. SQL_SUCCESS_WITH_INFO (men inte SQL_ERROR) kan returneras för argumentet OutputHandle . Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLAllocHandle 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.

Comments

SQLAllocHandle används för att tilldela handtag för miljöer, anslutningar, satser och deskriptorer, som beskrivs i följande avsnitt. För allmän information om handtag, se Handtag.

Mer än en miljö, anslutning eller satshantering kan allokeras av en applikation samtidigt om flera allokeringar stöds av drivrutinen. I ODBC är ingen gräns för antalet miljö-, anslutnings-, sats- eller deskriptorhandtag som kan tilldelas samtidigt. Förare kan införa en gräns för hur många av en viss typ av handtag som kan tilldelas samtidigt; För mer information, se drivrutinsdokumentationen.

Om applikationen anropar SQLAllocHandle med *OutputHandlePtr inställt på en miljö, anslutning, sats eller deskriptorhandle som redan finns, skriver drivrutinen över informationen kopplad till handtaget, om inte applikationen använder connection pooling (se "Allocating an Environment Attribute for Connection Pooling" senare i detta avsnitt). Driver Manager kontrollerar inte om handtaget som anges i *OutputHandlePtr redan används, och kontrollerar inte heller det tidigare innehållet i ett handtag innan det skrivs över.

På operativsystem som stödjer flera trådar kan applikationer använda samma miljö, anslutning, sats eller deskriptorhandtag på olika trådar. Drivrutiner måste därför stödja säker, flertrådad åtkomst till denna information; Ett sätt att uppnå detta är till exempel att använda en kritisk sektion eller en semafor. För mer information om trådning, se Multitrådning.

SQLAllocHandle sätter inte attributet SQL_ATTR_ODBC_VERSION miljö när det anropas för att allokera ett miljöhandtag; miljöattributet måste sättas av applikationen, annars returneras SQLSTATE HY010 (Function sequence error) när SQLAllocHandle anropas för att allokera ett anslutningshandtag.

För standardkompatibla applikationer mappas SQLAllocHandle till SQLAllocHandleStd vid kompileringstillfället. Skillnaden mellan dessa två funktioner är att SQLAllocHandleStd sätter attributet SQL_ATTR_ODBC_VERSION miljö till SQL_OV_ODBC3 när det anropas med argumentet HandleType satt till SQL_HANDLE_ENV. Detta görs eftersom standardanpassade applikationer alltid är ODBC 3. x applikationer. Dessutom kräver standarderna inte att applikationsversionen är registrerad. Detta är den enda skillnaden mellan dessa två funktioner; annars är de identiska. SQLAllocHandleStd mappas till SQLAllocHandle i drivrutinshanteraren. Därför behöver tredjepartsdrivrutiner inte implementera SQLAllocHandleStd.

ODBC 3.8-applikationer bör använda:

• SQLAllocHandle och inte SQLAllocHandleStd för att allokera ett miljöhandtag.

• SQLSetEnvAttr för att sätta attributet SQL_ATTR_ODBC_VERSION miljö till SQL_OV_ODBC3_80.

Allokering av ett miljöhandtag

Ett miljöhandtag ger tillgång till global information såsom giltiga anslutningshandtag och aktiva anslutningshandtag. För allmän information om miljöhandtag, se Miljöhandtag.

För att begära ett miljöhandtag anropar en applikation SQLAllocHandle med HandleType SQL_HANDLE_ENV och InputHandle SQL_NULL_HANDLE. Drivrutinen allokerar minne för miljöinformationen och skickar tillbaka värdet på det tillhörande handtaget i *OutputHandlePtr-argumentet . Applikationen skickar *OutputHandle-värdet i alla efterföljande anrop som kräver ett miljöhandtagsargument. Mer information finns i Allokering av miljöhandtaget.

Under en Driver Manager's miljöhandtag, om det redan finns ett drivrutinsmiljöhandtag, anropas inte SQLAllocHandle med en HandleType av SQL_HANDLE_ENV i den drivrutinen när en anslutning upprättas, endast SQLAllocHandle med en HandleType SQL_HANDLE_DBC. Om en drivrutins miljöhandtag inte finns under Driver Managers miljöhandtag, anropas både SQLAllocHandle med en HandleType av SQL_HANDLE_ENV och SQLAllocHandle med en HandleType av SQL_HANDLE_DBC i drivrutinen när miljöns första anslutningshandtag kopplas till drivrutinen.

När Driver Manager bearbetar SQLAllocHandle-funktionen med en HandleType SQL_HANDLE_ENV, kontrollerar den nyckelordet Trace i [ODBC]-sektionen i systeminformationen. Om den är inställd på 1 aktiverar Driver Manager spårning för den aktuella applikationen. Om trace-flaggan är satt börjar spårningen när det första miljöhandtaget är allokerat och slutar när det senaste miljöhandtaget frigörs. För mer information, se Konfigurera datakällor.

Efter att ha allokerat ett miljöhandtag måste en applikation anropa SQLSetEnvAttr på miljöhandtaget för att sätta attributet SQL_ATTR_ODBC_VERSION miljö. Om detta attribut inte sätts innan SQLAllocHandle anropas för att allokera ett anslutningshandtag i miljön, kommer anropet för att allokera anslutningen att returnera SQLSTATE HY010 (Funktionssekvensfel). För mer information, se Deklaration av applikationens ODBC-version.

Allokering av delade miljöer för anslutningspoolning

Miljöer kan delas mellan flera komponenter i en och samma process. En delad miljö kan användas av mer än en komponent samtidigt. När en komponent använder en delad miljö kan den använda poolade anslutningar, vilket gör det möjligt att allokera och använda en befintlig anslutning utan att återskapa den anslutningen.

Innan en applikation allokerar en delad miljö som kan användas för anslutningspoolning måste den anropa SQLSetEnvAttr för att sätta attributet SQL_ATTR_CONNECTION_POOLING miljö till SQL_CP_ONE_PER_DRIVER eller SQL_CP_ONE_PER_HENV. SQLSetEnvAttr kallas i detta fall med EnvironmentHandle satt till null, vilket gör attributet till ett processnivåattribut.

Efter att anslutningspooling har aktiverats anropar en applikation SQLAllocHandle med argumentet HandleType satt till SQL_HANDLE_ENV. Miljön som allokeras av det här anropet är en implicit delad miljö eftersom anslutningspooler har aktiverats.

När en delad miljö allokeras bestäms inte vilken miljö som ska användas förrän SQLAllocHandle med en HandleType av SQL_HANDLE_DBC anropas. Då försöker Driver Manager hitta en befintlig miljö som matchar de miljöattribut som applikationen efterfrågar. Om ingen sådan miljö finns skapas en sådan miljö som en delad miljö. Driver Manager upprätthåller en referensräkning för varje delad miljö; Antalet sätts till 1 när miljön först skapas. Om en matchande miljö hittas returneras hanteringen för den miljön till applikationen och referensantalet ökar. Ett miljöhandtag som allokerats på detta sätt kan användas i vilken ODBC-funktion som helst som accepterar ett miljöhandtag som inmatningsargument.

Allokera ett anslutningshandtag

Ett anslutningshandtag ger tillgång till information såsom det giltiga sats- och deskriptorhandtaget på anslutningen samt om en transaktion för närvarande är öppen. För allmän information om anslutningshandtag, se Anslutningshandtag.

För att begära ett anslutningshandtag anropar en applikation SQLAllocHandle med HandleType SQL_HANDLE_DBC. Argumentet InputHandle sätts till det miljöhandtag som returnerades av anropet till SQLAllocHandle som tilldelade det handtaget. Drivrutinen tilldelar minne för anslutningsinformationen och skickar tillbaka värdet på det tillhörande handtaget i *OutputHandlePtr. Applikationen skickar värdet *OutputHandlePtr) i alla efterföljande anrop som kräver ett anslutningshandtag. För mer information, se Allokering av en anslutningshandtag.

Driver Manager bearbetar SQLAllocHandle-funktionen och anropar drivrutinens SQLAllocHandle-funktion när applikationen anropar SQLConnect, SQLBrowseConnect eller SQLDriverConnect. (För mer information, se SQLConnect Function.)

Om attributet SQL_ATTR_ODBC_VERSION environment inte sätts innan SQLAllocHandle anropas för att allokera ett anslutningshandtag i miljön, kommer anropet för att allokera anslutningen att returnera SQLSTATE HY010 (Function sequence error).

När en applikation anropar SQLAllocHandle med argumentet InputHandle satt till SQL_HANDLE_DBC och även inställt på ett delat miljöhandtag, försöker Driver Manager hitta en befintlig delad miljö som matchar de miljöattribut som applikationen har satt. Om det inte finns någon sådan miljö skapas en med ett referensantal (underhålls av drivrutinshanteraren) på 1. Om en matchande delad miljö hittas returneras det handtaget till applikationen och dess referensantal ökar.

Den faktiska anslutningen som ska användas bestäms inte av Driver Manager förrän SQLConnect eller SQLDriverConnect anropas. Driver Manager använder anslutningsalternativen i anropet till SQLConnect (eller anslutningsnyckelorden i anropet till SQLDriverConnect) och anslutningsattributen som angetts efter anslutningsallokeringen för att avgöra vilken anslutning i poolen som ska användas. För mer information, se SQLConnect Function.

Allokera en hanterare för uttalanden

Ett satshandtag ger tillgång till satsinformation, såsom felmeddelanden, markörens namn och statusinformation för SQL-satshantering. För allmän information om statementhandtag, se Statement Handles.

För att begära ett statement handle ansluter en applikation till en datakälla och anropar sedan SQLAllocHandle innan den skickar in SQL-satser. I detta anrop ska HandleType sättas till SQL_HANDLE_STMT och InputHandle till det anslutningshandtag som returnerades av anropet till SQLAllocHandle som tilldelade det handtaget. Drivrutinen allokerar minne för satsinformationen, kopplar satshandtaget till den specificerade anslutningen och skickar tillbaka värdet på det tillhörande handtaget i *OutputHandlePtr. Applikationen skickar *OutputHandlePtr-värdet i alla efterföljande anrop som kräver ett statement-handtag. För mer information, se Allokering av ett kontohandtag.

När satshandtaget tilldelas allokerar drivrutinen automatiskt en uppsättning av fyra deskriptorer och tilldelar handtagen för dessa deskriptorer till attributen SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC och SQL_ATTR_IMP_PARAM_DESC. Dessa kallas implicit allokerade deskriptorer. För att explicit allokera en applikationsbeskrivare, se följande avsnitt, "Allokering av ett deskriptorhandtag."

Allokering av ett deskriptorhandtag

När en applikation anropar SQLAllocHandle med HandleType SQL_HANDLE_DESC, allokerar drivrutinen en applikationsbeskrivare. Dessa kallas explicit tilldelade deskriptorer. Applikationen instruerar en drivrutin att använda en explicit allokerad applikationsbeskrivare istället för en automatiskt tilldelad för ett givet satshandtag genom att anropa SQLSetStmtAttr-funktionen med attributet SQL_ATTR_APP_ROW_DESC eller SQL_ATTR_APP_PARAM_DESC. En implementationsbeskrivare kan inte tilldelas explicit, och en implementeringsbeskrivare kan inte heller specificeras i ett SQLSetStmtAttr-funktionsanrop .

Explicit tilldelade deskriptorer är kopplade till ett anslutningshandtag istället för ett satshandtag (som automatiskt tilldelade deskriptorer är). Deskriptorer förblir tilldelade endast när en applikation faktiskt är ansluten till databasen. Eftersom explicit tilldelade deskriptorer är kopplade till ett anslutningshandtag kan en applikation associera en explicit allokerad deskriptor med mer än en sats inom en anslutning. En implicit allokerad applikationsbeskrivning kan däremot inte associeras med mer än ett statementhandtag. (Den kan inte kopplas till något annat statement handle än det som den var tilldelad för.) Explicit tilldelade deskriptorhandtag kan frigöras explicit antingen av applikationen eller genom att anropa SQLFreeHandle med en HandleType SQL_HANDLE_DESC, eller implicit när anslutningen stängs.

När den explicit tilldelade beskrivaren frigörs associeras den implicit tilldelade beskrivaren återigen med satsen. (Attributet SQL_ATTR_APP_ROW_DESC eller SQL_ATTR_APP_PARAM_DESC för den satsen sätts återigen till det implicit tilldelade deskriptorhandtaget.) Detta gäller för alla satser som var kopplade till den explicit tilldelade beskrivaren på anslutningen.

Mer information om deskriptorer finns i Beskrivningar.

Kodexempel

Se exempel på ODBC-program, SQLBrowseConnect-funktionen, SQLConnect-funktionen och SQLSetCursorName-funktionen.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler