Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
Megfelelőség
Bevezetett verzió: ODBC 1.0 szabványmegfelelőség: ISO 92
Összefoglalás
SQLPrepare előkészít egy SQL string for execution.
Syntax
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Arguments
StatementHandle
[Bemenet] Utasításkezelő.
Utasításszöveg
[Bemenet] SQL szöveg string.
TextLength
[Bemenet] *Utasításszöveg hossza karakterekben.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR vagy SQL_INVALID_HANDLE.
Diagnostics
Amikor az SQLPrepare SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad vissza, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_STMT HandleType és egy HandleType (StatementHandle) hívja. Az alábbi táblázat felsorolja az SQLPrepare á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 | Error | Description |
|---|---|---|
| 01000 | Általános figyelmeztetés | Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 01S02 | A beállítás értéke módosult | A megadott utasításattribútum a megvalósítási munkafeltételek miatt érvénytelen volt, ezért a rendszer ideiglenesen egy hasonló értéket helyettesített. (Az SQLGetStmtAttr meghívható annak meghatározásához, hogy mi az ideiglenesen helyettesített érték.) A helyettesítő érték érvényes a StatementHandle számára, amíg a kurzor be nem zárul. A változtatható állítás attribútumok a következők: SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (A függvény SQL_SUCCESS_WITH_INFO ad vissza.) |
| 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. |
| 21S01 | Az értéklista beszúrása nem egyezik az oszloplistával | * A StatementText tartalmazott egy INSERT utasítást, és a beillesztendő értékek száma nem egyezett meg a levezetett tábla fokával. |
| 21S02 | A származtatott tábla mértéke nem egyezik az oszloplistával | * A StatementText tartalmazott egy CREATE VIEW utasítást, és a megadott nevek száma nem egyezik meg a lekérdezés által meghatározott származtatott táblával. |
| 22018 | Érvénytelen karakterérték az öntött specifikációhoz | * Az StatementText tartalmazott egy SQL utasítást, amely literált vagy paramétert tartalmazott, és az érték nem volt kompatibilis a hozzá tartozó táboszlop adattípusával. |
| 22019 | Érvénytelen feloldó karakter | Az StatementText érv tartalmazott egy LIKE predikátumot egy ESCAPE-vel a WHERE klauzulában, és az ESCAPE utáni escape karakter hossza nem volt egyenlő 1-gyel. |
| 22025 | Érvénytelen feloldási sorozat | Az StatementText érvelés tartalmazta a "LIKEmintaértékESCAPEescape karaktert" a WHERE klauzulában, és az escape karaktert követő karakter sem "%", sem "_" volt. |
| 24000 | Érvénytelen kurzorállapot | (DM) A StatementHandle kurzora nyitva volt, és meghívták a SQLFetch vagy SQLFetchScroll . A kurzor nyitva volt a StatementHandle-en, de az SQLFetch vagy SQLFetchScroll nem volt meghívva. |
| 34000 | Érvénytelen kurzornév | * ÁllításSzöveg egy pozicionált DELETE vagy pozitívált UPDATE, és a kijelentés által hivatkozott kurzor nem volt nyitott. |
| 3D000 | Érvénytelen katalógusnév | Az Utasításszövegben megadott katalógusnév érvénytelen volt. |
| 3F000 | Érvénytelen sémanév | Az Utasításszövegben megadott sémanév érvénytelen volt. |
| 42000 | Szintaxishiba vagy hozzáférés-megsértés |
*
Az StatementText olyan SQL-utasítást tartalmazott, amely nem készült el, vagy szintaxishibát tartalmazott. * A StatementText tartalmazott egy olyan kijelentést, amelyhez a felhasználó nem rendelkezett a szükséges jogosultságokkal. |
| 42S01 | Az alaptábla vagy nézet már létezik | * A StatementText tartalmazott egy CREATE TABLE vagy CREATE VIEW utasítást, és a megadott táblanév vagy nézet név már létezik. |
| 42S02 | Az alaptábla vagy nézet nem található |
*
A StatementText tartalmazott egy DROP TABLE vagy DROP VIEW egy utasítást, és a megadott táblanév vagy nézet név nem létezett. * A StatementText tartalmazott egy ALTER TABLE utasítást, és a megadott táblanév nem létezett. * Az StatementText tartalmazott egy CREATE VIEW utasítást, és a lekérdezési specifikáció által meghatározott táblanév vagy nézetnév nem létezett. * A StatementText tartalmazott egy CREATE INDEX utasítást, és a megadott táblanév nem létezett. * A StatementText tartalmazott egy GRANT vagy REVOKE utasítást, és a megadott táblanév vagy nézet nem létezett. * Az Utasításszöveg tartalmazott egy SELECT utasítást, és a megadott táblanév vagy nézetnév nem létezik. * A StatementText tartalmazott egy DELETE, INSERT, vagy UPDATE utasítást, és a megadott táblanév nem létezett. * A StatementText tartalmazott egy CREATE TABLE utasítást, és egy korlátozásban meghatározott tábla (amely más táblára utal, mint a létrehozott táblára) nem létezett. |
| 42S11 | Az index már létezik | * A StatementText tartalmazott egy CREATE INDEX utasítást, és a megadott indexnév már létezett. |
| 42S12 | Az index nem található | * A StatementText tartalmazott egy DROP INDEX utasítást, és a megadott indexnév nem létezett. |
| 42S21 | Az oszlop már létezik | * A StatementText tartalmazott egy ALTER TABLE utasítást, és az ADD záradékban megadott oszlop nem egyedi, vagy nem azonosít egy meglévő oszlopot az alaptáblában. |
| 42S22 | Az oszlop nem található |
*
A StatementText tartalmazott egy CREATE INDEX utasítást, és az oszloplistában megadott oszlopnevek közül egy vagy több nem létezett. * A StatementText tartalmazott egy GRANT vagy REVOKE utasítást, és egy meghatározott oszlopnév nem létezett. * A StatementText tartalmazott egy SELECT, DELETE, INSERT, vagy UPDATE utasítást, és egy meghatározott oszlopnév nem létezett. * A StatementText tartalmazott egy CREATE TABLE utasítást, és egy olyan oszlop, amely egy korlátozásban (amely egy másik táblázatra utal, nem a létrehozott táblára) nem létezett. |
| 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 | Művelet megszakítva | Az aszinkron feldolgozás engedélyezve lett a StatementHandle-ben. A függvényt hívták, és mielőtt befejezte volna a végrehajtást, az SQLCancel vagy SQLCancelHandle meghívása a StatementHandle-en, majd a függvényt ismét meghívták a StatementHandle-en. 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) NyilatkozatSzöveg null pointer volt. |
| HY010 | Függvényütemezési hiba | (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 akkor futott, amikor az SQLPrepare 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. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations vagy SQLSetPos lett meghívva az Utasításkezelőhöz , és SQL_NEED_DATA. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg. |
| 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. |
| HY090 | Érvénytelen sztring vagy puffer hossza | (DM) A TextLength argumentum kisebb vagy egyenlő, mint 0, de nem egyenlő SQL_NTS. |
| 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. |
| HYC00 | A választható funkció nem implementálva | Az egyidejű beállítás érvénytelen volt a definiált kurzor típusához. A SQL_ATTR_USE_BOOKMARKS utasítás attribútuma SQL_UB_VARIABLE lett beállítva, és a SQL_ATTR_CURSOR_TYPE utasítás attribútum olyan kurzortípusra lett beállítva, amelyhez az illesztőprogram nem támogatja a könyvjelzőket. |
| HYT00 | Az időtúllépés lejárt | Az időtúli időszak lejárt, mielőtt az adatforrás visszahozta az eredményhalmazt. Az időtúllépési időszak az SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT keresztül van beállítva. |
| 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. |
Comments
Az alkalmazás SQLPrepare hívja, hogy egy SQL utasítást küldjön az adatforrásnak az előkészítéshez. További információért a Előkészített végrehajtásról lásd: Előkészített végrehajtás. Az alkalmazás tartalmazhat egy vagy több paraméterjelölőt az SQL utasításban. Paraméterjelölő beépítéséhez az alkalmazás kérdőjelet (?) ágyaznak be az SQL stringbe a megfelelő helyen. A paraméterekkel kapcsolatos információkért lásd: Utasításparaméterek.
Note
Ha egy alkalmazás SQLPrepare segítségével készít elő, SQLExecute-t pedig COMMIT vagy ROLLBACK utasítás beküldésére, akkor nem lesz interoperabilis a DBMS termékek között. Tranzakció véglegesítéséhez vagy visszaállításához hívja meg az SQLEndTrant.
Az illesztervezető módosíthatja az utasítást úgy, hogy az adatforrás által használt SQL formát használja, majd elküldheti az adatforrásnak előkészítésre. Különösen az illesztőprogram módosítja az escape szekvenciákat, amelyeket bizonyos funkciók SQL szintaxisának meghatározásához használnak. (Az SQL utasítás nyelvtanának leírásáért lásd Escape Sequences in ODBC és Appendix C (Melléklet: SQL Grammar) című területet.) A meghajtó esetében a mondatazonosító azonosító hasonló az SQL beágyazott SQL kódban található utasításazonosítóhoz. Ha az adatforrás támogatja az utasításazonosítókat, az illesztőprogram küldhet egy utasításazonosítót és paraméterértékeket az adatforrásnak.
Miután egy utasítást elkészítettek, az alkalmazás a utasítás handle-t használja, hogy a későbbi függvényhívásokban hivatkozzon az utasításra. Az utasítás handle hozzátartozó előkészített utasítás újrafuttatható SQLExecute hívásával, amíg az alkalmazás fel nem szabadítja az utasítást az SQLFreeStmt hívásával a SQL_DROP opcióval, vagy amíg az utasítás handle fel nem válik az SQLPrepare, SQLExecDirect vagy valamelyik katalógus függvény (SQLColumns, SQLTables stb.) hívásában. Miután az alkalmazás elkészít egy utasítást, kérhet információt az eredményhalmaz formátumáról. Egyes megvalósításoknál az SQLDescribeCol vagy SQLDescribeParam hívása SQLPrepare után nem feltétlenül olyan hatékony, mint a függvény hívása az SQLExecute vagy SQLExecDirect után.
Néhány illesztőprogram nem tudja visszaadni a szintaxishibákat vagy hozzáférési jogsértéseket, amikor az alkalmazás SQLPrepare-t hív. Egy sofőr kezelheti a szintaxishibákat és hozzáférési szabálysértéseket, csak a szintaxishibákat, vagy sem a szintaxishibakat, sem a hozzáférési szabálysértéseket. Ezért egy alkalmazásnak képesnek kell lennie kezelni ezeket a feltételeket, amikor további kapcsolódó függvényeket, például SQLNumResultCols, SQLDescribeCol, SQLColAttribute és SQLExecute hívja.
Az illesztőprogram és az adatforrás képességeitől függően a paraméterinformációk (például adattípusok) ellenőrizhetők, amikor az utasítás elkészült (ha minden paraméter van kötve), vagy amikor végrehajtják (ha nem minden paraméter volt kötve). A maximális interoperabilitás érdekében az alkalmazásnak minden olyan paramétert el kell bonnia, amely egy régi SQL utasításra vonatkozik, mielőtt új SQL utasítást készítene ugyanezen az utasításon. Ez megakadályozza azokat a hibákat, amelyek a régi paraméterinformációk miatt keletkeznek, és az új utasításra alkalmazzák.
Important
Egy tranzakció elkötése, akár kifejezetten az SQLEndTran hívásával, akár automatikus commit módban működik, az adatforrás törli az összes hozzáférési tervet egy kapcsolaton. További információért lásd az SQLGetInfo SQL_CURSOR_COMMIT_BEHAVIOR és SQL_CURSOR_ROLLBACK_BEHAVIOR információtípusokat a Tranzakciók Hatása a kurzorokra és előkészített kimutatásokra.
Kódpélda
Lásd SQLBindParameter, SQLPutData és SQLSetPos.
Kapcsolódó funkciók
| Információ erről: | Nézze |
|---|---|
| Utasításkezelő kijelölése | SQLAllocHandle függvény |
| Puffer kötése egy eredményhalmaz oszlopához | SQLBindCol függvény |
| Puffer kötése egy paraméterhez | SQLBindParameter függvény |
| Utasításfeldolgozás megszakítása | SQLCancel függvény |
| Véglegesítési vagy visszaállítási művelet végrehajtása | SQLEndTran 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 kijelentés által érintett sor számának visszaküldése | SQLRowCount függvény |
| Kurzornév beállítása | SQLSetCursorName függvény |