📄 prepare.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Compiling An SQL Statement</title><style type="text/css">body { margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px;}.toolbar { font-variant: small-caps; text-align: center; line-height: 1.6em; margin: 0; padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw { background: url(../images/sw.png) 0% 100% no-repeat }.ne { background: url(../images/ne.png) 100% 0% no-repeat }.nw { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td> <div class="se"><div class="sw"><div class="ne"><div class="nw"> <div class="toolbar"> <a href="../about.html">About</a> <a href="../sitemap.html">Sitemap</a> <a href="../docs.html">Documentation</a> <a href="../download.html">Download</a> <a href="../copyright.html">License</a> <a href="../news.html">News</a> <a href="http://www.sqlite.org/cvstrac/index">Developers</a> <a href="../support.html">Support</a> </div></div></div></div></div></td></tr></table> <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Compiling An SQL Statement</h2><blockquote><pre>int sqlite3_prepare( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */);int sqlite3_prepare_v2( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */);int sqlite3_prepare16( sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */);int sqlite3_prepare16_v2( sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */);</pre></blockquote><p>To execute an SQL query, it must first be compiled into a byte-codeprogram using one of these routines.</p><p>The first argument "db" is an <a href="../c3ref/sqlite3.html">database connection</a>obtained from a prior call to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open_v2()</a>or <a href="../c3ref/open.html">sqlite3_open16()</a>.The second argument "zSql" is the statement to be compiled, encodedas either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()use UTF-16.</p><p>If the nByte argument is lessthan zero, then zSql is read up to the first zero terminator.If nByte is non-negative, then it is the maximum number ofbytes read from zSql. When nByte is non-negative, thezSql string ends at either the first '\000' or '\u0000' character orthe nByte-th byte, whichever comes first. If the caller knowsthat the supplied string is nul-terminated, then there is a smallperformance advantage to be had by passing an nByte parameter thatis equal to the number of bytes in the input string <i>including</i>the nul-terminator bytes.</p><p>*pzTail is made to point to the first byte past the end of thefirst SQL statement in zSql. These routines only compiles the firststatement in zSql, so *pzTail is left pointing to what remainsuncompiled.</p><p>*ppStmt is left pointing to a compiled <a href="../c3ref/stmt.html">prepared statement</a> that can beexecuted using <a href="../c3ref/step.html">sqlite3_step()</a>. Or if there is an error, *ppStmt isset to NULL. If the input text contains no SQL (if the inputis and empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting thecompiled SQL statementusing <a href="../c3ref/finalize.html">sqlite3_finalize()</a> after it has finished with it.</p><p>On success, <a href="../c3ref/c_abort.html">SQLITE_OK</a> is returned. Otherwise an<a href="../c3ref/c_abort.html">error code</a> is returned.</p><p>The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces arerecommended for all new programs. The two older interfaces are retainedfor backwards compatibility, but their use is discouraged.In the "v2" interfaces, the prepared statementthat is returned (the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object) contains a copy of theoriginal SQL text. This causes the <a href="../c3ref/step.html">sqlite3_step()</a> interface tobehave a differently in two ways:</p><p><ol><li>If the database schema changes, instead of returning <a href="../c3ref/c_abort.html">SQLITE_SCHEMA</a> as italways used to do, <a href="../c3ref/step.html">sqlite3_step()</a> will automatically recompile the SQLstatement and try to run it again. If the schema has changed ina way that makes the statement no longer valid, <a href="../c3ref/step.html">sqlite3_step()</a> will stillreturn <a href="../c3ref/c_abort.html">SQLITE_SCHEMA</a>. But unlike the legacy behavior,<a href="../c3ref/c_abort.html">SQLITE_SCHEMA</a> is now a fatal error. Calling<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> again will not make theerror go away. Note: use <a href="../c3ref/errcode.html">sqlite3_errmsg()</a> to find the textof the parsing error that results in an <a href="../c3ref/c_abort.html">SQLITE_SCHEMA</a> return.</li></p><p><li>When an error occurs,<a href="../c3ref/step.html">sqlite3_step()</a> will return one of the detailed<a href="../c3ref/c_abort.html">error codes</a> or <a href="../c3ref/c_ioerr_blocked.html">extended error codes</a>.The legacy behavior was that <a href="../c3ref/step.html">sqlite3_step()</a> would only return a generic<a href="../c3ref/c_abort.html">SQLITE_ERROR</a> result code and you would have to make a second call to<a href="../c3ref/reset.html">sqlite3_reset()</a> in order to find the underlying cause of the problem.With the "v2" prepare interfaces, the underlying reason for the error isreturned immediately.</li></ol></p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F13011</td> <td valign="top">The <a href="../c3ref/prepare.html">sqlite3_prepare(db,zSql,...)</a> and<a href="../c3ref/prepare.html">sqlite3_prepare_v2(db,zSql,...)</a> interfaces interpret thetext in their zSql parameter as UTF-8.</td></tr><tr><td valign="top">F13012</td> <td valign="top">The <a href="../c3ref/prepare.html">sqlite3_prepare16(db,zSql,...)</a> and<a href="../c3ref/prepare.html">sqlite3_prepare16_v2(db,zSql,...)</a> interfaces interpret thetext in their zSql parameter as UTF-16 in the native byte order.</td></tr><tr><td valign="top">F13013</td> <td valign="top">If the nByte argument to <a href="../c3ref/prepare.html">sqlite3_prepare_v2(db,zSql,nByte,...)</a>and its variants is less than zero, then SQL text isread from zSql is read up to the first zero terminator.</td></tr><tr><td valign="top">F13014</td> <td valign="top">If the nByte argument to <a href="../c3ref/prepare.html">sqlite3_prepare_v2(db,zSql,nByte,...)</a>and its variants is non-negative, then at most nBytes bytesSQL text is read from zSql.</td></tr><tr><td valign="top">F13015</td> <td valign="top">In <a href="../c3ref/prepare.html">sqlite3_prepare_v2(db,zSql,N,P,pzTail)</a> and its variantsif the zSql input text contains more than one SQL statementand pzTail is not NULL, then *pzTail is made to point to thefirst byte past the end of the first SQL statement in zSql.<font color="red">(TODO: What does *pzTail point to if there is one statement?)</font></td></tr><tr><td valign="top">F13016</td> <td valign="top">A successful call to <a href="../c3ref/prepare.html">sqlite3_prepare_v2(db,zSql,N,ppStmt,...)</a>or one of its variants writes into *ppStmt a pointer to a new<a href="../c3ref/stmt.html">prepared statement</a> or a pointer to NULLif zSql contains nothing other than whitespace or comments.</td></tr><tr><td valign="top">F13019</td> <td valign="top">The <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> interface and its variants return<a href="../c3ref/c_abort.html">SQLITE_OK</a> or an appropriate <a href="../c3ref/c_abort.html">error code</a> upon failure.</td></tr><tr><td valign="top">F13021</td> <td valign="top">Before <a href="../c3ref/prepare.html">sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)</a> or itsvariants returns an error (any value other than <a href="../c3ref/c_abort.html">SQLITE_OK</a>)it first sets *ppStmt to NULL.</td></tr></table></p><p>See also lists of <a href="objlist.html">Objects</a>, <a href="constlist.html">Constants</a>, and <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/05/12 13:08:44 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -