Pilot Address Selection Library

(c) Joergen Pisarz, Berlin, Germany 1997


Short description
=================
PilotADR.dll supports the selection and export of one address from the 
Pilot Database without running the Pilot Desktop program. 
A "Microsoft Word for Windows 6 and 7" macro and a "Lotus WordPro 96"
script is included for getting an address into a document with a few
mouseclicks.


Description
===========
The DLL exports the functions "GetPilotADR" and "GetPilotAddress"
which shows a dialog containing all names in Pilot's address
database. Display, sorting and extraction of names can be changed.
By choosing a name the function returns a data set containing
following items:

"name","fistname","title","company","faxnumber","address","ctiy","country",
"code","state","custom1","custom2","custom3","custom4"

The calling process can use the data set as its like.

The included macros for Winword and scripts for WordPro will insert
a set at cursor in a form like

	name firstname
	title
	company
	address
	code city country
	state

respectively 

	name firstname
	title
	company
	faxnumber

Additional information
----------------------
PilotADR reads directly from harddisk. If you are changing addresses with 
Pilot Desktop, you have to save these changes, before PilotADR will notice 
it. (Saving your work is a good idea, anyway!)

PilotADR uses the database of the user who was active, when Pilot Desktop 
runs last time. So if you're changing the user in Pilot Desktop, you have 
to close the application (and restart, if you want). After that PilotADR 
will notice the change.


Files
=====
README.TXT      this file
LIESMICH.TXT    this file in German

PILOTADR.DLL    function library for access to Pilot's addresses

P_ADR_E6.DOT    Winword 6 macro using PilotADR.dll
P_ADR_E7.DOT    Winword 7 macro using PilotADR.dll
P_ADR_D6.DOT    Winword 6 macro using PilotADR.dll in German
P_ADR_D7.DOT    Winword 7 macro using PilotADR.dll in German

PILOTADR.LSS    WordPro 96 script inserts an address
PILOTFAX.LSS    WordPro 96 script inserts a faxnumber
P_ADR_EN.SMI    WordPro 96 Smarticon definition file
P_ADR_DE.SMI    WordPro 96 Smarticon definition file in German
PILOTADR.BMP    WordPro 96 Smarticon bitmap
PILOTFAX.BMP    WordPro 96 Smarticon bitmap


Installation
============
PilotADR.dll
------------
Copy PilotADR.dll in windows system directory (e.g. C:\WINDOWS\SYSTEM).

Microsoft Word for Windows 7
----------------------------
Copy P_ADR_E7.dot in Word startup directory (e.g. C:\MOSOFFICE\WORD\STARTUP).

Mircrosoft Word for Windows 6
-----------------------------
Copy P_ADR_E6.dot in Word startup directory (e.g. C:\MOSOFFICE\WORD\STARTUP).

Lotus WordPro 96
----------------
Copy PILOTADR.LSS and PILOTFAX.LSS in the "script" directory 
of WordPro (e.g. C:\LOTUS\WORDPRO\SCRIPTS),
copy PILOTADR.BMP, PILOTFAX.BMP and P_ADR_EN.SMI in the "icon"
directory of WordPro (e.g. C:\LOTUS\WORDPRO\ICONS).

(P_ADR_D?.* is identical to P_ADR_E?.*, except of german menus.)

Systemrequirement
=================
Win95, Pilot Desktop 1 or 2
Microsoft Word for Windows (version 6 or 7) or Lotus WordPro 96 for
macros/scripts.

Usage in Winword and WordPro
============================
Navigate cursor on desired position, choose "Insert - Address" (resp. 
"Insert - Fax") or press the book-icon (resp. telefon-icon), choose
the person you want, press OK (or hit Return), ready.
In WordPro you will find a Smarticon bar with two buttons "book" and
"telefon".
A context menu can be opened with a right mouse click.  You can change the
sorting, display and extraction of datasets.

Why did I write this Program?
=============================
The original macros delivered with PalmPilot are too complex and un-handy.

Technical Notes
===============
PilotADR.dll (Version: 1.0)
---------------------------------

exported function:

	GetPilotADR(Sort, Display, Filter, Menu: Integer; ADR:  PChar):Bool
	GetPilotAddress(ADR :  PChar):Bool

GetPilotADR(Sort, Display, Filter, Menu: Integer; ADR:  PChar):Bool
-------------------------------------------------------------------
Shows a dialog for choosing a name. The dialog contains a list of 
address sets.  If a set has more than one faxnumber the set is
shown more than one time. The dialog is titled with the actual user name.
By typing some chars you can look for specific name (like in your pilot). 
Your input is shown in dialog's title, exchanging the user name. You can 
correct your input by using the backspace key. 
If a name is selected, the function returns "True" and ADR is filled with 
the set. Canceling the dialog returns "False". ADR will not be changed.

