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 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.