Hosszú adatok küldése

A DBMS-ek a hosszú adatokat bármely karakterként vagy bináris adatként definiálják egy bizonyos méreten, például 254 karakteren keresztül. Előfordulhat, hogy a hosszú adatok teljes elemét nem lehet a memóriában tárolni, például ha az elem hosszú szöveges dokumentumot vagy bitképet jelöl. Mivel ezek az adatok nem tárolhatók egyetlen pufferben, az adatforrás az utasítás végrehajtásakor az SQLPutData részeiben küldi el az illesztőprogramnak. Azokat a paramétereket, amelyekre a végrehajtás során adatokat küldenek, adatvégrehajtási paramétereknek nevezzük.

Megjegyzés:

Az alkalmazások bármilyen típusú adatot küldhetnek a végrehajtási időben az SQLPutData használatával, bár csak karakter- és bináris adatok küldhetők részekben. Ha azonban az adatok elég kicsik ahhoz, hogy egyetlen pufferben elférjenek, általában nincs ok az SQLPutData használatára. Sokkal egyszerűbb a puffer kötése, és lehetővé tenni, hogy az illesztőprogram lekérje az adatokat a pufferből.

Ha végrehajtáskor szeretne adatokat küldeni, az alkalmazás a következő műveleteket hajtja végre:

1. Egy 32 bites értéket ad át, amely a paramétert az SQLBindParameterParameterValuePtr argumentumában azonosítja a puffer címének átadása helyett. Ezt az értéket az illesztőprogram nem elemzi. Később visszakerül az alkalmazásba, ezért az az alkalmazás számára jelent valamit. Ez lehet például az adatokat tartalmazó fájl paraméterének vagy leírójának száma.

2. Az SQLBindParameterStrLen_or_IndPtr argumentumában adja át a hossz-/mutatópuffer címét.

3. Tárolja a SQL_DATA_AT_EXEC vagy a SQL_LEN_DATA_AT_EXEC(hossz) makró eredményét a hossz-/mutatópufferben. Mindkét érték azt jelzi az illesztőprogramnak, hogy a paraméter adatait az SQLPutData küldi el. SQL_LEN_DATA_AT_EXEC(hossz) akkor használatos, ha hosszú adatokat küld egy adatforrásnak, és tudnia kell, hogy hány bájtnyi hosszú adatot küld el, hogy az előre elhelyezhesse a helyet. Annak megállapításához, hogy egy adatforrásnak szüksége van-e erre az értékre, az alkalmazás meghívja az SQLGetInfo-t a SQL_NEED_LONG_DATA_LEN lehetőséggel. Minden illesztőprogramnak támogatnia kell ezt a makrót; ha az adatforráshoz nem szükséges a bájthossz, az illesztőprogram figyelmen kívül hagyhatja.

4. Meghívja az SQLExecute vagyaz SQLExecDirect parancsot. Az illesztő felderíti, hogy a hossz/mutató puffer tartalmazza a SQL_DATA_AT_EXEC vagy a SQL_LEN_DATA_AT_EXEC(hossz) makró eredményét, és a függvény visszatérési értékeként SQL_NEED_DATA ad vissza.

5. Meghívja az SQLParamData-t a SQL_NEED_DATA visszatérési értékre válaszul. Ha hosszú adatokat kell elküldeni, az SQLParamData SQL_NEED_DATA ad vissza. A ValuePtrPtr argumentum által mutatott pufferben az illesztő az adatvégrehajtási paramétert azonosító értéket adja vissza. Ha egynél több adatvégrehajtási paraméter van, az alkalmazásnak ezt az értéket kell használnia annak meghatározásához, hogy melyik paraméternek kell adatokat küldenie; az illesztőnek nem kell adatokat kérnie az adatvégrehajtási paraméterekről egy adott sorrendben.

6. Meghívja az SQLPutData-t , hogy küldje el a paraméteradatokat az illesztőprogramnak. Ha a paraméteradatok nem férnek bele egyetlen pufferbe, ahogyan a hosszú adatok esetében is gyakran előfordul, az alkalmazás ismételten meghívja az SQLPutData-t , hogy részekben küldje el az adatokat; az illesztőprogramon és az adatforráson múlik az adatok újraértékelése. Ha az alkalmazás null-terminált sztring adatot ad át, az illesztőprogramnak vagy az adatforrásnak el kell távolítania a null-terminálási karaktert az összeszerelési folyamat részeként.

7. Ismét meghívja az SQLParamData-t , hogy jelezze, hogy elküldte a paraméter összes adatát. Ha vannak olyan adatvégrehajtási paraméterek, amelyekhez nem lettek elküldve adatok, az illesztő visszaadja a SQL_NEED_DATA és a következő paramétert azonosító értéket; az alkalmazás visszatér a 6. lépéshez. Ha az összes adatvégrehajtási paraméterhez adatokat küldtek, a rendszer végrehajtja az utasítást. Az SQLParamData SQL_SUCCESS vagy SQL_SUCCESS_WITH_INFO ad vissza, és bármilyen visszatérési értéket vagy diagnosztikai értéket visszaadhat, amelyet az SQLExecute vagy az SQLExecDirect vissza tud adni.

Miután az SQLExecute vagy az SQLExecDirect visszaadja az SQL_NEED_DATA kódot, és mielőtt az adatok teljesen elküldésre kerültek volna az utolsó végrehajtáskor megadott paraméterhez, az utasítás adatszükségleti állapotban van. Bár egy utasítás adatszükségleti állapotban van, az alkalmazás csak SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField vagy SQLGetDiagRec hívására képes; minden más függvény az SQLSTATE HY010-et adja vissza (függvényütemezési hiba). Az SQLCancel meghívása megszakítja az utasítás végrehajtását, és visszaadja az előző állapotba. További információkért lásd a B függeléket: ODBC állapotátmenet táblázatok.

Az adatok végrehajtási időben történő küldéséhez lásd az SQLPutData függvény leírását.