home *** CD-ROM | disk | FTP | other *** search
/ PSION CD 2 / PsionCDVol2.iso / Programs / 375 / README.TXT < prev    next >
Encoding:
Text File  |  1998-10-18  |  8.2 KB  |  278 lines
  1. AGENDA2.OPX, version 1.11
  2. (C) 1998 A Clarkson
  3.  
  4. CONTACT
  5. -------
  6.  
  7. I can be reached via email at andyc@csi.com
  8.  
  9. Also see the following www page:
  10.  
  11.     http://ourworld.compuserve.com/homepages/andyc
  12.  
  13. CONTENTS
  14. --------
  15.  
  16. agenda2.sis - redistributable SIS file for installation of agenda2.opx only
  17.  
  18. agenda2.opx - install into \System\Opx directory
  19. agenda2.oxh - install into \System\Opl directory
  20. agenda2.txh - plain text version of agenda2.oxh
  21.  
  22. agenda2_demo.opl - sample OPL code
  23.  
  24. agenda2_wins.opx - WINS emulator version (rename & install as above)
  25.  
  26. INTRODUCTION
  27. ------------
  28.  
  29. This AGENDA2.OPX allows an OPL programmer to read and write data in an
  30. Psion EPOC32 Agenda file.
  31.  
  32. Note that there is a separate AGENDA.OPX supplied by Psion which allows
  33. day entries to be written to an Agenda. This newer OPX provides the same
  34. capabilities but in addition supports all other agenda entry types, i.e.
  35. day entries, events, todos, anniversaries and todo lists.
  36.  
  37. I wrote this in order to enable me to support the transfer of todo entries
  38. from my shareware application Plan5. Check out how Plan5 works if you want
  39. to see the AGENDA2.OPX in action. I have released AGENDA2.OPX into the public
  40. domain as freeware for you to use in your own applications.
  41.  
  42. When distributing the software please make use of the supplied AGENDA2.SIS
  43. file for installation to avoid problems with old versions being installed
  44. over new ones.
  45.  
  46. If you have the Psion EPOC32 C++ SDK and would like a copy of the C++
  47. source code for the OPX then drop me an email.
  48.  
  49. WARNING
  50. -------
  51.  
  52. If you don't write your OPL code correctly to use the supplied OPX it is
  53. very likely that you will either crash your program or corrupt your Agenda
  54. file. So you should thoroughly test your code on a scratch Agenda file
  55. before using or distributing code based upon the AGENDA2.OPX.
  56.  
  57. The author of AGENDA2.OPX takes no responsability for loss caused by use
  58. of this software.
  59.  
  60. OVERVIEW
  61. --------
  62.  
  63. Use of this OPX involves firstly opening an existing agenda file.
  64. Creation of a new file is not supported. To open a file use:
  65.  
  66.     AgnOpen:(file$)
  67.  
  68. You need to ensure that the file is not open in Agenda before using
  69. AgnOpen. See the demo OPL code for details of how to automatically
  70. close and reopen Agenda. When finished close the file using:
  71.  
  72.     AgnClose:
  73.  
  74. There are 4 basic entries that can be read/written to an Agenda:
  75.  
  76.     appointments/day entry's
  77.     events
  78.     todo's
  79.     anniversaries
  80.  
  81. There are also todo-lists within which todo's reside.
  82.  
  83. Creation of entries involves the following steps:
  84.  
  85. 1. first creating an entry in memory and obtaining a handle to
  86. it, e.g.
  87.  
  88.     appt& = AgnEnNewAppt&:
  89.  
  90. 2. setting properties on the entry, e.g. start and end times
  91.  
  92.     AgnEnSetText:(appt&,"Text")
  93.     AgnApSetStartTime:(appt&,1998,12,25,13,0)
  94.  
  95. 3. adding the entry to the file, i.e.
  96.  
  97.     AgnAdd&:(appt&)
  98.  
  99. 4. finally freeing the entry in memory
  100.  
  101.     AgnEnFree:(appt&)
  102.  
  103. It is important that these steps are followed in order to avoid
  104. memory leaks, panics and errors in your code.
  105.  
  106. Most of the functions require a memory handle returned by one
  107. of the AgnEnNew* family of functions, the AgnFirstEntry& or
  108. AgnNextEntry& functions, or the AgnFetch& function. If any of
  109. these are called then it is important to call AgnEnFree at the
  110. end.
  111.  
  112. Some functions take an id parameter which identifies the object
  113. in the agenda file, e.g. AgnFetch&. This id can be obtained when
  114. the entry is added using AgnAdd& or for an existing entry
  115. which has been retrieved from the file use AgnEnGetId&.
  116.  
  117. OPX FUNCTIONS
  118. -------------
  119.  
  120. The complete Agenda API is as follows:
  121.  
  122. To open and close the agenda file:
  123.  
  124.     AgnOpen:(filename$)
  125.     AgnClose:
  126.  
  127. To scan through all the entries in an agenda use:
  128.  
  129.     AgnFirstEntry&:
  130.     AgnNextEntry&:
  131.  
  132. To create a new entry in memory use one of:
  133.  
  134.     AgnEnNewAppt&:
  135.     AgnEnNewTodo&:
  136.     AgnEnNewEvent&:
  137.     AgnEnNewAnniv&:
  138.  
  139. To read/write entries in the file use:
  140.  
  141.     AgnAdd&:(entry&)
  142.     AgnModify:(entry&)
  143.     AgnDelete:(entry&)
  144.     AgnFetch&:(id&)
  145.  
  146. To set properties of any of the 4 types of entry use:
  147.  
  148.     AgnEnSetText:(entry&,text$)
  149.     AgnEnSetSymbol:(entry&,symbol$)
  150.     AgnEnSetAlarm:(entry&,dayswarning&,hour&,minute&,alarm$)
  151.     AgnEnSetCrossOut:(entry&,flag%)
  152.     AgnEnSetTentative:(entry&,flag%)
  153.  
  154. With AgnEnSetSymbol, pass an empty string to remove the symbol from an entry.
  155. If you use AgnEnSetAlarm:(entry&,-1,-1,-1,"") then the alarm will be disabled.
  156. The alarm$ parameter should be something like "Chimes", "Rings",... 
  157. For AgnEnSetCrossOut and AgnEnSetTentative, flag%=1 or 0.
  158.  
  159. To retrieve properties of any of the 4 types of entry use:
  160.  
  161.     AgnEnGetId&:(entry&)
  162.     AgnEnGetType%:(entry&)
  163.     AgnEnGetText$:(entry&)
  164.     AgnEnGetSymbol$:(entry&)
  165.     AgnEnGetAlarm$:(entry&,BYREF dayswarning&,BYREF hour&,BYREF minute&)
  166.     AgnEnGetCrossOut%:(entry&)
  167.     AgnEnGetTentative%:(entry&)
  168.  
  169. With AgnEnGetText$ don't expect to be able to retrieve embeded objects such
  170. as pictures! If an entry doesn't have an alarm then dayswarning&=-1,
  171. hour&=-1 and minute&=-1. The AgnEnGetType% function will tell you the type
  172. of an entry as follows:
  173.  
  174.     0=appointment/day entry
  175.     1=todo
  176.     2=event
  177.     3=anniversay
  178.  
  179. For AgnEnGetCrossOut% and AgnEnGetTentative% the return value is
  180. either 1 or 0.
  181.  
  182. To free an entry in memory following a call to AgnEnNew*&, AgnFetch&,
  183. AgnFirstEntry& or AgnNextEntry&:
  184.  
  185.     AgnEnFree:(entry&)
  186.  
  187. To set/get properties of appointment/day entries entries:
  188.  
  189.     AgnApSetStartTime:(appt&,year&,month&,day&,hour&,minute&)
  190.     AgnApSetEndTime:(appt&,year&,month&,day&,hour&,minute&)
  191.     AgnApGetStartTime:(appt&,BYREF year&,BYREF month&,BYREF day&,BYREF hour&,BYREF minute&)
  192.     AgnApGetEndTime:(appt&,BYREF year&,BYREF month&,BYREF day&,BYREF hour&,BYREF minute&)
  193.  
  194. To set/get properties of todo entries:
  195.  
  196.     AgnTdAt&:(list&,index&)
  197.     AgnTdSetList:(todo&,list&)
  198.     AgnTdSetPriority:(todo&,priority&)
  199.     AgnTdSetDueDate:(todo&,year&,month&,day&)
  200.     AgnTdSetDuration:(todo&,days&)
  201.     AgnTdGetList&:(todo&)
  202.     AgnTdGetPriority&:(todo&)
  203.     AgnTdGetDueDate:(todo&,BYREF year&,BYREF month&,BYREF day&)
  204.     AgnTdGetDuration&:(todo&) 
  205.  
  206. The AgnTdAt& function can be used to loop over the todo's in a
  207. todo list. This requires a handle on the todo list. Use AgnTdSetList to set
  208. which list a todo belongs using the todo list id. With AgnTdSetPriority
  209. the priority parameter should in the range 1-9. With AgnTdSetDueDate
  210. if all the parameters are zero (except todo& of course) then the todo
  211. will be made undated.
  212.  
  213. To set/get properties of events:
  214.  
  215.     AgnEvSetStartDate:(event&,year&,month&,day&)
  216.     AgnEvSetEndDate:(event&,year&,month&,day&)
  217.     AgnEvGetStartDate:(event&,BYREF year&,BYREF month&,BYREF day&)
  218.     AgnEvGetEndDate:(event&,BYREF year&,BYREF month&,BYREF day&)
  219.  
  220. To set/get properties of anniversaries:
  221.  
  222.     AgnAnSetDate:(anniv&,year&,month&,dayofmonth&)
  223.     AgnAnSetShow:(anniv&,flag%)
  224.     AgnAnGetDate:(anniv&,BYREF year&,BYREF month&,BYREF dayofmonth&)
  225.     AgnAnGetShow%:(anniv&)
  226.  
  227. There are a number of alternatve ways of setting an entry using Agenda. The
  228. OPX AgnAnSetDate function assumes that it is an anniversary with a base year
  229. which repeats yearly forever. For the show get/set functions above flag
  230. parameter takes the following values:
  231.  
  232.         0=none
  233.         1=base year
  234.         2=elapsed years
  235.         3=both
  236.  
  237. To read/write todo lists in the file use:
  238.  
  239.     AgnLiAdd&:(list&)
  240.     AgnLiModify:(list&)
  241.     AgnLiDelete:(list&)
  242.     AgnLiFetch&:(id&)
  243.  
  244. To create a new todo list in memory use:
  245.  
  246.     AgnLiNew&:
  247.  
  248. To loop over the todo lists in an Agenda use:
  249.  
  250.     AgnLiAt&:(index&)
  251.  
  252. To set/get properties of todo lists:
  253.  
  254.     AgnLiSetTitle:(list&,name$)
  255.     AgnLiSetOrder:(list&,order%)
  256.     AgnLiSetViewDisplay:(list&,display%,hour&,minute&)
  257.     AgnLiGetId&:(list&)
  258.     AgnLiGetTitle$:(list&)
  259.     AgnLiGetOrder%:(list&)
  260.     AgnLiGetViewDisplay%:(list&,BYREF hour&,BYREF minute&)
  261.     AgnLiChangePosition:(oldPos&, newPos&)
  262.  
  263. The order% parameter takes the following values:
  264.  
  265.         0=manual
  266.         1=by date
  267.         2=by priority
  268.  
  269. Use the AgnLiSetDisplayView function to control whether todo
  270. entries are displayed in the other views, if display%=1 then
  271. they are shown, 0 means they aren't. If todo's are displayed
  272. then the hour and minute parameter controls the time slot they
  273. are displayed at.
  274.  
  275. To free an entry in memory following a call to AgnLiNew&, AgnLiFetch&
  276. or AgnLiAt&:
  277.  
  278.     AgnLiFree:(list&)