SQLParamData-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLParamData används tillsammans med SQLPutData för att tillhandahålla parameterdata vid satsexekvering, och med SQLGetData för att hämta strömmade utdataparameterdata.

Syntax

  
SQLRETURN SQLParamData(  
     SQLHSTMT       StatementHandle,  
     SQLPOINTER *   ValuePtrPtr);

Arguments

StatementHandle
[Indata] Instruktionshandtag.

ValuePtrPtr
[Utdata] Pekare till en buffert där adressen till ParameterValuePtr-bufferten som anges i SQLBindParameter (för parameterdata) eller adressen till TargetValuePtr-bufferten specificerad i SQLBindCol (för kolumndata) returneras i adressen till TargetValuePtr-bufferten som anges i SQLBindCol (för kolumndata), som finns i fältet SQL_DESC_DATA_PTR deskriptorpost.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE eller SQL_PARAM_DATA_AVAILABLE.

Diagnostics

När SQLParamData returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med HandleType SQL_HANDLE_STMT och Handle of StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLParamData 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.

SQLSTATE Error Beskrivning
01000 Allmän varning Informationsmeddelande för drivrutinsspecifikt. (Funktionen returnerar SQL_SUCCESS_WITH_INFO.)
07006 Attributöverträdelse för begränsad datatyp Datavärdet som identifierades av argumentet ValueType i SQLBindParameter för den bundna parametern kunde inte konverteras till den datatyp som identifierades av ParameterType-argumentet i SQLBindParameter.

Datavärdet som returneras för en parameter som är bunden som SQL_PARAM_INPUT_OUTPUT eller SQL_PARAM_OUTPUT kunde inte konverteras till den datatyp som identifierades av argumentet ValueType i SQLBindParameter.

(Om datavärdena för en eller flera rader inte kunde konverteras, men en eller flera rader returnerades framgångsrikt, returnerar denna funktion SQL_SUCCESS_WITH_INFO.)
08S01 Kommunikationslänkfel Kommunikationslänken mellan drivrutinen och datakällan som drivrutinen var ansluten till misslyckades innan funktionen slutförde bearbetningen.
22026 Strängdata, längdmatchningsfel Den SQL_NEED_LONG_DATA_LEN informationstypen i SQLGetInfo var "Y", och mindre data skickades för en lång parameter (datatypen var SQL_LONGVARCHAR, SQL_LONGVARBINARY eller en lång datakällasspecifik datatyp) än vad som specificerades med argumentet StrLen_or_IndPtr i SQLBindParameter.

Den SQL_NEED_LONG_DATA_LEN informationstypen i SQLGetInfo var "Y", och mindre data skickades för en lång kolumn (datatypen var SQL_LONGVARCHAR, SQL_LONGVARBINARY eller en lång datakällasspecifik datatyp) än vad som specificerades i den längdbuffert som motsvarade en kolumn i en rad data som lades till eller uppdaterades med SQLBulkOperations eller uppdaterades med SQLSetPos.
40001 Serialiseringsfel Transaktionen återställdes på grund av ett resursstopp med en annan transaktion.
40003 Slutförande av instruktion okänd Den associerade anslutningen misslyckades under körningen av den här funktionen och transaktionens tillstånd kan inte fastställas.
HY000 Allmänt fel Ett fel uppstod för vilket det inte fanns någon specifik SQLSTATE och för vilken ingen implementeringsspecifik SQLSTATE definierades. Felmeddelandet som returnerades av SQLGetDiagRec i *MessageText-bufferten beskriver felet och dess orsak.
HY001 Fel vid minnesallokering Drivrutinen kunde inte allokera minne som krävs för att stödja körning eller slutförande av funktionen.
HY008 Åtgärden avbröts Asynkron bearbetning aktiverades för StatementHandle. Funktionen anropades, och innan den var klar med exekveringen anropades SQLCancel eller SQLCancelHandle på StatementHandle; funktionen anropades sedan igen på StatementHandle.

Funktionen anropades och innan körningen slutfördes anropades SQLCancel eller SQLCancelHandle på StatementHandle från en annan tråd i ett flertrådsprogram.
HY010 Funktionssekvensfel (DM) Det föregående funktionsanropet var inte ett anrop till SQLExecDirect, SQLExecute, SQLBulkOperations eller SQLSetPos där returkoden var SQL_NEED_DATA, eller det föregående funktionsanropet var ett anrop till SQLPutData.

Det föregående funktionsanropet var ett anrop till SQLParamData.

(DM) En asynkront körande funktion anropades för anslutningshandtaget som är associerat med StatementHandle. Denna asynkrona funktion kördes fortfarande när SQLParamData-funktionen anropades.

(DM) En asynkront körande funktion (inte den här) anropades för StatementHandle och kördes fortfarande när den här funktionen anropades.

