Debian Codegraph @

www/session/sqlite3session_attach.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>Attach A Table To A Session Object</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 <a href="../session/intro.html"><h2>Session Module C Interface</h2></a><h2>Attach A Table To A Session Object</h2><blockquote><pre>int sqlite3session_attach(
119 sqlite3_session *pSession, /* Session object */
120 const char *zTab /* Table name */
121 );
122 </pre></blockquote><p>
123 If argument zTab is not NULL, then it is the name of a table to attach
124 to the session object passed as the first argument. All subsequent changes
125 made to the table while the session object is enabled will be recorded. See
126 documentation for <a href="../session/sqlite3session_changeset.html">sqlite3session_changeset()</a> for further details.</p>
127
128 <p>Or, if argument zTab is NULL, then changes are recorded for all tables
129 in the database. If additional tables are added to the database (by
130 executing "CREATE TABLE" statements) after this call is made, changes for
131 the new tables are also recorded.</p>
132
133 <p>Changes can only be recorded for tables that have a PRIMARY KEY explicitly
134 defined as part of their CREATE TABLE statement. It does not matter if the
135 PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
136 KEY may consist of a single column, or may be a composite key.</p>
137
138 <p>It is not an error if the named table does not exist in the database. Nor
139 is it an error if the named table does not have a PRIMARY KEY. However,
140 no changes will be recorded in either of these scenarios.</p>
141
142 <p>Changes are not recorded for individual rows that have NULL values stored
143 in one or more of their PRIMARY KEY columns.</p>
144
145 <p>SQLITE_OK is returned if the call completes without error. Or, if an error
146 occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.</p>
147
148 <p><h3>Special sqlite_stat1 Handling</h3></p>
149
150 <p>As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
151 some of the rules above. In SQLite, the schema of sqlite_stat1 is:
152 <pre>
153 &nbsp; CREATE TABLE sqlite_stat1(tbl,idx,stat)
154 </pre></p>
155
156 <p>Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
157 recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
158 are recorded for rows for which (idx IS NULL) is true. However, for such
159 rows a zero-length blob (SQL value X'') is stored in the changeset or
160 patchset instead of a NULL value. This allows such changesets to be
161 manipulated by legacy implementations of sqlite3changeset_invert(),
162 concat() and similar.</p>
163
164 <p>The sqlite3changeset_apply() function automatically converts the
165 zero-length blob back to a NULL value when updating the sqlite_stat1
166 table. However, if the application calls sqlite3changeset_new(),
167 sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
168 iterator directly (including on a changeset iterator passed to a
169 conflict-handler callback) then the X'' value is returned. The application
170 must translate X'' to NULL itself if required.</p>
171
172 <p>Legacy (older than 3.22.0) versions of the sessions module cannot capture
173 changes made to the sqlite_stat1 table. Legacy versions of the
174 sqlite3changeset_apply() function silently ignore any modifications to the
175 sqlite_stat1 table that are part of a changeset or patchset.
176 </p><p>See also lists of
177 <a href="../session/objlist.html">Objects</a>,
178 <a href="../session/constlist.html">Constants</a>, and
179 <a href="../session/funclist.html">Functions</a>.</p>
180