Max's database ( i.e. More...
Collaboration diagram for Database:Typedefs | |
| typedef t_object | t_database |
| A database object. More... | |
| typedef t_object | t_db_result |
| A database result object. More... | |
| typedef t_object | t_db_view |
| A database view object. More... | |
Functions | |
| BEGIN_USING_C_LINKAGE t_max_err | db_open (t_symbol *dbname, const char *fullpath, t_database **db) |
| Create an instance of a database. More... | |
| t_max_err | db_open_ext (t_symbol *dbname, const char *fullpath, t_database **db, long flags) |
| Create an instance of a database. More... | |
| t_max_err | db_close (t_database **db) |
| Close an open database. More... | |
| t_max_err | db_query (t_database *db, t_db_result **dbresult, const char *sql,...) |
| Execute a SQL query on the database. More... | |
| t_max_err | db_query_direct (t_database *db, t_db_result **dbresult, const char *sql) |
| Execute a SQL query on the database. More... | |
| t_max_err | db_query_silent (t_database *db, t_db_result **dbresult, const char *sql,...) |
| Execute a SQL query on the database, temporarily overriding the database's error logging attribute. More... | |
| t_max_err | db_query_getlastinsertid (t_database *db, long *id) |
| Determine the id (key) number for the most recent INSERT query executed on the database. More... | |
| t_max_err | db_query_table_new (t_database *db, const char *tablename) |
| Create a new table in a database. More... | |
| t_max_err | db_query_table_addcolumn (t_database *db, const char *tablename, const char *columnname, const char *columntype, const char *flags) |
| Add a new column to an existing table in a database. More... | |
| t_max_err | db_transaction_start (t_database *db) |
| Begin a database transaction. More... | |
| t_max_err | db_transaction_end (t_database *db) |
| Finalize a database transaction. More... | |
| t_max_err | db_transaction_flush (t_database *db) |
| Force any open transactions to close. More... | |
| t_max_err | db_view_create (t_database *db, const char *sql, t_db_view **dbview) |
| A database view is a way of looking at a particular set of records in the database. More... | |
| t_max_err | db_view_remove (t_database *db, t_db_view **dbview) |
| Remove a database view created using db_view_create(). More... | |
| t_max_err | db_view_getresult (t_db_view *dbview, t_db_result **result) |
| Fetch the pointer for a t_db_view's query result. More... | |
| t_max_err | db_view_setquery (t_db_view *dbview, char *newquery) |
| Set the query used by the view. More... | |
| char ** | db_result_nextrecord (t_db_result *result) |
| Return the next record from a set of results that you are walking. More... | |
| void | db_result_reset (t_db_result *result) |
| Reset the interface for walking a result's record list to the first record. More... | |
| void | db_result_clear (t_db_result *result) |
| Zero-out a database result. More... | |
| long | db_result_numrecords (t_db_result *result) |
| Return a count of all records in the query result. More... | |
| long | db_result_numfields (t_db_result *result) |
| Return a count of all fields (columns) in the query result. More... | |
| char * | db_result_fieldname (t_db_result *result, long fieldindex) |
| Return the name of a field specified by its index number. More... | |
| char * | db_result_string (t_db_result *result, long recordindex, long fieldindex) |
| Return a single value from a result according to its index and field coordinates. More... | |
| long | db_result_long (t_db_result *result, long recordindex, long fieldindex) |
| Return a single value from a result according to its index and field coordinates. More... | |
| float | db_result_float (t_db_result *result, long recordindex, long fieldindex) |
| Return a single value from a result according to its index and field coordinates. More... | |
| t_ptr_uint | db_result_datetimeinseconds (t_db_result *result, long recordindex, long fieldindex) |
| Return a single value from a result according to its index and field coordinates. More... | |
| void | db_util_stringtodate (const char *string, t_ptr_uint *date) |
| A utility to convert from a sql datetime string into seconds. More... | |
| void | db_util_datetostring (const t_ptr_uint date, char *string) |
| A utility to convert from seconds into a sql-ready datetime string. More... | |
Max's database ( i.e.
t_database ) support currently consists of a SQLite ( http://sqlite.org ) extension which is loaded dynamically by Max at launch time. Because it is loaded dynamically, all interfacing with the sqlite object relies on Max's message passing interface, using object_method() and related functions.
For most common database needs, a C-interface is defined in the ext_database.h header file and implemented in the ext_database.c source file. The functions defined in this interface wrap the message passing calls and provide a convenient means by which you can work with databases. ext_database.c is located in the 'common' folder inside of the 'max-includes' folder. If you use any of the functions defined ext_database.h, you will need to add ext_database.c to your project.
| typedef t_object t_database |
A database object.
Use db_open() and db_close() to create and free database objects.
| typedef t_object t_db_result |
A database result object.
This is what the database object returns when a query is executed.
A database view object.
A database view wraps a query and a result for a given database, and is always updated and in-sync with the database.
| t_max_err db_close | ( | t_database ** | db | ) |
Close an open database.
| db | The address of the t_database pointer for your database instance. The pointer will be freed and set NULL upon return. |
| BEGIN_USING_C_LINKAGE t_max_err db_open | ( | t_symbol * | dbname, |
| const char * | fullpath, | ||
| t_database ** | db | ||
| ) |
Create an instance of a database.
| dbname | The name of the database. |
| fullpath | If a database with this dbname is not already open, this will specify a full path to the location where the database is stored on disk. If NULL is passed for this argument, the database will reside in memory only. The path should be formatted as a Max style path. |
| db | The address of a t_database pointer that will be set to point to the new database instance. If the pointer is not NULL, then it will be treated as a pre-existing database instance and thus will be freed. |
| t_max_err db_open_ext | ( | t_symbol * | dbname, |
| const char * | fullpath, | ||
| t_database ** | db, | ||
| long | flags | ||
| ) |
Create an instance of a database.
| dbname | The name of the database. |
| fullpath | If a database with this dbname is not already open, this will specify a full path to the location where the database is stored on disk. If NULL is passed for this argument, the database will reside in memory only. The path should be formatted as a Max style path. |
| db | The address of a t_database pointer that will be set to point to the new database instance. If the pointer is not NULL, then it will be treated as a pre-existing database instance and thus will be freed. |
| flags | Any flags to be passed to the database backend while opening the db. At this time, DB_OPEN_FLAGS_READONLY (0x01) is the only flag available. |
| t_max_err db_query | ( | t_database * | db, |
| t_db_result ** | dbresult, | ||
| const char * | sql, | ||
| ... | |||
| ) |
Execute a SQL query on the database.
| db | The t_database pointer for your database instance. |
| dbresult | The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult, which will be filled in with the query results. When you are done with the dbresult you should free it with object_free(). |
| sql | A C-string containing a valid SQL query, possibly with sprintf() formatting codes. |
| ... | If an sprintf() formatting codes are used in the sql string, these values will be interpolated into the sql string. |
| t_max_err db_query_direct | ( | t_database * | db, |
| t_db_result ** | dbresult, | ||
| const char * | sql | ||
| ) |
Execute a SQL query on the database.
| db | The t_database pointer for your database instance. |
| dbresult | The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult, which will be filled in with the query results. When you are done with the dbresult you should free it with object_free(). |
| sql | A C-string containing a valid SQL query. |
| t_max_err db_query_getlastinsertid | ( | t_database * | db, |
| long * | id | ||
| ) |
Determine the id (key) number for the most recent INSERT query executed on the database.
| db | The t_database pointer for your database instance. |
| id | The address of a variable to hold the result on return. |
| t_max_err db_query_silent | ( | t_database * | db, |
| t_db_result ** | dbresult, | ||
| const char * | sql, | ||
| ... | |||
| ) |
Execute a SQL query on the database, temporarily overriding the database's error logging attribute.
| db | The t_database pointer for your database instance. |
| dbresult | The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult, which will be filled in with the query results. When you are done with the dbresult you should free it with object_free(). |
| sql | A C-string containing a valid SQL query, possibly with sprintf() formatting codes. |
| ... | If an sprintf() formatting codes are used in the sql string, these values will be interpolated into the sql string. |
| t_max_err db_query_table_addcolumn | ( | t_database * | db, |
| const char * | tablename, | ||
| const char * | columnname, | ||
| const char * | columntype, | ||
| const char * | flags | ||
| ) |
Add a new column to an existing table in a database.
| db | The t_database pointer for your database instance. |
| tablename | The name of the table to which the column should be added. |
| columnname | The name to use for the new column. |
| columntype | The SQL type for the data that will be stored in the column. For example: "INTEGER" or "VARCHAR" |
| flags | If you wish to specify any additional information for the column, then pass that here. Otherwise pass NULL. |
| t_max_err db_query_table_new | ( | t_database * | db, |
| const char * | tablename | ||
| ) |
Create a new table in a database.
| db | The t_database pointer for your database instance. |
| tablename | The name to use for the new table. The new table will be created with one column, which holds the primary key for the table, and is named according the form {tablename}_id. |
| void db_result_clear | ( | t_db_result * | result | ) |
Zero-out a database result.
| result | The t_db_result pointer for your query results. |
| t_ptr_uint db_result_datetimeinseconds | ( | t_db_result * | result, |
| long | recordindex, | ||
| long | fieldindex | ||
| ) |
Return a single value from a result according to its index and field coordinates.
The value will be coerced from an expected datetime field into seconds.
| result | The t_db_result pointer for your query results. |
| recordindex | The zero-based index number of the record (row) in the result. |
| fieldindex | The zero-based index number of the field (column) in the result. |
| char* db_result_fieldname | ( | t_db_result * | result, |
| long | fieldindex | ||
| ) |
Return the name of a field specified by its index number.
| result | The t_db_result pointer for your query results. |
| fieldindex | The zero-based index number of the field (column) in the result. |
| float db_result_float | ( | t_db_result * | result, |
| long | recordindex, | ||
| long | fieldindex | ||
| ) |
Return a single value from a result according to its index and field coordinates.
| result | The t_db_result pointer for your query results. |
| recordindex | The zero-based index number of the record (row) in the result. |
| fieldindex | The zero-based index number of the field (column) in the result. |
| long db_result_long | ( | t_db_result * | result, |
| long | recordindex, | ||
| long | fieldindex | ||
| ) |
Return a single value from a result according to its index and field coordinates.
| result | The t_db_result pointer for your query results. |
| recordindex | The zero-based index number of the record (row) in the result. |
| fieldindex | The zero-based index number of the field (column) in the result. |
| char** db_result_nextrecord | ( | t_db_result * | result | ) |
Return the next record from a set of results that you are walking.
When you are returned a result from a query of the database, the result is prepared for walking the results from the beginning. You can also reset the result manually to the beginning of the record list by calling db_result_reset().
| result | The t_db_result pointer for your query results. |
| long db_result_numfields | ( | t_db_result * | result | ) |
Return a count of all fields (columns) in the query result.
| result | The t_db_result pointer for your query results. |
| long db_result_numrecords | ( | t_db_result * | result | ) |
Return a count of all records in the query result.
| result | The t_db_result pointer for your query results. |
| void db_result_reset | ( | t_db_result * | result | ) |
Reset the interface for walking a result's record list to the first record.
| result | The t_db_result pointer for your query results. |
| char* db_result_string | ( | t_db_result * | result, |
| long | recordindex, | ||
| long | fieldindex | ||
| ) |
Return a single value from a result according to its index and field coordinates.
| result | The t_db_result pointer for your query results. |
| recordindex | The zero-based index number of the record (row) in the result. |
| fieldindex | The zero-based index number of the field (column) in the result. |
| t_max_err db_transaction_end | ( | t_database * | db | ) |
Finalize a database transaction.
| db | The t_database pointer for your database instance. |
| t_max_err db_transaction_flush | ( | t_database * | db | ) |
Force any open transactions to close.
| db | The t_database pointer for your database instance. |
| t_max_err db_transaction_start | ( | t_database * | db | ) |
Begin a database transaction.
When you are working with a file-based database, then the database will not be flushed to disk until db_transacation_end() is called. This means that you can _much_ more efficiently execute a sequence of queries in one transaction rather than independently.
That database object reference counts transactions, so it is possible nest calls to db_transacation_start() and db_transacation_end(). It is important to balance all calls with db_transacation_end() or the database contents will never be flushed to disk.
| db | The t_database pointer for your database instance. |
| void db_util_datetostring | ( | const t_ptr_uint | date, |
| char * | string | ||
| ) |
A utility to convert from seconds into a sql-ready datetime string.
| date | The datetime represented in seconds. |
| string | The address of a valid C-string whose contents will be set to a SQL-ready string format upon return. |
| void db_util_stringtodate | ( | const char * | string, |
| t_ptr_uint * | date | ||
| ) |
A utility to convert from a sql datetime string into seconds.
| string | A C-string containing a date and time in SQL format. |
| date | The datetime represented in seconds upon return. |
| t_max_err db_view_create | ( | t_database * | db, |
| const char * | sql, | ||
| t_db_view ** | dbview | ||
| ) |
A database view is a way of looking at a particular set of records in the database.
This particular set of records is defined with a standard SQL query, and the view maintains a copy of the results of the query internally. Any time the database is modified the internal result set is updated, and any objects listening to the view are notified via object_notify().
| db | The t_database pointer for your database instance. |
| sql | A SQL query that defines the set of results provided by the view. |
| dbview | The address of a NULL t_db_view pointer which will be set with the new view upon return. |
| t_max_err db_view_getresult | ( | t_db_view * | dbview, |
| t_db_result ** | result | ||
| ) |
Fetch the pointer for a t_db_view's query result.
| dbview | The t_db_view pointer for your database view instance. |
| result | The address of a pointer to a t_db_result object. This pointer will be overwritten with the view's result pointer upon return. |
| t_max_err db_view_remove | ( | t_database * | db, |
| t_db_view ** | dbview | ||
| ) |
Remove a database view created using db_view_create().
| db | The t_database pointer for your database instance for which this view was created. |
| dbview | The address of the t_db_view pointer for the view. This pointer will be freed and set NULL upon return. |
