Funkce SQLPutData

Soulad
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92

Summary
SQLPutData umožňuje aplikaci odesílat data pro parametr nebo sloupec ovladači při vykonávání příkazu. Tato funkce může být použita k odeslání znakových nebo binárních datových hodnot v částech do sloupce s datovým typem se znakem, binárním kódem nebo datovým typem specifickým pro zdroj dat (například parametry typů SQL_LONGVARBINARY nebo SQL_LONGVARCHAR). SQLPutData podporuje vazbu na datový typ Unicode C, i když základní ovladač nepodporuje Unicode data.

Syntax

  
SQLRETURN SQLPutData(  
      SQLHSTMT     StatementHandle,  
      SQLPOINTER   DataPtr,  
      SQLLEN       StrLen_or_Ind);

Arguments

StatementHandle
[Vstup] Popisovač příkazu

DataPtr
[Vstup] Ukazatel na buffer obsahující skutečná data pro parametr nebo sloupec. Data musí být v C datovém typu specifikovaném v argumentu ValueTypev SQLBindParameter (pro parametrická data) nebo v argumentu TargetTypev SQLBindCol (pro sloupcová data).

StrLen_or_Ind
[Vstup] Délka *DataPtr. Specifikuje množství dat zaslaných při volání do SQLPutData. Množství dat se může lišit s každým voláním pro daný parametr nebo sloupec. StrLen_or_Ind se ignoruje, pokud nesplňuje jednu z následujících podmínek:

StrLen_or_Ind je SQL_NTS, SQL_NULL_DATA nebo SQL_DEFAULT_PARAM.
Datový typ C specifikovaný v SQLBindParameter nebo SQLBindCol je SQL_C_CHAR nebo SQL_C_BINARY.
Typ dat C je SQL_C_DEFAULT a výchozí typ dat C pro specifikovaný SQL typ je SQL_C_CHAR nebo SQL_C_BINARY.

