Difference between revisions of "Database/Drivers/New Driver Tutorial"

From Apache OpenOffice Wiki
Jump to: navigation, search
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== Preface ==
 
== Preface ==
  
This small How To contains simple step-by-step introduction how to put your driver inside connectivity module. Second part of this document covers differences between driver in connectivity module and driver in an UNO package. This document is not manual how to write driver, but how to put it in OpenOffice.org connectivity module.
+
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 ==
 
== Parts of our driver ==
  
Lets say, that our driver implements following services:
+
Lets say that our driver implements the following services:
  
 
     sdbc.Driver - org.openoffice.comp.connectivity.6sql.Driver
 
     sdbc.Driver - org.openoffice.comp.connectivity.6sql.Driver
 
     sdbc.Connection – org.openoffice.comp.connectivity.6sql.Connection
 
     sdbc.Connection – org.openoffice.comp.connectivity.6sql.Connection
  
For more complicated example, lets assume that our driver depends on two external libraries. Because we are covering Windows platform only, these libraries are in DLL files. Name of these libraries are lib6sql.dll and lib6sql-security.dll. These libraries must be installed inside OpenOffice.org/program directory otherwise our driver will not work.
+
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 libraries ==
Line 21: Line 21:
 
     ..\6sql\lib6sql-security.dll %_DEST%\bin%_EXT%\lib6sql-security.dll
 
     ..\6sql\lib6sql-security.dll %_DEST%\bin%_EXT%\lib6sql-security.dll
  
This makes deliver happy and your DLL libraries will be deliver to solver directory.
+
This makes deliver happy and your DLL libraries will be delivered to solver directory.
  
 
=== Installation ===
 
=== Installation ===
  
You have to look at scp2 module. Define gid's for your libraries in scp2/source/ooo/file_library_ooo.scp:
+
You have to look at scp2 module. Define gids for your libraries in scp2/source/ooo/file_library_ooo.scp:
  
 
     #ifdef WNT
 
     #ifdef WNT
Line 45: Line 45:
 
     #endif
 
     #endif
  
Do not forget to put your gid's in scp2/source/ooo/module_hidden_ooo.scp to install your DLL libraries within hidden module.
+
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 ==
 
== Driver ==
Line 51: Line 51:
 
=== Connectivity module ===
 
=== Connectivity module ===
  
We put our driver in connectivity/source/drivers/6sql directory. To build and deliver it properly, we need to modify build.lst and d.lst files. Add following line in connectivity/prj/build.lst file:
+
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
 
     cn connectivity\source\drivers\6sql nmake - all cn_6sql cn_dbtools NULL
  
And add following line in connectivity/prj/d.lst file:
+
And add the following line in the connectivity/prj/d.lst file:
  
 
     ..\source\drivers\6sql\*.xml %_DEST%\xml%_EXT%\*.xml
 
     ..\source\drivers\6sql\*.xml %_DEST%\xml%_EXT%\*.xml
  
This makes build and deliver happy when build process reaches connectivity module.
+
This makes build and deliver happy when the build process reaches the connectivity module.
  
 
=== Driver service ===
 
=== Driver service ===
  
Let's assume that our sdbc.Driver service is implemented and compiled into 6sql-driver.dll library. We have to create 6sql-driver.xml file with following content:
+
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"?>
 
     <?xml version='1.0' encoding="UTF-8"?>
Line 83: Line 83:
 
     </module-description>
 
     </module-description>
  
Do not forget to put your build and run dependencies in this file. Search for xml files inside source/drivers directory to get more examples.
+
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 ===
 
=== Connection service ===
Line 111: Line 111:
 
=== Installation ===
 
=== 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:
+
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
 
     #ifdef WNT
Line 133: Line 133:
 
     #endif
 
     #endif
  
And do not forget to put our gid's in module_hidden_ooo.scp file.
+
And do not forget to put our gids in module_hidden_ooo.scp file.
  
 
=== Configuration ===
 
=== 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:
+
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="UserDefinedDriverSettings">
Line 153: Line 153:
 
     </node>
 
     </node>
  
This makes your driver visible in available drivers list. Now, make this driver visible to OpenOffice.org with following lines:
+
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">
 
     <node oor:name="org.openoffice.comp.connectivity.6sql.Driver" oor:op="replace">
Line 167: Line 167:
 
     </node>
 
     </node>
  
This node should be placed in ConnectionPool/DriverSettings node.
+
This node should be placed in the ConnectionPool/DriverSettings node.
  
 
== Driver as UNO package ==
 
== 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:
+
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="UserDefinedDriverSettings">
Line 187: Line 187:
 
     </node>
 
     </node>
  
Easy? Yes, it is. Be modular and use UNO packages ;-) Easier way and you can update your driver more frequently.
+
Easy? Yes, it is. Be modular and use UNO packages ;-) It's an easier way, and you can update your driver more frequently.
  
 
== Summary ==
 
== 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.
+
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, just let me know.
+
This just works. I'm not sure if everything is OK or not. If you find mistakes, let me know.
 +
 
 +
[[Category:Base_Tutorials]]
 +
[[Category:Database Drivers|Tutorial]]

Revision as of 12:13, 21 November 2008

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.

Personal tools