aRT is a package for manipulating spatial data using TerraLib. As TerraLib manipulates data stored in databases, we need to establish connections to them. This short document introduces the primary class of the package, aRTconn, that implements a virtual connection to a DBMS.
After load the package, we need to establish a DBMS connection, and we can do it calling openConn(). This function takes four arguments: user, password, host and port, and their default values are variable USER in the environment, empty string, “localhost” and 3306, respectively1 . For example:
This function returns an aRTconn object if successful. Once the object conn is created, the variables it contains cannot be changed. If you need to set them, the only way is to create another object. It happens because data is stored in an external pointer.
If the connection cannot be established, the function stops with an error:
One aRTconn object stores a 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 using aRT, perhaps you will need to add permissions to some users. To do this, use addUser():
This function gives all permissions in all databases to a user, and only root can do that. If you want to do something different, you will need to run mysql for yourself, and use the grant command [2].
With an aRTconn object, you can also see the available databases (the ones which the user has permission):
and then you can remove databases using this object:
The argument force=TRUE is used to avoid a keyboard confirmation, because it is a dangerous operation and cannot be undone.
Databases can be opened with openDb():
or created, using createDb():
Both objects belong to class aRTdb, and store a real connection to a database. Therefore these objects do not need the virtual connection anymore.
Note that an aRTdb object can become inconsistent if the database is removed from the DBMS, and it can generate a core dump. It cannot be avoided, because the database can be removed from anywhere, since another aRTconn object, directly from MySQL, or by another TerraLib-based program. The better solution is to remove the database connection from memory before delete it.
[1] Chambers, J.M., 1998, Programming with data, a guide to the S language. Springer, New York.
[2] MySQL Documentation. http://dev.mysql.com/doc/. Last access: 08/14/2005