U všech ostatních typů C dat, pokud StrLen_or_Ind není SQL_NULL_DATA nebo SQL_DEFAULT_PARAM, ovladač předpokládá, že velikost bufferu *DataPtr je velikost datového typu C specifikovaného pomocí ValueType nebo TargetType a odešle celou datovou hodnotu. Pro více informací viz Převod dat z C do SQL datových typů v příloze D: Datové typy.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLPutData 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 HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLPutData 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.)
01004	Řetězcová data, zkrácená vpravo	Řetězcová nebo binární data vrácená pro výstupní parametr vedla k okrácení neprázdných znakových nebo ne-NULL binárních dat. Pokud se jednalo o řetězcovou hodnotu, byla zkrácena doprava. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
07006	Porušení atributu omezeného datového typu	Datová hodnota identifikovaná argumentem ValueType v SQLBindParameter pro vázaný parametr nelze převést na datový typ identifikovaný argumentem ParameterType v SQLBindParameter.
07S01	Neplatné použití výchozího parametru	Hodnota parametru nastavená pomocí SQLBindParameter byla SQL_DEFAULT_PARAM a odpovídající parametr neměl výchozí hodnotu.
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í zprava	Přiřazení znaku nebo binární hodnoty ke sloupci vedlo k okrácení neprázdných (znaků) nebo nenulových (binárních) znaků či bajtů. Typ SQL_NEED_LONG_DATA_LEN informací v SQLGetInfo byl "Y" a pro dlouhý parametr (typ dat byl SQL_LONGVARCHAR, SQL_LONGVARBINARY nebo dlouhý datový typ specifický pro zdroj dat) bylo odesláno více dat, než bylo specifikováno argumentem StrLen_or_IndPtr v SQLBindParametru. Typ informací SQL_NEED_LONG_DATA_LEN v SQLGetInfo byl "Y" a pro dlouhý sloupec (typ dat byl SQL_LONGVARCHAR, SQL_LONGVARBINARY nebo dlouhý datový typ specifický pro zdroj dat) bylo odesláno více dat, než bylo specifikováno v dlouhém bufferu odpovídajícím sloupci v řádku dat, která byla přidána nebo aktualizována pomocí SQLBulkOperations nebo aktualizována pomocí SQLSetPos.
22003	Číselná hodnota mimo rozsah	Data odeslaná pro vázaný číselný parametr nebo sloupec způsobila, že celá (na rozdíl od zlomkové) část čísla byla při přiřazení do příslušného sloupce tabulky zkrácena. Vrácení číselné hodnoty (jako číselné nebo řetězce) pro jeden nebo více vstupních/výstupních parametrů by způsobilo zkrácení celé části čísla (na rozdíl od zlomků).
22007	Neplatný formát data a času	Data odeslaná pro parametr nebo sloupec, který byl vázán na dat, čas nebo časovou strukturu, byla v pořadí neplatným datem, časem nebo časovým razítkem. Vstupní/výstupní nebo výstupní parametr byl vázán na strukturu jazyka C data, času nebo časového razítka a hodnota vráceného parametru byla neplatné datum, čas nebo časové razítko. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
22008	Přetečení pole Datetime	Výraz datetime vypočítaný pro vstupní/výstupní nebo výstupní parametr způsobil neplatnou strukturu jazyka C data, času nebo časového razítka.
22012	Dělení nulou	Aritmetický výraz vypočítaný pro vstupní/výstupní nebo výstupní parametr způsobil dělení nulou.
22015	Přetečení pole intervalu	Data odeslaná pro přesný číselný nebo intervalový sloupec či parametr do intervalového SQL datového typu způsobovala ztrátu významných číslic. Data byla odesílána pro intervalový sloupec nebo parametr s více než jedním polím, byla převedena na číselný datový typ a neměla žádnou reprezentaci v numerickém datovém typu. Data odeslaná pro sloupce nebo parametrová data byla přiřazena intervalovému SQL typu a v intervalovém SQL typu nebyla žádná reprezentace hodnoty C typu. Data odeslaná pro přesný číselný nebo intervalový sloupec C či parametr do intervalu typu C způsobila ztrátu významných číslic. Data odeslaná pro sloupcová nebo parametrová data byla přiřazena ke struktuře intervalu C a data v intervalové datové struktuře nebyla reprezentována.
22018	Neplatná hodnota znaku pro specifikaci přetypování	Typ C byl přesná nebo přibližná číselná číslice, datový čas nebo intervalový datový typ; SQL typ sloupce byl datový typ znaku; a hodnota ve sloupci nebo parametru nebyla platným literálem vázaného typu C. SQL typ byl přesná nebo přibližná číselná číslice, datový čas nebo intervalový datový typ; typ C byl SQL_C_CHAR; a hodnota ve sloupci nebo parametru nebyla platným literálem vázaného SQL typu.
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.
HY008	Operace byla zrušena.	Asynchronní zpracování bylo povoleno pro StatementHandle. Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel nebo SQLCancelHandle pro PříkazHandle. Pak byla funkce znovu volána v StatementHandle. Funkce byla volána a před dokončením provádění byla volána funkce SQLCancel neboSQLCancelHandlez jiného vlákna v aplikaci s více vlákny.
HY009	Neplatné použití ukazatele null	(DM) Argument DataPtr byl nulový ukazatel a argument StrLen_or_Ind nebyl 0, SQL_DEFAULT_PARAM ani SQL_NULL_DATA.
HY010	Chyba posloupnosti funkcí	(DM) Předchozí volání funkce nebylo voláním SQLPutData ani SQLParamData. (DM) Byla volána asynchronně spuštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byla volána funkce SQLPutData. (DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl volána pro StatementHandle a vrácena SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. (DM) Pro PříkazHandle byla volána asynchronně spuštěná funkce (ne tato) a při zavolání této funkce se stále spouštěla.
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.
HY019	Neznaková a nebinární data odesílaná v částech	SQLPutData byla volána více než jednou pro parametr nebo sloupec a nebyla používána k odeslání dat znaku C do sloupce s datovým typem se znakem, binárním souborem nebo datovým typem specifickým pro zdroj dat, ani k odeslání binárních dat C do sloupce s datovým typem se znakem, binárním nebo specifickým datovým typem pro datový zdroj.
HY020	Pokus o spojení nulové hodnoty	SQLPutData byla od návratu SQL_NEED_DATA volána více než jednou a v jednom z těchto volání obsahoval argument StrLen_or_Ind SQL_NULL_DATA nebo SQL_DEFAULT_PARAM.
HY090	Neplatná délka řetězce nebo vyrovnávací paměti	Argument DataPtr nebyl nulovým ukazatelem a argument StrLen_or_Ind byl menší než 0, ale ne roven SQL_NTS nebo SQL_NULL_DATA.
HY117	Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení.	(DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran.
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řidružený k StatementHandle nepodporuje funkci.
IM017	Dotazování je zakázané v asynchronním režimu oznámení.	Při každém použití modelu oznámení je dotazování zakázané.
IM018	K dokončení předchozí asynchronní operace na tomto popisovači nebyla volána funkce SQLCompleteAsync.	Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolen režim oznámení, musí být sqlCompleteAsync volán na popisovači, aby bylo možné provést následné zpracování a dokončit operaci.

Pokud je SQLPutData volán při odesílání dat pro parametr v SQL příkazu, může vrátit jakýkoli SQLSTATE, který může být vrácen funkcí volanou k vykonání příkazu (SQLExecute nebo SQLExecDirect). Pokud je volán při odesílání dat pro sloupec, který je aktualizován nebo přidáván pomocí SQLBulkOperations , nebo se aktualizuje pomocí SQLSetPos, může vrátit jakýkoli SQLSTATE, který může vrátit SQLBulkOperations nebo SQLSetPos.

Comments

SQLPutData lze volat k poskytnutí dat při vykonání pro dva účely: parametrová data použitá při volání SQLExecute nebo SQLExecDirect, nebo sloupcová data, která se použijí, když je řádek aktualizován nebo přidán voláním do SQLBulkOperations , nebo je aktualizován voláním do SQLSetPos.

Když aplikace volá SQLParamData , aby určila, která data má odeslat, ovladač vrátí indikátor, který aplikace může použít k určení, která parametrická data odeslat nebo kde lze sloupcová data najít. Také vrací SQL_NEED_DATA, což je signál pro aplikaci, že by měla zavolat SQLPutData k odeslání dat. V argumentu DataPtr vůči SQLPutData aplikace předává ukazatel do bufferu obsahující skutečná data pro parametr nebo sloupec.

Když ovladač vrátí SQL_SUCCESS pro SQLPutData, aplikace znovu volá SQLParamData . SQLParamData SQL_NEED_DATA vrátí, pokud je potřeba odeslat více dat, v takovém případě aplikace SQLPutData znovu volá. Vrací SQL_SUCCESS, pokud byla odeslána všechna data při vykonání. Aplikace pak znovu volá SQLParamData . Pokud ovladač vrátí SQL_NEED_DATA a další indikátor v *ValuePtrPtr, vyžaduje data pro jiný parametr nebo sloupec a SQLPutData je znovu volán. Pokud ovladač vrátí SQL_SUCCESS, byla odeslána všechna data při vykonání a lze spustit SQL příkaz nebo zpracovat volání SQLBulkOperations či SQLSetPos .

Pro více informací o tom, jak jsou data parametrů dat-at-execution předávána při vykonávání příkazů, viz "Passing Parameter Values" v SQLBindParameter a Sending Long Data. Pro více informací o tom, jak jsou data z datových sloupců při vykonání aktualizována nebo přidávána, viz sekce "Používání SQLSetPos" v SQLSetPos, "Provádění hromadných aktualizací pomocí záložek" v SQLBulkOperations a Long Data a SQLSetPos a SQLBulkOperations.

Note

Aplikace může použít SQLPutData k odesílání dat v částech pouze při odesílání dat znaku C do sloupce s typem datových znaků, binárního souboru nebo datového zdroje specifického, nebo při odesílání binárních dat C do sloupce s datovým typem znaku, binárním nebo datovým typem specifickým pro zdroj dat. Pokud je SQLPutData vyvolán více než jednou za jiných podmínek, vrátí SQL_ERROR a SQLSTATE HY019 (neznaková a nebinární data odeslaná po částech).

Example

Následující ukázka předpokládá název zdroje dat nazvaný Test. Související databáze by měla obsahovat tabulku, kterou můžete vytvořit, a to následovně:

CREATE TABLE emp4 (NAME char(30), AGE int, BIRTHDAY datetime, Memo1 text)

// SQLPutData.cpp  
// compile with: odbc32.lib user32.lib  
#include <stdio.h>  
#include <windows.h>  
#include <sqlext.h>  
#include <odbcss.h>  
  
#define TEXTSIZE  12000  
#define MAXBUFLEN 256  
  
SQLHENV henv = SQL_NULL_HENV;  
SQLHDBC hdbc1 = SQL_NULL_HDBC;       
SQLHSTMT hstmt1 = SQL_NULL_HSTMT;  
  
void Cleanup() {  
   if (hstmt1 != SQL_NULL_HSTMT)  
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);  
  
   if (hdbc1 != SQL_NULL_HDBC) {  
      SQLDisconnect(hdbc1);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);  
   }  
  
   if (henv != SQL_NULL_HENV)  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}  
  
