Changeset: 6c66571f54e1 for MonetDB
URL: https://dev.monetdb.org/hg/MonetDB/rev/6c66571f54e1
Modified Files:
documentation/monetdbe/manual_pages/monetdbe_options.rst
documentation/monetdbe/monetdbe_api.rst
tools/monetdbe/monetdbe.c
Branch: Dec2023
Log Message:
Bring monetdbe_api.rst documentation in-line with monetdbe API as defined in
monetdbe.[ch].
Added: monetdbe_get_columns(), monetdbe_null(), monetdbe_get_mapi_port() and
monetdbe_version().
Corrected: monetdbe_cleanup() into monetdbe_cleanup_result().
Removed: monetdbe_restore().
diffs (219 lines):
diff --git a/documentation/monetdbe/manual_pages/monetdbe_options.rst
b/documentation/monetdbe/manual_pages/monetdbe_options.rst
--- a/documentation/monetdbe/manual_pages/monetdbe_options.rst
+++ b/documentation/monetdbe/manual_pages/monetdbe_options.rst
@@ -20,7 +20,7 @@ SYNOPSIS
int nr_threads;
monetdbe_remote* remote;
monetdbe_mapi_server* mapi_server;
-
+ const char *trace_file;
} monetdbe_options;
DESCRIPTION
@@ -30,9 +30,10 @@ MonetDBe options struct. Object can be p
(1) int memorylimit. Top off the amount of RAM to be used, in MB.
(2) int querytimeout. Gracefully terminate query after a few seconds.
(3) int sessiontimeout. Graceful terminate the session after a few seconds.
-(4) int nr_threads. Maximum number of worker treads, limits level of
parallelism.
-(5) monetdbe_remote* remote. Pointer to a monetdbe_remote object.
-(6) monetdbe_mapi_server* mapi_server. Pointer to a monetdbe_mapi_server
object.
+(4) int nr_threads. Maximum number of worker treads, limits level of
parallelism.
+(5) monetdbe_remote* remote. Pointer to a monetdbe_remote object.
+(6) monetdbe_mapi_server* mapi_server. Pointer to a monetdbe_mapi_server
object.
+(7) const char *trace_file. File to which log output should be written.
EXAMPLES
========
diff --git a/documentation/monetdbe/monetdbe_api.rst
b/documentation/monetdbe/monetdbe_api.rst
--- a/documentation/monetdbe/monetdbe_api.rst
+++ b/documentation/monetdbe/monetdbe_api.rst
@@ -39,6 +39,8 @@ monetdbe_data_time time
monetdbe_data_timestamp timestamp
======================= =====================
+Other data types such as timestamptz, timetz, json, inet, url, uuid, geom are
currently not supported.
+
Connection and server options
-----------------------------
@@ -50,23 +52,27 @@ Connection and server options
The ``NULL`` and local path options lead to an exclusive lock on the
database storage.
Opening the same database multiple times concurrently is allowed, but
opening another one concurrently will throw an error for now.
There may be multiple connections to multiple MonetDB servers.
+ Return: 0 for success, else errno: -1 (allocation failed) or -2 (error in
db)
.. c:function:: int 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 and
any pending result set is cleaned up.
Be aware that the content of an 'in-memory' database is discarded.
+ Return: 0 for success, else errno: -2 (error in db)
Transaction management
----------------------
.. c:function:: char* monetdbe_get_autocommit(monetdbe_database db, int*
result)
- Retrieve the current transaction mode, i.e. 'autocommit' or 'no-autocommit'
+ Retrieve the current transaction mode, i.e. 'autocommit' or
'no-autocommit' in the result parameter.
+ Return: NULL for success, else error message.
.. c:function:: char *monetdbe_set_autocommit(monetdbe_database db, int value)
Set the auto-commit mode to either true or false.
+ Return: NULL for success, else error message.
.. c:function:: int monetdbe_in_transaction(monetdbe_database db);
@@ -78,17 +84,22 @@ Query execution
.. 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 SQL command interface to the database kernel. The query should
obey the MonetDB SQL syntax.
+ If the query produced a result set, it sets the result, i.e. a collection
of columns in binary form.
+ If the query changed data the affected_rows parameter will contain the
number of rows affected.
+ Return: NULL for success, else error message.
-.. c:function:: char* monetdbe_result_fetch(monetdbe_result *mres,
monetdbe_column** res, size_t column_index);
+.. 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.
+ It contains the type and a C-array of values.
+ The number of rows is part of the monetdbe_result structure.
+ Return: NULL for success, else error message.
-.. c:function:: char* monetdbe_cleanup(monetdbe_database db, monetdbe_result
*result);
+.. c:function:: char* monetdbe_cleanup_result(monetdbe_database db,
monetdbe_result* result);
Remove the result set structure. The result is assigned NULL afterwards.
+ Return: NULL for success, else error message.
Query prepare, bind, execute
----------------------------
@@ -97,47 +108,71 @@ Query prepare, bind, execute
Sent a query to the database server and prepare an execution plan. The
plan is assigned to
the monetdbe_statement structure for subsequent execution.
+ Return: NULL for success, else error message.
.. 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??]]
+ Return: NULL for success, else error message.
.. 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.
+ Return: NULL for success, else error message.
.. c:function:: char* monetdbe_cleanup_statement(monetdbe_database db,
monetdbe_statement *stmt);
- Remove the execution pland and all bound variables.
+ Remove the execution plan and all bound variables.
+ Return: NULL for success, else error message.
+
+Metadata
+--------
-Database append
----------------
+.. c:function:: char* monetdbe_get_columns(monetdbe_database db, const char*
schema_name, const char *table_name, size_t *column_count, monetdbe_column
**columns);
+
+ Get column count and columns info of a specific table or view in a
specific schema or current schema when schema_name is NULL.
+ Return: NULL for success, else error message.
+
+Table append
+------------
.. 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.
+ Append the result set data obtained from a query to an existing table.
+ This is a faster way than using an SQL: INSERT INTO . . . SELECT . . .
+ Return: NULL for success, else error message.
Backup and restore
------------------
.. c:function:: char* monetdbe_dump_database(monetdbe_database db, char
*backupfile);
- Dump a in-memory database as a collection of SQL statements on a local file
+ Dump an in-memory database as a collection of SQL statements on a local
file.
+ Return: NULL for success, else error message.
.. c:function:: char* monetdbe_dump_table(monetdbe_database db, const char
*schema_name, const char *table_name, const char *backupfile);
- Dump a specific tables
-
-.. c:function:: char* monetdbe_restore(monetdbe_database db, char *localfile);
-
- [TODO] Restore a SQL dump to initialize the 'in-memory' case. This is
similar to loading a SQL script.
+ Dump a specific table
+ Return: NULL for success, else error message.
Miscellaneous
-------------
.. c:function:: char * monetdbe_error(monetdbe_database db)
- return the last error associated with the connection object.
+ Return the last error message associated with the connection object. It
can return NULL.
+
+.. c:function:: const void * monetdbe_null(monetdbe_database dbhdl,
monetdbe_types t)
+
+ Return the internal NULL representation for the specific monetdbe type or
NULL when the type is not found/supported.
+
+.. c:function:: const char* monetdbe_get_mapi_port(void)
+
+ Return the mapi port or NULL if not used.
+
+.. c:function:: const char * monetdbe_version(void)
+
+ Return the MonetDBe version.
Caveats and errors
------------------
diff --git a/tools/monetdbe/monetdbe.c b/tools/monetdbe/monetdbe.c
--- a/tools/monetdbe/monetdbe.c
+++ b/tools/monetdbe/monetdbe.c
@@ -1064,7 +1064,7 @@ monetdbe_set_autocommit(monetdbe_databas
if (!validate_database_handle_noerror(mdbe)) {
- return 0;
+ return NULL;
}
mvc *m = ((backend *) mdbe->c->sqlcontext)->mvc;
@@ -1783,7 +1783,7 @@ monetdbe_cleanup_result(monetdbe_databas
assert(mdbe->c);
MT_thread_set_qry_ctx(&mdbe->c->qryctx);
if (!result) {
- set_error(mdbe, createException(MAL,
"monetdbe.monetdbe_cleanup_result_internal", "Parameter result is NULL"));
+ set_error(mdbe, createException(MAL,
"monetdbe.monetdbe_cleanup_result", "Parameter result is NULL"));
} else {
mdbe->msg = monetdbe_cleanup_result_internal(mdbe, res);
}
@@ -1794,14 +1794,14 @@ monetdbe_cleanup_result(monetdbe_databas
static inline void
cleanup_get_columns_result(size_t column_count, monetdbe_column* columns)
{
- if (columns) for (size_t c = 0; c < column_count; c++) {
- GDKfree(columns[c].name);
- GDKfree(columns[c].sql_type.name);
+ if (columns) {
+ for (size_t c = 0; c < column_count; c++) {
+ GDKfree(columns[c].name);
+ GDKfree(columns[c].sql_type.name);
}
-
GDKfree(columns);
-
columns = NULL;
+ }
}
static char *
_______________________________________________
checkin-list mailing list -- checkin-list@monetdb.org
To unsubscribe send an email to checkin-list-le...@monetdb.org
