1.Dd December 19, 2018 2.Dt SQLITE3CHANGESET_START 3 3.Os 4.Sh NAME 5.Nm sqlite3changeset_start , 6.Nm sqlite3changeset_start_v2 7.Nd Create An Iterator To Traverse A Changeset 8.Sh SYNOPSIS 9.Ft int 10.Fo sqlite3changeset_start 11.Fa "sqlite3_changeset_iter **pp" 12.Fa "int nChangeset" 13.Fa "void *pChangeset " 14.Fc 15.Ft int 16.Fo sqlite3changeset_start_v2 17.Fa "sqlite3_changeset_iter **pp" 18.Fa "int nChangeset" 19.Fa "void *pChangeset" 20.Fa "int flags " 21.Fc 22.Sh DESCRIPTION 23Create an iterator used to iterate through the contents of a changeset. 24If successful, *pp is set to point to the iterator handle and SQLITE_OK 25is returned. 26Otherwise, if an error occurs, *pp is set to zero and an SQLite error 27code is returned. 28.Pp 29The following functions can be used to advance and query a changeset 30iterator created by this function: 31.Bl -bullet 32.It 33sqlite3changeset_next() 34.It 35sqlite3changeset_op() 36.It 37sqlite3changeset_new() 38.It 39sqlite3changeset_old() 40.El 41.Pp 42It is the responsibility of the caller to eventually destroy the iterator 43by passing it to sqlite3changeset_finalize(). 44The buffer containing the changeset (pChangeset) must remain valid 45until after the iterator is destroyed. 46.Pp 47Assuming the changeset blob was created by one of the sqlite3session_changeset(), 48sqlite3changeset_concat() or sqlite3changeset_invert() 49functions, all changes within the changeset that apply to a single 50table are grouped together. 51This means that when an application iterates through a changeset using 52an iterator created by this function, all changes that relate to a 53single table are visited consecutively. 54There is no chance that the iterator will visit a change the applies 55to table X, then one for table Y, and then later on visit another change 56for table X. 57.Pp 58The behavior of sqlite3changeset_start_v2() and its streaming equivalent 59may be modified by passing a combination of supported flags 60as the 4th parameter. 61.Pp 62Note that the sqlite3changeset_start_v2() API is still \fBexperimental\fP 63and therefore subject to change. 64.Sh SEE ALSO 65.Xr sqlite3changeset_concat 3 , 66.Xr sqlite3changeset_finalize 3 , 67.Xr sqlite3changeset_invert 3 , 68.Xr sqlite3changeset_new 3 , 69.Xr sqlite3changeset_next 3 , 70.Xr sqlite3changeset_old 3 , 71.Xr sqlite3changeset_op 3 , 72.Xr sqlite3session_changeset 3 , 73.Xr SQLITE_CHANGESETSTART_INVERT 3 74