The list can be change with the following parameters:

	Sort = 0 : sorted by name, display is "Firstname Name"
	     = 1 : sorted by name, display is "Name, Firstname"
	     = 2 : sorted by company, display is "Company, Name"

If an entry has no information in name field the company filed is
shown instead.

	Display = 0 : diplay name only
		= 1 : display name and address
		= 2 : display name and faxnumber

	Filter = 0 : shows all entries in Pilot's database.
	       = 1 : shows entries with information in address field only
	       = 2 : shows entries with an faxnumber only

	Menu = 0 : The context menu is not availible
	     = 1 : context menu pop up on right mouse click

In contextmenu the first three parameters can be changed dynamically.

The Set is delivered in "Comma Delimited Format", i.e. the items are quoted 
in "-signs and separated by commas. The list of items is shown above. An 
empty item will result in an empty string.

The calling process has to reserve enough memory for ADR. The length of ADR 
is depending on the dataset. PilotADR.dll will blow up by more than 3000 
characters. In my opinion there is no need for more than 500 characters 
(all my sets are less than 160).

GetPilotAddress(ADR :  PChar):Bool
----------------------------------
That's the short version of GetPilotADR(0,0,0,1,ADR), i.e. all
datasets are shown, sorted by name in form "Firstname Name".  This
function brings compatibility to older versions of PilotADR.


P_ADR_E7.dot
------------
defined macros:

	PilotAddress
	PilotFax

Added menus:

	Insert (4th item) | Address to call PilotAddress
	Insert (4th item) | Fax to call PilotFax

Added Buttons:

	Standardset | Book - Icon: call PilotAddress
	Standardset | Phone - Icon: call PilotFax

As Example the main part of PilotAddress is shown here:

  Declare Function GetPilotAddress Lib "PilotADR.dll"(Adr As String) As 
Long

  Sub MAIN

  'Reserve memory
  String Adr$ = String$(500, "*")
  'call dll 
  If GetPilotADR(0,1,0,1,Adr$) Then 
      'calculate items 
      Dim N$(13) 
      For I = 0 To 12 
      	  N$(I) = Mid$(adr$, 2, InStr(adr$, ",") - 3)
          adr$ = Mid$(adr$, InStr(adr$, ",") + 1) 
      Next I 
      N$(13) = Mid$(adr$, 2, Len(adr$) - 1)

N$ holds now all items, inserted in your document in different ways.

Feel free to change parameters in the line

  If GetPilotADR(0,1,0,1,Adr$) Then

for customizing the startup behavior of the list.


P_ADR_E6.dot
------------
is similar to P_ADR_E7.dot.  
Winword 6 is a 16 Bit Software and can't call a 32 Bit DLL.  Because
of this the macro calls PilotADR via some special functions in
Windows 95 which translate between 16 and 32 Bit:

   Declare Function LoadLibraryEx32W Lib "kernel"(library As
       String, hfile As Long, dwFlags As Long) As Long
    Declare Function GetProcAddress32W Lib "kernel"(hnd As Long,
       fun As String) As Long
    Declare Function CallProc32W Lib "kernel"(adr As String,
       funadr As Long, paratran As Long, paranum As Long ) As Integer

	Sub MAIN

    'Reserve memory
	Adr$ = String$(500, "*")

	'call dll via thunk
	hnd = LoadLibraryEx32W("PilotADR.DLL", 0, 0)
	funadr = GetProcAddress32W(hnd, "GetPilotAddress")

	If CallProc32W(Adr$, funadr, 1, 1) Then

	...

Note:  This transfer routines are defined only in Windows 95, not in
Windows NT.

Scripts for WordPro 96
----------------------
The two *.LSS files contain the Basic scripts as readable text.
They are very similar to the macros of P_ADR_E7.dot.
The *.BMP files contain the Smarticon bitmaps, P_ADR_EN.SMI
contains the Smarticon definition.

Copyrights and Trademarks
=========================
PilotADR.dll V 1.0 is freeware, copyright by Joergen Pisarz, Berlin.
The library can be freely distributed alone (with this readme file) or 
inside another freeware product. Distribution inside a commercial or 
shareware product needs permission by the author.
Usage of this software is on your own risk, no liability, no guarantee.
P_ADR_??.* is Public Domain.
PalmPilot is Trademark of U.S.Robotics, all rights on WordPro
reserve Lotus Development Corporation, Winword belongs to Microsoft.


Thanks to
=========
Makrus Reichart, Andreas Kaenzig and Laurent Breyton for ideas and
testing support.

Actual version
==============
is availible:

	in Compuserve: GO PALMB, Lib 5
	  in Internet: http://ourworld.compuserve.com/homepages/pisarz
	

Contact
=======

	Internet: pisarz@compuserve.com
         CIS: 100415,3174

Enjoy!
