Debian Codegraph @

www/session/sqlite3session_changeset.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>Generate A Changeset From 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>Generate A Changeset From A Session Object</h2><blockquote><pre>int sqlite3session_changeset(
119 sqlite3_session *pSession, /* Session object */
120 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
121 void **ppChangeset /* OUT: Buffer containing changeset */
122 );
123 </pre></blockquote><p>
124 Obtain a changeset containing changes to the tables attached to the
125 session object passed as the first argument. If successful,
126 set *ppChangeset to point to a buffer containing the changeset
127 and *pnChangeset to the size of the changeset in bytes before returning
128 SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
129 zero and return an SQLite error code.</p>
130
131 <p>A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
132 each representing a change to a single row of an attached table. An INSERT
133 change contains the values of each field of a new database row. A DELETE
134 contains the original values of each field of a deleted database row. An
135 UPDATE change contains the original values of each field of an updated
136 database row along with the updated values for each updated non-primary-key
137 column. It is not possible for an UPDATE change to represent a change that
138 modifies the values of primary key columns. If such a change is made, it
139 is represented in a changeset as a DELETE followed by an INSERT.</p>
140
141 <p>Changes are not recorded for rows that have NULL values stored in one or
142 more of their PRIMARY KEY columns. If such a row is inserted or deleted,
143 no corresponding change is present in the changesets returned by this
144 function. If an existing row with one or more NULL values stored in
145 PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
146 only an INSERT is appears in the changeset. Similarly, if an existing row
147 with non-NULL PRIMARY KEY values is updated so that one or more of its
148 PRIMARY KEY columns are set to NULL, the resulting changeset contains a
149 DELETE change only.</p>
150
151 <p>The contents of a changeset may be traversed using an iterator created
152 using the <a href="../session/sqlite3changeset_start.html">sqlite3changeset_start()</a> API. A changeset may be applied to
153 a database with a compatible schema using the <a href="../session/sqlite3changeset_apply.html">sqlite3changeset_apply()</a>
154 API.</p>
155
156 <p>Within a changeset generated by this function, all changes related to a
157 single table are grouped together. In other words, when iterating through
158 a changeset or when applying a changeset to a database, all changes related
159 to a single table are processed before moving on to the next table. Tables
160 are sorted in the same order in which they were attached (or auto-attached)
161 to the sqlite3_session object. The order in which the changes related to
162 a single table are stored is undefined.</p>
163
164 <p>Following a successful call to this function, it is the responsibility of
165 the caller to eventually free the buffer that *ppChangeset points to using
166 <a href="../c3ref/free.html">sqlite3_free()</a>.</p>
167
168 <p><h3>Changeset Generation</h3></p>
169
170 <p>Once a table has been attached to a session object, the session object
171 records the primary key values of all new rows inserted into the table.
172 It also records the original primary key and other column values of any
173 deleted or updated rows. For each unique primary key value, data is only
174 recorded once - the first time a row with said primary key is inserted,
175 updated or deleted in the lifetime of the session.</p>
176
177 <p>There is one exception to the previous paragraph: when a row is inserted,
178 updated or deleted, if one or more of its primary key columns contain a
179 NULL value, no record of the change is made.</p>
180
181 <p>The session object therefore accumulates two types of records - those
182 that consist of primary key values only (created when the user inserts
183 a new record) and those that consist of the primary key values and the
184 original values of other table columns (created when the users deletes
185 or updates a record).</p>
186
187 <p>When this function is called, the requested changeset is created using
188 both the accumulated records and the current contents of the database
189 file. Specifically:</p>
190
191 <p><ul>
192 <li> For each record generated by an insert, the database is queried
193 for a row with a matching primary key. If one is found, an INSERT
194 change is added to the changeset. If no such row is found, no change
195 is added to the changeset.</p>
196
197 <p> <li> For each record generated by an update or delete, the database is
198 queried for a row with a matching primary key. If such a row is
199 found and one or more of the non-primary key fields have been
200 modified from their original values, an UPDATE change is added to
201 the changeset. Or, if no such row is found in the table, a DELETE
202 change is added to the changeset. If there is a row with a matching
203 primary key in the database, but all fields contain their original
204 values, no change is added to the changeset.
205 </ul></p>
206
207 <p>This means, amongst other things, that if a row is inserted and then later
208 deleted while a session object is active, neither the insert nor the delete
209 will be present in the changeset. Or if a row is deleted and then later a
210 row with the same primary key values inserted while a session object is
211 active, the resulting changeset will contain an UPDATE change instead of
212 a DELETE and an INSERT.</p>
213
214 <p>When a session object is disabled (see the <a href="../session/sqlite3session_enable.html">sqlite3session_enable()</a> API),
215 it does not accumulate records when rows are inserted, updated or deleted.
216 This may appear to have some counter-intuitive effects if a single row
217 is written to more than once during a session. For example, if a row
218 is inserted while a session object is enabled, then later deleted while
219 the same session object is disabled, no INSERT record will appear in the
220 changeset, even though the delete took place while the session was disabled.
221 Or, if one field of a row is updated while a session is enabled, and
222 then another field of the same row is updated while the session is disabled,
223 the resulting changeset will contain an UPDATE change that updates both
224 fields.
225 </p><p>See also lists of
226 <a href="../session/objlist.html">Objects</a>,
227 <a href="../session/constlist.html">Constants</a>, and
228 <a href="../session/funclist.html">Functions</a>.</p>
229