%  aRT : API R - TerraLib                                                
%  Copyright (C) 2003-2005  LEG                                          
%                                                                        
%  This program is free software; you can redistribute it and/or modify  
%  it under the terms of the GNU General Public License as published by  
%  the Free Software Foundation; either version 2 of the License, or     
%  (at your option) any later version.                                   
%                                                                        
%  This program is distributed in the hope that it will be useful,       
%  but WITHOUT ANY WARRANTY; without even the implied warranty of        
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
%  GNU General Public License for more details.                          
%                                                                        
%  You should have received a copy of the GNU Lesser General Public      
%  License along with this library.

\documentclass{article}

\usepackage{Sweave}

\newcommand{\aRT}{{\tt aRT}}
\newcommand{\tl}{\textsf{TerraLib}}
\newcommand{\code}[1]{{\tt #1}}
\newcommand{\R}{}

\title{Connecting and Managing Databases with \aRT}
\author{Pedro Ribeiro de Andrade Neto\\
Paulo Justiniano Ribeiro Júnior}
%\date{Aug 2005}

\begin{document}
\maketitle

<<label=Rsettings,echo=FALSE,results=hide>>=
options(width=69)
#options(SweaveHooks=list(fig=function() par(mar=c(3,3,1,0.5),
#mgp=c(2,0.8,0))))
#set.seed(123)
@

\section{Introduction}
\aRT\ is a package for manipulating spatial data through \tl.
%But, besides it, \aRT\ can execute some administration tasks.
As \tl\ manipulates data stored in databases, we need to stablish
connections to them. This short document introduces the primary
class of the package, {\tt aRTconn}, that implements a virtual 
connection to a DBMS.

<<label="Loading package">>=   
require(aRT)
@

\section{Connections}
After load the package, we need a DBMS connection, and we can do it calling
the function {\tt openConn}. This function takes four arguments:
\code{user}, \code{password}, \code{host} and \code{port}, and their default
values are variable USER in the environment, empty string, ``localhost''
and 3306, respectivaly\footnote{In the future, there will be a fifth argument,
\code{DBMS}, with values ``MySQL'', ``Postgres'', ``PostGIS'', etc.}. For
example:

<<label="Creating a DBMS connection">>=
conn <- openConn(user="root", host="localhost", pass="")
@

This function returns an \code{aRTconn} object if successfull. 
Once the object \code{conn} is created, the variables it contains cannot be 
changed. If you need to set them, the only way is to create another object.
This occours because data is stored in a external pointer.
<<label="conn">>=
conn
@

If the connection cannot be stablished, the function stops with an error:
<<label="Creating a DBMS connection">>=
err= try(conn2 <- openConn(user="root", pass="abc321"))
strsplit(err[1]," : ")
@

One {\tt aRTconn} object stores a \emph{virtual} connection, i.e., all time
that a database access is required, it connects, does some stuff, and then
disconnects. For example, if it is the first time you are
running \aRT, perhaps you will need to add permissions to some users. To do
this, use \code{addUser()}:
<<label="Adding user">>=
addUser(conn, "pedro")
@
This function gives \emph{all} permissions in \emph{all} databases to a user,
and only root can do that. If you want to do something different, you need to
run mysql for yourself, and use the \emph{grant} command.

With an {\tt aRTconn} object, you can also see the available databases
(the ones which the user has permission):
<<label="Showing databases">>=
showDbs(conn)
@
and then you can open remove databases:
<<label="deleteDb">>=
if(any(showDbs(conn) == "intro")) deleteDb(conn, "intro", force=T)
@
The argument \code{force=TRUE} is used to avoid a keyboard confirmation,
because it is a dangerous operation and cannot be undone.

Databases can also be opened...
<<label="openDb">>=
db = openDb(conn, showDbs(conn)[1])
@
or created...
<<label="createDb">>=
dbintro = createDb(conn, "intro")
@
Both objects store a real connection to a database, and do not need the
connection anymore.

Note that an \code{aRTdb} object can become inconsistent if the database is
removed, and it can generate a core dump. It cannot be avoided, because the
database can be removed from anywhere,
since another \code{aRTconn} object, directly from MySQL, or another \tl-based
program. The better solution is remove the database connection from memory
before delete it.
<<label="rm gc">>=
rm(db)
rm(dbintro)
invisible(gc())
@

\section*{References}
\begin{description}
\item Chambers, J.M., 1998, Programming with data, a guide to the S language.
Springer, New York.
\end{description}

\end{document}

% vim:syntax=tex
