GRASS DBMI DataBase Management Interface

by GRASS Development Team

http://grass.osgeo.org

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:

• DBF: xBase files (default)
• ODBC: to interface from http://www.unixodbc.org
• PostgreSQL driver (note that PostgreSQL can also be accessed through ODBC): http://www.postgresql.org
• mySQL: http://mysql.com/
• SQLite: http://www.sqlite.org/

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).

DBMI library functions

The db_*() functions are the programmer's API for GRASS DBMI programming. There are three groups:

• dbmi_base: contains functions for modules, drivers (../../db/drivers/)
• dbmi_client: contains functions for modules
• dbmi_driver: contains functions for drivers (../../db/drivers/)

See details here:

DBMI BASE functions

[ to be moved here from below list ]

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()

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()

DBMI functions list (incomplete)

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)

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)

DB column routines

DB columnfmt routines

DB connect routines

int db_get_connection (dbConnection *connection )

int db_set_connection (dbConnection *connection )

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)

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)

DB datetime routines

DB zero routines

DB dbmscap routines

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 )

DB dirent routines

DB error routines

DB handle routines

DB index routines

DB interval routines

DB isdir routines

DB login routines

DB ret_codes routines

DB sqlCtype routines

DB sqlCtype routines

DB sqltype routines

DB string routines

DB strip routines

DB table routines

DB token routines

DB value routines

DB valuefmt routines

DB whoami routines

DB xdr routines

DB xdrchar *routines

DB xdrchar *routines

DB xdrcolumn routines

DB xdrdatetime routines

DB xdrdouble routines

DB xdrfloat routines

DB xdrhandle routines

DB xdrindex routines

DB xdrint routines

DB xdrprocedure routines

DB xdrshort routines

DB xdrstring routines

DB xdrstring routines

DB xdrtable routines

DB xdrtoken routines

DB xdrvalue routines

DB c_add_col routines

int db_add_column (dbDriver driver, dbString *tableName, dbColumn column)

DB c_bindupdate routines

int db_bind_update (dbCursor *cursor)

DB c_close_cur routines

int db_close_cursor (dbCursor *cursor)

DB c_closedb routines

int db_close_database (dbDriver driver)

DB c_create_idx routines

int db_create_index (dbDriver driver, dbIndex index)

DB c_create_tab routines

int db_create_table (dbDriver driver, dbTable *table)

DB c_createdb routines

DB c_createdb routines

int db_create_database (dbDriver driver, dbHandle *handle)

DB c_delete routines

int db_delete (dbCursor *cursor)

DB c_deletedb routines

int db_delete_database (dbDriver driver, dbHandle *handle)

DB c_desc_table routines

int db_describe_table (dbDriver driver, dbString *name, dbTable *table)

DB c_drop_col routines

int db_drop_column (dbDriver driver, dbString *tableName, dbString *columnName)

DB c_drop_index routines

int db_drop_index (dbDriver driver, dbString *name)

DB c_drop_tab routines

int db_drop_table (dbDriver driver, dbString *name)

DB c_execute routines

int db_begin_transaction (dbDriver driver)

int db_commit_transaction (dbDriver driver)

int db_execute_immediate (dbDriver driver, dbString *SQLstatement)

DB c_fetch routines

int db_fetch (dbCursor *cursor, int position, int more)

int db_find_database (dbDriver driver, dbHandle *handle, int found)

DB c_insert routines

int db_insert (dbCursor *cursor)

DB c_list_drivers routines

char *db_list_drivers (void)

DB c_list_idx routines

int db_list_indexes (dbDriver driver, dbString *table_name, dbIndex list, int count)

DB c_list_tabs routines

int db_list_tables (dbDriver driver, dbString *names, int count, int system)

DB c_listdb routines

int db_list_databases (dbDriver driver, dbString *path, int npaths, dbHandle *handles, int count)

DB c_opendb routines

DB c_openinsert routines

DB c_openselect routines

DB c_openupdate routines

DB c_priv routines

DB c_priv routines

DB c_rows routines

int db_get_num_rows ( dbCursor *cursor )

DB c_update routines

DB c_version 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 ()

DB db routines

int db_close_database_shutdown_driver ()

int db_start_driver_open_database ()

DB delete_tab routines

int db_delete_table ()

DB printtab routines

DB select routines

DB shutdown routines

DB shutdown routines

DB start routines

DB d_add_col routines

DB d_bindupdate routines

DB d_close_cur routines

DB d_closedb routines

DB d_create_idx routines

DB d_create_tab routines

DB d_createdb routines

DB d_delete routines

DB d_deletedb routines

DB d_deletedb routines

DB d_desc_table routines

DB d_drop_col routines

DB d_drop_index routines

DB d_drop_tab routines

DB d_execute routines

DB d_fetch routines

DB d_finddb routines

DB d_insert routines

DB d_list_idx routines

DB d_list_tabs routines

DB d_list_tabs routines

DB d_listdb routines

int db_d_list_databases (void)

DB d_mkdir routines

DB d_opendb routines

DB d_openinsert routines

DB d_openselect routines

DB d_openupdate routines

DB d_priv routines

DB d_rows routines

DB d_update routines

DB d_version routines

DB d_version routines

DB driver routines

int db_driver ()

DB driver_state routines

Contacts

GRASS Development Team: http://grass.osgeo.org (preferably developers mailing list)

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

See Also

GRASS 6 Vector Architecture: GRASS 6 Vector Architecture

Last change:

Date:

2011-02-18 06:55:16 -0800 (Fri, 18 Feb 2011)