Geografic-Information-System/lib/db/dbmilib.dox

/*! \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 <b>DBMI library</b>
(DataBase Management Interface) with its integrated drivers. At time of this
writing following DBMI drivers for attribute storage are available:

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

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
<tt>mapset + map + field + category</tt> exists one unique combination
<tt>driver + database + table + row</tt>. 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:

<ul>
 <li> dbmi_base:   contains functions for modules, drivers (../../db/drivers/) </li>
 <li> dbmi_client: contains functions for modules </li>
 <li> dbmi_driver: contains functions for drivers (../../db/drivers/) </li>
</ul>

See details here:<br>

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


\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 vectorlib

Last change: $Date$
*/