int main() {  
   RETCODE retcode;  
  
   // SQLBindParameter variables.  
   SQLLEN cbTextSize, lbytes;  
  
   // SQLParamData variable.  
   PTR pParmID;  
  
   // SQLPutData variables.  
   UCHAR  Data[] =   
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"  
      "abcdefghijklmnopqrstuvwxyz";  
  
   SDWORD cbBatch = (SDWORD)sizeof(Data) - 1;  
  
   // Allocate the ODBC environment and save handle.  
   retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);  
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {  
      printf("SQLAllocHandle(Env) Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Notify ODBC that this is an ODBC 3.0 app.  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);  
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {  
      printf("SQLSetEnvAttr(ODBC version) Failed\n\n");  
      Cleanup();  
      return(9);      
   }  
  
   // Allocate ODBC connection handle and connect.  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);  
   if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {  
      printf("SQLAllocHandle(hdbc1) Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Sample uses Integrated Security, create SQL Server DSN using Windows NT authentication.   
   retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"",SQL_NTS, (UCHAR*)"", SQL_NTS);  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("SQLConnect() Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Allocate statement handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc1, &hstmt1);  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("SQLAllocHandle(hstmt1) Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Set parameters based on total data to send.  
   lbytes = (SDWORD)TEXTSIZE;  
   cbTextSize = SQL_LEN_DATA_AT_EXEC(lbytes);  
  
   // Bind the parameter marker.  
   retcode = SQLBindParameter (hstmt1,           // hstmt  
                               1,                // ipar  
                               SQL_PARAM_INPUT,  // fParamType  
                               SQL_C_CHAR,       // fCType  
                               SQL_LONGVARCHAR,  // FSqlType  
                               lbytes,           // cbColDef  
                               0,                // ibScale  
                               (VOID *)1,        // rgbValue  
                               0,                // cbValueMax  
                               &cbTextSize);     // pcbValue  
  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("SQLBindParameter Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Execute the command.  
   retcode =   
      SQLExecDirect(hstmt1, (UCHAR*)"INSERT INTO emp4 VALUES('Paul Borm', 46,'1950-11-12 00:00:00', ?)", SQL_NTS);  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_NEED_DATA) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("SQLExecDirect Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Check to see if NEED_DATA; if yes, use SQLPutData.  
   retcode = SQLParamData(hstmt1, &pParmID);  
   if (retcode == SQL_NEED_DATA) {  
      while (lbytes > cbBatch) {  
         SQLPutData(hstmt1, Data, cbBatch);  
         lbytes -= cbBatch;  
      }  
      // Put final batch.  
      retcode = SQLPutData(hstmt1, Data, lbytes);   
   }  
  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("SQLParamData Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Make final SQLParamData call.  
   retcode = SQLParamData(hstmt1, &pParmID);  
   if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {  
      printf("Final SQLParamData Failed\n\n");  
      Cleanup();  
      return(9);  
   }  
  
   // Clean up.  
   SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);  
   SQLDisconnect(hdbc1);  
   SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);  
   SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}

Informace o	Podívejte se
Vazba bufferu na parametr	Funkce SQLBindParameter
Zrušení zpracování příkazů	SQLCancel – funkce
Provádění SQL příkazu	SQLExecDirect Function
Spuštění připraveného příkazu SQL	FUNKCE SQLExecute
Vrácení dalšího parametru pro odesílání dat pro	SQLParamData – funkce

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-24