<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - SQL persistent database interface</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_150.html">previous</A>, <A HREF="ciao_152.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC632" HREF="ciao_toc.html#TOC632">SQL persistent database interface</A></H1>
<P>
<A NAME="IDX6977"></A>
<P>
<STRONG>Author(s):</STRONG> I. Caballero, D. Cabeza, J.M. Gómez, M. Hermenegildo, J. F. Morales, and M. Carro, <CODE>clip@dia.fi.upm.es</CODE>, <CODE>http://www.clip.dia.fi.upm.es/</CODE>, The CLIP Group, Facultad de Informática, Universidad Politécnica de Madrid.
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.9#113 (2003/11/27, 20:56:6 CET)
<P>
The purpose of this library is to implement an instance of the generic concept of
<A NAME="IDX6978"></A>
persistent predicates, where external
<A NAME="IDX6979"></A>
relational databases are used for storage (see the documentation of the
<A NAME="IDX6980"></A>
<CODE>persdb</CODE> library and [CHGT98,Par97] for details). To this end, this library exports SQL persistent versions of the
<A NAME="IDX6981"></A>
<CODE>assertz_fact/1</CODE>,
<A NAME="IDX6982"></A>
<CODE>retract_fact/1</CODE> and
<A NAME="IDX6983"></A>
<CODE>retractall_fact/1</CODE> builtin predicates. Persistent predicates also allow
<A NAME="IDX6984"></A>
concurrent updates from several programs, since each update is atomic.
<P>
The notion of persistence provides a very natural and transparent way to access database relations from a Prolog program. Stub definitions are provided for such predicates which access the database when the predicate is called (using the
<A NAME="IDX6985"></A>
<CODE>db_client</CODE> library). A
<A NAME="IDX6986"></A>
Prolog to SQL translator is used to generate the required
<A NAME="IDX6987"></A>
SQL code dynamically (see library
<A NAME="IDX6988"></A>
<CODE>pl2sql</CODE>).
<P>
This library also provides facilities for reflecting more complex
<A NAME="IDX6989"></A>
views of the database relations as Prolog predicates. Such views can be constructed as conjunctions, disjunctions, projections, etc. of database relations. Also,
<A NAME="IDX6990"></A>
SQL-like
<A NAME="IDX6991"></A>
aggregation operations are supported.
<UL>
<LI><A HREF="ciao_151.html#SEC633">Implementation of the Database Interface</A>
<LI><A HREF="ciao_151.html#SEC634">Example(s)</A>
<LI><A HREF="ciao_151.html#SEC635">Usage and interface (persdbrt_mysql)</A>
<LI><A HREF="ciao_151.html#SEC636">Documentation on exports (persdbrt_mysql)</A>
<LI><A HREF="ciao_151.html#SEC637">Documentation on multifiles (persdbrt_mysql)</A>
<LI><A HREF="ciao_151.html#SEC638">Documentation on internals (persdbrt_mysql)</A>
<LI><A HREF="ciao_151.html#SEC639">Known bugs and planned improvements (persdbrt_mysql)</A>
</UL>
<H2><A NAME="SEC633" HREF="ciao_toc.html#TOC633">Implementation of the Database Interface</A></H2>
<P>
The architecture of the low-level implementation of the database interface was defined with two goals in mind:
<UL>
<LI>to simplify the communication between the Prolog system and the relational database engines as much as possible, and
<LI>to give as much flexibility as possible to the overall system. This includes simultaneous access to several databases, allowing both the databases and clients to reside on the same physical machine or different machines, and allowing the clients to reside in Win95/NT or Unix machines.
</UL>
<P>
In order to allow the flexibility mentioned above, a client-sever architecture was chosen. At the server side, a MySQL server connects to the databases using the MySQL. At the client side, a MySQL client interface connects to this server. The server daemon (mysqld) should be running in the server machine; check your MySQL documentation on how to do that.
<P>
After the connection is established a client can send commands to the mediator server which will pass them to the corresponding database server, and then the data will traverse in the opposite direction. These messages include logging on and off from the database, sending SQL queries, and receiving the responses.
<P>
The low level implementation of the current library is accomplished by providing abstraction levels over the MySQL interface library. These layers of abstraction implement the persistent predicate view, build the appropriate commands for the database using a translator of Prolog goals to SQL commands, issue such commands using the mediator send/receive procedures, parse the responses, and present such responses to the Prolog engine via backtracking.
<H2><A NAME="SEC634" HREF="ciao_toc.html#TOC634">Example(s)</A></H2>
<PRE>
</PRE>
<H2><A NAME="SEC635" HREF="ciao_toc.html#TOC635">Usage and interface (<CODE>persdbrt_mysql</CODE>)</A></H2>
<div class="cartouche">
<UL>
<LI><STRONG>Library usage:</STRONG>
Typically, this library is used including the 'persdb_mysql' package into the package list of the module, or using the
<A NAME="IDX6992"></A>
<CODE>use_package/1</CODE> declaration:
<DL COMPACT>
<DT>In a module:
<DD>
<PRE>
:- module(bar, [main/1], [persdb_mysql]).
</PRE>
or
<PRE>
:- module(bar, [main/1]).
:- include(library(persdb_mysql)).
</PRE>
<DT>In a <EM>user</EM> file:
<DD>
<PRE>
:- use_package([persdb_mysql]).
</PRE>
or
<PRE>
:- include(library(persdb_mysql)).
</PRE>
</DL>
This loads the run-time and compile-time versions of the library (<CODE>persdbtr_mysql.pl</CODE> and <CODE>persdbrt_mysql.pl</CODE>) and includes some needed declarations.
<LI><STRONG>Exports:</STRONG>
<UL>
<LI><EM>Predicates:</EM>
<A NAME="IDX6993"></A>
<CODE>init_sql_persdb/0</CODE>,
<A NAME="IDX6994"></A>
<CODE>dbassertz_fact/1</CODE>,
<A NAME="IDX6995"></A>
<CODE>dbretract_fact/1</CODE>,
<A NAME="IDX6996"></A>
<CODE>dbcurrent_fact/1</CODE>,
<A NAME="IDX6997"></A>
<CODE>dbretractall_fact/1</CODE>,
<A NAME="IDX6998"></A>
<CODE>make_sql_persistent/3</CODE>,
<A NAME="IDX6999"></A>
<CODE>dbfindall/4</CODE>,
<A NAME="IDX7000"></A>
<CODE>dbcall/2</CODE>,
<A NAME="IDX7001"></A>
<CODE>sql_query/3</CODE>,
<A NAME="IDX7002"></A>
<CODE>sql_get_tables/2</CODE>,
<A NAME="IDX7003"></A>
<CODE>sql_table_types/3</CODE>.
<LI><EM>Multifiles:</EM>
<A NAME="IDX7004"></A>
<CODE>sql_persistent_location/2</CODE>.
</UL>
<LI><STRONG>Other modules used:</STRONG>
<UL>
<LI><EM>System library modules:</EM>
<A NAME="IDX7005"></A>
<CODE>det_hook/det_hook_rt</CODE>,
<A NAME="IDX7006"></A>
<CODE>persdb_mysql/db_client_types</CODE>,
<A NAME="IDX7007"></A>
<CODE>persdb_mysql/pl2sql</CODE>,
<A NAME="IDX7008"></A>
<CODE>persdb_sql_common/sqltypes</CODE>,
<A NAME="IDX7009"></A>
<CODE>dynamic</CODE>,
<A NAME="IDX7010"></A>
<CODE>terms</CODE>,
<A NAME="IDX7011"></A>
<CODE>terms_vars</CODE>,
<A NAME="IDX7012"></A>
<CODE>messages</CODE>,
<A NAME="IDX7013"></A>
<CODE>lists</CODE>,
<A NAME="IDX7014"></A>
<CODE>aggregates</CODE>,
<A NAME="IDX7015"></A>
<CODE>persdb_mysql/mysql_client</CODE>,
<A NAME="IDX7016"></A>
<CODE>persdb_sql_common/pl2sqlinsert</CODE>,
<A NAME="IDX7017"></A>
<CODE>persdb_mysql/delete_compiler/pl2sqldelete</CODE>.
</UL>
</UL>
</div class="cartouche">
<H2><A NAME="SEC636" HREF="ciao_toc.html#TOC636">Documentation on exports (<CODE>persdbrt_mysql</CODE>)</A></H2>
<P>
<A NAME="IDX7018"></A>
<A NAME="IDX7019"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>init_sql_persdb/0:</B>
<DD><A NAME="IDX7020"></A>
<P>
<STRONG>Usage:</STRONG>
<UL>
<LI><EM>Description:</EM> Internal predicate, used to transform predicates statically declared as persistent (see
<A NAME="IDX7021"></A>
<CODE>sql_persistent/3</CODE>) into real persistent predicates.
</UL>
</DL>
<P>
<A NAME="IDX7022"></A>
<A NAME="IDX7023"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbassertz_fact/1:</B>
<DD><A NAME="IDX7024"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbassertz_fact(+Fact)</CODE>
<UL>
<LI><EM>Description:</EM> Persistent extension of
<A NAME="IDX7025"></A>
<CODE>assertz_fact/1</CODE>: the current instance of <CODE>Fact</CODE> is interpreted as a fact (i.e., a relation tuple) and is added to the end of the definition of the corresponding predicate. If any integrity constraint violation is done (database stored predicates), an error will be displayed. The predicate concerned must be statically (
<A NAME="IDX7026"></A>
<CODE>sql_persistent/3</CODE>) or dinamically (
<A NAME="IDX7027"></A>
<CODE>make_sql_persistent/3</CODE>) declared. Any uninstantiated variables in the <CODE>Fact</CODE> will be replaced by new, private variables. <STRONG>Note:</STRONG> <EM>assertion of facts with uninstantiated variables not implemented at this time.</EM>
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Fact</CODE> is a fact (a term whose main functor is not <CODE>':-'/2</CODE>).
(<CODE>persdbrt_mysql:fact/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7028"></A>
<A NAME="IDX7029"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbretract_fact/1:</B>
<DD><A NAME="IDX7030"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbretract_fact(+Fact)</CODE>
<UL>
<LI><EM>Description:</EM> Persistent extension of
<A NAME="IDX7031"></A>
<CODE>retract_fact/1</CODE>: deletes on backtracking all the facts which unify with <CODE>Fact</CODE>. The predicate concerned must be statically (
<A NAME="IDX7032"></A>
<CODE>sql_persistent/3</CODE>) or dinamically (
<A NAME="IDX7033"></A>
<CODE>make_sql_persistent/3</CODE>) declared.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Fact</CODE> is a fact (a term whose main functor is not <CODE>':-'/2</CODE>).
(<CODE>persdbrt_mysql:fact/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7034"></A>
<A NAME="IDX7035"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbcurrent_fact/1:</B>
<DD><A NAME="IDX7036"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbcurrent_fact(+Fact)</CODE>
<UL>
<LI><EM>Description:</EM> Persistent extension of
<A NAME="IDX7037"></A>
<CODE>current_fact/1</CODE>: the fact <CODE>Fact</CODE> exists in the current database. The predicate concerned must be declared
<A NAME="IDX7038"></A>
<CODE>sql_persistent/3</CODE>. Provides on backtracking all the facts (tuples) which unify with <CODE>Fact</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Fact</CODE> is a fact (a term whose main functor is not <CODE>':-'/2</CODE>).
(<CODE>persdbrt_mysql:fact/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7039"></A>
<A NAME="IDX7040"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbretractall_fact/1:</B>
<DD><A NAME="IDX7041"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbretractall_fact(+Fact)</CODE>
<UL>
<LI><EM>Description:</EM> Persistent extension of
<A NAME="IDX7042"></A>
<CODE>retractall_fact/1</CODE>: when called deletes all the facts which unify with <CODE>Fact</CODE>. The predicate concerned must be statically (
<A NAME="IDX7043"></A>
<CODE>sql_persistent/3</CODE>) or dinamically (
<A NAME="IDX7044"></A>
<CODE>make_sql_persistent/3</CODE>) declared.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Fact</CODE> is a fact (a term whose main functor is not <CODE>':-'/2</CODE>).
(<CODE>persdbrt_mysql:fact/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7045"></A>
<A NAME="IDX7046"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>make_sql_persistent/3:</B>
<DD><A NAME="IDX7047"></A>
<P>
<EM>Meta-predicate</EM> with arguments: <CODE>make_sql_persistent(addmodule,?,?)</CODE>.
<P>
<STRONG>Usage:</STRONG> <CODE>make_sql_persistent(PrologPredTypes, TableAttributes, Keyword)</CODE>
<UL>
<LI><EM>Description:</EM> Dynamic version of the
<A NAME="IDX7048"></A>
<CODE>sql_persistent/3</CODE> declaration.
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>PrologPredTypes</CODE> is a structure describing a Prolog predicate name with its types.
(<CODE>persdbrt_mysql:prologPredTypes/1</CODE>)
<CODE>TableAttributes</CODE> is a structure describing a table name and some attributes.
(<CODE>persdbrt_mysql:tableAttributes/1</CODE>)
<CODE>Keyword</CODE> is the name of a persistent storage location.
(<CODE>persdbrt_mysql:persLocId/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7049"></A>
<A NAME="IDX7050"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbfindall/4:</B>
<DD><A NAME="IDX7051"></A>
<P>
<EM>Meta-predicate</EM> with arguments: <CODE>dbfindall(?,?,goal,?)</CODE>.
<P>
<STRONG>Usage:</STRONG> <CODE>dbfindall(+DBId, +Pattern, +ComplexGoal, -Results)</CODE>
<UL>
<LI><EM>Description:</EM> Similar to
<A NAME="IDX7052"></A>
<CODE>findall/3</CODE>, but <CODE>Goal</CODE> is executed in database <CODE>DBId</CODE>. Certain restrictions and extensions apply to both <CODE>Pattern</CODE> and <CODE>ComplexGoal</CODE> stemming from the Prolog to SQL translation involved (see the corresponding type definitions for details).
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+Pattern</CODE> is a database projection term.
(<CODE>pl2sql:projterm/1</CODE>)
<CODE>+ComplexGoal</CODE> is a database query goal.
(<CODE>pl2sql:querybody/1</CODE>)
<CODE>-Results</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7053"></A>
<A NAME="IDX7054"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>dbcall/2:</B>
<DD><A NAME="IDX7055"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbcall(+DBId, +ComplexGoal)</CODE>
<UL>
<LI><EM>Description:</EM> Internal predicate, used by the transformed versions of the persistent predicates. Not meant to be called directly by users. It is exported by the library so that it can be used by the transformed versions of the persistent predicates in the modules in which they reside. Sends <CODE>ComplexGoal</CODE> to database <CODE>DBId</CODE> for evaluation. <CODE>ComplexGoal</CODE> must be a call to a persistent predicate which resides in database <CODE>DBId</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+ComplexGoal</CODE> is a database query goal.
(<CODE>pl2sql:querybody/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7056"></A>
<A NAME="IDX7057"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>sql_query/3:</B>
<DD><A NAME="IDX7058"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>sql_query(+DBId, +SQLString, AnswerTableTerm)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>ResultTerm</CODE> is the response from database <CODE>DBId</CODE> to the
<A NAME="IDX7059"></A>
SQL query in <CODE>SQLString</CODE> to database <CODE>DBId</CODE>. <CODE>AnswerTableTerm</CODE> can express a set of tuples, an error answer or a 'ok' response (see
<A NAME="IDX7060"></A>
<CODE>answertableterm/1</CODE> for details). At the moment,
<A NAME="IDX7061"></A>
<CODE>sql_query/3</CODE> log in and out for each query. This should be changed to log in only the first time and log out on exit and/or via a timer in the standard way.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+SQLString</CODE> is a string containing SQL code.
(<CODE>pl2sql:sqlstring/1</CODE>)
<CODE>AnswerTableTerm</CODE> is a response from the ODBC database interface.
(<CODE>persdbrt_mysql:answertableterm/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7062"></A>
<A NAME="IDX7063"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>sql_get_tables/2:</B>
<DD><A NAME="IDX7064"></A>
<P>
<STRONG>Usage 1:</STRONG> <CODE>sql_get_tables(+Location, -Tables)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Tables</CODE> contains the tables available in <CODE>Location</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Location</CODE> is a structure describing a database.
(<CODE>persdbrt_mysql:database_desc/1</CODE>)
<CODE>-Tables</CODE> is a list of <CODE>atm</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
<P>
<STRONG>Usage 2:</STRONG> <CODE>sql_get_tables(+DbConnection, -Tables)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Tables</CODE> contains the tables available in <CODE>DbConnection</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DbConnection</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>-Tables</CODE> is a list of <CODE>atm</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7065"></A>
<A NAME="IDX7066"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>sql_table_types/3:</B>
<DD><A NAME="IDX7067"></A>
<P>
<STRONG>Usage 1:</STRONG> <CODE>sql_table_types(+Location, +Table, -AttrTypes)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>AttrTypes</CODE> are the attributes and types of <CODE>Table</CODE> in <CODE>Location</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+Location</CODE> is a structure describing a database.
(<CODE>persdbrt_mysql:database_desc/1</CODE>)
<CODE>+Table</CODE> is an atom.
(<CODE>basic_props:atm/1</CODE>)
<CODE>-AttrTypes</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
</UL>
<P>
<STRONG>Usage 2:</STRONG> <CODE>sql_table_types(+DbConnection, +Table, -AttrTypes)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>AttrTypes</CODE> are the attributes and types of <CODE>Table</CODE> in <CODE>DbConnection</CODE>.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DbConnection</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+Table</CODE> is an atom.
(<CODE>basic_props:atm/1</CODE>)
<CODE>-AttrTypes</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7068"></A>
<A NAME="IDX7069"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>socketname/1:</B>
<DD><A NAME="IDX7070"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>socketname(IPP)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>IPP</CODE> is a structure describing a complete TCP/IP port address.
</UL>
</DL>
<P>
<A NAME="IDX7071"></A>
<A NAME="IDX7072"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>dbname/1:</B>
<DD><A NAME="IDX7073"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbname(DBId)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>DBId</CODE> is the identifier of an database.
</UL>
</DL>
<P>
<A NAME="IDX7074"></A>
<A NAME="IDX7075"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>user/1:</B>
<DD><A NAME="IDX7076"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>user(User)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>User</CODE> is a user name in the database.
</UL>
</DL>
<P>
<A NAME="IDX7077"></A>
<A NAME="IDX7078"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>passwd/1:</B>
<DD><A NAME="IDX7079"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>passwd(Passwd)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Passwd</CODE> is the password for the user name in the database.
</UL>
</DL>
<P>
<A NAME="IDX7080"></A>
<A NAME="IDX7081"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>projterm/1:</B>
<DD><A NAME="IDX7082"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>projterm(DBProjTerm)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>DBProjTerm</CODE> is a database projection term.
</UL>
</DL>
<P>
<A NAME="IDX7083"></A>
<A NAME="IDX7084"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>querybody/1:</B>
<DD><A NAME="IDX7085"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>querybody(DBGoal)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>DBGoal</CODE> is a database query goal.
</UL>
</DL>
<P>
<A NAME="IDX7086"></A>
<DL>
<DT><span class="define">(UNDOC_REEXPORT):</span> <B>sqltype/1:</B>
<DD><A NAME="IDX7087"></A>
<P>
Imported from
<A NAME="IDX7088"></A>
<CODE>sqltypes</CODE> (see the corresponding documentation for details).
</DL>
<H2><A NAME="SEC637" HREF="ciao_toc.html#TOC637">Documentation on multifiles (<CODE>persdbrt_mysql</CODE>)</A></H2>
<P>
<A NAME="IDX7089"></A>
<A NAME="IDX7090"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>sql_persistent_location/2:</B>
<DD><A NAME="IDX7091"></A>
<P>
Relates names of locations (the <CODE>Keyword</CODE>s) with descriptions of such locations (<CODE>Location</CODE>s).
<P>
The predicate is <EM>multifile</EM>.
<P>
The predicate is of type <EM>dynamic</EM>.
<P>
<STRONG>Usage:</STRONG> <CODE>sql_persistent_location(Keyword, DBLocation)</CODE>
<UL>
<LI><EM>Description:</EM> In this usage, <CODE>DBLocation</CODE> is a <EM>relational database</EM>, in which case the predicate is stored as tuples in the database.
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>Keyword</CODE> is the name of a persistent storage location.
(<CODE>persdbrt_mysql:persLocId/1</CODE>)
<CODE>DBLocation</CODE> is a structure describing a database.
(<CODE>persdbrt_mysql:database_desc/1</CODE>)
</UL>
</DL>
<H2><A NAME="SEC638" HREF="ciao_toc.html#TOC638">Documentation on internals (<CODE>persdbrt_mysql</CODE>)</A></H2>
<P>
<A NAME="IDX7092"></A>
<A NAME="IDX7093"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>tuple/1:</B>
<DD><A NAME="IDX7094"></A>
<PRE>
tuple(T) :-
list(T,atm).
tuple(T) :-
list(T,atm).
</PRE>
<P>
<STRONG>Usage:</STRONG> <CODE>tuple(T)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>T</CODE> is a tuple of values from the ODBC database interface.
</UL>
</DL>
<P>
<A NAME="IDX7095"></A>
<A NAME="IDX7096"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>dbconnection/1:</B>
<DD><A NAME="IDX7097"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>dbconnection(H)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>H</CODE> a unique identifier of a database session connection.
</UL>
</DL>
<P>
<A NAME="IDX7098"></A>
<A NAME="IDX7099"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>sql_persistent/3:</B>
<DD><A NAME="IDX7100"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>sql_persistent(PrologPredTypes, TableAttributes, Keyword)</CODE>.
<UL>
<LI><EM>Description:</EM> Declares the predicate corresponding to the main functor of <CODE>PrologPredTypes</CODE> as SQL persistent. <CODE>Keyword</CODE> is the
<A NAME="IDX7101"></A>
name of a location where the
<A NAME="IDX7102"></A>
persistent storage for the predicate is kept, which in this case must be an external relational database. The description of this database is given through the
<A NAME="IDX7103"></A>
<CODE>sql_persistent_location</CODE> predicate, which must contain a fact in which the first argument unifies with <CODE>Keyword</CODE>. <CODE>TableAttributes</CODE> provides the
<A NAME="IDX7104"></A>
table name and
<A NAME="IDX7105"></A>
attributes in the database corresponding respectively to the predicate name and arguments of the (virtual) Prolog predicate.
Although a predicate may be persistent, other usual clauses can be defined in the source code. When querying a persistent predicate with non-persistent clauses, persistent and non-persisten clauses will be evaluated in turn; the order of evaluation is the usual Prolog order, considering that persistent clauses are defined in the program point where the
<A NAME="IDX7106"></A>
<CODE>sql_persistent/3</CODE> declaration is.
<STRONG>Example:</STRONG>
<PRE>
:- sql_persistent(product( integer, integer, string, string ),
product( quantity, id, name, size ),
radiowebdb).
sql_persistent_location(radiowebdb,
db('SQL Anywhere 5.0 Sample', user, pass,
'r2d5.dia.fi.upm.es':2020)).
</PRE>
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>PrologPredTypes</CODE> is a structure describing a Prolog predicate name with its types.
(<CODE>persdbrt_mysql:prologPredTypes/1</CODE>)
<CODE>TableAttributes</CODE> is a structure describing a table name and some attributes.
(<CODE>persdbrt_mysql:tableAttributes/1</CODE>)
<CODE>Keyword</CODE> is the name of a persistent storage location.
(<CODE>persdbrt_mysql:persLocId/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7107"></A>
<A NAME="IDX7108"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>db_query/4:</B>
<DD><A NAME="IDX7109"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>db_query(+DBId, +ProjTerm, +Goal, ResultTerm)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>ResultTerm</CODE> contains all the
<A NAME="IDX7110"></A>
tuples which are the response from database <CODE>DBId</CODE> to the Prolog query <CODE>Goal</CODE>, projected onto <CODE>ProjTerm</CODE>. Uses
<A NAME="IDX7111"></A>
<CODE>pl2sqlstring/3</CODE> for the
<A NAME="IDX7112"></A>
Prolog to SQL translation and
<A NAME="IDX7113"></A>
<CODE>sql_query/3</CODE> for posing the actual query.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+ProjTerm</CODE> is a database projection term.
(<CODE>pl2sql:projterm/1</CODE>)
<CODE>+Goal</CODE> is a database query goal.
(<CODE>pl2sql:querybody/1</CODE>)
<CODE>ResultTerm</CODE> is a tuple of values from the ODBC database interface.
(<CODE>persdbrt_mysql:tuple/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7114"></A>
<A NAME="IDX7115"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>db_query_one_tuple/4:</B>
<DD><A NAME="IDX7116"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>db_query_one_tuple(+DBId, +ProjTerm, +Goal, ResultTerm)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>ResultTerm</CODE> is one of the
<A NAME="IDX7117"></A>
tuples which are the response from database <CODE>DBId</CODE> to the Prolog query <CODE>Goal</CODE>, projected onto <CODE>ProjTerm</CODE>. Uses
<A NAME="IDX7118"></A>
<CODE>pl2sqlstring/3</CODE> for the
<A NAME="IDX7119"></A>
Prolog to SQL translation and
<A NAME="IDX7120"></A>
<CODE>sql_query_one_tuple/3</CODE> for posing the actual query. After last tuple has been reached, a null tuple is unified with ResultTerm, and the connection to the database finishes.
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+ProjTerm</CODE> is a database projection term.
(<CODE>pl2sql:projterm/1</CODE>)
<CODE>+Goal</CODE> is a database query goal.
(<CODE>pl2sql:querybody/1</CODE>)
<CODE>ResultTerm</CODE> is a predicate containing a tuple.
(<CODE>persdbrt_mysql:answertupleterm/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX7121"></A>
<A NAME="IDX7122"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>sql_query_one_tuple/3:</B>
<DD><A NAME="IDX7123"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>sql_query_one_tuple(+DBId, +SQLString, ResultTuple)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>ResultTuple</CODE> contains an element from the set of tuples which represents the response in <CODE>DBId</CODE> to the
<A NAME="IDX7124"></A>
SQL query <CODE>SQLString</CODE>. If the connection is kept, succesive calls return consecutive tuples, until the last tuple is reached. Then a null tuple is unified with <CODE>ResultTuple</CODE> and the connection is finished (calls to
<A NAME="IDX7125"></A>
<CODE>mysql_disconnect/1</CODE>).
<LI><EM>Call and exit should be <EM>compatible</EM> with:</EM>
<CODE>+DBId</CODE> a unique identifier of a database session connection.
(<CODE>mysql_client:dbconnection/1</CODE>)
<CODE>+SQLString</CODE> is a string containing SQL code.
(<CODE>pl2sql:sqlstring/1</CODE>)
<CODE>ResultTuple</CODE> is a tuple of values from the ODBC database interface.
(<CODE>persdbrt_mysql:tuple/1</CODE>)
</UL>
</DL>
<H2><A NAME="SEC639" HREF="ciao_toc.html#TOC639">Known bugs and planned improvements (<CODE>persdbrt_mysql</CODE>)</A></H2>
<UL>
<LI>
At least in the shell, reloading a file after changing the definition of a persistent predicate does not eliminate the old definition...
<LI>
Functionality missing: some questions need to be debugged.
<LI>
Warning: still using kludgey string2term and still using some non-uniquified temp files.
<LI>
Needs to be unified with the file-based library.
</UL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_150.html">previous</A>, <A HREF="ciao_152.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
