Debian Codegraph @

www/c3ref/free_table.html

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