                      PUI/TCLPUI  v0.5.2
                      ==================

                     Pilot-Unix Interface

         Copyright (c) 1996, Scotter <scotter@iname.com>

 This is free software, licensed under the GNU Library Public License V2.

This archive contains two subdirectories.
You may need to change a reference to your
"pilot-link" directory in {pui,tclpui}/Makefile.
(And other Makefile changes for non-Linux/i386 Architectures.)


pui
===

  Pui is a first pass at a Pilot-Unix Interface, storing pilot
  data records in a gdbm file. (I call them .pui files to distinguish
  them from .pdb/.prc files.)

  "Pui" consists of a library, libpui.a, to be used when writing
  programs that communicate in this format, and several
  sample executable files.

  Pui files can be created either through communicating
  directly with a pilot or by converting ".pdb" files.
  "pui-xfer" is a direct rip-off from pilot-xfer, though
  it reads and writes ".pui" files.
  "pdb2pui" and "pui2pdb" convert from and to standard .pdb files.

  "pui-dump" dumps the contents of a gdbm ".pui" file.
  "pui-clear" removes all records from a database that are
  tagged for deletion.

  The library for talking to the ".pui" gdbm database contains no
  references to the pisocket code. Idealy, manipulation of data
  can be independent of communication to the pilot.

  The database reserves all 4-byte keys for actual records from
  the pilot, using their 4-byte id as the key.

  For each record, a header record is also stored, with the attribute
  and category information, and linked list "pointers" to allow the
  entries to be kept in a specific order.
  The "header_record" has a 5-byte key, the first four repeating
  the id, and the fifth a "magic number." (42, for the obvious reason.)

  Additionally, there are two records in the database with one-byte
  keys. One is the DBInfo of the database; see pilot-link for details.
  The other contains global information-- number of records, head
  and tail of linked list, etc.

  I've spotted in some "locks" but am currently not using them.

  The ".pui" files currently do not store AppInfo data, so
  user preferences will be lost during a clean reset.
  (This will be added.)

tclpui
======
  Tclpui is a tcl front-end for ".pui" files.
  It is built as a dynamically shared object to be
  loaded into tclsh/wish scripts with the "load" command.

  Since pilot records are binary, they can't themselves be used
  in tcl. (There are binary extensions to tcl, but they are a pain
  to use.)

  Instead, tclpui uses the "pack/unpack" routines from pilot-link
  for each type of database.

  Rather than pass all of a record's entries via command line,
  the record data is transferred via array variables. The
  array indices match the field names in the header files.

  For example, in an AddressDB, one might use:

    load tclpui.so
    set puidb [puiOpen AddressDB.pui]
    foreach id [puiList $puidb] {
      puiRead $puidb $id record
      puts "$record(lastname), $record(firstname)"
    }
    puiClose $puidb

  to dump out all the names in the database.

  pui-addressbook is a simple script that allows an AddressDB.pui file
  to be browsed and editted. It does NOT try to mimic the pilot interface.

  pui-dumpdb is a simple script to dump all the fields from all the
  records of any database. No interpretation of the fields is made.

  pui-dumptodos is similar to dumpdb, but is specific to ToDoDB databases.
  (Note how the date is converted to something readable.)

  pui-prez shows a "business card" script.

  pui-addmemo takes stdin and adds it to a memo database.
  pui-mailtomemo uses "addmemo" to add mail messages to the memo database.

  pui-dbinfo prints the DBInfo for a given database.

  pui-makenew creates new, empty databases of the four standard types:
  AddressDB, MemoDB, ToDoDB, and DatebookDB. This script contains
  the default "DBInfo" data needed for these new databases to be
  recognized by the pilot.

  pui-names dumps all the names from a database
  pui-names2 same as above, with a different loop method.

  pui-tabtoaddress sample script to build an address book from
  tab-delimited data.

  pui-archivetodos tags "completed" todo items for archiving.

  pui-backup script to backup and clean databases.

--------------
Scotter <scotter@iname.com>

