Changeset: 7402b7294141 for MonetDB
URL: http://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=7402b7294141
Modified Files:
clients/mapilib/Makefile.ag
clients/mapilib/mapi.c
clients/mapilib/mapi.h
clients/mapilib/mapi.mx
Branch: default
Log Message:
mapi.mx split into mapi.c and mapi.h.
diffs (truncated from 2529 to 300 lines):
diff --git a/clients/mapilib/Makefile.ag b/clients/mapilib/Makefile.ag
--- a/clients/mapilib/Makefile.ag
+++ b/clients/mapilib/Makefile.ag
@@ -21,7 +21,7 @@
lib_mapi = {
VERSION = $(MAPI_VERSION)
- SOURCES = mapi.mx mapi.rc
+ SOURCES = mapi.c mapi.rc
LIBS = $(SOCKET_LIBS) ../../common/stream/libstream \
../../common/options/libmoptions $(openssl_LIBS)
}
@@ -29,7 +29,7 @@
headers_mapi = {
DIR = includedir/monetdb
HEADERS = h
- SOURCES = mapi.mx
+ SOURCES = mapi.h
}
headers_pc = {
diff --git a/clients/mapilib/mapi.mx b/clients/mapilib/mapi.c
rename from clients/mapilib/mapi.mx
rename to clients/mapilib/mapi.c
--- a/clients/mapilib/mapi.mx
+++ b/clients/mapilib/mapi.c
@@ -1,776 +1,777 @@
-@/
-The contents of this file are subject to the MonetDB Public License
-Version 1.1 (the "License"); you may not use this file except in
-compliance with the License. You may obtain a copy of the License at
-http://monetdb.cwi.nl/Legal/MonetDBLicense-1.1.html
-
-Software distributed under the License is distributed on an "AS IS"
-basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
-License for the specific language governing rights and limitations
-under the License.
-
-The Original Code is the MonetDB Database System.
-
-The Initial Developer of the Original Code is CWI.
-Portions created by CWI are Copyright (C) 1997-July 2008 CWI.
-Copyright August 2008-2011 MonetDB B.V.
-All Rights Reserved.
-@
-
-@f mapi
-@a M.L. Kersten, K.S. Mullender, Fabian Groffen
-@v 2.0
-@* The MonetDB Programming Interface
-@+ The Mapi Library
-
-The easiest way to extend the functionality of MonetDB is to construct
-an independent application, which communicates with a running server
-using a database driver with a simple API and a textual protocol. The
-effectiveness of such an approach has been demonstrated by the wide
-use of database API implementations, such as Perl DBI, PHP, ODBC,...
-
-@menu
-* An Example:: a C/C++ code example to get going.
-* Command Summary:: the list of API functions.
-* Library Synopsis:: an short explanation of how MAPI works.
-* Mapi Function Reference:: per API function its parameters and expected
results.
-@end menu
-
-@ifclear XQRYmanual
-@node An Example, Command Summary, The Mapi Library, The Mapi Library
-@subsection Sample MAPI Application
-
-The database driver implementation given in this document focuses on
-developing applications in C. The command collection has been
-chosen to align with common practice, i.e. queries follow a prepare,
-execute, and fetch_row paradigm. The output is considered a regular
-table. An example of a mini application below illustrates the main
-operations.
-
-@example
-@verbatim
-#include <mapi.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-void die(Mapi dbh, MapiHdl hdl)
-{
- if (hdl != NULL) {
- mapi_explain_query(hdl, stderr);
- do {
- if (mapi_result_error(hdl) != NULL)
- mapi_explain_result(hdl, stderr);
- } while (mapi_next_result(hdl) == 1);
- mapi_close_handle(hdl);
- mapi_destroy(dbh);
- } else if (dbh != NULL) {
- mapi_explain(dbh, stderr);
- mapi_destroy(dbh);
- } else {
- fprintf(stderr, "command failed\n");
- }
- exit(-1);
-}
-
-MapiHdl query(Mapi dbh, char *q)
-{
- MapiHdl ret = NULL;
- if ((ret = mapi_query(dbh, q)) == NULL || mapi_error(dbh) != MOK)
- die(dbh, ret);
- return(ret);
-}
-
-void update(Mapi dbh, char *q)
-{
- MapiHdl ret = query(dbh, q);
- if (mapi_close_handle(ret) != MOK)
- die(dbh, ret);
-}
-
-int main(int argc, char *argv[])
-{
- Mapi dbh;
- MapiHdl hdl = NULL;
- char *name;
- char *age;
-
- dbh = mapi_connect("localhost", 50000, "monetdb", "monetdb", "sql",
"demo");
- if (mapi_error(dbh))
- die(dbh, hdl);
-
- update(dbh, "CREATE TABLE emp (name VARCHAR(20), age INT)");
- update(dbh, "INSERT INTO emp VALUES ('John', 23)");
- update(dbh, "INSERT INTO emp VALUES ('Mary', 22)");
-
- hdl = query(dbh, "SELECT * FROM emp");
-
- while (mapi_fetch_row(hdl)) {
- name = mapi_fetch_field(hdl, 0);
- age = mapi_fetch_field(hdl, 1);
- printf("%s is %s\n", name, age);
- }
-
- mapi_close_handle(hdl);
- mapi_destroy(dbh);
-
- return(0);
-}
-@end verbatim
-@end example
-
-The @code{mapi_connect()} operation establishes a communication channel with
-a running server.
-The query language interface is either "sql" or "mal".
-
-Errors on the interaction can be captured using @code{mapi_error()},
-possibly followed by a request to dump a short error message
-explanation on a standard file location. It has been abstracted away
-in a macro.
-
-Provided we can establish a connection, the interaction proceeds as in
-many similar application development packages. Queries are shipped for
-execution using @code{mapi_query()} and an answer table can be consumed one
-row at a time. In many cases these functions suffice.
-
-The Mapi interface provides caching of rows at the client side.
-@code{mapi_query()} will load tuples into the cache, after which they can be
-read repeatedly using @code{mapi_fetch_row()} or directly accessed
-(@code{mapi_seek_row()}). This facility is particularly handy when small,
-but stable query results are repeatedly used in the client program.
-
-To ease communication between application code and the cache entries,
-the user can bind the C-variables both for input and output to the
-query parameters, and output columns, respectively. The query
-parameters are indicated by '?' and may appear anywhere in the query
-template.
-
-The Mapi library expects complete lines from the server as answers to
-query actions. Incomplete lines leads to Mapi waiting forever on the
-server. Thus formatted printing is discouraged in favor of tabular
-printing as offered by the @code{table.print()} commands.
-@end ifclear
-
-@ifset XQRYmanual
-@node An Example
-@subsection An Example
-
-C and C++ programs can use the MAPI library to execute queries on MonetDB.
-
-We give a short example with a minimal Mapi program:
-@itemize
-@item @code{mapi_connect()} and @code{mapi_disconnect()}: make a connection to
a database server (@code{Mapi mid;}).
- @strong{note:} pass the value @code{"sql"} in the @code{language}
parameter, when connecting.
-@item @code{mapi_error()} and @code{mapi_error_str()}: check for and print
connection errors (on @code{Mapi mid}).
-@item @code{mapi_query()} and @code{mapi_close_handle()} do a query and get a
handle to it (@code{MapiHdl hdl}).
-@item @code{mapi_result_error()}: check for query evaluation errors (on
@code{MapiHdl hdl}).
-@item @code{mapi_fetch_line()}: get a line of (result or error) output from
the server (on @code{MapiHdl hdl}).
- @strong{note:} output lines are prefixed with a @code{'='} character
that must be escaped.
-@end itemize
-
-@example
-@verbatim
-#include <stdio.h>
-#include <mapi.h>
-#include <stdlib.h>
-
-int
-main(int argc, char** argv) {
- const char *prog = argv[0];
- const char *host = argv[1]; /* where Mserver is started, e.g.
localhost */
- const char *db = argv[2]; /* database name e.g. demo */
- int port = atoi(argv[3]); /* mapi_port e.g. 50000 */
- char *mode = argv[4]; /* output format e.g. xml */
- const char *query = argv[5]; /* single-line query e.g. '1+1' (use
quotes) */
- FILE *fp = stderr;
- char *line;
-
- if (argc != 6) {
- fprintf(fp, "usage: %s <host> <db> <port> <mode> <query>\n",
prog);
- fprintf(fp, " e.g. %s localhost demo 50000 xml '1+1'\n",
prog);
- } else {
- /* CONNECT TO SERVER, default unsecure user/password,
language="sql" */
- Mapi mid = mapi_connect(host, port, "monetdb", "monetdb",
"sql", db);
- MapiHdl hdl;
- if (mid == NULL) {
- fprintf(fp, "%s: failed to connect.\n", prog);
- } else {
- hdl = mapi_query(mid, query); /* FIRE OFF A QUERY */
-
- if (hdl == NULL || mapi_error(mid) != MOK) /* CHECK
CONNECTION ERROR */
- fprintf(fp, "%s: connection error: %s\n", prog,
mapi_error_str(mid)); /* GET CONNECTION ERROR STRING */
- if (hdl) {
- if (mapi_result_error(hdl) != MOK) /* CHECK
QUERY ERROR */
- fprintf(fp, "%s: query error\n", prog);
- else
- fp = stdout; /* success:
connection&query went ok */
-
- /* FETCH SERVER QUERY ANSWER LINE-BY-LINE */
- while((line = mapi_fetch_line(hdl)) != NULL) {
- if (*line == '=') line++; // XML result
lines start with '='
- fprintf(fp, "%s\n", line);
- }
- }
- mapi_close_handle(hdl); /* CLOSE QUERY HANDLE */
- }
- mapi_disconnect(mid); /* CLOSE CONNECTION */
- }
- return (fp == stdout)? 0 : -1;
-}
-@end verbatim
-@end example
-@end ifset
-
-The following action is needed to get a working program.
-Compilation of the application relies on the @emph{monetdb-config}
-program shipped with the distribution.
-It localizes the include files and library directories.
-Once properly installed, the application can be compiled and linked as
-follows:
-@example
-@verbatim
-cc sample.c `monetdb-clients-config --cflags --libs` -lmapi -o sample
-./sample
-@end verbatim
-@end example
-
-It assumes that the dynamic loadable libraries are in public places.
-If, however, the system is installed in your private environment
-then the following option can be used on most ELF platforms.
-
-@example
-@verbatim
-cc sample.c `monetdb-clients-config --cflags --libs` -lmapi -o sample \
-`monetdb-clients-config --libs | sed -e's:-L:-R:g'`
-./sample
-@end verbatim
-@end example
-
-The compilation on Windows is slightly more complicated. It requires
-more attention towards the location of the include files and libraries.
-
-@ifclear XQRYmanual
-@node Command Summary, Library Synopsis, An Example, The Mapi Library
-@subsection Command Summary
-@end ifclear
-@ifset XQRYmanual
-@node Command Summary
-@subsection Command Summary
-@end ifset
-
-The quick reference guide to the Mapi library is given below. More
-details on their constraints and defaults are given in the next
-section.
-
-
-@multitable @columnfractions 0.25 0.75
-@item mapi_bind() @tab Bind string C-variable to a field
-@item mapi_bind_numeric() @tab Bind numeric C-variable to field
-@item mapi_bind_var() @tab Bind typed C-variable to a field
-@item mapi_cache_freeup() @tab Forcefully shuffle fraction for cache
refreshment
-@item mapi_cache_limit() @tab Set the tuple cache limit
-@item mapi_cache_shuffle() @tab Set shuffle fraction for cache refreshment
-@item mapi_clear_bindings() @tab Clear all field bindings
-@item mapi_clear_params() @tab Clear all parameter bindings
_______________________________________________
Checkin-list mailing list
[email protected]
http://mail.monetdb.org/mailman/listinfo/checkin-list
