1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Convenience Routines For Running Queries</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_free_table sqlite3_get_table -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Convenience Routines For Running Queries</h2>
</div>
<blockquote><pre>
int sqlite3_get_table(
sqlite3 *db, /* An open database */
const char *zSql, /* SQL to be evaluated */
char ***pazResult, /* Results of the query */
int *pnRow, /* Number of result rows written here */
int *pnColumn, /* Number of result columns written here */
char **pzErrmsg /* Error msg written here */
);
void sqlite3_free_table(char **result);
</pre></blockquote>
<p>
This is a legacy interface that is preserved for backwards compatibility.
Use of this interface is not recommended.</p>
<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 the
complete query results from one or more queries.</p>
<p>The table conceptually has a number of rows and columns. But
these numbers are not part of the result table itself. These
numbers are obtained separately. Let N be the number of rows
and M be the number of columns.</p>
<p>A result table is an array of pointers to zero-terminated UTF-8 strings.
There are (N+1)*M elements in the array. The first M pointers point
to zero-terminated strings that contain the names of the columns.
The remaining entries all point to query results. NULL values result
in NULL pointers. All other values are in their 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 consist 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 result
is as follows:</p>
<p><blockquote><pre>
Name | Age
-----------------------
Alice | 43
Bob | 28
Cindy | 21
</pre></blockquote></p>
<p>There are two columns (M==2) and three rows (N==3). Thus the
result table has 8 entries. Suppose the result table is stored
in an array named 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 more
semicolon-separated SQL statements in the zero-terminated UTF-8
string of its 2nd parameter and returns a result table to the
pointer given in its 3rd parameter.</p>
<p>After the application has finished with the result from sqlite3_get_table(),
it must pass the result table pointer to sqlite3_free_table() in order to
release the memory that was malloced. Because of the way the
<a href="../c3ref/free.html">sqlite3_malloc()</a> happens within sqlite3_get_table(), the calling
function 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 access
to any internal data structures of SQLite. It uses only the public
interface defined here. As a consequence, errors that occur in the
wrapper layer outside of the internal <a href="../c3ref/exec.html">sqlite3_exec()</a> call are not
reflected in subsequent calls to <a href="../c3ref/errcode.html">sqlite3_errcode()</a> or
<a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.
</p><p>See also lists of
<a href="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|
