Changeset: 93c1953c81a8 for MonetDB
URL: https://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=93c1953c81a8
Added Files:
documentation/monetdbe/authors.rst
documentation/monetdbe/conf.py
documentation/monetdbe/dev_notes.rst
documentation/monetdbe/examples.rst
documentation/monetdbe/index.rst
documentation/monetdbe/installation.rst
documentation/monetdbe/introduction.rst
documentation/monetdbe/monetdbe_api.rst
Removed Files:
documentation/embedded/authors.rst
documentation/embedded/conf.py
documentation/embedded/dev_notes.rst
documentation/embedded/examples.rst
documentation/embedded/index.rst
documentation/embedded/installation.rst
documentation/embedded/introduction.rst
documentation/embedded/monetdbe_api.rst
Branch: default
Log Message:
A pass over the monetdbe API documentation
diffs (196 lines):
diff --git a/documentation/embedded/authors.rst
b/documentation/monetdbe/authors.rst
rename from documentation/embedded/authors.rst
rename to documentation/monetdbe/authors.rst
diff --git a/documentation/embedded/conf.py b/documentation/monetdbe/conf.py
rename from documentation/embedded/conf.py
rename to documentation/monetdbe/conf.py
diff --git a/documentation/embedded/dev_notes.rst
b/documentation/monetdbe/dev_notes.rst
rename from documentation/embedded/dev_notes.rst
rename to documentation/monetdbe/dev_notes.rst
diff --git a/documentation/embedded/examples.rst
b/documentation/monetdbe/examples.rst
rename from documentation/embedded/examples.rst
rename to documentation/monetdbe/examples.rst
diff --git a/documentation/embedded/index.rst b/documentation/monetdbe/index.rst
rename from documentation/embedded/index.rst
rename to documentation/monetdbe/index.rst
diff --git a/documentation/embedded/installation.rst
b/documentation/monetdbe/installation.rst
rename from documentation/embedded/installation.rst
rename to documentation/monetdbe/installation.rst
diff --git a/documentation/embedded/introduction.rst
b/documentation/monetdbe/introduction.rst
rename from documentation/embedded/introduction.rst
rename to documentation/monetdbe/introduction.rst
diff --git a/documentation/embedded/monetdbe_api.rst
b/documentation/monetdbe/monetdbe_api.rst
rename from documentation/embedded/monetdbe_api.rst
rename to documentation/monetdbe/monetdbe_api.rst
--- a/documentation/embedded/monetdbe_api.rst
+++ b/documentation/monetdbe/monetdbe_api.rst
@@ -2,7 +2,8 @@ MonetDBe API
============
The application built around the MonetDBe library. All instructions return a
string which contains possible
-errors encountered during the interpretation. If all went well they return a
NULL.
+error messages encountered during the interpretation. If all went well they
return a NULL. Otherwise it the
+exception message thrown by the MonetDB kernel.
General considerations
---------------------
@@ -37,99 +38,113 @@ Data Types
Connection and server options
---------------------------------
-.. c:char* monetdbe_open(char* dbname, bool sequential);
-
- Initialize access to a database component. The dbname is an URL and denote
either ':memory:', /path/directory,
- mapi:monetdb://company.nl:50000/database. The latter refers to a MonetDB
server location.
- The :memory: and local path options lead to an exclusive lock. There may
be multiple connections to the MonetDB servers.
-
- The sequential argument indicates [WHAT]
+.. c:function::char* monetdbe_export char* monetdbe_open(monetdbe_database
*db, char *url, monetdbe_options *opts);
-.. c:char* monetdbe_close(monetdbe_connection *conn);
+ Initialize a monetdbe_database structure. The database of interest is
denoted by an url and denote either ':memory:', /path/directory,
+ mapi:monetdb://company.nl:50000/database. The latter refers to a MonetDB
server location.
+ The :memory: and local path options lead to an exclusive lock.
+ Opening the same database is allowed, but opening another one concurrently
will throw an error for now.
+ [OK?]There may be multiple connections to the MonetDB servers.
+
+.. c:function::char* monetdbe_close(monetdbe_database *db);
+
+ Close the database handler and release the resources for another database
connection.
From here on the connection can not be used anymore to pass queries or any
pending result set is cleaned up.
- Be aware that the content of an ':inmemory:' database is discarded.
+ Be aware that the content of an ':memory:' database is discarded.
+
Transaction management
---------------------
-.. c: char* monetdbe_get_autocommit(monetdbe_connection conn, int* result);
+.. c:function:: char* monetdbe_get_autocommit(monetdbe_database db, int*
result);
Retrieve the current transaction mode, i.e. 'autocommit' or
'no-autocommit' [TODO ?]
-.. c:char *monetdbe_set_autocommit(monetdbe_connection conn, int value);
+.. c:function::char *monetdbe_set_autocommit(monetdbe_database db, int value);
+
+ Set the auto-commit mode to either true or false.
- Set the auto-commit mode to either true or false. An error is raised when
you attempt
- to ...??
+.. c:function::int monetdbe_in_transaction(monetdbe_database db);
+
+ Boolean function to check if we are in a compound transaction.
Query execution
______________
-.. c:char* monetdbe_query(monetdbe_connection conn, char* query,
monetdbe_result** result, monetdbe_cnt* affected_rows)
+.. c:function::char* monetdbe_query(monetdbe_database db, char* query,
monetdbe_result** result, monetdbe_cnt* affected_rows)
+
+ The main query interface to the database kernel. The query should obey the
MonetDB SQL syntax. It returns a
+ result set, i.e. a collection of columns in binary form and the number of
rows affected by an update.
- The main query interface to the database kernel. The query should obey the
MonetDB syntax. It returns a nested
- structure with the result set in binary form and the number of rows in the
result set or affected by an update.
+.. c:function:: char* monetdbe_result_fetch(monetdbe_result *mres,
monetdbe_column** res, size_t column_index);
+
+ Given a result set from a query obtain an individual column description.
+ It contains the type and a C-array of values. The number of rows is part
of the monetdbe_result structure.
-.. c:char* monetdbe_prepare(monetdbe_connection conn, char *query,
monetdbe_statement **stmt);
+.. c:function:: char* monetdbe_cleanup(monetdbe_database db, monetdbe_result
*result);
+
+ Remove the result set structure. The result is assigned NULL afterwards.
- Sent a query to the database server and prepare an execution plan. Its
arguments should be passed when called.
+Query prepare, bind, execute
+----------------------------
+.. c:function::char* monetdbe_prepare(monetdbe_database db, char *query,
monetdbe_statement **stmt);
-.. c:char* monetdbe_bind(monetdbe_statement *stmt, void *data, size_t
parameter_nr);
+ Sent a query to the database server and prepare an execution plan. The
plan is assigned to
+ the monetdbe_statement structure for subsequent execution.
+
+.. c:function::char* monetdbe_bind(monetdbe_statement *stmt, void *data,
size_t parameter_nr);
Bind a local variable to a parameter in the prepared query structure.
[TODO by pointer, do do you take a copy??]]
-.. c:char* monetdbe_execute(monetdbe_statement *stmt, monetdbe_result
**result, monetdbe_cnt* affected_rows);
+.. c:function::char* monetdbe_execute(monetdbe_statement *stmt,
monetdbe_result **result, monetdbe_cnt* affected_rows);
When all parameters are bound, the statement is executed by the database
server. An error is thrown if the
number of parameters does not match.
-.. c: char* monetdbe_cleanup_statement(monetdbe_connection conn,
monetdbe_statement *stmt);
+.. c:function:: char* monetdbe_cleanup_statement(monetdbe_database db,
monetdbe_statement *stmt);
Remove the execution pland and all bound variables.
-Database insert
+Database append
--------------
-.. c: char* monetdbe_append(monetdbe_connection conn, const char* schema,
const char* table, monetdbe_column **input, size_t column_count);
+.. c:function:: char* monetdbe_append(monetdbe_database db, const char*
schema, const char* table, monetdbe_result *result, size_t column_count);
- The result set obtained from any query can be assigned to a new database
table. [TODO which schema...]
+ The result set obtained from any query can be assigned to a new database
table.
-Result set
-----------
-.. c: char* monetdbe_result_fetch(monetdbe_connection conn, monetdbe_result
*mres, monetdbe_column** res, size_t column_index);
-
- Given a result set from a query obtain its structure as a collection of
column descriptors. [TODO]
+Backup and restore
+------------------
+.. c:function:: char* monetdbe_backup(monetdbe_database db, char *backupfile);
-.. c: char* monetdbe_backup(monetdbe_connection conn, char *localfile);
-
- [TODO] Dump an :inmemory: database as a collection of SQL statements on a
local file
-
-.. c: char* monetdbe_restore(monetdbe_connection conn, char *localfile);
+ [TODO] Dump a :memory: database as a collection of SQL statements on a
local file
- [TODO] Restore a SQL dump to initialize the ':inmemory:' case.
-
-Schema inspection
-----------------
+.. c:function:: monetdbe_export char* monetdbe_dump_table(monetdbe_database
db, const char *schema_name, const char *table_name, const char *backupfile);
+
+ [TODO] Dump a specific tables
-.. c:char* monetdbe_get_table(monetdbe_connection conn, monetdbe_table**
table, const char* schema_name, const char* table_name);
-
- Retrieve the structure of the schema.table into the monetdbe_table
structure.
+.. c:function:: char* monetdbe_restore(monetdbe_database db, char *localfile);
-.. c:char* monetdbe_get_columns(monetdbe_connection conn, const char*
schema_name, const char *table_name, size_t *column_count, char
***column_names, int **column_types);
-
- Retrieve the details of each column.
+ [TODO] Restore a SQL dump to initialize the ':memory:' case. This is
simular to loading a SQL script.
Miscellaneous
-------------
-.. c:bool monetdbe_is_initialized(void)
+.. c:function::bool monetdbe_is_initialized(void)
Simple function to check if MonetDBe has already been started. [TODO For a
remote connection
it behaves like a 'ping', telling if the remote server is available for
interactions.]
-.. c:char * monetdbe_error(monetdbe_connection conn)
+.. c:function::char * monetdbe_error(monetdbe_database db)
[TODO] return the last error associated with the connection object.
+
+Caveats and errors
+------------------
+
+If the program with the monetdbe.so library is killed forcefully then there
may be some garbage files left behind in the
+database directory. In particular, you may have to remove the .gdk_lock and
uuid files.
+
_______________________________________________
checkin-list mailing list
checkin-list@monetdb.org
https://www.monetdb.org/mailman/listinfo/checkin-list
