1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Convenience Routines For Running Queries</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Convenience Routines For Running Queries</h2><blockquote><pre>int sqlite3_get_table(
121
sqlite3 *db, /* An open database */
122
const char *zSql, /* SQL to be evaluated */
123
char ***pazResult, /* Results of the query */
124
int *pnRow, /* Number of result rows written here */
125
int *pnColumn, /* Number of result columns written here */
126
char **pzErrmsg /* Error msg written here */
128
void sqlite3_free_table(char **result);
129
</pre></blockquote><p>
130
This is a legacy interface that is preserved for backwards compatibility.
131
Use of this interface is not recommended.</p>
133
<p>Definition: A <b>result table</b> is memory data structure created by the
134
<a href="../c3ref/free_table.html">sqlite3_get_table()</a> interface. A result table records the
135
complete query results from one or more queries.</p>
137
<p>The table conceptually has a number of rows and columns. But
138
these numbers are not part of the result table itself. These
139
numbers are obtained separately. Let N be the number of rows
140
and M be the number of columns.</p>
142
<p>A result table is an array of pointers to zero-terminated UTF-8 strings.
143
There are (N+1)*M elements in the array. The first M pointers point
144
to zero-terminated strings that contain the names of the columns.
145
The remaining entries all point to query results. NULL values result
146
in NULL pointers. All other values are in their UTF-8 zero-terminated
147
string representation as returned by <a href="../c3ref/column_blob.html">sqlite3_column_text()</a>.</p>
149
<p>A result table might consist of one or more memory allocations.
150
It is not safe to pass a result table directly to <a href="../c3ref/free.html">sqlite3_free()</a>.
151
A result table should be deallocated using <a href="../c3ref/free_table.html">sqlite3_free_table()</a>.</p>
153
<p>As an example of the result table format, suppose a query result
158
-----------------------
162
</pre></blockquote></p>
164
<p>There are two column (M==2) and three rows (N==3). Thus the
165
result table has 8 entries. Suppose the result table is stored
166
in an array names azResult. Then azResult holds this content:</p>
169
azResult[0] = "Name";
170
azResult[1] = "Age";
171
azResult[2] = "Alice";
172
azResult[3] = "43";
173
azResult[4] = "Bob";
174
azResult[5] = "28";
175
azResult[6] = "Cindy";
176
azResult[7] = "21";
177
</pre></blockquote></p>
179
<p>The sqlite3_get_table() function evaluates one or more
180
semicolon-separated SQL statements in the zero-terminated UTF-8
181
string of its 2nd parameter and returns a result table to the
182
pointer given in its 3rd parameter.</p>
184
<p>After the application has finished with the result from sqlite3_get_table(),
185
it must pass the result table pointer to sqlite3_free_table() in order to
186
release the memory that was malloced. Because of the way the
187
<a href="../c3ref/free.html">sqlite3_malloc()</a> happens within sqlite3_get_table(), the calling
188
function must not try to call <a href="../c3ref/free.html">sqlite3_free()</a> directly. Only
189
<a href="../c3ref/free_table.html">sqlite3_free_table()</a> is able to release the memory properly and safely.</p>
191
<p>The sqlite3_get_table() interface is implemented as a wrapper around
192
<a href="../c3ref/exec.html">sqlite3_exec()</a>. The sqlite3_get_table() routine does not have access
193
to any internal data structures of SQLite. It uses only the public
194
interface defined here. As a consequence, errors that occur in the
195
wrapper layer outside of the internal <a href="../c3ref/exec.html">sqlite3_exec()</a> call are not
196
reflected in subsequent calls to <a href="../c3ref/errcode.html">sqlite3_errcode()</a> or
197
<a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.
198
</p><p>See also lists of
199
<a href="objlist.html">Objects</a>,
200
<a href="constlist.html">Constants</a>, and
201
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/free_table.html
