SQLPutData függvény

Megfelelőség
Bevezetett verzió: ODBC 1.0 szabványmegfelelőség: ISO 92

Summary
Az SQLPutData lehetővé teszi, hogy egy alkalmazás egy paraméter vagy oszlop adatait küldje az utasítás végrehajtási idején. Ez a függvény arra szolgál, hogy karakter- vagy bináris adatértékeket osztanaként küldjenek egy oszlopba, ahol karakter, bináris vagy adatforrás-specifikus adattípus található (például a SQL_LONGVARBINARY vagy SQL_LONGVARCHAR típusú paraméterek). Az SQLPutData támogatja a kötést egy Unicode C adattípushoz, még akkor is, ha az alapillesztő nem támogatja az Unicode adatokat.

Syntax

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

Arguments

StatementHandle
[Bemenet] Utasításkezelő.

DataPtr
[Bemenet] Mutató egy pufferre, amely tartalmazza a paraméter vagy oszlop tényleges adatait. Az adatnak a C adattípusban kell lennie, amely az SQLBindParameterValueType argumentumában (paraméteradatok esetén) vagy az SQLBindColTargetType argumentumában (oszlopadatok esetén) van megadva.

StrLen_or_Ind
[Bemenet] *DataPtr. Megadja, hogy mennyi adatot küldenek egy SQLPutData hívásban. Az adatmennyiség változó lehet minden egyes paraméter vagy oszlop hívásánként. StrLen_or_Ind figyelmen kívül hagyják, hacsak nem teljesíti az alábbi feltételek egyikét:

StrLen_or_Ind SQL_NTS, SQL_NULL_DATA vagy SQL_DEFAULT_PARAM.
Az SQLBindParameter vagy SQLBindCol által megadott C adattípus SQL_C_CHAR vagy SQL_C_BINARY.
A C adattípus SQL_C_DEFAULT, és a megadott SQL adattípus alapértelmezett C adattípusa SQL_C_CHAR vagy SQL_C_BINARY.

Minden más C adattípus esetén, ha StrLen_or_Ind nem SQL_NULL_DATA vagy SQL_DEFAULT_PARAM, az illesztőprogram feltételezi, hogy a *DataPtr puffer mérete a ValueType vagy TargetType által megadott C adattípus mérete, és az egész adatértéket küldi. További információért lásd: Adatátalakítás C-ből SQL-re a D. mellékletben: Adattípusok.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR vagy SQL_INVALID_HANDLE.

Diagnostics

Amikor az SQLPutData SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_STMT HandleType és egy HandleType (StatementHandle) segítségével szól. Az alábbi táblázat felsorolja az SQLPutData által gyakran visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

