.Dd $Mdocdate$
.Dt SQLITE3CHANGEGROUP_CHANGE_FINISH 3
.Os
.Sh NAME
.Nm sqlite3changegroup_change_finish
.Nd finish adding one-at-at-time changes to a changegroup
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3changegroup_change_finish
.Fa "sqlite3_changegroup*"
.Fa "int bDiscard"
.Fa "char **pzErr"
.Fc
.Sh DESCRIPTION
This function may only be called following a successful call to sqlite3changegroup_change_begin().
Otherwise, it is an SQLITE_MISUSE error.
.Pp
If parameter bDiscard is non-zero, then the current change is simply
discarded.
In this case this function is always successful and SQLITE_OK returned.
.Pp
If parameter bDiscard is zero, then an attempt is made to add the current
change to the changegroup.
Assuming the changegroup is configured to produce a changeset (not
a patchset), this requires that:
.Pp
*  If the change is an INSERT or DELETE, then a value must be specified
for all columns of the new.* or old.* record, respectively.
.Pp
*  If the change is an UPDATE record, then values must be provided
for the PRIMARY KEY columns of the old.* record, but must not be provided
for PRIMARY KEY columns of the new.* record.
.Pp
*  If the change is an UPDATE record, then for each non-PRIMARY KEY
column in the old.* record for which a value has been provided, a value
must also be provided for the same column in the new.* record.
Similarly, for each non-PK column in the old.* record for which a value
is not provided, a value must not be provided for the same column in
the new.* record.
.Pp
*  All values specified for PRIMARY KEY columns must be non-NULL.
.Pp
Otherwise, it is an error.
.Pp
If the changegroup already contains a change for the same row (identified
by PRIMARY KEY columns), then the current change is combined with the
existing change in the same way as for sqlite3changegroup_add().
.Pp
For a patchset, all of the above rules apply except that it doesn't
matter whether or not values are provided for the non-PK old.* record
columns for an UPDATE or DELETE change.
This means that code used to produce a changeset using the sqlite3changegroup_change_xxx()
APIs may also be used to produce patchsets.
.Pp
If the call is successful, SQLITE_OK is returned.
Otherwise, if an error occurs, an SQLite error code is returned.
If an error is returned and parameter pzErr is not NULL, then (*pzErr)
may be set to point to a buffer containing a nul-terminated, utf-8
encoded, English language error message.
It is the responsibility of the caller to eventually free any such
error message buffer using sqlite3_free().
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 13515.
.Bd -literal
SQLITE_API int sqlite3changegroup_change_finish(
  sqlite3_changegroup*,
  int bDiscard,
  char **pzErr
);
.Ed