# # FILE .../CPAN/hp200lx-db/README # # $VERSION= '0.09'; # # written: 1998-01-10 # latest update: 2000-01-02 22:06:11 # $Id: $ # Purpose: DB.pm implements the perl package HP200LX::DB which is intended to provide a perl 5 interface for files in the generic database format of the HP 200LX palmtop computer. The perl modules are intended to be used on a work station such as a Unix machine or a PC to read and write data records from and to a database file. Goals and Non-Goals of this Project: The primary goal was to read and write complete generic database files, e.g. GDB, PDB or NDB files on a host computer. The transfer from and to the palmtop computer, synchronization and reconciliation were not considered at all yet. Also, other built-in applications operate on slightly different DB files, these are not dealt with yet. The creation, definition and layout of new databases are not handled yet. Project Roadmap: 1. read/write GDB, PDB, and NDB files [quite complete] 2. a simple GUI to browse the DB files [in progress] 3. tools to import/export data in different formats [in progress] 4. extend the DB module for ADB and WDB files [in progress] 5. creation of DB files including format definitions etc. 6. dealing with encrypted DB files [in progress] Status: The package and any other files are in a completely EXPERIMENTAL STATUS and should not be used without proper backup. Use it at your own risk, no support can be provided but bug reports and suggestions by e-mail are welcome. Please read the notes below first. Note: The package emits all sorts of diagnostic information, these are not errors and change from release to release, depending on the development progress. Note: The DB formats have a number of limitations, this package tries to enforce them but most are not dealt with properly yet. Note: reading ADB files is fairly complete, an extension which can also write and update ADB files is currently in development. Installation: The usual installation strategy perl Makefile.PL make make test make install should produce viable modules. Note: Under 4Dos do not run dmake. "command /c dmake" should work. Limitations: Development has been driven by my own requirements and my needs are not so big, so you should not be surprised if much remains left to be done. Here is a list of missing things that I'm aware of: + Databases can only be read or updated. It's not possible to create a database from scratch. + Only GDB, PDB and NDB files are covered, the more special formats ADB and WDB need a few more hacks. As of now, these files can be read but not written! + When storing records to the database, make sure that fieldnames match exactly, including blanks, case, and national characters. + Lines in note fields should be stored with \r\n line endings. This is not checked here. + The viewpoint table is not rebuilt by default when a database is updated. This must be done explicitly on the HP 200LX after loading the database by starting the "SORT" dialog. Resorting a view point is usually done by pressing F7 and F10. The DB also supports a method to update view points: $db->refresh_viewpt (-1); + Databases with password protection are not handled yet correctly, it is however possible to read the password using the $db->recover_password (); method! If you didn't already know, the password protection is not very secure in the HP-LX! + Be also aware of Perl's limited TIEARRAY implementation. Array elements need to be accessed by index. No push, pop, shift and unshift operators are available. Examples: The directory "demo" contains a few code fragments, working scripts can be found in the "scripts" directory: catadb.pl export the contents of an ADB file in various formats catgdb.pl export the contents of GDB, PDB, NDB and WDB files txt2ndb.pl import text paragraphs into a NDB file xdb.pl Perl/Tk GUI for DB files leer.ndb empty german NDB file used for txt2ndb.pl Availability and Contact: This package is available from my FTP archives ftp://ftp.wu-wien.ac.at/pub/usr/edvz/gonter/hp200lx/ http://falbala.wu-wien.ac.at:8684/pub/english.cgi/0/24065 and I can be reached as Gerhard.Gonter@wu-wien.ac.at or g.gonter@ieee.org . Redistribution is permitted but it must include the README file. Copyright: Copyright (c) 1998 Gerhard Gonter. All rights reserved. This is free software; you can redistribute it and or modify it under the same terms as Perl itself. ----------------------------------------------------------------------------- interface functions $db= HP200LX::DB::openDB ($fnm) read database and return an DB object $db= HP200LX::DB::new ($fnm) create database and return an DB object $db->saveDB ($fnm) save DB object as a (new) file array tie implementation to access database data records tie (@dbd, HP200LX::DB, $db); access database data in array form TIEARRAY stub to get an tie for the database FETCH retrieve a record STORE store a record $db->get_last_index () return highest index Notes: All database data are read from file or written back in one burst. No attempt has been made to read data when it is accessed by the perl application. This only complicates matters and does not seem to be necessary since a type HP 200LX only has about 4 MB to store.