SQLSTATE	Hiba	Description
01000	Általános figyelmeztetés	Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01004	Sztringadatok, jobb csonkolt	A kimeneti paraméterhez visszaadott string vagy bináris adatok nem üres karakter vagy nem NULL bináris adatok lerövidítését eredményezték. Ha sztringérték volt, akkor jobbról csonkolt. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
07006	Korlátozott adattípus-attribútumok megsértése	A kötött paraméterHEZ tartozó SQLBindParameterValueType argumentuma által azonosított adatérték nem konvertálható az SQLBindParameterParameterType argumentuma által azonosított adattípusra.
07S01	Az alapértelmezett paraméter használata érvénytelen	Az SQLBindParameterrel beállított paraméterérték SQL_DEFAULT_PARAM volt, és a megfelelő paraméter nem rendelkezik alapértelmezett értékkel.
08S01	Kommunikációs kapcsolat hibája	Az illesztőprogram és az adatforrás közötti kommunikációs kapcsolat, amelyhez az illesztőprogram csatlakoztatva volt, nem sikerült, mielőtt a függvény befejeződött a feldolgozás.
22001	Karakterlánc, jobb oldali csonkítás	Egy karakter vagy bináris érték hozzárendelése egy oszlophoz a nem üres (karakter) vagy nem null (bináris) karakterek vagy bájtok lerövidítését eredményezte. Az SQLGetInfo SQL_NEED_LONG_DATA_LEN információtípusa "Y" volt, és több adatot küldtek egy hosszú paraméterre (az adattípus SQL_LONGVARCHAR, SQL_LONGVARBINARY vagy egy hosszú adatforrás-specifikus adattípus), mint amennyit az SQLBindParameterStrLen_or_IndPtr argumentumával megadtak. Az SQLGetInfo SQL_NEED_LONG_DATA_LEN információtípusa "Y" volt, és több adatot küldtek egy hosszú oszlophoz (az adattípus SQL_LONGVARCHAR, SQL_LONGVARBINARY vagy egy hosszú adatforrás-specifikus adattípus volt), mint amennyit a hosszpufferben megadott volt, amely egy sor oszlopának felelt meg, amelyet SQLBulkOperations vagy SQLSetPos segítségével adtak hozzá vagy frissítettek.
22003	Numerikus érték a tartományon kívül	Az adott adatok egy kötött numerikus paraméterhez vagy oszlophoz küldtek, amikor a szám teljes (nem tört) része lerövidült, amikor a hozzá tartozó táblázatoszlophoz osztották. Egy vagy több bemeneti/kimeneti vagy kimeneti paraméter numerikus értékének (számként vagy sztringként) visszaadása miatt a szám egésze (a törtrész helyett) csonkolt lett volna.
22007	Érvénytelen dátum/idő formátum	Az adat, amelyet egy dátumhoz, időhöz vagy időbélyegrendszerhez kötött paraméterhez vagy oszlophoz küldtek, érvénytelen dátum, idő vagy időbélyeg voltak. Egy bemeneti/kimeneti vagy kimeneti paraméter egy dátum, idő vagy időbélyeg C struktúrához volt kötve, és a visszaadott paraméter értéke érvénytelen dátum, idő vagy időbélyeg volt. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
22008	Datetime mező túlcsordul	Egy bemeneti/kimeneti vagy kimeneti paraméterhez kiszámított datetime kifejezés érvénytelen C-struktúrát eredményezett.
22012	Osztás nullával	Egy bemeneti/kimeneti vagy kimeneti paraméterre számított aritmetikai kifejezés nullával való osztást eredményezett.
22015	Intervallummező túlcsordult	Az adott adatok pontos numerikus vagy intervallum oszlopra vagy paraméterre küldtek egy intervallum SQL adattípushoz, jelentős számjegyek elvesztését okozták. Az adatokat egy intervallum oszlopra vagy paraméterre küldték, több mezővel együtt, átalakították numerikus adattípusra, és nem volt ábrázolásuk a numerikus adattípusban. Az oszlop- vagy paraméteradatokhoz küldött adatokat egy intervallum SQL típushoz rendelték, és nem volt ábrázolva a C típus értéke az intervallum SQL típusban. Az adatok egy pontos numerikus vagy intervallum C oszlopra vagy paraméterre küldtek egy C intervallum típusnak jelentős számjegyek elvesztését okozták. Az oszlop- vagy paraméteradatokhoz küldött adatokat egy C intervallum struktúrához rendelték, és az intervallum adatszerkezetben nem volt ábrázolva.
22018	Érvénytelen karakterérték az öntött specifikációhoz	A C típus pontos vagy közelítő numerikus, dátumi vagy intervallum adattípus volt; az oszlop SQL típusa karakteradattípus volt; és az oszlopban vagy paraméterben szereplő érték nem volt érvényes literális a kötött C típusból. Az SQL típus pontos vagy közelítő numerikus, dátumidő, illetve intervallum adattípus volt; a C típus SQL_C_CHAR; és az oszlopban vagy paraméterben lévő érték nem volt érvényes literális a kötött SQL típusnak.
HY000	Általános hiba	Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *MessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát.
HY001	Memóriafoglalási hiba	Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát.
HY008	A műveletet megszakították	Az aszinkron feldolgozás engedélyezve lett a StatementHandle-ben. A függvény meghívása megtörtént, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle meghívása megtörtént az Utasításkezelőben. Ezután a függvény ismét meghívásra került az Utasításkezelőben. A függvény meghívása megtörtént, és a végrehajtás befejezése előtt az SQLCancel vagy az SQLCancelHandle egy másik szálról lett meghívva a StatementHandle-ra egy többszálas alkalmazásból.
HY009	Érvénytelen null mutató használata	(DM) A DataPtr érv null pointer volt, és az érv StrLen_or_Ind nem volt 0, SQL_DEFAULT_PARAM vagy SQL_NULL_DATA.
HY010	Függvényütemezési hiba	(DM) Az előző függvényhívás nem volt SQLPutData vagy SQLParamData hívása. (DM) A StatementHandle-hez társított kapcsolati leíróhoz aszinkron módon végrehajtó függvény lett meghívva. Ez az aszinkron függvény még mindig futott, amikor az SQLPutData függvényt hívták. (DM) SQLExecute, SQLExecDirect vagy SQLMoreResults lett meghívva az Utasításkezelőhöz , és SQL_PARAM_DATA_AVAILABLE ad vissza. Ez a függvény az összes streamelt paraméter adatainak lekérése előtt lett meghívva. (DM) Egy aszinkron módon végrehajtó függvény (nem ez) lett meghívva az StatementHandle-hez , és a függvény meghívásakor továbbra is végrehajtó volt.
HY013	Memóriakezelési hiba	A függvényhívás nem dolgozható fel, mert a mögöttes memóriaobjektumok nem érhetők el, esetleg a memóriahiány miatt.
HY019	Darabokban küldött nem-karakter- és nembináris adatok	Az SQLPutData-t többször is meghívták egy paraméterhez vagy oszlophoz, és nem használták C karakter adatot egy karakter-, bináris vagy adatforrás-specifikus adattípusú oszlopba, illetve bináris C adat küldésére egy karakter-, bináris vagy adatforrás-specifikus adattípusú oszlopba.
HY020	Nullérték összekötésének kísérlete	Az SQLPutData-t többször hívták a visszahívó hívás SQL_NEED_DATA óta, és az egyik hívásban az StrLen_or_Ind érv SQL_NULL_DATA vagy SQL_DEFAULT_PARAM tartalmazott.
HY090	Érvénytelen sztring vagy puffer hossza	A DataPtr érv nem volt null pointer, és az érv StrLen_or_Ind kevesebb volt 0-nál, de nem egyenlő SQL_NTS vagy SQL_NULL_DATA.
HY117	A kapcsolat ismeretlen tranzakciós állapot miatt fel van függesztve. Csak a leválasztási és írásvédett függvények engedélyezettek.	(DM) A felfüggesztett állapotról további információt az SQLEndTran függvényben talál.
HYT01	A kapcsolati időkorlát lejárt	A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka az SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT keresztül van beállítva.
IM001	Az illesztőprogram nem támogatja ezt a függvényt	(DM) Az StatementHandle-hez társított illesztőprogram nem támogatja a függvényt.
IM017	A lekérdezés aszinkron értesítési módban le van tiltva	Az értesítési modell használata esetén a lekérdezés le van tiltva.
IM018	Az SQLCompleteAsync nem lett meghívva az előző aszinkron művelet végrehajtásához ezen a leírón.	Ha a leíró előző függvényhívása SQL_STILL_EXECUTING ad vissza, és ha az értesítési mód engedélyezve van, az SQLCompleteAsync-et a leírón kell meghívni a művelet utófeldolgozásához és befejezéséhez.

