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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
<!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>Generate A Changeset From A Session Object</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>
<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(
sqlite3_session *pSession, /* Session object */
int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
void **ppChangeset /* OUT: Buffer containing changeset */
);
</pre></blockquote><p>
Obtain a changeset containing changes to the tables attached to the
session object passed as the first argument. If successful,
set *ppChangeset to point to a buffer containing the changeset
and *pnChangeset to the size of the changeset in bytes before returning
SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
zero and return an SQLite error code.</p>
<p>A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
each representing a change to a single row of an attached table. An INSERT
change contains the values of each field of a new database row. A DELETE
contains the original values of each field of a deleted database row. An
UPDATE change contains the original values of each field of an updated
database row along with the updated values for each updated non-primary-key
column. It is not possible for an UPDATE change to represent a change that
modifies the values of primary key columns. If such a change is made, it
is represented in a changeset as a DELETE followed by an INSERT.</p>
<p>Changes are not recorded for rows that have NULL values stored in one or
more of their PRIMARY KEY columns. If such a row is inserted or deleted,
no corresponding change is present in the changesets returned by this
function. If an existing row with one or more NULL values stored in
PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
only an INSERT is appears in the changeset. Similarly, if an existing row
with non-NULL PRIMARY KEY values is updated so that one or more of its
PRIMARY KEY columns are set to NULL, the resulting changeset contains a
DELETE change only.</p>
<p>The contents of a changeset may be traversed using an iterator created
using the <a href="../session/sqlite3changeset_start.html">sqlite3changeset_start()</a> API. A changeset may be applied to
a database with a compatible schema using the <a href="../session/sqlite3changeset_apply.html">sqlite3changeset_apply()</a>
API.</p>
<p>Within a changeset generated by this function, all changes related to a
single table are grouped together. In other words, when iterating through
a changeset or when applying a changeset to a database, all changes related
to a single table are processed before moving on to the next table. Tables
are sorted in the same order in which they were attached (or auto-attached)
to the sqlite3_session object. The order in which the changes related to
a single table are stored is undefined.</p>
<p>Following a successful call to this function, it is the responsibility of
the caller to eventually free the buffer that *ppChangeset points to using
<a href="../c3ref/free.html">sqlite3_free()</a>.</p>
<p><h3>Changeset Generation</h3></p>
<p>Once a table has been attached to a session object, the session object
records the primary key values of all new rows inserted into the table.
It also records the original primary key and other column values of any
deleted or updated rows. For each unique primary key value, data is only
recorded once - the first time a row with said primary key is inserted,
updated or deleted in the lifetime of the session.</p>
<p>There is one exception to the previous paragraph: when a row is inserted,
updated or deleted, if one or more of its primary key columns contain a
NULL value, no record of the change is made.</p>
<p>The session object therefore accumulates two types of records - those
that consist of primary key values only (created when the user inserts
a new record) and those that consist of the primary key values and the
original values of other table columns (created when the users deletes
or updates a record).</p>
<p>When this function is called, the requested changeset is created using
both the accumulated records and the current contents of the database
file. Specifically:</p>
<p><ul>
<li> For each record generated by an insert, the database is queried
for a row with a matching primary key. If one is found, an INSERT
change is added to the changeset. If no such row is found, no change
is added to the changeset.</p>
<p> <li> For each record generated by an update or delete, the database is
queried for a row with a matching primary key. If such a row is
found and one or more of the non-primary key fields have been
modified from their original values, an UPDATE change is added to
the changeset. Or, if no such row is found in the table, a DELETE
change is added to the changeset. If there is a row with a matching
primary key in the database, but all fields contain their original
values, no change is added to the changeset.
</ul></p>
<p>This means, amongst other things, that if a row is inserted and then later
deleted while a session object is active, neither the insert nor the delete
will be present in the changeset. Or if a row is deleted and then later a
row with the same primary key values inserted while a session object is
active, the resulting changeset will contain an UPDATE change instead of
a DELETE and an INSERT.</p>
<p>When a session object is disabled (see the <a href="../session/sqlite3session_enable.html">sqlite3session_enable()</a> API),
it does not accumulate records when rows are inserted, updated or deleted.
This may appear to have some counter-intuitive effects if a single row
is written to more than once during a session. For example, if a row
is inserted while a session object is enabled, then later deleted while
the same session object is disabled, no INSERT record will appear in the
changeset, even though the delete took place while the session was disabled.
Or, if one field of a row is updated while a session is disabled, and
another field of the same row is updated while the session is enabled, the
resulting changeset will contain an UPDATE change that updates both fields.
</p><p>See also lists of
<a href="../session/objlist.html">Objects</a>,
<a href="../session/constlist.html">Constants</a>, and
<a href="../session/funclist.html">Functions</a>.</p>
|
