AGENDA2.OPX, version 1.11
(C) 1998 A Clarkson

CONTACT
-------

I can be reached via email at andyc@csi.com

Also see the following www page:

	http://ourworld.compuserve.com/homepages/andyc

CONTENTS
--------

agenda2.sis - redistributable SIS file for installation of agenda2.opx only

agenda2.opx - install into \System\Opx directory
agenda2.oxh - install into \System\Opl directory
agenda2.txh - plain text version of agenda2.oxh

agenda2_demo.opl - sample OPL code

agenda2_wins.opx - WINS emulator version (rename & install as above)

INTRODUCTION
------------

This AGENDA2.OPX allows an OPL programmer to read and write data in an
Psion EPOC32 Agenda file.

Note that there is a separate AGENDA.OPX supplied by Psion which allows
day entries to be written to an Agenda. This newer OPX provides the same
capabilities but in addition supports all other agenda entry types, i.e.
day entries, events, todos, anniversaries and todo lists.

I wrote this in order to enable me to support the transfer of todo entries
from my shareware application Plan5. Check out how Plan5 works if you want
to see the AGENDA2.OPX in action. I have released AGENDA2.OPX into the public
domain as freeware for you to use in your own applications.

When distributing the software please make use of the supplied AGENDA2.SIS
file for installation to avoid problems with old versions being installed
over new ones.

If you have the Psion EPOC32 C++ SDK and would like a copy of the C++
source code for the OPX then drop me an email.

WARNING
-------

If you don't write your OPL code correctly to use the supplied OPX it is
very likely that you will either crash your program or corrupt your Agenda
file. So you should thoroughly test your code on a scratch Agenda file
before using or distributing code based upon the AGENDA2.OPX.

The author of AGENDA2.OPX takes no responsability for loss caused by use
of this software.

OVERVIEW
--------

Use of this OPX involves firstly opening an existing agenda file.
Creation of a new file is not supported. To open a file use:

	AgnOpen:(file$)

You need to ensure that the file is not open in Agenda before using
AgnOpen. See the demo OPL code for details of how to automatically
close and reopen Agenda. When finished close the file using:

	AgnClose:

There are 4 basic entries that can be read/written to an Agenda:

	appointments/day entry's
	events
	todo's
	anniversaries

There are also todo-lists within which todo's reside.

Creation of entries involves the following steps:

1. first creating an entry in memory and obtaining a handle to
it, e.g.

	appt& = AgnEnNewAppt&:

2. setting properties on the entry, e.g. start and end times

	AgnEnSetText:(appt&,"Text")
	AgnApSetStartTime:(appt&,1998,12,25,13,0)

3. adding the entry to the file, i.e.

	AgnAdd&:(appt&)

4. finally freeing the entry in memory

	AgnEnFree:(appt&)

It is important that these steps are followed in order to avoid
memory leaks, panics and errors in your code.

Most of the functions require a memory handle returned by one
of the AgnEnNew* family of functions, the AgnFirstEntry& or
AgnNextEntry& functions, or the AgnFetch& function. If any of
these are called then it is important to call AgnEnFree at the
end.

Some functions take an id parameter which identifies the object
in the agenda file, e.g. AgnFetch&. This id can be obtained when
the entry is added using AgnAdd& or for an existing entry
which has been retrieved from the file use AgnEnGetId&.

OPX FUNCTIONS
-------------

The complete Agenda API is as follows:

To open and close the agenda file:

	AgnOpen:(filename$)
	AgnClose:

To scan through all the entries in an agenda use:

	AgnFirstEntry&:
	AgnNextEntry&:

To create a new entry in memory use one of:

	AgnEnNewAppt&:
	AgnEnNewTodo&:
	AgnEnNewEvent&:
	AgnEnNewAnniv&:

To read/write entries in the file use:

	AgnAdd&:(entry&)
	AgnModify:(entry&)
	AgnDelete:(entry&)
	AgnFetch&:(id&)

To set properties of any of the 4 types of entry use:

	AgnEnSetText:(entry&,text$)
	AgnEnSetSymbol:(entry&,symbol$)
	AgnEnSetAlarm:(entry&,dayswarning&,hour&,minute&,alarm$)
	AgnEnSetCrossOut:(entry&,flag%)
	AgnEnSetTentative:(entry&,flag%)

With AgnEnSetSymbol, pass an empty string to remove the symbol from an entry.
If you use AgnEnSetAlarm:(entry&,-1,-1,-1,"") then the alarm will be disabled.
The alarm$ parameter should be something like "Chimes", "Rings",... 
For AgnEnSetCrossOut and AgnEnSetTentative, flag%=1 or 0.

