1.Dd January 24, 2024 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.In sqlite3.h 9.Ft void * 10.Fo sqlite3_aggregate_context 11.Fa "sqlite3_context*" 12.Fa "int nBytes" 13.Fc 14.Sh DESCRIPTION 15Implementations of aggregate SQL functions use this routine to allocate 16memory for storing their state. 17.Pp 18The first time the sqlite3_aggregate_context(C,N) routine is called 19for a particular aggregate function, SQLite allocates N bytes of memory, 20zeroes out that memory, and returns a pointer to the new memory. 21On second and subsequent calls to sqlite3_aggregate_context() for the 22same aggregate function instance, the same buffer is returned. 23Sqlite3_aggregate_context() is normally called once for each invocation 24of the xStep callback and then one last time when the xFinal callback 25is invoked. 26When no rows match an aggregate query, the xStep() callback of the 27aggregate function implementation is never called and xFinal() is called 28exactly once. 29In those cases, sqlite3_aggregate_context() might be called for the 30first time from within xFinal(). 31.Pp 32The sqlite3_aggregate_context(C,N) routine returns a NULL pointer when 33first called if N is less than or equal to zero or if a memory allocation 34error occurs. 35.Pp 36The amount of space allocated by sqlite3_aggregate_context(C,N) is 37determined by the N parameter on first successful call. 38Changing the value of N in any subsequent call to sqlite3_aggregate_context() 39within the same aggregate function instance will not resize the memory 40allocation. 41Within the xFinal callback, it is customary to set N=0 in calls to 42sqlite3_aggregate_context(C,N) so that no pointless memory allocations 43occur. 44.Pp 45SQLite automatically frees the memory allocated by sqlite3_aggregate_context() 46when the aggregate query concludes. 47.Pp 48The first parameter must be a copy of the SQL function context 49that is the first parameter to the xStep or xFinal callback routine 50that implements the aggregate function. 51.Pp 52This routine must be called from the same thread in which the aggregate 53SQL function is running. 54.Sh IMPLEMENTATION NOTES 55These declarations were extracted from the 56interface documentation at line 5831. 57.Bd -literal 58SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 59.Ed 60.Sh SEE ALSO 61.Xr sqlite3_context 3 62