Database/Drivers/New Driver Tutorial
Contents
Preface
This small How-To contains a simple step-by-step introduction on how to put your driver inside the connectivity module. The second part of this document covers differences between a driver in connectivity module and a driver in an UNO package. This document is a not manual on how to write a driver, but how to put it in an OpenOffice.org connectivity module.
Parts of our driver
Lets say that our driver implements the following services:
sdbc.Driver - org.openoffice.comp.connectivity.6sql.Driver sdbc.Connection – org.openoffice.comp.connectivity.6sql.Connection
For a more complicated example, let's assume that our driver depends on two external libraries. Because we are covering the Windows platform only, these libraries are in DLL files. The names of these libraries are lib6sql.dll and lib6sql-security.dll. These libraries must be installed inside the OpenOffice.org/program directory; otherwise our driver will not work.
External libraries
External module and deliver script
Put your external libraries in external/6sql directory and add following lines in external/prj/d.lst file:
..\6sql\lib6sql.dll %_DEST%\bin%_EXT%\lib6sql.dll ..\6sql\lib6sql-security.dll %_DEST%\bin%_EXT%\lib6sql-security.dll
This makes deliver happy and your DLL libraries will be delivered to solver directory.
Installation
You have to look at scp2 module. Define gids for your libraries in scp2/source/ooo/file_library_ooo.scp:
#ifdef WNT File gid_File_Lib_6sql BIN_FILE_BODY; Styles = (PACKED); Dir = gid_Dir_Program; Name = "lib6sql.dll"; End File gid_File_Lib_6sql_security BIN_FILE_BODY; Styles = (PACKED); Dir = gid_Dir_Program; Name = "lib6sql-security.dll"; End #endif
Do not forget to put your gids in scp2/source/ooo/module_hidden_ooo.scp to install your DLL libraries within the hidden module.
Driver
Connectivity module
We put our driver in the connectivity/source/drivers/6sql directory. To build and deliver it properly, we need to modify the build.lst and d.lst files. Add the following line in connectivity/prj/build.lst file:
cn connectivity\source\drivers\6sql nmake - all cn_6sql cn_dbtools NULL
And add the following line in the connectivity/prj/d.lst file:
..\source\drivers\6sql\*.xml %_DEST%\xml%_EXT%\*.xml
This makes build and deliver happy when the build process reaches the connectivity module.
Driver service
Let's assume that our sdbc.Driver service is implemented and compiled into the 6sql-driver.dll library. We have to create an 6sql-driver.xml file with following content:
<?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE COMPONENTDESCRIPTION PUBLIC "-//W3C//DTD HTML 3.2//EN" "module-description.dtd"> <module-description xmlns:xlink="http://www.w3.org/1999/xlink"> <module-name> 6sql-driver </module-name> <component-description> <Author>Your Name</Author> <Name>org.openoffice.comp.connectivity.6sql.Driver</Name> <Description> This is the implementation of the 6SQL bridge. </Description> <loader-name>com.sun.star.loader.SharedLibrary</loader-name> <language>c++</language> <status value="final"/> <supported-service> com.sun.star.sdbc.Driver </supported-service> <service-dependency> ... </service-dependency> </component-description> </module-description>
Do not forget to put your build and run dependencies in this file. Search for XML files inside the source/drivers directory to get more examples.
Connection service
Let's assume that our sdbc.Connection service is implemented and compiled into 6sql-connection.dll library. We have to create 6sql-connection.xml file with following content:
<?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE COMPONENTDESCRIPTION PUBLIC "-//W3C//DTD HTML 3.2//EN" "module-description.dtd"> <module-description xmlns:xlink="http://www.w3.org/1999/xlink"> <module-name> 6sql-connection </module-name> <component-description> <Author>Your Name</Author> <Name>org.openoffice.comp.connectivity.6sql.Connection</Name> <Description> This is the implementation of the 6SQL connection. </Description> <loader-name>com.sun.star.loader.SharedLibrary</loader-name> <language>c++</language> <status value="final"/> <supported-service> com.sun.star.sdbc.Connection </supported-service> <service-dependency> ... </service-dependency> </component-description> </module-description>
Again, do not forget to put some build and run dependencies in this file. Now, you should have idea why we put *.xml in project deliver file.
Installation
We have to install our driver libraries similar to the external libraries. Our driver implements services (it's an UNO component), so we have to modify our gid's definitions. So, put following lines in scp2/source/ooo/file_library_ooo.scp file:
#ifdef WNT File gid_File_Lib_6sql_driver TXT_FILE_BODY; Styles = (PACKED,UNO_COMPONENT,PATCH); RegistryId = gid_Starregistry_Services_Rdb; Dir = gid_Dir_Program; Name = "6sql-driver.dll"; End File gid_File_Lib_6sql_connection TXT_FILE_BODY; Styles = (PACKED,UNO_COMPONENT,PATCH); RegistryId = gid_Starregistry_Services_Rdb; Dir = gid_Dir_Program; Name = "6sql-connection.dll"; End #endif
And do not forget to put our gids in module_hidden_ooo.scp file.
Configuration
The last step is to make our driver visible to OpenOffice.org. Everything is inside the officecfg/registry/data/org/openoffice/Office/DataAccess.xcu file. The following node should be placed there as a root node:
<node oor:name="UserDefinedDriverSettings"> <node oor:name="6SQL Driver" oor:op="replace"> <prop oor:name="DriverTypeDisplayName"> <value>6SQL</value> </prop> <prop oor:name="DriverPageDisplayName"> <value>6SQL</value> </prop> <prop oor:name="DriverDsnPrefix"> <value>sdbc:6sql:</value> </prop> </node> </node>
This makes your driver visible in the "available drivers" list. Now, make this driver visible to OpenOffice.org with the following lines:
<node oor:name="org.openoffice.comp.connectivity.6sql.Driver" oor:op="replace"> <prop oor:name="DriverName"> <value>org.openoffice.comp.connectivity.6sql.Driver</value> </prop> <prop oor:name="Enable"> <value>false</value> </prop> <prop oor:name="Timeout"> <value>60</value> </prop> </node>
This node should be placed in the ConnectionPool/DriverSettings node.
Driver as UNO package
If you want to publish your driver as an UNO package, you have to build your driver libraries and then put them inside the UNO package with DataAccess.xcu file only. The content of this file should be:
<node oor:name="UserDefinedDriverSettings"> <node oor:name="6SQL Driver" oor:op="replace"> <prop oor:name="DriverTypeDisplayName"> <value>6SQL</value> </prop> <prop oor:name="DriverPageDisplayName"> <value>6SQL</value> </prop> <prop oor:name="DriverDsnPrefix"> <value>sdbc:6sql:</value> </prop> </node> </node>
Easy? Yes, it is. Be modular and use UNO packages ;-) It's an easier way, and you can update your driver more frequently.
Summary
You can use this How To for other platforms too. You have to use #ifdef, .so instead of .dll, etc. Search for more examples in all the aforementioned files. This just works. I'm not sure if everything is OK or not. If you find mistakes, let me know.