Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Soulad
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92
Shrnutí
SQLPrepare připravuje SQL řetězec pro vykonání.
Syntax
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Arguments
StatementHandle
[Vstup] Popisovač příkazu
Text příkazu
[Vstup] SQL textový řetězec.
TextLength
[Vstup] Délka *StatementText v znaznach.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostics
Když SQLPrepare vrací SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLeDiagRec voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLPrepare 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.) |
| 01S02 | Změna hodnoty možnosti | Zadaný atribut příkazu byl neplatný kvůli pracovním podmínkám implementace, takže podobná hodnota byla dočasně nahrazena. (SQLGetStmtAttr lze volat pro určení dočasně nahrané hodnoty.) Substituční hodnota je platná pro StatementHandle , dokud není kurzor uzavřen. Atributy výroku, které lze změnit, jsou: 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 (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 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. |
| 21S01 | Seznam vložených hodnot neodpovídá seznamu sloupců | * StatementText obsahoval INSERT příkaz a počet vložených hodnot neodpovídal stupni odvozené tabulky. |
| 21S02 | Stupeň odvozené tabulky neodpovídá seznamu sloupců | * StatementText obsahoval CREATE VIEW příkaz a počet specifikovaných jmen není stejný jako odvozená tabulka definovaná dotazovací specifikací. |
| 22018 | Neplatná hodnota znaku pro specifikaci přetypování | * StatementText obsahoval SQL příkaz, který obsahoval literál nebo parametr, a hodnota byla nekompatibilní s datovým typem příslušného sloupce tabulky. |
| 22019 | Neplatný řídicí znak | Argument StatementText obsahoval predikát LIKE s ESCAPE v klauzuli WHERE a délka znaku escape po ESCAPE nebyla rovna 1. |
| 22025 | Neplatná řídicí sekvence | Argumentový StatementText obsahoval v klauzuli WHERE "LIKEpattern valueESCAPEcharacter" a znak následující za escape znakem v hodnotě vzoru nebyl ani "%", ani "_". |
| 24000 | Neplatný stav kurzoru | (DM) Kurzor byl otevřen na StatementHandle a byl volán SQLFetch nebo SQLFetchScroll . Na StatementHandle byl otevřený kurzor, ale SQLFetch nebo SQLFetchScroll nebyly volány. |
| 34000 | Neplatný název kurzoru | * StatementText obsahoval pozicied DELETE nebo positioned UPDATE, a kurzor, na který se odkazovalo připravované tvrzení, nebyl otevřený. |
| 3D000 | Neplatný název katalogu | Název katalogu zadaný v části StatementText byl neplatný. |
| 3F000 | Neplatný název schématu | Název schématu zadaný v části StatementText byl neplatný. |
| 42000 | Chyba syntaxe nebo porušení přístupu |
*
Příkaz StatementText obsahoval příkaz SQL, který nebyl předparovatelný nebo obsahoval chybu syntaxe. * StatementText obsahoval příkaz, pro který uživatel neměl požadovaná oprávnění. |
| 42S01 | Základní tabulka nebo zobrazení již existují. | * StatementText obsahoval CREATE TABLE příkaz or CREATE VIEW a specifikovaný název tabulky nebo view již existuje. |
| 42S02 | Základní tabulka nebo zobrazení nebyly nalezeny. |
*
StatementText obsahoval nebo DROP TABLEDROP VIEW příkaz, přičemž specifikovaný název tabulky nebo view neexistoval. * StatementText obsahovalALTER TABLE příkaz a specifikovaný název tabulky neexistoval. * StatementText obsahoval CREATE VIEW příkaz a název tabulky nebo view definovaný specifikací dotazu neexistoval. * StatementText obsahoval CREATE INDEX příkaz a specifikovaný název tabulky neexistoval. * StatementText obsahoval GRANT příkaz or REVOKE a specifikovaný název tabulky nebo view neexistoval. * Text příkazu StatementText obsahoval příkaz SELECT a zadaný název tabulky nebo název zobrazení neexistuje. * StatementText obsahoval DELETE, INSERT, nebo UPDATE příkaz, a specifikovaný název tabulky neexistoval. * StatementText obsahoval CREATE TABLE příkaz a tabulka specifikovaná v omezení (odkazující na tabulku jinou než tvořenou) neexistovala. |
| 42S11 | Index již existuje. | * StatementText obsahovalCREATE INDEX příkaz a specifikovaný název indexu již existoval. |
| 42S12 | Index nebyl nalezen. | * StatementText obsahoval DROP INDEX příkaz a specifikovaný název indexu neexistoval. |
| 42S21 | Sloupec již existuje. | * StatementText obsahovalALTER TABLE příkaz a sloupec specifikovaný v klauzuli ADD není jedinečný ani neidentifikuje existující sloupec v základní tabulce. |
| 42S22 | Sloupec nebyl nalezen. |
*
StatementText obsahovalCREATE INDEX příkaz a jeden nebo více jmen sloupců uvedených v seznamu sloupců neexistovalo. * StatementText obsahoval GRANT příkaz or REVOKE a specifikovaný název sloupce neexistoval. * StatementText obsahoval SELECT, DELETE, INSERT, nebo UPDATE příkaz, a specifikovaný název sloupce neexistoval. * StatementText obsahoval CREATE TABLE příkaz a sloupec specifikovaný v omezení (odkazující na tabulku jinou než tvořenou) neexistoval. |
| 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 vyvolána a před dokončením vykonávání byl na StatementHandlezavolán SQLCancel nebo SQLCancelHandle a poté byla funkce znovu volána na 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) VýrokText byl nulový ukazatel. |
| HY010 | Chyba posloupnosti funkcí | (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 vykonávala, když byla volána funkce SQLPrepare . (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. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle a vráceny SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. |
| 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. |
| HY090 | Neplatná délka řetězce nebo vyrovnávací paměti | (DM) Argument TextLength byl menší nebo roven 0, ale nerovná se SQL_NTS. |
| 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. |
| HYC00 | Nepovinná funkce není implementována. | Nastavení souběžnosti bylo neplatné pro typ kurzoru, který byl definován. Atribut příkazu SQL_ATTR_USE_BOOKMARKS byl nastaven na SQL_UB_VARIABLE a atribut příkazu SQL_ATTR_CURSOR_TYPE byl nastaven na typ kurzoru, pro který ovladač nepodporuje záložky. |
| HYT00 | Vypršel časový limit. | Časová doba vypršela dříve, než zdroj dat vrátil výslednou sadu. Časový limit je nastavený prostřednictvím sqlSetStmtAttr SQL_ATTR_QUERY_TIMEOUT. |
| 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. |
Comments
Aplikace volá SQLPrepare a pošle SQL příkaz ke zdroji dat k přípravě. Pro více informací o připravené realizaci viz Připravená realizace. Aplikace může zahrnout jeden nebo více parametrů v SQL příkazu. Pro zařazení parametru aplikace vloží otazník (?) do SQL řetězce na příslušné pozici. Informace oparametrch
Note
Pokud aplikace používá SQLPrepare k přípravě a SQLExecute k odeslání příkazu COMMIT nebo ROLLBACK , nebude interoperabilní mezi produkty DBMS. Chcete-li potvrdit nebo vrátit transakce zpět, zavolejte SQLEndTran.
Ovladač může příkaz upravit tak, aby používal formu SQL používanou datovým zdrojem, a poté jej odeslat datovému zdroji k přípravě. Konkrétně ovladač upravuje escape sekvence používané k definování SQL syntaxe pro určité funkce. (Pro popis SQL příkazové gramatiky viz Escape Sequences in ODBC a Appendix C: SQL Grammar.) Pro ovladač je handle příkazu podobný identifikátoru příkazu v embedded SQL kódu. Pokud zdroj dat podporuje identifikátory příkazů, může ovladač odeslat identifikátor příkazu a hodnoty parametrů do zdroje.
Po přípravě příkazu aplikace používá handle příkazu k odkazu na příkaz v pozdějších volání funkcí. Připravený příkaz spojený s handle příkazu lze znovu spustit voláním SQLExecute , dokud aplikace neuvolní příkaz voláním SQLFreeStmt s volbou SQL_DROP, nebo dokud není handle příkazu použit při volání SQLPrepare, SQLExecDirect nebo některé z katalogových funkcí (SQLColumns, SQLTables a podobně). Jakmile aplikace připraví příkaz, může požadovat informace o formátu výsledné množiny. U některých implementací nemusí být volání SQLDescribeCol nebo SQLDescribeParam po SQLPrepare tak efektivní jako volání funkce po SQLExecute nebo SQLExecDirect.
Některé ovladače nemohou vrátit syntaxní chyby nebo porušení přístupu, když aplikace volá SQLPrepare. Ovladač dokáže řešit syntaxní chyby a porušení přístupu, pouze chyby syntaxe, nebo ani chyby syntaxe či porušení přístupu. Proto musí aplikace být schopna zvládnout tyto podmínky při volání dalších souvisejících funkcí, jako jsou SQLNumResultCols, SQLDescribeCol, SQLColAttribute a SQLExecute.
V závislosti na schopnostech ovladače a zdroje dat mohou být informace o parametrech (například datové typy) kontrolovány při přípravě příkazu (pokud jsou všechny parametry omezeny) nebo při jeho provedení (pokud nejsou všechny parametry omezeny). Pro maximální interoperabilitu by aplikace měla před přípravou nového SQL příkazu odvázat všechny parametry, které se vztahovaly na starý SQL příkaz. To zabraňuje chybám, které jsou způsobeny aplikací starých parametrů na nový příkaz.
Important
Potvrzování transakce, ať už explicitním voláním SQLEndTran nebo prací v režimu automatického závazku, může způsobit, že zdroj dat smaže přístupové plány pro všechny příkazy na spojení. Pro více informací viz typy informací SQL_CURSOR_COMMIT_BEHAVIOR a SQL_CURSOR_ROLLBACK_BEHAVIOR v SQLGetInfo a Vliv transakcí na kurzory a připravené výpisy.
Příklad kódu
Viz SQLBindParameter, SQLPutData a SQLSetPos.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Přiřazení rukojeti příkazu | SQLAllocHandle Function |
| Vytvoření vazby vyrovnávací paměti ke sloupci v sadě výsledků | SQLBindCol – funkce |
| Vazba bufferu na parametr | Funkce SQLBindParameter |
| Zrušení zpracování příkazů | SQLCancel – funkce |
| Provedení operace potvrzení nebo vrácení zpět | FUNKCE SQLEndTran |
| Provádění SQL příkazu | SQLExecDirect Function |
| Spuštění připraveného příkazu SQL | FUNKCE SQLExecute |
| Vrácení počtu řádků ovlivněných příkazem | Funkce SQLRowCount |
| Nastavení názvu kurzoru | FUNKCE SQLSetCursorName |