db/dbmi_client: initial doxygenization, message standardization, update dbmilib doxygen page

(merge from devbr6, https://trac.osgeo.org/grass/changeset/32620 and https://trac.osgeo.org/grass/changeset/32621)


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@32622 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/db/dbmi_client/c_add_col.c

@@ -1,12 +1,30 @@
+/*!
+ * \file db/dbmi_client/c_add_col.c
+ * 
+ * \brief DBMI Library (client) - add column to table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_add_column (dbDriver *driver, dbString *tableName, dbColumn *column)
-   \brief 
-   \return 
-   \param 
- */
+   \brief Add column to table
+
+   \param driver db driver
+   \param tableName table name
+   \param column new column description (dbColumn structure)
+
+   \return DB_OK on success
+   \return DB_FAILED on failure
+*/
 int db_add_column(dbDriver * driver, dbString * tableName, dbColumn * column)
 {
     int ret_code;

lib/db/dbmi_client/c_bindupdate.c

@@ -1,11 +1,27 @@
+/*!
+ * \file db/dbmi_client/c_bindupdate.c
+ * 
+ * \brief DBMI Library (client) - bind update
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_bind_update (dbCursor *cursor)
-   \brief 
-   \return 
-   \param 
+  \brief ADD
+
+  \param cursor db cursor
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_bind_update(dbCursor * cursor)
 {

lib/db/dbmi_client/c_close_cur.c

@@ -1,14 +1,29 @@
+/*!
+ * \file db/dbmi_client/c_close_cur.c
+ * 
+ * \brief DBMI Library (client) - close cursor
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <grass/dbmi.h>
 #include "macros.h"
 
-
 /*!
-   \fn int db_close_cursor (dbCursor *cursor)
-   \brief 
-   \return 
-   \param 
- */
+  \brief Close cursor
+  
+  \param cursor cursor to be close
+  
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_close_cursor(dbCursor * cursor)
 {
     int ret_code;

lib/db/dbmi_client/c_closedb.c

@@ -1,12 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_closedb.c
+ * 
+ * \brief DBMI Library (client) - close database connection
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_close_database (dbDriver *driver)
-   \brief 
-   \return 
-   \param 
- */
+  \brief Close database connection
+
+  \param driver db driver
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_close_database(dbDriver * driver)
 {
     int ret_code;

lib/db/dbmi_client/c_create_idx.c

@@ -1,13 +1,30 @@
+/*!
+ * \file db/dbmi_client/c_create_idx.c
+ * 
+ * \brief DBMI Library (client) - create index
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <string.h>
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_create_index (dbDriver *driver, dbIndex *index)
-   \brief 
-   \return 
-   \param 
- */
+  \brief Create index
+
+  \param driver db driver
+  \param index index info (pointer to dbIndex structure)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_create_index(dbDriver * driver, dbIndex * index)
 {
     int ret_code;
@@ -32,13 +49,17 @@ int db_create_index(dbDriver * driver, dbIndex * index)
 }
 
 /*!
-   \brief  Create unique index
-   \return 
-   \param 
+  \brief Create unique index
+
+  \param driver db driver
+  \param table_name table name
+  \param column_name column name (where to create index)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_create_index2(dbDriver * driver, const char *table_name,
-		 const char *column_name)
+int db_create_index2(dbDriver * driver, const char *table_name,
+		     const char *column_name)
 {
     int ret;
     dbIndex index;

lib/db/dbmi_client/c_create_tab.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_create_tab.c
+ * 
+ * \brief DBMI Library (client) - create table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_create_table (dbDriver *driver, dbTable *table)
-   \brief 
-   \return 
-   \param 
+  \brief Create table
+
+  \param driver db driver
+  \param table table description (pointer to dbTable structure)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_create_table(dbDriver * driver, dbTable * table)
 {

lib/db/dbmi_client/c_createdb.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_createdb.c
+ * 
+ * \brief DBMI Library (client) - create database
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_create_database (dbDriver *driver, dbHandle *handle)
-   \brief create database
-   \return nothing
-   \param driver, handle
+  \brief Create database
+  
+  \param driver db driver
+  \param handle handle
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_create_database(dbDriver * driver, dbHandle * handle)
 {

lib/db/dbmi_client/c_delete.c

@@ -1,11 +1,27 @@
+/*!
+ * \file db/dbmi_client/c_delete.c
+ * 
+ * \brief DBMI Library (client) - delete record
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_delete (dbCursor *cursor)
-   \brief 
-   \return 
-   \param 
+  \brief Delete record (?)
+
+  \param cursor db cursor
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_delete(dbCursor * cursor)
 {

lib/db/dbmi_client/c_deletedb.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_deletedb.c
+ * 
+ * \brief DBMI Library (client) - delete database
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_delete_database (dbDriver *driver, dbHandle *handle)
-   \brief 
-   \return 
-   \param 
+  \brief Delete database
+  
+  \param driver db driver
+  \param handle handle info
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_delete_database(dbDriver * driver, dbHandle * handle)
 {

lib/db/dbmi_client/c_desc_table.c

@@ -1,11 +1,29 @@
+/*!
+ * \file db/dbmi_client/c_desc_table.c
+ * 
+ * \brief DBMI Library (client) - describe table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_describe_table (dbDriver *driver, dbString *name, dbTable **table)
-   \brief 
-   \return 
-   \param 
+  \brief Describe table
+  
+  \param driver db driver
+  \param name table name
+  \param[out] pointer to dbTable structure
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_describe_table(dbDriver * driver, dbString * name, dbTable ** table)
 {

lib/db/dbmi_client/c_drop_col.c

@@ -1,14 +1,31 @@
+/*!
+ * \file db/dbmi_client/c_drop_col.c
+ * 
+ * \brief DBMI Library (client) - drop column
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_drop_column (dbDriver *driver, dbString *tableName, dbString *columnName)
-   \brief 
-   \return 
-   \param 
+  \brief driver db driver
+
+  \param driver db driver
+  \param tableName table name
+  \param columnName column name to be dropped
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_drop_column(dbDriver * driver, dbString * tableName, dbString * columnName)
+int db_drop_column(dbDriver * driver, dbString * tableName, dbString * columnName)
 {
     int ret_code;
 

lib/db/dbmi_client/c_drop_index.c

@@ -1,12 +1,29 @@
+/*!
+ * \file db/dbmi_client/c_drop_index.c
+ * 
+ * \brief DBMI Library (client) - drop index
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_drop_index (dbDriver *driver, dbString *name)
-   \brief 
-   \return 
-   \param 
- */
+  \brief Drop index
+
+  \param driver db driver
+  \param name index name
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_drop_index(dbDriver * driver, dbString * name)
 {
     int ret_code;

lib/db/dbmi_client/c_drop_tab.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_drop_tab.c
+ * 
+ * \brief DBMI Library (client) - drop table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_drop_table (dbDriver *driver, dbString *name)
-   \brief 
-   \return 
-   \param 
+  \brief Drop table
+
+  \param driver db driver
+  \param name table name to be dropped
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_drop_table(dbDriver * driver, dbString * name)
 {

lib/db/dbmi_client/c_execute.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_execute.c
+ * 
+ * \brief DBMI Library (client) - execute SQL statements
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_execute_immediate (dbDriver *driver, dbString *SQLstatement)
-   \brief 
-   \return 
-   \param 
+  \brief Execute SQL statements
+
+  \param driver db driver
+  \param SQLstatement SQL statement (alter, update, ...)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_execute_immediate(dbDriver * driver, dbString * SQLstatement)
 {
@@ -29,10 +46,12 @@ int db_execute_immediate(dbDriver * driver, dbString * SQLstatement)
 }
 
 /*!
-   \fn int db_begin_transaction (dbDriver *driver)
-   \brief 
-   \return 
-   \param 
+  \brief Begin transaction
+
+  \return driver db driver
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_begin_transaction(dbDriver * driver)
 {
@@ -53,10 +72,12 @@ int db_begin_transaction(dbDriver * driver)
 }
 
 /*!
-   \fn int db_commit_transaction (dbDriver *driver)
-   \brief 
-   \return 
-   \param 
+  \brief Commit transaction
+  
+  \param driver db driver
+  
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_commit_transaction(dbDriver * driver)
 {

lib/db/dbmi_client/c_fetch.c

@@ -1,11 +1,29 @@
+/*!
+ * \file db/dbmi_client/c_fetch.c
+ * 
+ * \brief DBMI Library (client) - fetch data
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_fetch (dbCursor *cursor, int position, int *more)
-   \brief 
-   \return 
-   \param 
+  \brief Fetch data
+
+  \param cursor db cursor
+  \param position cursor position
+  \param[out] more get more?
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_fetch(dbCursor * cursor, int position, int *more)
 {

lib/db/dbmi_client/c_finddb.c

@@ -1,12 +1,30 @@
+/*!
+ * \file db/dbmi_client/c_finddb.c
+ * 
+ * \brief DBMI Library (client) - find database
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_find_database (dbDriver *driver, dbHandle *handle, int *found)
-   \brief 
-   \return 
-   \param 
+  \brief Find database
+
+  \param driver db driver
+  \param handle handle info
+  \param[out] found if non-zero database found
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_find_database(dbDriver * driver, dbHandle * handle, int *found)
 {

lib/db/dbmi_client/c_insert.c

@@ -1,12 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_insert.c
+ * 
+ * \brief DBMI Library (client) - insert new record
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_insert (dbCursor *cursor)
-   \brief 
-   \return 
-   \param 
- */
+  \brief Insert new record into table
+
+  \param cursor db cursor
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_insert(dbCursor * cursor)
 {
     int ret_code;

lib/db/dbmi_client/c_list_drivers.c

@@ -1,10 +1,23 @@
+/*!
+ * \file db/dbmi_client/c_list_drivers.c
+ * 
+ * \brief DBMI Library (client) - list drivers
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 
 /*!
-   \fn char *db_list_drivers(void)
-   \brief return comma separated list of existing DB drivers, used for driver parameter options
-   \return return char
-   \param void
+  \brief Return comma separated list of existing DB drivers, used for driver parameter options
+
+  \return list of db drivers
  */
 const char *db_list_drivers(void)
 {

lib/db/dbmi_client/c_list_idx.c

@@ -1,15 +1,33 @@
+/*!
+ * \file db/dbmi_client/c_list_idx.c
+ * 
+ * \brief DBMI Library (client) - list indexes
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_list_indexes (dbDriver *driver, dbString *table_name, dbIndex **list, int *count)
-   \brief 
-   \return 
-   \param 
+  \brief List indexes
+
+  \param driver db driver
+  \param table_name table name
+  \param[out] list of db indexes
+  \param[out] number of items in the list
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_list_indexes(dbDriver * driver, dbString * table_name, dbIndex ** list,
-		int *count)
+int db_list_indexes(dbDriver * driver, dbString * table_name, dbIndex ** list,
+		    int *count)
 {
     int ret_code;
 

lib/db/dbmi_client/c_list_tabs.c

@@ -1,3 +1,17 @@
+/*!
+ * \file db/dbmi_client/c_list_tabs.c
+ * 
+ * \brief DBMI Library (client) - list tables
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <grass/dbmi.h>
@@ -12,12 +26,15 @@ static int cmp_dbstr(const void *pa, const void *pb)
 }
 
 /*!
-   \fn int db_list_tables (dbDriver *driver, dbString **names, int *count, int system)
-   \brief list available tables for given connection
-   \return names of tables, success: DB_OK; DB_FAILED otherwise
-   \param names: names of tables
-   \param
-   \param
+   \brief List available tables for given connection
+
+   \param driver db driver
+   \param[out] names list of table names
+   \param[out] count number of items in the list
+   \param system ?
+
+   \return DB_OK on success
+   \return DB_FAILED on failure
  */
 int
 db_list_tables(dbDriver * driver, dbString ** names, int *count, int system)

lib/db/dbmi_client/c_listdb.c

@@ -1,15 +1,34 @@
+/*!
+ * \file db/dbmi_client/c_listdb.c
+ * 
+ * \brief DBMI Library (client) - list databases
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_list_databases (dbDriver *driver, dbString *path, int npaths, dbHandle **handles, int *count)
-   \brief 
-   \return 
-   \param 
- */
-int
-db_list_databases(dbDriver * driver, dbString * path, int npaths,
-		  dbHandle ** handles, int *count)
+  \brief List databases
+  
+  \param driver db driver
+  \param path db path
+  \param npaths number of given paths
+  \param[out] handles handle infos
+  \param[out] number of handle infos
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_list_databases(dbDriver * driver, dbString * path, int npaths,
+		      dbHandle ** handles, int *count)
 {
     int ret_code;
     int i;

lib/db/dbmi_client/c_opendb.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_opendb.c
+ * 
+ * \brief DBMI Library (client) - open database connection
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Open database connection
+
+  \param driver db driver
+  \param handle handle info
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_open_database(dbDriver * driver, dbHandle * handle)
 {

lib/db/dbmi_client/c_openinsert.c

@@ -1,11 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_openinsert.c
+ * 
+ * \brief DBMI Library (client) - open insert cursor
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Open insert cursor
+
+  \param driver db driver
+  \param cursor cursor to be opened
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_open_insert_cursor(dbDriver * driver, dbCursor * cursor)
 {

lib/db/dbmi_client/c_openselect.c

@@ -1,15 +1,33 @@
+/*!
+ * \file db/dbmi_client/c_openselect.c
+ * 
+ * \brief DBMI Library (client) - open select cursor
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Open select cursor
+
+  \param driver db driver
+  \param select SQL select statement
+  \param cursor db cursor to be opened
+  \param mode open mode (?)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_open_select_cursor(dbDriver * driver, dbString * select, dbCursor * cursor,
-		      int mode)
+int db_open_select_cursor(dbDriver * driver, dbString * select, dbCursor * cursor,
+			  int mode)
 {
     int ret_code;
 

lib/db/dbmi_client/c_openupdate.c

@@ -1,15 +1,35 @@
+/*!
+ * \file db/dbmi_client/c_openupdate.c
+ * 
+ * \brief DBMI Library (client) - open update cursor
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Open update cursor
+
+  \param driver db driver
+  \param table_name table name
+  \param select SQL update statement (?)
+  \param cursor db cursor to be opened
+  \param mode open mode (?)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_open_update_cursor(dbDriver * driver, dbString * table_name,
-		      dbString * select, dbCursor * cursor, int mode)
+
+int db_open_update_cursor(dbDriver * driver, dbString * table_name,
+			  dbString * select, dbCursor * cursor, int mode)
 {
     int ret_code;
 

lib/db/dbmi_client/c_priv.c

@@ -1,14 +1,32 @@
+/*!
+ * \file db/dbmi_client/c_priv.c
+ * 
+ * \brief DBMI Library (client) - privileges management
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \brief Grant privileges 
-   \return 
-   \param priv privileges: DB_PRIV_SELECT
-   \param to grant to : DB_GROUP | DB_PUBLIC
- */
-int
-db_grant_on_table(dbDriver * driver, const char *tableName, int priv, int to)
+  \brief Grant privileges 
+
+  \param driver db driver
+  \param tableName table name
+  \param priv privileges DB_PRIV_SELECT
+  \param to grant to DB_GROUP | DB_PUBLIC
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_grant_on_table(dbDriver * driver, const char *tableName, int priv, int to)
 {
     int ret_code;
     dbString name;

lib/db/dbmi_client/c_rows.c

@@ -1,11 +1,27 @@
+/*!
+ * \file db/dbmi_client/c_rows.c
+ * 
+ * \brief DBMI Library (client) - get number of records
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn int db_get_num_rows ( dbCursor *cursor )
-   \brief get number of selected rows
-   \return 
-   \param 
+  \brief Get number of selected rows
+
+  \param cursor db select cursor
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
 int db_get_num_rows(dbCursor * cursor)
 {

lib/db/dbmi_client/c_update.c

@@ -1,12 +1,28 @@
+/*!
+ * \file db/dbmi_client/c_update.c
+ * 
+ * \brief DBMI Library (client) - update statemets
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
+  \brief ?
+
+  \param cursor db cursor
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db_update(dbCursor * cursor)
 {
     int ret_code;

lib/db/dbmi_client/c_version.c

@@ -1,17 +1,35 @@
+/*!
+ * \file db/dbmi_client/c_version.c
+ * 
+ * \brief DBMI Library (client) - version info
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
 #include "macros.h"
 
-/* Note: renamed from db_version to db_gversion to avoid name conflict
-   with Berkeley DB etc */
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
-int
-db_gversion(dbDriver * driver, dbString * client_version,
-	    dbString * driver_version)
+  \brief Get version info
+
+  Note: renamed from db_version to db_gversion to avoid name conflict
+  with Berkeley DB etc.
+  
+  \param driver db driver
+  \param[out] client_version client version
+  \param[out] driver_version driver version
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_gversion(dbDriver * driver, dbString * client_version,
+		dbString * driver_version)
 {
     int ret_code;
 

lib/db/dbmi_client/column.c

@@ -1,21 +1,19 @@
+/*!
+ * \file db/dbmi_client/column.c
+ * 
+ * \brief DBMI Library (client) - column info
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ * \author Update by Glynn Clement <glynn gclements.plus.com>
+ * and Martin Landa <landa.martin gmail.com>
+ */
 
-/****************************************************************************
-*
-* MODULE:       DBMI Library - dbmi_client column lib
-*   	    	
-* AUTHOR(S):    Radim Blazek (original contributor)
-*               Glynn Clement <glynn gclements.plus.com>,
-*               Martin Landa <landa.martin gmail.com>
-*
-* PURPOSE:      Higher level functions for DBMI DataBase Management Interface
-*
-* COPYRIGHT:    (C) 2001-2007 by the GRASS Development Team
-*
-*               This program is free software under the GNU General Public
-*   	    	License (>=v2). Read the file COPYING that comes with GRASS
-*   	    	for details.
-*
-*****************************************************************************/
 #include <stdlib.h>
 #include <string.h>
 #include <grass/gis.h>
@@ -23,15 +21,17 @@
 #include <grass/glocale.h>
 
 /*!
-   \fn int db_column_sqltype (dbDriver *driver, const char *tab, const char *col)
-   \brief Get column sqltype
-
-   See db_sqltype_name ()
-   \return column sqltype or -1 on error
-   \param driver DB driver
-   \param tab table name
-   \param col column name
- */
+  \brief Get column sqltype
+
+  See db_sqltype_name().
+
+  \param driver DB driver
+  \param tab table name
+  \param col column name
+
+  \return column sqltype
+  \return -1 on error
+*/
 int db_column_sqltype(dbDriver * driver, const char *tab, const char *col)
 {
     dbTable *table;
@@ -59,14 +59,16 @@ int db_column_sqltype(dbDriver * driver, const char *tab, const char *col)
 }
 
 /*!
-   \fn int db_column_Ctype (dbDriver *driver, const char *tab, const char *col)
-   \brief Get column Ctype
-
-   See db_sqltype_to_Ctype()
-   \return column Ctype or -1 on error
-   \param driver DB driver
-   \param tab table name
-   \param col column name
+  \brief Get column ctype
+
+  See db_sqltype_to_Ctype().
+
+  \param driver DB driver
+  \param tab table name
+  \param col column name
+
+  \return column Ctype
+  \return -1 on error
  */
 int db_column_Ctype(dbDriver * driver, const char *tab, const char *col)
 {
@@ -81,19 +83,20 @@ int db_column_Ctype(dbDriver * driver, const char *tab, const char *col)
 }
 
 /*!
-   \fn int db_get_column ( dbDriver *Driver, const char *tname, const char *cname, dbColumn **Column )
-   \brief Get column structure by table and column name.
-
-   Column is set to new dbColumn structure or NULL if column was not found
-   \return DB_OK on success, DB_FAILED on error
-   \param Driver DB driver
-   \param tname table name
-   \param cname column name
-   \param Column column structure to store within
- */
-int
-db_get_column(dbDriver * Driver, const char *tname, const char *cname,
-	      dbColumn ** Column)
+  \brief Get column structure by table and column name.
+
+  Column is set to new dbColumn structure or NULL if column was not found
+  
+  \param Driver DB driver
+  \param tname table name
+  \param cname column name
+  \param[out] Column column structure to store within
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_get_column(dbDriver * Driver, const char *tname, const char *cname,
+		  dbColumn ** Column)
 {
     int i, ncols;
     dbTable *Table;
@@ -104,7 +107,7 @@ db_get_column(dbDriver * Driver, const char *tname, const char *cname,
     db_set_string(&tabname, tname);
 
     if (db_describe_table(Driver, &tabname, &Table) != DB_OK) {
-	G_warning(_("Cannot describe table <%s>"), tname);
+      G_warning(_("Unable to describe table <%s>"), tname);
 	return DB_FAILED;
     }
 

lib/db/dbmi_client/copy_tab.c

@@ -1,6 +1,21 @@
+/*!
+ * \file db/dbmi_client/copy_tab.c
+ * 
+ * \brief DBMI Library (client) - copy table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
 #include "macros.h"
 
 static int cmp(const void *pa, const void *pb)
@@ -15,25 +30,36 @@ static int cmp(const void *pa, const void *pb)
     return 0;
 }
 
-/* Copy table, used by various db_copy_table* 
-
-   Parameters: 
-   where: WHERE SQL condition (without where key word) or NULL
-   select: full select statement
-   selcol: name of column used to select records by values in ivals or NULL
-   ivals: pointer to array of integer values or NULL
-   nvals: number of values in ivals
-
-   Use either 'where' or 'select' or 'selcol'+'ivals'+'nvals' but never more than one
-
+/*!
+  \brief Copy table, used by various db_copy_table*
+  
+  Use either 'where' or 'select' or 'selcol'+'ivals'+'nvals' but
+  never more than one.
+
+  Warning: driver opened as second must be closed as first, otherwise
+  it hangs, not sure why.
+
+  \param from_dvrname name of driver from table is copied
+  \param from_dbname name of database from table is copied
+  \param from_tbl_name name of table to be copied
+  \param to_dvrname name of driver to - where table is copied to
+  \param to_dbname name of database to - where table is copied to
+  \param to_dbname name of copied table
+  \param where WHERE SQL condition (without where key word) or NULL
+  \param select full select statement
+  \param selcol name of column used to select records by values in ivals or NULL
+  \param ivals pointer to array of integer values or NULL
+  \param nvals number of values in ivals
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-/* Warning, driver opened as second must be closed as first, otherwise it hangs, not sure why */
-int
-db__copy_table(const char *from_drvname, const char *from_dbname,
-	       const char *from_tblname, const char *to_drvname,
-	       const char *to_dbname, const char *to_tblname,
-	       const char *where, const char *select, const char *selcol,
-	       int *ivals, int nvals)
+
+int db__copy_table(const char *from_drvname, const char *from_dbname,
+		   const char *from_tblname, const char *to_drvname,
+		   const char *to_dbname, const char *to_tblname,
+		   const char *where, const char *select, const char *selcol,
+		   int *ivals, int nvals)
 {
     int col, ncols, sqltype, ctype, more, selcol_found;
     char buf[1000];
@@ -71,12 +97,13 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
     /* Open input driver and database */
     from_driver = db_start_driver(from_drvname);
     if (from_driver == NULL) {
-	G_warning("Cannot open driver '%s'", from_drvname);
+	G_warning(_("Unable to start driver <%s>"), from_drvname);
 	return DB_FAILED;
     }
     db_set_handle(&from_handle, from_dbname, NULL);
     if (db_open_database(from_driver, &from_handle) != DB_OK) {
-	G_warning("Cannot open database '%s'", from_dbname);
+	G_warning(_("Unable to open database <%s> by driver <%s>"),
+		  from_drvname, from_dbname);
 	db_close_database_shutdown_driver(from_driver);
 	return DB_FAILED;
     }
@@ -90,13 +117,14 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
     else {
 	to_driver = db_start_driver(to_drvname);
 	if (to_driver == NULL) {
-	    G_warning("Cannot open driver '%s'", to_drvname);
+	    G_warning(_("Unable to start driver <%s>"), to_drvname);
 	    db_close_database_shutdown_driver(from_driver);
 	    return DB_FAILED;
 	}
 	db_set_handle(&to_handle, to_dbname, NULL);
 	if (db_open_database(to_driver, &to_handle) != DB_OK) {
-	    G_warning("Cannot open database '%s'", to_dbname);
+	    G_warning(_("Unable to open database <%s> by driver <%s>"),
+		      to_drvname, to_dbname);
 	    db_close_database_shutdown_driver(to_driver);
 	    if (from_driver != to_driver) {
 		db_close_database_shutdown_driver(from_driver);
@@ -113,7 +141,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 
     /* test if the table exists */
     if (db_list_tables(to_driver, &tblnames, &count, 0) != DB_OK) {
-	G_warning("Cannot list tables in database '%s'", to_dbname);
+	G_warning(_("Unable to get list tables in database <%s>"),
+		  to_dbname);
 	db_close_database_shutdown_driver(to_driver);
 	if (from_driver != to_driver)
 	    db_close_database_shutdown_driver(from_driver);
@@ -125,7 +154,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 	const char *tblname = db_get_string(&tblnames[i]);
 
 	if (strcmp(to_tblname, tblname) == 0) {
-	    G_warning("Table '%s' already exists", to_dbname);
+	    G_warning(_("Table <%s> already existsin database <%s>"),
+		      to_dbname, to_dbname);
 	    db_close_database_shutdown_driver(to_driver);
 	    if (from_driver != to_driver)
 		db_close_database_shutdown_driver(from_driver);
@@ -166,7 +196,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
     G_debug(3, db_get_string(&sql));
     if (db_open_select_cursor(from_driver, &sql, &cursor, DB_SEQUENTIAL) !=
 	DB_OK) {
-	G_warning("Cannot open select cursor: '%s'", db_get_string(&sql));
+	G_warning(_("Unable to open select cursor: '%s'"),
+		  db_get_string(&sql));
 	db_close_database_shutdown_driver(to_driver);
 	if (from_driver != to_driver) {
 	    db_close_database_shutdown_driver(from_driver);
@@ -197,7 +228,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 
 	if (selcol && G_strcasecmp(colname, selcol) == 0) {
 	    if (ctype != DB_C_TYPE_INT)
-		G_fatal_error("Column '%s' is not integer", colname);
+		G_fatal_error(_("Column <%s> is not integer"),
+			      colname);
 	    selcol_found = 1;
 	}
 
@@ -213,10 +245,11 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
     db_close_cursor(&cursor);
 
     if (selcol && !selcol_found)
-	G_fatal_error("Column '%s' not found", selcol);
+	G_fatal_error(_("Column <%s> not found"), selcol);
 
     if (db_create_table(to_driver, out_table) != DB_OK) {
-	G_warning("Cannot create new table");
+	G_warning(_("Unable to create table <%s>"),
+		  out_table);
 	db_close_database_shutdown_driver(to_driver);
 	if (from_driver != to_driver) {
 	    db_close_database_shutdown_driver(from_driver);
@@ -240,7 +273,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
     G_debug(3, db_get_string(&sql));
     if (db_open_select_cursor(from_driver, &sql, &cursor, DB_SEQUENTIAL) !=
 	DB_OK) {
-	G_warning("Cannot open select cursor: '%s'", db_get_string(&sql));
+	G_warning(_("Unable to open select cursor: '%s'"),
+		  db_get_string(&sql));
 	db_close_database_shutdown_driver(to_driver);
 	if (from_driver != to_driver) {
 	    db_close_database_shutdown_driver(from_driver);
@@ -258,7 +292,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 	int select;
 
 	if (db_fetch(&cursor, DB_NEXT, &more) != DB_OK) {
-	    G_warning("Cannot fetch row");
+	    G_warning(_("Unable to fetch data from table <%s>"),
+		      from_tblname);
 	    db_close_cursor(&cursor);
 	    db_close_database_shutdown_driver(to_driver);
 	    if (from_driver != to_driver) {
@@ -313,7 +348,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 		}
 		break;
 	    default:
-		G_warning("Unknown column type (%s)", colname);
+		G_warning(_("Unknown column type (column <%s>)"),
+			  colname);
 		db_close_cursor(&cursor);
 		db_close_database_shutdown_driver(to_driver);
 		if (from_driver != to_driver) {
@@ -327,7 +363,8 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 	db_append_string(&sql, ")");
 	G_debug(3, db_get_string(&sql));
 	if (db_execute_immediate(to_driver, &sql) != DB_OK) {
-	    G_warning("Cannot insert new record: '%s'", db_get_string(&sql));
+	    G_warning("Unable to insert new record: '%s'",
+		      db_get_string(&sql));
 	    db_close_cursor(&cursor);
 	    db_close_database_shutdown_driver(to_driver);
 	    if (from_driver != to_driver) {
@@ -351,16 +388,21 @@ db__copy_table(const char *from_drvname, const char *from_dbname,
 }
 
 /*!
-   \fn int db_copy_table (const char *from_drvname, const char *from_dbname, const char *from_tblname,
-   const char *to_drvname, const char *to_dbname, const char *to_tblname )
-   \brief Copy a table
-   \return 
-   \param
+  \brief Copy a table
+ 
+  \param from_dvrname name of driver from table is copied
+  \param from_dbname name of database from table is copied
+  \param from_tbl_name name of table to be copied
+  \param to_dvrname name of driver to - where table is copied to
+  \param to_dbname name of database to - where table is copied to
+  \param to_dbname name of copied table
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_copy_table(const char *from_drvname, const char *from_dbname,
-	      const char *from_tblname, const char *to_drvname,
-	      const char *to_dbname, const char *to_tblname)
+int db_copy_table(const char *from_drvname, const char *from_dbname,
+		  const char *from_tblname, const char *to_drvname,
+		  const char *to_dbname, const char *to_tblname)
 {
     return db__copy_table(from_drvname, from_dbname, from_tblname,
 			  to_drvname, to_dbname, to_tblname,
@@ -368,17 +410,23 @@ db_copy_table(const char *from_drvname, const char *from_dbname,
 }
 
 /*!
-   \fn int db_copy_table_where (const char *from_drvname, const char *from_dbname, const char *from_tblname,
-   const char *to_drvname, const char *to_dbname, const char *to_tblname, const char *where )
-   \brief Copy a table
-   \return 
-   \param where WHERE SQL condition (without where key word) or NULL
- */
-int
-db_copy_table_where(const char *from_drvname, const char *from_dbname,
-		    const char *from_tblname, const char *to_drvname,
-		    const char *to_dbname, const char *to_tblname,
-		    const char *where)
+  \brief Copy a table (by where statement)
+
+  \param from_dvrname name of driver from table is copied
+  \param from_dbname name of database from table is copied
+  \param from_tbl_name name of table to be copied
+  \param to_dvrname name of driver to - where table is copied to
+  \param to_dbname name of database to - where table is copied to
+  \param to_dbname name of copied table
+  \param where WHERE SQL condition (without where key word)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_copy_table_where(const char *from_drvname, const char *from_dbname,
+			const char *from_tblname, const char *to_drvname,
+			const char *to_dbname, const char *to_tblname,
+			const char *where)
 {
     return db__copy_table(from_drvname, from_dbname, from_tblname,
 			  to_drvname, to_dbname, to_tblname,
@@ -386,17 +434,23 @@ db_copy_table_where(const char *from_drvname, const char *from_dbname,
 }
 
 /*!
-   \fn int db_copy_table_select ( const char *from_drvname, const char *from_dbname, const char *from_tblname,
-   const char *to_drvname, const char *to_dbname, const char *to_tblname, const char *select )
-   \brief Copy a table
-   \return 
-   \param select is full select statement or NULL
- */
-int
-db_copy_table_select(const char *from_drvname, const char *from_dbname,
-		     const char *from_tblname, const char *to_drvname,
-		     const char *to_dbname, const char *to_tblname,
-		     const char *select)
+  \brief Copy a table (by select statement)
+
+  \param from_dvrname name of driver from table is copied
+  \param from_dbname name of database from table is copied
+  \param from_tbl_name name of table to be copied
+  \param to_dvrname name of driver to - where table is copied to
+  \param to_dbname name of database to - where table is copied to
+  \param to_dbname name of copied table
+  \param select full select statement
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_copy_table_select(const char *from_drvname, const char *from_dbname,
+			 const char *from_tblname, const char *to_drvname,
+			 const char *to_dbname, const char *to_tblname,
+			 const char *select)
 {
     return db__copy_table(from_drvname, from_dbname, from_tblname,
 			  to_drvname, to_dbname, to_tblname,
@@ -404,21 +458,25 @@ db_copy_table_select(const char *from_drvname, const char *from_dbname,
 }
 
 /*!
-   \fn int db_copy_table_by_ints ( const char *from_drvname, const char *from_dbname, const char *from_tblname,
-   const char *to_drvname, const char *to_dbname, const char *to_tblname,
-   const char *selcol, int *ivals, int nvals )
-   \brief Copy a table, but only records where value of column 'selcol'
-   is in 'ivals' 
-   \return 
-   \param selcol name of column used to select records by values in ivals or NULL
-   \param ivals pointer to array of integer values or NULL
-   \param nvals number of values in ivals
- */
-int
-db_copy_table_by_ints(const char *from_drvname, const char *from_dbname,
-		      const char *from_tblname, const char *to_drvname,
-		      const char *to_dbname, const char *to_tblname,
-		      const char *selcol, int *ivals, int nvals)
+  \brief Copy a table (by keys)
+
+  \param from_dvrname name of driver from table is copied
+  \param from_dbname name of database from table is copied
+  \param from_tbl_name name of table to be copied
+  \param to_dvrname name of driver to - where table is copied to
+  \param to_dbname name of database to - where table is copied to
+  \param to_dbname name of copied table
+  \param selcol name of column used to select records by values in ivals or NULL
+  \param ivals pointer to array of integer values or NULL
+  \param nvals number of values in ivals
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
+int db_copy_table_by_ints(const char *from_drvname, const char *from_dbname,
+			  const char *from_tblname, const char *to_drvname,
+			  const char *to_dbname, const char *to_tblname,
+			  const char *selcol, int *ivals, int nvals)
 {
     return db__copy_table(from_drvname, from_dbname, from_tblname,
 			  to_drvname, to_dbname, to_tblname,

lib/db/dbmi_client/db.c

@@ -1,11 +1,29 @@
+/*!
+ * \file db/dbmi_client/db.c
+ * 
+ * \brief DBMI Library (client) - open/close driver/database connection
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
 #include "macros.h"
 
 /*!
-   \fn dbDriver * db_start_driver_open_database ( const char *drvname, const char *dbname )
-   \brief 
-   \return 
-   \param 
+  \brief Open driver/database connection
+
+  \param drvname driver name
+  \param dbname database name
+
+  \return poiner to dbDriver structure
+  \return NULL on failure
  */
 dbDriver *db_start_driver_open_database(const char *drvname,
 					const char *dbname)
@@ -13,20 +31,20 @@ dbDriver *db_start_driver_open_database(const char *drvname,
     dbHandle handle;
     dbDriver *driver;
 
-    G_debug(3,
-	    "db_start_driver_open_database():\n  drvname = %s, dbname = %s",
+    G_debug(3, "db_start_driver_open_database():\n  drvname = %s, dbname = %s",
 	    drvname, dbname);
 
     db_init_handle(&handle);
 
     driver = db_start_driver(drvname);
     if (driver == NULL) {
-	G_warning("Cannot open driver '%s'", drvname);
+	G_warning(_("Unable to start driver <%s>"), drvname);
 	return NULL;
     }
     db_set_handle(&handle, dbname, NULL);
     if (db_open_database(driver, &handle) != DB_OK) {
-	G_warning("Cannot open database '%s'", dbname);
+	G_warning(_("Unable to open database <%s> by driver <%s>"),
+		  dbname, drvname);
 	db_shutdown_driver(driver);
 	return NULL;
     }
@@ -35,11 +53,12 @@ dbDriver *db_start_driver_open_database(const char *drvname,
 }
 
 /*!
-   \fn int db_close_database_shutdown_driver (dbDriver *driver )
-   \brief 
-   \return 
-   \param 
- */
+  \brief Close driver/database connection
+
+  \param driver db driver
+
+  \return DB_OK
+*/
 int db_close_database_shutdown_driver(dbDriver * driver)
 {
     db_close_database(driver);

lib/db/dbmi_client/delete_tab.c

@@ -1,14 +1,32 @@
+/*!
+ * \file db/dbmi_client/delete_tab.c
+ * 
+ * \brief DBMI Library (client) - delete table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
 #include "macros.h"
 
 /*!
-   \fn int db_delete_table ( const char *drvname, const char *dbname, const char *tblname )
-   \brief 
-   \return 
-   \param 
+  \brief Delete table
+
+  \param drv driver name
+  \param dbname database name
+  \param tblname table name
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
  */
-int
-db_delete_table(const char *drvname, const char *dbname, const char *tblname)
+int db_delete_table(const char *drvname, const char *dbname, const char *tblname)
 {
     dbDriver *driver;
     dbHandle handle;
@@ -23,12 +41,13 @@ db_delete_table(const char *drvname, const char *dbname, const char *tblname)
     /* Open driver and database */
     driver = db_start_driver(drvname);
     if (driver == NULL) {
-	G_warning("Cannot open driver '%s'", drvname);
+	G_warning(_("Unable to open driver <%s>"), drvname);
 	return DB_FAILED;
     }
     db_set_handle(&handle, dbname, NULL);
     if (db_open_database(driver, &handle) != DB_OK) {
-	G_warning("Cannot open database '%s'", dbname);
+	G_warning(_("Unable to open database <%s> by driver <%s>"),
+		  dbname, drvname);
 	db_shutdown_driver(driver);
 	return DB_FAILED;
     }
@@ -40,7 +59,8 @@ db_delete_table(const char *drvname, const char *dbname, const char *tblname)
     G_debug(3, db_get_string(&sql));
 
     if (db_execute_immediate(driver, &sql) != DB_OK) {
-	G_warning("Cannot drop table: '%s'", db_get_string(&sql));
+	G_warning(_("Unable to drop table: '%s'"),
+		  db_get_string(&sql));
 	db_close_database(driver);
 	db_shutdown_driver(driver);
 	return DB_FAILED;

lib/db/dbmi_client/printtab.c

@@ -1,14 +1,28 @@
+/*!
+ * \file db/dbmi_client/printtab.c
+ * 
+ * \brief DBMI Library (client) - print table description info
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <string.h>
 #include <grass/dbmi.h>
 
 static void print_priv();
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
+  \brief Print table definition info
+
+  \param fd file descriptor
+  \param table table info
+*/
 void db_print_table_definition(FILE * fd, dbTable * table)
 {
     int ncols, col;
@@ -28,6 +42,12 @@ void db_print_table_definition(FILE * fd, dbTable * table)
     }
 }
 
+/*!
+  \brief Print column definition info
+
+  \param fd file descriptor
+  \param column column info
+*/
 void db_print_column_definition(FILE * fd, dbColumn * column)
 {
     dbString value_string;

lib/db/dbmi_client/select.c

@@ -1,7 +1,22 @@
+/*!
+ * \file db/dbmi_client/select.c
+ * 
+ * \brief DBMI Library (client) - select records from table
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
 
 static int cmp(const void *pa, const void *pb)
 {
@@ -74,16 +89,17 @@ static int cmpvaluestring(const void *pa, const void *pb)
 }
 
 /*!
-   \fn db_select_int (dbDriver *driver, const char *tab, const char *col, const char *where, int **pval)
-   \brief Select array of ordered integers from table/column
-   \return number of selected values, -1 on error
-   \param driver DB driver
-   \param tab table name
-   \param col column name
-   \param where where statement
-   \param pval array of ordered integer values
- */
+  \brief Select array of ordered integers from table/column
 
+  \param driver DB driver
+  \param tab table name
+  \param col column name
+  \param where where statement
+  \param[out] pval array of ordered integer values
+
+  \return number of selected values
+  \return -1 on error
+*/
 int db_select_int(dbDriver * driver, const char *tab, const char *col,
 		  const char *where, int **pval)
 {
@@ -164,15 +180,17 @@ int db_select_int(dbDriver * driver, const char *tab, const char *col,
 }
 
 /*!
-   \fn db_select_value (dbDriver *driver, const char *tab, const char *key, int id, const char *col, dbValue *val) 
-   \brief Select one (first) value from table/column for key/id
-   \return number of selected values, -1 on error
-   \param driver DB driver
-   \param tab table name
-   \param key key column name
-   \param id identifier in key column
-   \param col name of column to select the value from
-   \param val dbValue to store within
+  \brief Select one (first) value from table/column for key/id
+
+  \param driver DB driver
+  \param tab table name
+  \param key key column name
+  \param id identifier in key column
+  \param col name of column to select the value from
+  \param[out] val dbValue to store within
+
+  \return number of selected values
+  \return -1 on error
  */
 int db_select_value(dbDriver * driver, const char *tab, const char *key,
 		    int id, const char *col, dbValue * val)
@@ -215,14 +233,16 @@ int db_select_value(dbDriver * driver, const char *tab, const char *key,
 }
 
 /*!
-   \fn int db_select_CatValArray (dbDriver *driver, const char *tab, const char *key, const char *col, const char *where, dbCatValArray *cvarr)
-   \brief Select pairs key/value to array, values are sorted by key (must be integer)
-   \return number of selected values, -1 on error
-   \param driver DB driver
-   \param tab table name
-   \param key key column name
-   \param col value column name
-   \param cvarr dbCatValArray to store within
+  \brief Select pairs key/value to array, values are sorted by key (must be integer)
+
+  \param driver DB driver
+  \param tab table name
+  \param key key column name
+  \param col value column name
+  \param[out] cvarr dbCatValArray to store within
+
+  \return number of selected values
+  \return -1 on error
  */
 int db_select_CatValArray(dbDriver * driver, const char *tab, const char *key,
 			  const char *col, const char *where,
@@ -256,7 +276,7 @@ int db_select_CatValArray(dbDriver * driver, const char *tab, const char *key,
     nrows = db_get_num_rows(&cursor);
     G_debug(3, "  %d rows selected", nrows);
     if (nrows < 0)
-	G_fatal_error("Cannot select rows from database");
+	G_fatal_error(_("Unable select records from table <%s>"), tab);
 
     db_CatValArray_alloc(cvarr, nrows);
 
@@ -343,20 +363,21 @@ int db_select_CatValArray(dbDriver * driver, const char *tab, const char *key,
 }
 
 /*!
-   \fn void db_CatValArray_sort (dbCatValArray *arr)
-   \brief Sort key/value array by key
-   \param arr dbCatValArray (key/value array)
- */
+  \brief Sort key/value array by key
+  \param[in,out] arr dbCatValArray (key/value array)
+*/
 void db_CatValArray_sort(dbCatValArray * arr)
 {
     qsort((void *)arr->value, arr->n_values, sizeof(dbCatVal), cmpcat);
 }
 
 /*!
-   \fn int db_CatValArray_sort_by_value (dbCatValArray *arr)
-   \brief Sort key/value array by value
-   \return DB_OK on success, DB_FAILED on error
-   \param arr dbCatValArray (key/value array)
+  \brief Sort key/value array by value
+  
+  \param[in,out] arr dbCatValArray (key/value array)
+  
+  \return DB_OK on success
+  \return DB_FAILED on error
  */
 int db_CatValArray_sort_by_value(dbCatValArray * arr)
 {
@@ -385,12 +406,14 @@ int db_CatValArray_sort_by_value(dbCatValArray * arr)
 }
 
 /*!
-   \fn int db_CatValArray_get_value (dbCatValArray *arr, int key, dbCatVal **cv)
-   \brief Find value by key
-   \return DB_OK on success, DB_FAILED on error
-   \param arr dbCatValArray (key/value array)
-   \param key key value
-   \param cv dbCatVal structure (key/value) to store within
+  \brief Find value by key
+
+  \param arr dbCatValArray (key/value array)
+  \param key key value
+  \param[out] cv dbCatVal structure (key/value) to store within
+
+  \return DB_OK on success
+  \return DB_FAILED on error
  */
 int db_CatValArray_get_value(dbCatValArray * arr, int key, dbCatVal ** cv)
 {
@@ -409,12 +432,14 @@ int db_CatValArray_get_value(dbCatValArray * arr, int key, dbCatVal ** cv)
 }
 
 /*!
-   \fn int db_CatValArray_get_value_int (dbCatValArray *arr, int key, int *val)
-   \brief Find value (integer) by key
-   \return DB_OK on success, DB_FAILED on error
-   \param arr dbCatValArray (key/value array)
-   \param key key value
-   \param val found value (integer)
+  \brief Find value (integer) by key
+
+  \param arr dbCatValArray (key/value array)
+  \param key key value
+  \param[out] val found value (integer)
+
+  \return DB_OK on success
+  \return DB_FAILED on error
  */
 int db_CatValArray_get_value_int(dbCatValArray * arr, int key, int *val)
 {
@@ -433,13 +458,15 @@ int db_CatValArray_get_value_int(dbCatValArray * arr, int key, int *val)
 }
 
 /*!
-   \fn int db_CatValArray_get_value_double (dbCatValArray *arr, int key, double *val)
-   \brief Find value (double) by key
-   \return DB_OK on success, DB_FAILED on error
-   \param arr dbCatValArray (key/value array)
-   \param key key value
-   \param val found value (double)
- */
+  \brief Find value (double) by key
+  
+  \param arr dbCatValArray (key/value array)
+  \param key key value
+  \param[out] val found value (double)
+
+  \return DB_OK on success
+  \return DB_FAILED on error
+*/
 int db_CatValArray_get_value_double(dbCatValArray * arr, int key, double *val)
 {
     dbCatVal *catval;

lib/db/dbmi_client/shutdown.c

@@ -1,3 +1,17 @@
+/*!
+ * \file db/dbmi_client/shutdown.c
+ * 
+ * \brief DBMI Library (client) - shutdown database connection
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 
 #ifdef __MINGW32__
@@ -9,19 +23,19 @@
 #include "macros.h"
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
-/* closedown the driver, and free the driver structure */
-/* NOTE: the management of the memory for the driver structure
- * probably should be handled differently.
- *
- * db_start_driver() could take a pointer to driver structure as
- * an argument, instead of returning the pointer to allocated
- * then there would be no hidden free required
- */
+  \brief Closedown the driver, and free the driver structure
+
+  <b>Note:</b> the management of the memory for the driver structure
+  probably should be handled differently.
+ 
+  db_start_driver() could take a pointer to driver structure as
+  an argument, instead of returning the pointer to allocated
+  then there would be no hidden free required
+
+  \param driver db driver
+
+  \return status (?)
+*/
 int db_shutdown_driver(dbDriver * driver)
 {
 #ifndef __MINGW32__

lib/db/dbmi_client/start.c

@@ -1,3 +1,17 @@
+/*!
+ * \file db/dbmi_client/start.c
+ * 
+ * \brief DBMI Library (client) - open database connection
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <string.h>
 #include <stdlib.h>
 #include <unistd.h>
@@ -14,18 +28,17 @@
 #define WRITE 1
 
 
-/**
- * \fn dbDriver *db_start_driver (const char *name)
- *
- * \brief Initialize a new dbDriver for db transaction.
- *
- * If <b>name</b> is NULL, the db name will be assigned 
- * connection.driverName.
- *
- * \param[in] const char * driver name
- * \return NULL on error
- */
-
+/*!
+  \brief Initialize a new dbDriver for db transaction.
+ 
+  If <i>name</i> is NULL, the db name will be assigned 
+  connection.driverName.
+  
+  \param name driver name
+  
+  \return pointer to dbDriver structure
+  \return NULL on error
+*/
 dbDriver *db_start_driver(const char *name)
 {
     dbDriver *driver;

lib/db/dbmi_client/table.c

@@ -1,19 +1,35 @@
+/*!
+ * \file db/dbmi_client/table.c
+ * 
+ * \brief DBMI Library (client) - table management
+ *
+ * (C) 1999-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author Radim Blazek
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
 
 /*!
-   \fn int db_table_exists ( const char *, const char *, const char *)
-   \brief check if table exists
-   \param drvname: driver name
-   \param dbname: database name
-   \param tabname: table name
-   \return: 1 exist, 0 doesn't exist, -1 error
-   \param 
- */
-int
-db_table_exists(const char *drvname, const char *dbname, const char *tabname)
+  \brief Check if table exists
+
+  \param drvname driver name
+  \param dbname database name
+  \param tabname table name
+
+  \return 1 exist
+  \return 0 doesn't exist
+  \return -1 error
+*/
+int db_table_exists(const char *drvname, const char *dbname, const char *tabname)
 {
     dbDriver *driver;
     dbString *names;
@@ -27,7 +43,7 @@ db_table_exists(const char *drvname, const char *dbname, const char *tabname)
 
     driver = db_start_driver_open_database(drvname, dbname);
     if (driver == NULL) {
-	G_warning("Cannot open database '%s' by driver '%s'", dbname,
+	G_warning(_("Unable open database <%s> by driver <%s>"), dbname,
 		  drvname);
 	return -1;
     }
@@ -77,20 +93,23 @@ db_table_exists(const char *drvname, const char *dbname, const char *tabname)
 }
 
 /*!
-   \fn
-   \brief return number of rows of table
-   \return
-   \param
- */
+  \brief Get number of rows of table
+
+  \param driver db driver
+  \param sql SQL statement
+
+  \return number of records
+  \return -1
+*/
 int db_get_table_number_of_rows(dbDriver * driver, dbString * sql)
 {
     int nrows;
     dbCursor cursor;
 
     if (db_open_select_cursor(driver, sql, &cursor, DB_SEQUENTIAL) != DB_OK) {
-	G_warning("Cannot open select cursor: '%s'", db_get_string(sql));
+	G_warning(_("Unable to open select cursor: '%s'"), db_get_string(sql));
 	db_close_database_shutdown_driver(driver);
-	return DB_FAILED;
+	return -1;
     }
 
     nrows = db_get_num_rows(&cursor);

lib/db/dbmilib.dox

@@ -9,16 +9,17 @@ http://grass.osgeo.org
 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
+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 www.unixodbc.org
+<li> ODBC: to interface from http://www.unixodbc.org
 <li> PostgreSQL driver (note that PostgreSQL can also be accessed through
-     ODBC)
-<li> mySQL
+     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
@@ -35,12 +36,13 @@ 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, 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.
+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).
 
@@ -63,8 +65,117 @@ See details here:<br>
 
 \section dbmi_client DBMI CLIENT functions
 
-[ to be moved here from below list ]
+ - 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
 
 [ to be moved here from below list ]