Ha az SQLPutData-t egy paraméter adatainak küldése közben hívják meg az SQL utasításban, akkor vissza tud adni bármely SQLSTATE-t, amelyet a kijelentés végrehajtásához hívott függvény (SQLExecute vagy SQLExecDirect) tud visszaadni. Ha az oszlop adatküldése közben hívják meg, amelyet frissítenek vagy hozzáadnak SQLBulkOperations-szel , vagy SQLSetPos-szal frissítenek, akkor bármilyen SQLBulkOperations vagy SQLSetPos által vissza tud téríthető SQLSTATE-et visszaadni.

Comments

Az SQLPutData két célra is meghívható, hogy adatokat szolgáltasson végrehajtásnál: paraméteradatok, amelyeket SQLExecute vagy SQLExecDirect hívásához használnak, vagy oszlopadatot, amelyet akkor használnak, amikor egy sor frissítés vagy hozzáadás történik az SQLBulkOperations hívásával, vagy az SQLSetPos hívásával.

Amikor egy alkalmazás SQLParamData-t hív, hogy meghatározza, melyik adatot kell küldenie, az illesztőprogram egy indikátort ad vissza, amellyel az alkalmazás meghatározhatja, melyik paraméteradatokat küldje, vagy hol találhatók az oszlopadatok. Emellett SQL_NEED_DATA-t is visszaad, ami jelzi az alkalmazásnak, hogy az SQLPutData-t kell hívnia az adatok elküldéséhez. Az SQLPutDataDataPtr argumentumban az alkalmazás egy mutatót továbbít a pufferre, amely tartalmazza a paraméter vagy oszlop tényleges adatait.

