Database/Drivers/New Driver Tutorial
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 in similiar way as external libraries. Our driver implements services, it's an UNO compoment, 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 gid's in module_hidden_ooo.scp file.
Configuration
Last step is to make our driver visible to OpenOffice.org. Everything is inside officecfg/registry/data/org/openoffice/Office/DataAccess.xcu file. 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 available drivers list. Now, make this driver visible to OpenOffice.org with 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 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, put them inside UNO package with DataAccess.xcu file only. 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 ;-) 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 mentioned files. This just works. I'm not sure if everything is OK or not. If you find mistakes, just let me know.