/*! \page dbmilib GRASS DBMI DataBase Management Interface by GRASS Development Team http://grass.osgeo.org \section intro Introduction The attribute management was completely changed in GRASS 6 to achieve multi-attribute capabilities managed within external databases. The former dig_cats/ files are not used any more and all vector attributes are stored in external database. Connection with database is done through DBMI library (DataBase Management Interface) with its integrated drivers. At time of this writing following DBMI drivers for attribute storage are available: These drivers are compiled depending on present DB related libraries and 'configure' settings. Only the DBF driver is always compiled. The default DBMI driver is defined in include/dbmi.h (#define DB_DEFAULT_DRIVER "dbf"). In general records in table are linked to vector entities by field number and category number. The field number identifies a database table and the category number identifies the record record. I.e. for unique combination mapset + map + field + category exists one unique combination driver + database + table + row. Each element may have none, one or more categories (cats). More cats are distinguished by field number (field). The flexibility of this approach even supports the extreme case, that one vector entity may be linked to attributes in different tables in different databases connected by different drivers at the same time. The DBMI library contains drivers such as DBF, SQLite, ODBC, MySQL and PostgreSQL. The functionality of the database support varies with the capabilities of the underlying RDBMS. Main features are multi-attributes support for various data types, also multiple tables may optionally be linked to one or many vector entity/ies. SQL (Structured Query Language) is used for all drivers, but in a limited implementation. For DBMI architecture details please read Blazek et al. 2002 (see below). \section dbmifunc DBMI library functions The db_*() functions are the programmer's API for GRASS DBMI programming. There are three groups: See details here:
\section dbmi_base DBMI BASE functions [ to be moved here from below list ] \section dbmi_client DBMI CLIENT functions - db_add_column() - db_begin_transaction() - db_bind_update() - db_CatValArray_get_value() - db_CatValArray_get_value_double() - db_CatValArray_get_value_int() - db_CatValArray_sort() - db_CatValArray_sort_by_value() - db_close_cursor() - db_close_database() - db_close_database_shutdown_driver() - db_column_Ctype() - db_column_sqltype() - db_commit_transaction() - db_copy_table() - db_copy_table_where() - db_copy_table_select() - db_copy_table_by_ints() - db_create_database() - db_create_index() - db_create_table() - db_delete() - db_delete_database() - db_delete_table() - db_describe_table() - db_drop_column() - db_drop_index() - db_drop_table() - db_execute_immediate() - db_fetch() - db_find_database() - db_get_column() - db_get_num_rows() - db_get_table_number_of_rows() - db_grant_on_table() - db_gversion() - db_insert() - db_list_databases() - db_list_drivers() - db_list_indexes() - db_list_tables() - db_open_database() - db_open_insert_cursor() - db_open_select_cursor() - db_open_update_cursor() - db_print_column_definition() - db_print_table_definition() - db_start_driver_open_database() - db_select_CatValArray() - db_select_int() - db_select_value() - db_shutdown_driver() - db_start_driver() - db_table_exists() - db_update() - db__copy_table() \section dbmi_driver DBMI DRIVER functions - db_driver() - db_driver_mkdir() - db_d_add_column() - db_d_begin_transaction() - db_d_bind_update() - db_d_close_cursor() - db_d_close_database() - db_d_commit_transaction() - db_d_create_database() - db_d_create_index() - db_d_create_table() - db_d_delete() - db_d_delete_database() - db_d_describe_table() - db_d_drop_column() - db_d_drop_index() - db_d_drop_table() - db_d_execute_immediate() - db_d_fetch() - db_d_find_database() - db_d_get_num_rows() - db_driver_mkdir() - db_d_grant_on_table() - db_d_insert() - db_d_list_databases() - db_d_list_indexes() - db_d_list_tables() - db_d_open_database() - db_d_open_insert_cursor() - db_d_open_select_cursor() - db_d_open_update_cursor() - db_d_update() - db_d_update() - db__add_cursor_to_driver_state() - db__close_all_cursors() - db__drop_cursor_from_driver_state() - db__init_driver_state() - db__mark_database_closed() - db__mark_database_open() - db__test_database_open() \section dbmi_functions DBMI functions list (incomplete) \subsection DB_alloc_routines DB alloc routines char *#db_store (char *s) void #db_calloc (int n, int m) void #db_malloc (int n) void #db_realloc (void *s, int n) void #db_free (void *s, int n) \subsection DB_case_routines DB case routines int #db_nocase_compare (char *a, char *b) void #db_char_to_lowercase (char *s) void #db_char_to_uppercase (char *s) void #db_Cstring_to_lowercase (char *s) void #db_Cstring_to_uppercase (char *s) \subsection DB_column_routines DB column routines \subsection DB_columnfmt_routines DB columnfmt routines \subsection DB_connect_routines DB connect routines int #db_get_connection (dbConnection *connection ) int #db_set_connection (dbConnection *connection ) \subsection DB_cursor_routines DB *cursor routines dbTable *#db_get_cursor_table (dbCursor *cursor) dbToken #db_get_cursor_token (dbCursor *cursor) int #db_alloc_cursor_column_flags (dbCursor *cursor) int #db_alloc_cursor_table (dbCursor *cursor, int ncols) int #db_get_cursor_number_of_columns (dbCursor *cursor) int #db_test_cursor_any_column_flag (dbCursor *cursor) int #db_test_cursor_any_column_for_update (dbCursor *cursor) int #db_test_cursor_column_flag (dbCursor *cursor, int col) \subsection DB_datetime_routines DB datetime routines int #db_test_cursor_column_for_update (dbCursor *cursor, int col) int #db_test_cursor_mode_insensitive (dbCursor *cursor) int #db_test_cursor_mode_scroll (dbCursor *cursor) int #db_test_cursor_type_fetch (dbCursor *cursor) int #db_test_cursor_type_insert (dbCursor *cursor) int #db_test_cursor_type_update (dbCursor *cursor) void #db_free_cursor_column_flags (dbCursor *cursor) void #db_free_cursor (dbCursor *cursor) void #db_init_cursor (dbCursor *cursor) void #db_set_cursor_column_flag (dbCursor *cursor, int col) void #db_set_cursor_column_for_update (dbCursor *cursor, int col) void #db_set_cursor_mode (dbCursor *cursor, int mode) void #db_set_cursor_mode_insensitive (dbCursor *cursor) void #db_set_cursor_mode_scroll (dbCursor *cursor) void #db_set_cursor_table (dbCursor *cursor, dbTable *table) void #db_set_cursor_token (dbCursor *cursor, dbToken token) void #db_set_cursor_type_insert (dbCursor *cursor) void #db_set_cursor_type_readonly (dbCursor *cursor) void #db_set_cursor_type_update (dbCursor *cursor) void #db_unset_cursor_column_flag (dbCursor *cursor, int col) void #db_unset_cursor_column_for_update (dbCursor *cursor, int col) void #db_unset_cursor_mode (dbCursor *cursor) void #db_unset_cursor_mode_insensitive (dbCursor *cursor) void #db_unset_cursor_mode_scroll (dbCursor *cursor) \subsection DB_datetime_routines DB datetime routines \subsection DB_zero_routines DB zero routines \subsection DB_dbmscap_routines DB dbmscap routines \subsection DB_default_name_routines DB default_name routines \subsection DB_default_name_routines DB default_name routines char *#db_get_default_database ( void ) char *#db_get_default_driver ( void ) char *#db_get_default_group_name ( void ) char *#db_get_default_schema_name ( void ) \subsection DB_dirent_routines DB dirent routines \subsection DB_error_routines DB error routines \subsection DB_handle_routines DB handle routines \subsection DB_index_routines DB index routines \subsection DB_interval_routines DB interval routines \subsection DB_isdir_routines DB isdir routines \subsection DB_login_routines DB login routines \subsection DB_ret_codes_routines DB ret_codes routines \subsection DB_sqlCtype_routines DB sqlCtype routines \subsection DB_sqlCtype_routines DB sqlCtype routines \subsection DB_sqltype_routines DB sqltype routines \subsection DB_string_routines DB string routines \subsection DB_strip_routines DB strip routines \subsection DB_table_routines DB table routines \subsection DB_token_routines DB token routines \subsection DB_value_routines DB value routines \subsection DB_valuefmt_routines DB valuefmt routines \subsection DB_whoami_routines DB whoami routines \subsection DB_xdr_routines DB xdr routines \subsection DB_xdrchar_routines DB xdrchar *routines \subsection DB_xdrchar_routines DB xdrchar *routines \subsection DB_xdrcolumn_routines DB xdrcolumn routines \subsection DB_xdrdatetime_routines DB xdrdatetime routines \subsection DB_xdrdouble_routines DB xdrdouble routines \subsection DB_xdrfloat_routines DB xdrfloat routines \subsection DB_xdrhandle_routines DB xdrhandle routines \subsection DB_xdrindex_routines DB xdrindex routines \subsection DB_xdrint_routines DB xdrint routines \subsection DB_xdrprocedure_routines DB xdrprocedure routines \subsection DB_xdrshort_routines DB xdrshort routines \subsection DB_xdrstring_routines DB xdrstring routines \subsection DB_xdrstring_routines DB xdrstring routines \subsection DB_xdrtable_routines DB xdrtable routines \subsection DB_xdrtoken_routines DB xdrtoken routines \subsection DB_xdrvalue_routines DB xdrvalue routines \subsection DB_c_add_col_routines DB c_add_col routines int #db_add_column (dbDriver driver, dbString *tableName, dbColumn column) \subsection DB_c_bindupdate_routines DB c_bindupdate routines int #db_bind_update (dbCursor *cursor) \subsection DB_c_close_cur_routines DB c_close_cur routines int #db_close_cursor (dbCursor *cursor) \subsection DB_c_closedb_routines DB c_closedb routines int #db_close_database (dbDriver driver) \subsection DB_c_create_idx_routines DB c_create_idx routines int #db_create_index (dbDriver driver, dbIndex index) \subsection DB_c_create_tab_routines DB c_create_tab routines int #db_create_table (dbDriver driver, dbTable *table) \subsection DB_c_createdb_routines DB c_createdb routines \subsection DB_c_createdb_routines DB c_createdb routines int #db_create_database (dbDriver driver, dbHandle *handle) \subsection DB_c_delete_routines DB c_delete routines int #db_delete (dbCursor *cursor) \subsection DB_c_deletedb_routines DB c_deletedb routines int #db_delete_database (dbDriver driver, dbHandle *handle) \subsection DB_c_desc_table_routines DB c_desc_table routines int #db_describe_table (dbDriver driver, dbString *name, dbTable *table) \subsection DB_c_drop_col_routines DB c_drop_col routines int #db_drop_column (dbDriver driver, dbString *tableName, dbString *columnName) \subsection DB_c_drop_index_routines DB c_drop_index routines int #db_drop_index (dbDriver driver, dbString *name) \subsection DB_c_drop_tab_routines DB c_drop_tab routines int #db_drop_table (dbDriver driver, dbString *name) \subsection DB_c_execute_routines DB c_execute routines int #db_begin_transaction (dbDriver driver) int #db_commit_transaction (dbDriver driver) int #db_execute_immediate (dbDriver driver, dbString *SQLstatement) \subsection DB_c_fetch_routines DB c_fetch routines int #db_fetch (dbCursor *cursor, int position, int more) \subsection DB_c_find#db_routines DB c_finddb routines \subsection DB_c_find#db_routines DB c_finddb routines int #db_find_database (dbDriver driver, dbHandle *handle, int found) \subsection DB_c_insert_routines DB c_insert routines int #db_insert (dbCursor *cursor) \subsection DB_c_list_drivers_routines DB c_list_drivers routines char *#db_list_drivers (void) \subsection DB_c_list_idx_routines DB c_list_idx routines int #db_list_indexes (dbDriver driver, dbString *table_name, dbIndex list, int count) \subsection DB_c_list_tabs_routines DB c_list_tabs routines int #db_list_tables (dbDriver driver, dbString *names, int count, int system) \subsection DB_c_listdb_routines DB c_listdb routines int #db_list_databases (dbDriver driver, dbString *path, int npaths, dbHandle *handles, int count) \subsection DB_c_opendb_routines DB c_opendb routines \subsection DB_c_openinsert_routines DB c_openinsert routines \subsection DB_c_openselect_routines DB c_openselect routines \subsection DB_c_openupdate_routines DB c_openupdate routines \subsection DB_c_priv_routines DB c_priv routines \subsection DB_c_priv_routines DB c_priv routines \subsection DB_c_rows_routines DB c_rows routines int #db_get_num_rows ( dbCursor *cursor ) \subsection DB_c_update_routines DB c_update routines \subsection DB_c_version_routines DB c_version routines \subsection DB_copy_tab_routines DB copy_tab routines int #db_copy_table () int #db_copy_table_by_ints () int #db_copy_table_select () int #db_copy_table_where () \subsection DB_db_routines DB db routines int #db_close_database_shutdown_driver () int #db_start_driver_open_database () \subsection DB_delete_tab_routines DB delete_tab routines int #db_delete_table () \subsection DB_printtab_routines DB printtab routines \subsection DB_select_routines DB select routines \subsection DB_shutdown_routines DB shutdown routines \subsection DB_shutdown_routines DB shutdown routines \subsection DB_start_routines DB start routines \subsection DB_d_add_col_routines DB d_add_col routines \subsection DB_d_bindupdate_routines DB d_bindupdate routines \subsection DB_d_close_cur_routines DB d_close_cur routines \subsection DB_d_closedb_routines DB d_closedb routines \subsection DB_d_create_idx_routines DB d_create_idx routines \subsection DB_d_create_tab_routines DB d_create_tab routines \subsection DB_d_createdb_routines DB d_createdb routines \subsection DB_d_delete_routines DB d_delete routines \subsection DB_d_deletedb_routines DB d_deletedb routines \subsection DB_d_deletedb_routines DB d_deletedb routines \subsection DB_d_desc_table_routines DB d_desc_table routines \subsection DB_d_drop_col_routines DB d_drop_col routines \subsection DB_d_drop_index_routines DB d_drop_index routines \subsection DB_d_drop_tab_routines DB d_drop_tab routines \subsection DB_d_execute_routines DB d_execute routines \subsection DB_d_fetch_routines DB d_fetch routines \subsection DB_d_finddb_routines DB d_finddb routines \subsection DB_d_insert_routines DB d_insert routines \subsection DB_d_list_idx_routines DB d_list_idx routines \subsection DB_d_list_tabs_routines DB d_list_tabs routines \subsection DB_d_list_tabs_routines DB d_list_tabs routines \subsection DB_d_listdb_routines DB d_listdb routines int #db_d_list_databases (void) \subsection DB_d_mkdir_routines DB d_mkdir routines \subsection DB_d_opendb_routines DB d_opendb routines \subsection DB_d_openinsert_routines DB d_openinsert routines \subsection DB_d_openselect_routines DB d_openselect routines \subsection DB_d_openupdate_routines DB d_openupdate routines \subsection DB_d_priv_routines DB d_priv routines \subsection DB_d_rows_routines DB d_rows routines \subsection DB_d_update_routines DB d_update routines \subsection DB_d_version_routines DB d_version routines \subsection DB_d_version_routines DB d_version routines \subsection DB_driver_routines DB driver routines int #db_driver () \subsection DB_driver_state_routines DB driver_state routines \section contacts Contacts GRASS Development Team: http://grass.osgeo.org (preferably developers mailing list) \section references References Text based on: R. Blazek, M. Neteler, and R. Micarelli. The new GRASS 5.1 vector architecture. In Open source GIS - GRASS users conference 2002, Trento, Italy, 11-13 September 2002. University of Trento, Italy, 2002. http://www.ing.unitn.it/~grass/proceedings/proceedings/pdfs/Blazek_Radim.pdf \section seealso See Also GRASS 6 Vector Architecture: \ref Vector_Library Last change: $Date$ */