DTM database

From OESF

Revision as of 16:23, 21 September 2007

DTM HowTo:

original by: Dr. Stefan C. Kremer

Note: Dr. Kremer expresses the wish to no longer been contacted directly about any issues with the DTM database and programming. I received from him all the documents he has, he no longer develops for the Zaurus. As soon as I have a hint on how to transfer these documents on this site, I will update the page and put all the links to the documents. In the mean time, you may contact me: Daniel Savard

This document describes how to write code that interfaces with DTM (the PIM storage format)

The DTM is a simple database that runs on the Zaurus SL-5600 (and the v3.10 ROM for the SL-5500) and the SL-6000 (probably also on all Zaurii newer than the SL-5600). The new PIM applications use DTM for all data storage where the old PIM applications used XML files. DTM is faster, XML is easier to interface with other code (until now).

What you need to develop on the desktop:

1.Development tools

• need to set up your complier as described here
• probably don't really need qpe if you are not writing code with a GUI
• don't need qvfp

2.The specs and header files for the DTM access

• The files you need are here
• dtm.zip
• headers.zip

The headers and library are in the development image you can found on the ELSI for development on the Zaurus.

I haven't yet figure-out how to upload documents which are not images or sound files on this site for the benefit of everyone. I have two PDF documents on the DTM and PIM specifications I wish to make available here. E-mail me if you know how to upload them here (Daniel Savard).

3.libzdtm.so

• This is the actual shared library that you need to link against. It is found on the Zaurus in the /home/!QtPalmtop/lib/ directory. It needs to be moved to /opt/Qtopia/sharp/lib/ for cross compiling.

4.Example program

• Available here

What is in headers.zip

headers.zip has the header files for the libzdtml.so library. I copied these into my working directory for compiling, but they should probably be put somewhere sensible in the /opt file structure. These are critical since they spell out some details that are not clear from DTMSpecifications.pdf. For example that all the functions are preceded by underscore. And more info about the data types.

Potential Problems/Gotchas

1. header files aren't ansi-C. The header files are C++ compliant, but not ansi-C, so I ended up using the g++ compiler to avoid a slew of warning messages. I think it should be possible to translate the C++ files into ansi for greater compatibility.
2. no emulation. Since the only source for libzdtm.so is from the Zaurus itself and not a compiled library, it is not possible to emulate sofware on a PC architecture using qvfp or anything else. You can compile on your x86, but you'll have to move it to the Zaurus to actually make it run. I found that having the Zaurus on the network running sshd was critical to working effectively. I also put my ssh key on the Zaurus, so i wouldn't have to supply a password all the time. Then, I added an "install" directive to my makefile so that i could easily compile and copy over to code. I would run it in a seperate window on my desktop connected (again via ssh) to the Zaurus. This is the only way I could work efficiently. It would be really great if sharp released the source for DTM or at least an x86 compiled library.
3. unsigned char *. The header files define most strings as unsigned chars which is goofy. In particular, this is incompatible with all the standard string libraries on the Zaurus. As a consequence I had to do a lot of casting from (char *) to (unsigned char *) and back in order to get the compiler to quiet down.
4. Not without qte. The libzdtm.so requires libqte.so.2. I'm not sure why, it just does.

Running the Test Program

1. BACKUP YOUR MACHINE This code has only been tested on one single Zaurus. Although the database access in intended to be read-only...here comes the disclaimer... SHARP (nor Stefan Kremer) ASSUME ANY RESPONSIBILITY to any conflict, fault, or damage affecting the unit that rises from your tinkering with the DTM data.
2. Make sure you have the libzdrm.so on your computer in the appropriate directory and that all the links libzdtm.so.0.1 are there too.
3. Make sure you have the source code for the test program in the current directory.
4. Compile:
   1. arm-linux-g++ -I -c -Wall -ansi -pedantic -o arm-dtmdump.o dtmdump.cc
   2. arm-linux-g++ -Wall -ansi -pedantic -o arm-dtmdump arm-dtmdump.o -L/opt/Qtopia/sharp/lib -lzdtm
5. Transfer to Zaurus:

• scp arm-dtmdump zaurus@zaurus:/home/zaurus/dtmdump

The compilation should succeed with no warnings or errors. The scp requires your zaurus to be on the network with the machine name 'zaurus'.

Program Output/Operation

The program takes 1 or 2 arguments as follows:

 dtmdump {todo|calendar|addressbook|memo|category}      dtmdump -f /home/zaurus/Applications/dtm/SLTDODO.BOX

The first form opens up a database based on the name; while the second opens a database based on a path. The first version is case insensitive, while the second is not.

The program then prints out the contents of the given database in an XML format. NOTE: the XML format used is __not__ compatible with the original PIM XML format! (I originally tried to do this, but the two DB's contain different kinds of information, so that problem is much harder, especially while I don't know what "rinfo" means.) The purpose of the program is mostly instructional at this point, but it should make it easy for others to extract DTM info and use it for their own purposes.