1.Dd December 19, 2018 2.Dt SQLITE3_AGGREGATE_CONTEXT 3 3.Os 4.Sh NAME 5.Nm sqlite3_aggregate_context 6.Nd Obtain Aggregate Function Context 7.Sh SYNOPSIS 8.Ft void * 9.Fo sqlite3_aggregate_context 10.Fa "sqlite3_context*" 11.Fa "int nBytes" 12.Fc 13.Sh DESCRIPTION 14Implementations of aggregate SQL functions use this routine to allocate 15memory for storing their state. 16.Pp 17The first time the sqlite3_aggregate_context(C,N) routine is called 18for a particular aggregate function, SQLite allocates N of memory, 19zeroes out that memory, and returns a pointer to the new memory. 20On second and subsequent calls to sqlite3_aggregate_context() for the 21same aggregate function instance, the same buffer is returned. 22Sqlite3_aggregate_context() is normally called once for each invocation 23of the xStep callback and then one last time when the xFinal callback 24is invoked. 25When no rows match an aggregate query, the xStep() callback of the 26aggregate function implementation is never called and xFinal() is called 27exactly once. 28In those cases, sqlite3_aggregate_context() might be called for the 29first time from within xFinal(). 30.Pp 31The sqlite3_aggregate_context(C,N) routine returns a NULL pointer when 32first called if N is less than or equal to zero or if a memory allocate 33error occurs. 34.Pp 35The amount of space allocated by sqlite3_aggregate_context(C,N) is 36determined by the N parameter on first successful call. 37Changing the value of N in subsequent call to sqlite3_aggregate_context() 38within the same aggregate function instance will not resize the memory 39allocation. 40Within the xFinal callback, it is customary to set N=0 in calls to 41sqlite3_aggregate_context(C,N) so that no pointless memory allocations 42occur. 43.Pp 44SQLite automatically frees the memory allocated by sqlite3_aggregate_context() 45when the aggregate query concludes. 46.Pp 47The first parameter must be a copy of the SQL function context 48that is the first parameter to the xStep or xFinal callback routine 49that implements the aggregate function. 50.Pp 51This routine must be called from the same thread in which the aggregate 52SQL function is running. 53.Sh SEE ALSO 54.Xr sqlite3_context 3 55