SQLExecute, SQLExecDirect, SQLBulkOperations eller SQLSetPos anropades för StatementHandle och returnerade SQL_NEED_DATA. SQLCancel anropades innan data skickades för alla data-at-exekveringsparametrar eller kolumner.
HY013 Minneshanteringsfel Det gick inte att bearbeta funktionsanropet eftersom det inte gick att komma åt underliggande minnesobjekt, möjligen på grund av minnesbrist.
HY117 Anslutningen pausas på grund av okänt transaktionstillstånd. Endast frånkopplings- och skrivskyddade funktioner tillåts. (DM) Mer information om pausat tillstånd finns i SQLEndTran-funktion.
HYT01 Tidsgränsen för anslutningen gick ut Tidsgränsen för anslutningen löpte ut innan datakällan svarade på begäran. Tidsgränsen för anslutningen anges via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Drivrutinen stöder inte den här funktionen (DM) Drivrutinen som motsvarar StatementHandle stöder inte funktionen.
IM017 Avsökning är inaktiverat i asynkront meddelandeläge När meddelandemodellen används inaktiveras avsökningen.
IM018 SQLCompleteAsync har inte anropats för att slutföra den tidigare asynkrona åtgärden på det här handtaget. Om det tidigare funktionsanropet på handtaget returnerar SQL_STILL_EXECUTING och om meddelandeläget är aktiverat måste SQLCompleteAsync anropas på handtaget för att utföra efterbearbetningen och slutföra åtgärden.

Om SQLParamData anropas medan data för en parameter i en SQL-sats skickas kan den returnera vilken SQLSTATE som helst som kan returneras av funktionen som anropas för att köra satsen (SQLExecute eller SQLExecDirect). Om den anropas medan data skickas för en kolumn som uppdateras eller läggs till med SQLBulkOperations eller uppdateras med SQLSetPos, kan den returnera vilken SQLSTATE som helst som kan returneras av SQLBulkOperations eller SQLSetPos.

Comments

SQLParamData kan anropas för att tillhandahålla data vid exekveringsdata för två användningsområden: parameterdata som kommer att användas i ett anrop till SQLExecute eller SQLExecDirect, eller kolumndata som används när en rad uppdateras eller läggs till genom ett anrop till SQLBulkOperations eller uppdateras genom ett anrop till SQLSetPos. Vid exekveringstillfället returnerar SQLParamData till applikationen en indikator på vilken data drivrutinen kräver.

När en applikation anropar SQLExecute, SQLExecDirect, SQLBulkOperations eller SQLSetPos, returnerar drivrutinen SQL_NEED_DATA om den behöver data vid exekvering. En applikation anropar sedan SQLParamData för att avgöra vilken data som ska skickas. Om drivrutinen kräver parameterdata returnerar drivrutinen i *ValuePtrPtr-utgångsbufferten det värde som applikationen lade in i raduppsättningsbufferten. Applikationen kan använda detta värde för att avgöra vilken parameterdata drivrutinen begär. Om drivrutinen kräver kolumndata returnerar drivrutinen i *ValuePtrPtr-bufferten adressen som kolumnen ursprungligen var bunden till, enligt följande:

Bunden adress + Bindningsoffset + ((Radnummer - 1) x elementstorlek)

där variablerna definieras som anges i följande tabell.

Variable Beskrivning
Bunden adress Adressen som anges med argumentet TargetValuePtr i SQLBindCol.
Bindningsoffset Värdet som lagras på adressen som anges med attributet SQL_ATTR_ROW_BIND_OFFSET_PTR statement.
Radnummer Det 1-baserade numret för raden i raduppsättningen. För enkelradshämtningar, som är standard, är detta 1.
Elementstorlek Värdet av attributet SQL_ATTR_ROW_BIND_TYPE statement för både data och längd-/indikatorbuffertar.

Den returnerar också SQL_NEED_DATA, vilket är en indikator till applikationen att den ska anropa SQLPutData för att skicka data.

Applikationen anropar SQLPutData så många gånger som behövs för att skicka data vid exekveringsdata för kolumnen eller parametern. När all data har skickats för kolumnen eller parametern anropar applikationen SQLParamData igen. Om SQLParamData återigen returnerar SQL_NEED_DATA måste data skickas till en annan parameter eller kolumn. Därför anropar applikationen återigen SQLPutData. Om all data vid exekvering har skickats för alla parametrar eller kolumner, returnerar SQLParamData SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO, värdet i *ValuePtrPtr är odefinierat, och SQL-satsen kan köras eller anropet SQLBulkOperations eller SQLSetPos kan bearbetas.

Om SQLParamData tillhandahåller parameterdata för en sökt uppdaterings- eller delete-sats som inte påverkar några rader i datakällan, returnerar anropet till SQLParamData SQL_NO_DATA.

För mer information om hur parameterdata vid exekvering skickas vid exekveringstidpunkten, se "Passing Parameter Values" i SQLBindParameter och Sending Long Data. För mer information om hur data vid exekveringskolumndata uppdateras eller läggs till, se avsnittet "Using SQLSetPos" i SQLSetPos, "Performing Bulk Updates Using Bookmarks" i SQLBulkOperations, samt Long Data och SQLSetPos och SQLBulkOperations.

SQLParamData kan anropas för att hämta strömmade utdataparametrar. När SQLMoreResults, SQLExecute, SQLGetData eller SQLExecDirect returnerar SQL_PARAM_DATA_AVAILABLE, anropa SQLParamData för att avgöra vilken parameter som har ett tillgängligt värde. För mer information om SQL_PARAM_DATA_AVAILABLE och strömmade utdataparameter, se Hämta utgångsparametrar med hjälp av SQLGetData.

Kodexempel

Se SQLPutData.

Mer information om Se
Binda en buffert till en parameter SQLBindParameter-funktionen
Avbryta instruktionsbearbetning SQLCancel-funktion
Returnering av information om en parameter i en sats SQLDescribeParam-funktionen
Exekvering av en SQL-sats SQLExecDirect-funktionen
Köra en förberedd SQL-instruktion SQLExecute-funktion
Skicka parameterdata vid körning SQLPutData-funktion

Relaterat innehåll

  • Last updated on