To retrieve properties of any of the 4 types of entry use:

	AgnEnGetId&:(entry&)
	AgnEnGetType%:(entry&)
	AgnEnGetText$:(entry&)
	AgnEnGetSymbol$:(entry&)
	AgnEnGetAlarm$:(entry&,BYREF dayswarning&,BYREF hour&,BYREF minute&)
	AgnEnGetCrossOut%:(entry&)
	AgnEnGetTentative%:(entry&)

With AgnEnGetText$ don't expect to be able to retrieve embeded objects such
as pictures! If an entry doesn't have an alarm then dayswarning&=-1,
hour&=-1 and minute&=-1. The AgnEnGetType% function will tell you the type
of an entry as follows:

	0=appointment/day entry
	1=todo
	2=event
	3=anniversay

For AgnEnGetCrossOut% and AgnEnGetTentative% the return value is
either 1 or 0.

To free an entry in memory following a call to AgnEnNew*&, AgnFetch&,
AgnFirstEntry& or AgnNextEntry&:

	AgnEnFree:(entry&)

To set/get properties of appointment/day entries entries:

	AgnApSetStartTime:(appt&,year&,month&,day&,hour&,minute&)
	AgnApSetEndTime:(appt&,year&,month&,day&,hour&,minute&)
	AgnApGetStartTime:(appt&,BYREF year&,BYREF month&,BYREF day&,BYREF hour&,BYREF minute&)
	AgnApGetEndTime:(appt&,BYREF year&,BYREF month&,BYREF day&,BYREF hour&,BYREF minute&)

To set/get properties of todo entries:

	AgnTdAt&:(list&,index&)
	AgnTdSetList:(todo&,list&)
	AgnTdSetPriority:(todo&,priority&)
	AgnTdSetDueDate:(todo&,year&,month&,day&)
	AgnTdSetDuration:(todo&,days&)
	AgnTdGetList&:(todo&)
	AgnTdGetPriority&:(todo&)
	AgnTdGetDueDate:(todo&,BYREF year&,BYREF month&,BYREF day&)
	AgnTdGetDuration&:(todo&) 

The AgnTdAt& function can be used to loop over the todo's in a
todo list. This requires a handle on the todo list. Use AgnTdSetList to set
which list a todo belongs using the todo list id. With AgnTdSetPriority
the priority parameter should in the range 1-9. With AgnTdSetDueDate
if all the parameters are zero (except todo& of course) then the todo
will be made undated.

To set/get properties of events:

	AgnEvSetStartDate:(event&,year&,month&,day&)
	AgnEvSetEndDate:(event&,year&,month&,day&)
	AgnEvGetStartDate:(event&,BYREF year&,BYREF month&,BYREF day&)
	AgnEvGetEndDate:(event&,BYREF year&,BYREF month&,BYREF day&)

To set/get properties of anniversaries:

	AgnAnSetDate:(anniv&,year&,month&,dayofmonth&)
	AgnAnSetShow:(anniv&,flag%)
	AgnAnGetDate:(anniv&,BYREF year&,BYREF month&,BYREF dayofmonth&)
	AgnAnGetShow%:(anniv&)

There are a number of alternatve ways of setting an entry using Agenda. The
OPX AgnAnSetDate function assumes that it is an anniversary with a base year
which repeats yearly forever. For the show get/set functions above flag
parameter takes the following values:

		0=none
		1=base year
		2=elapsed years
		3=both

To read/write todo lists in the file use:

	AgnLiAdd&:(list&)
	AgnLiModify:(list&)
	AgnLiDelete:(list&)
	AgnLiFetch&:(id&)

To create a new todo list in memory use:

	AgnLiNew&:

To loop over the todo lists in an Agenda use:

	AgnLiAt&:(index&)

To set/get properties of todo lists:

	AgnLiSetTitle:(list&,name$)
	AgnLiSetOrder:(list&,order%)
	AgnLiSetViewDisplay:(list&,display%,hour&,minute&)
	AgnLiGetId&:(list&)
	AgnLiGetTitle$:(list&)
	AgnLiGetOrder%:(list&)
	AgnLiGetViewDisplay%:(list&,BYREF hour&,BYREF minute&)
	AgnLiChangePosition:(oldPos&, newPos&)

The order% parameter takes the following values:

		0=manual
		1=by date
		2=by priority

Use the AgnLiSetDisplayView function to control whether todo
entries are displayed in the other views, if display%=1 then
they are shown, 0 means they aren't. If todo's are displayed
then the hour and minute parameter controls the time slot they
are displayed at.

To free an entry in memory following a call to AgnLiNew&, AgnLiFetch&
or AgnLiAt&:

	AgnLiFree:(list&)