2018-12-20 01:21:13 +03:00
|
|
|
.Dd December 19, 2018
|
2016-03-31 00:31:44 +03:00
|
|
|
.Dt SQLITE3_AGGREGATE_CONTEXT 3
|
|
|
|
|
.Os
|
|
|
|
|
.Sh NAME
|
|
|
|
|
.Nm sqlite3_aggregate_context
|
|
|
|
|
.Nd Obtain Aggregate Function Context
|
|
|
|
|
.Sh SYNOPSIS
|
2017-03-11 19:29:51 +03:00
|
|
|
.Ft void *
|
2016-03-31 00:31:44 +03:00
|
|
|
.Fo sqlite3_aggregate_context
|
|
|
|
|
.Fa "sqlite3_context*"
|
|
|
|
|
.Fa "int nBytes"
|
|
|
|
|
.Fc
|
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
|
Implementations of aggregate SQL functions use this routine to allocate
|
|
|
|
|
memory for storing their state.
|
|
|
|
|
.Pp
|
|
|
|
|
The first time the sqlite3_aggregate_context(C,N) routine is called
|
|
|
|
|
for a particular aggregate function, SQLite allocates N of memory,
|
|
|
|
|
zeroes out that memory, and returns a pointer to the new memory.
|
|
|
|
|
On second and subsequent calls to sqlite3_aggregate_context() for the
|
|
|
|
|
same aggregate function instance, the same buffer is returned.
|
|
|
|
|
Sqlite3_aggregate_context() is normally called once for each invocation
|
|
|
|
|
of the xStep callback and then one last time when the xFinal callback
|
|
|
|
|
is invoked.
|
|
|
|
|
When no rows match an aggregate query, the xStep() callback of the
|
|
|
|
|
aggregate function implementation is never called and xFinal() is called
|
|
|
|
|
exactly once.
|
|
|
|
|
In those cases, sqlite3_aggregate_context() might be called for the
|
|
|
|
|
first time from within xFinal().
|
|
|
|
|
.Pp
|
|
|
|
|
The sqlite3_aggregate_context(C,N) routine returns a NULL pointer when
|
|
|
|
|
first called if N is less than or equal to zero or if a memory allocate
|
|
|
|
|
error occurs.
|
|
|
|
|
.Pp
|
|
|
|
|
The amount of space allocated by sqlite3_aggregate_context(C,N) is
|
|
|
|
|
determined by the N parameter on first successful call.
|
|
|
|
|
Changing the value of N in subsequent call to sqlite3_aggregate_context()
|
|
|
|
|
within the same aggregate function instance will not resize the memory
|
|
|
|
|
allocation.
|
|
|
|
|
Within the xFinal callback, it is customary to set N=0 in calls to
|
|
|
|
|
sqlite3_aggregate_context(C,N) so that no pointless memory allocations
|
|
|
|
|
occur.
|
|
|
|
|
.Pp
|
|
|
|
|
SQLite automatically frees the memory allocated by sqlite3_aggregate_context()
|
|
|
|
|
when the aggregate query concludes.
|
|
|
|
|
.Pp
|
|
|
|
|
The first parameter must be a copy of the SQL function context
|
|
|
|
|
that is the first parameter to the xStep or xFinal callback routine
|
|
|
|
|
that implements the aggregate function.
|
|
|
|
|
.Pp
|
|
|
|
|
This routine must be called from the same thread in which the aggregate
|
|
|
|
|
SQL function is running.
|
|
|
|
|
.Sh SEE ALSO
|
|
|
|
|
.Xr sqlite3_context 3
|
