📄 free_table.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Convenience Routines For Running Queries</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>Convenience Routines For Running Queries</h2><blockquote><pre>int sqlite3_get_table( sqlite3*, /* An open database */ const char *sql, /* SQL to be evaluated */ char ***pResult, /* Results of the query */ int *nrow, /* Number of result rows written here */ int *ncolumn, /* Number of result columns written here */ char **errmsg /* Error msg written here */);void sqlite3_free_table(char **result);</pre></blockquote><p>Definition: A <b>result table</b> is memory data structure created by the<a href="../c3ref/free_table.html">sqlite3_get_table()</a> interface. A result table records thecomplete query results from one or more queries.</p><p>The table conceptually has a number of rows and columns. Butthese numbers are not part of the result table itself. Thesenumbers are obtained separately. Let N be the number of rowsand M be the number of columns.</p><p>A result table is an array of pointers to zero-terminatedUTF-8 strings. There are (N+1)*M elements in the array.The first M pointers point to zero-terminated strings thatcontain the names of the columns.The remaining entries all point to query results. NULLvalues are give a NULL pointer. All other values are intheir UTF-8 zero-terminated string representation as returned by<a href="../c3ref/column_blob.html">sqlite3_column_text()</a>.</p><p>A result table might consists of one or more memory allocations.It is not safe to pass a result table directly to <a href="../c3ref/free.html">sqlite3_free()</a>.A result table should be deallocated using <a href="../c3ref/free_table.html">sqlite3_free_table()</a>.</p><p>As an example of the result table format, suppose a query resultis as follows:</p><p><blockquote><pre>Name | Age-----------------------Alice | 43Bob | 28Cindy | 21</pre></blockquote></p><p>There are two column (M==2) and three rows (N==3). Thus theresult table has 8 entries. Suppose the result table is storedin an array names azResult. Then azResult holds this content:</p><p><blockquote><pre>azResult[0] = "Name";azResult[1] = "Age";azResult[2] = "Alice";azResult[3] = "43";azResult[4] = "Bob";azResult[5] = "28";azResult[6] = "Cindy";azResult[7] = "21";</pre></blockquote></p><p>The sqlite3_get_table() function evaluates one or moresemicolon-separated SQL statements in the zero-terminated UTF-8string of its 2nd parameter. It returns a result table to thepointer given in its 3rd parameter.</p><p>After the calling function has finished using the result, it shouldpass the pointer to the result table to sqlite3_free_table() in order torelease the memory that was malloc-ed. Because of the way the<a href="../c3ref/free.html">sqlite3_malloc()</a> happens within sqlite3_get_table(), the callingfunction must not try to call <a href="../c3ref/free.html">sqlite3_free()</a> directly. Only<a href="../c3ref/free_table.html">sqlite3_free_table()</a> is able to release the memory properly and safely.</p><p>The sqlite3_get_table() interface is implemented as a wrapper around<a href="../c3ref/exec.html">sqlite3_exec()</a>. The sqlite3_get_table() routine does not have accessto any internal data structures of SQLite. It uses only the publicinterface defined here. As a consequence, errors that occur in thewrapper layer outside of the internal <a href="../c3ref/exec.html">sqlite3_exec()</a> call are notreflected in subsequent calls to <a href="../c3ref/errcode.html">sqlite3_errcode()</a> or<a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F12371</td> <td valign="top">If a <a href="../c3ref/free_table.html">sqlite3_get_table()</a> fails a memory allocation, thenit frees the result table under construction, aborts thequery in process, skips any subsequent queries, sets the*resultp output pointer to NULL and returns <a href="../c3ref/c_abort.html">SQLITE_NOMEM</a>.</td></tr><tr><td valign="top">F12373</td> <td valign="top">If the ncolumn parameter to <a href="../c3ref/free_table.html">sqlite3_get_table()</a> is not NULLthen <a href="../c3ref/free_table.html">sqlite3_get_table()</a> write the number of columns in theresult set of the query into *ncolumn if the query issuccessful (if the function returns SQLITE_OK).</td></tr><tr><td valign="top">F12374</td> <td valign="top">If the nrow parameter to <a href="../c3ref/free_table.html">sqlite3_get_table()</a> is not NULLthen <a href="../c3ref/free_table.html">sqlite3_get_table()</a> write the number of rows in theresult set of the query into *nrow if the query issuccessful (if the function returns SQLITE_OK).</td></tr><tr><td valign="top">F12376</td> <td valign="top">The <a href="../c3ref/free_table.html">sqlite3_get_table()</a> function sets its *ncolumn valueto the number of columns in the result set of the query in thesql parameter, or to zero if the query in sql has an emptyresult set.</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 + -