Amikor az illesztőprogram visszaadja SQL_SUCCESS SQLPutData számára, az alkalmazás ismét az SQLParamData-t hívja. Az SQLParamData SQL_NEED_DATA visszaadja a további adatküldést, amikor az alkalmazás ismét az SQLPutData-t hívja. Akkor SQL_SUCCESS visszaad, ha az összes adat végrehajtáskor elküldődött. Az alkalmazás ezután ismét az SQLParamData-t hívja. Ha az illesztőprogram SQL_NEED_DATA-ot és egy másik indikátort ad vissza a *ValuePtrPtr-ben, akkor egy másik paraméter vagy oszlop adataira van szükség, és az SQLPutData ismét meghívható. Ha az illezser SQL_SUCCESS-t ad, akkor minden adat végrehajtáskor elküldött, és az SQL utasítás végrehajtható, vagy feldolgozható az SQLBulkOperations vagy SQLSetPos hívás.

További információért arról, hogyan továbbítják a data-at-execution paraméteradatokat a kijelentés végrehajtási idején, lásd: "Paraméterértékek átadása" az SQLBindParameter és a Hosszú adatok küldése. További információért arról, hogyan frissítik vagy adják hozzá az adat-végrehajtáskor adatokat, lásd az SQLSetPos "SQLSetPos használata" című szakaszát, az SQLBulkOperations "Nagy mennyiségű frissítés könyvjelzők segítségével", valamint a Long Data és SQLSetPos és SQLBulkOperations részeket.

Note

Egy alkalmazás az SQLPutData segítségével csak akkor küldhet adatokat részekben, ha C karakter adatot küld egy oszlopba, ahol karakter, bináris vagy adatforrás-specifikus adattípus van, vagy amikor bináris C adatot küld egy oszlopba, ahol karakter, bináris vagy adatforrás-specifikus adattípus van. Ha az SQLPutData-t többször hívják bármely más feltétel mellett, akkor SQL_ERROR és SQLSTATE HY019-et (nem karakter és nembináris adatok darabokban küldve) adják vissza.

Example

A következő minta egy adatforrás nevet, amelyet Testnek hívnak. A kapcsolódó adatbázisnak tartalmaznia kell egy táblázatot, amit létrehozhatsz az alábbiak szerint:

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);  
}

Információ erről:	Nézze
Puffer kötése egy paraméterhez	SQLBindParameter függvény
Utasításfeldolgozás megszakítása	SQLCancel függvény
SQL utasítás végrehajtása	SQLExecDirect függvény
Előkészített SQL-utasítás végrehajtása	SQLExecute függvény
A következő paraméter visszaadása az adatok elküldéséhez:	SQLParamData függvény

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-08-24