mvConduit - FAQ
     

mvConduit for the PalmPilot

 The mvConduit is designed to allow you to sync MultiValue Data with the standard databases found on the PalmPilot.  These Databases are the Address Book, Date Book, To Do List, and the Memo Pad.

 The mvConduit allows you pick and choose which database you want to sync with your database, and then allow you to write a MultiValue BASIC program to be called to do the actual syncing work.

 The mvConduit can sync data with the following databases:

            D3 – using the D3 Objects
            UniVerse and UniData – using the UniObjects 5.1
            All Native databases – using Winlink32 4.3

The mvConduit requires that you are using HotSync 3.1.1 or later, as well as PalmDesktop 4.0.1 or later since HotSync 3.1.1 will not work without this version.

Multi-Value BASIC program requirements

The programs the mvConduit calls must have the following arguments:

SUBROUTINE PROGRAM.NAME(PALM.INFO,FROM.PALM,TO.PALM)

The records from and to the Palm will be delimited by AM (attribute marks), with the actual record data delimited by VM (Value or MultiValue Marks).

PALM.INFO<1> = Action the program is to proform, or the data the mvConduit is requesting from the database.

0 - Request information to update to palm. When the mvconduit askes for this information, the program is looking for all new changes or record that need to be sent to the PalmPilot.  This includes any records you want to delete from the PalmPilot database. 

1 - Review the changes and pass back updates.  The mvConduit is asking you program to review the changes that were done to this record.  This action is used when the mvConduit is doing a true 2-way sync.

2 - Delete from database.  The mvConduit has found a record on the palm that the user deleted.

3 - Delete all records from database.  The mvConduit was set to use the sync option: ‘Handheld overrides the data on the PC’.

4 - Notify the database to Remove all delete record.  The mvConduit is almost done syncing and it tell you that it is OK to remove from the Host  all the records you have marked as deleted.

5 - Update the Palm Record Id in the Database.  The mvConduit has sent a new record to the PalmPilot, and is notifying you of the PalmPilot record ID.  This is the ID that the information is saved under on the Palm.

6 - Category Request.  The mvConduit is looking for the all the category names to use in this database.

7 - Category Update.  The mvConduit is sending back all the category names that were updated on the PalmPilot for you to save.

PALM.INFO<2>        = Sync Type.  This is the type of syncing the mvConduit is going to do with the host.

0 – Fast Sync.  This Handheld has been synced by the mvConduit before.
1 – Slow Sync.  The handheld has not been synced with the mvConduit before.
2 – Handheld to PC.  The handheld is requesting that it’s data is the most current and correct and should override the data on the host.
3 – PC to Handheld.  The handheld will erase everything in it’s database and overwrite it with the data send from the Host.

PALM.INFO<3>        = PalmPilot User Name.  This is the name that the PalmPilot uses to during hotsync to tell the conduits who is request the new information.

PALM.INFO<4>        = The database that is currently being synced.

                                    AddressDB – Address Book
                                    DatebookDB – Date Book
                                    ToDoDB – To Do List
                                    MemoDB – Memo Pad 

PALM.INFO<5>        = Date the Palm Database was last modified

PALM.INFO<6>        = Date the Palm Database was created.

PALM.INFO<7>        = Date the Palm Database was last synced.

Data Format for Category

Every database has a category area that allows you to group information into like categories.  The standard Datebook found the Palm OS does not use Categories, but some of the third-part datebook applications do use the Category information.

You can define 15 different categories to place data into.  The Categories are saved per database, so you can have different category names for the Address book as you do for the To Do List.

There is always a Category 0 (zero) called “Unfiled”.  The mvConduit will always assign this Category so you do not have to worry about it.

PALM.FROM<Category Number,1>  = Name of Category
PALM.FROM<Category Number,2>  = Flagged as Changed (1-yes/0-no) 

The PALM.TO variable definition is the same as the PALM.FROM definition.

Data Format for Address Book

PALM.FROM<n,1>    = Palm Record Id

PALM.FROM<n,2>    = Category Number.  This is a number between 0 and 15, and represents the category this data is to go into.

PALM.FROM<n,3>    = Flagged for Delete.  (1-yes/0-no)

PALM.FROM<n,4>    = Flagged for Archive (1-yes/0-no)

PALM.FROM<n,5>    = Flagged as Changed (1-yes/0-no)

PALM.FROM<n,6>    = Flagged as Secret or private (1-yes/0-no)

PALM.FROM<n,7>    = First Name

PALM.FROM<n,8>    = Last Name

PALM.FROM<n,9>    = Company Name

PALM.FROM<n,10>  = Phone Number 1

PALM.FROM<n,11>  = Phone Number 1 Type (Work = 0, Home = 1, Fax = 2, Other = 3, Email = 4, Main = 5, Pager = 6, Mobole = 7)

PALM.FROM<n,12>  = Phone Number 2

PALM.FROM<n,13>  = Phone Number 2 Type (Work = 0, Home = 1, Fax = 2, Other = 3, Email = 4, Main = 5, Pager = 6, Mobole = 7)

PALM.FROM<n,14>  = Phone Number 3

PALM.FROM<n,15>  = Phone Number 3 Type  (Work = 0, Home = 1, Fax = 2, Other = 3, Email = 4, Main = 5, Pager = 6, Mobole = 7)

PALM.FROM<n,16>  = Phone Number 4

PALM.FROM<n,17>  = Phone Number 4 Type  (Work = 0, Home = 1, Fax = 2, Other = 3, Email = 4, Main = 5, Pager = 6, Mobole = 7)

PALM.FROM<n,18>  = Phone Number 5

PALM.FROM<n,19>  = Phone Number 5 Type  (Work = 0, Home = 1, Fax = 2, Other = 3, Email = 4, Main = 5, Pager = 6, Mobole = 7)

PALM.FROM<n,20>  = Main Phone Display (1-5).  Which phone number do you want to be displayed as the main phone number.

PALM.FROM<n,21>  = Address

PALM.FROM<n,22>  = City

PALM.FROM<n,23>  = State

PALM.FROM<n,24>  = Zip

PALM.FROM<n,25>  = Country

PALM.FROM<n,26>  = Title

PALM.FROM<n,27>  = Custom 1

PALM.FROM<n,28>  = Custom 2

PALM.FROM<n,29>  = Custom 3

PALM.FROM<n,30>  = Custom 4

PALM.FROM<n,31>  = Notes

PALM.FROM<n,32>  = Host Database Record Number.  This information is used by the mvConduit during syncing, but is not saved on the PalmPilot.

 

 The PALM.TO variable definition is the same as the PALM.FROM definition.

 

 Data Format for Date Book

 

PALM.FROM<n,1>    = Palm Record Id

PALM.FROM<n,2>    = Category Number.  This is a number between 0 and 15, and represents the category this data is to go into.

PALM.FROM<n,3>    = Flagged for Delete.  (1-yes/0-no)

PALM.FROM<n,4>    = Flagged for Archive (1-yes/0-no)

PALM.FROM<n,5>    = Flagged as Changed (1-yes/0-no)

PALM.FROM<n,6>    = Flagged as Secret or private (1-yes/0-no)

PALM.FROM<n,7>    = Appointment Start Time. If PALM.FROM<n,10> = 1 then this information will be ignored.

PALM.FROM<n,8>    = Appointment Date

PALM.FROM<n,9>    = Appointment End Time. If PALM.FROM<n,10> = 1 then this information will be ignored.

PALM.FROM<n,10>  = Untimed appointment (1-yes/0-no).  Flags this appointment as either an appointment reminder for the day, or a timed appointment.

PALM.FROM<n,11>  = Alarm Set (1-yes/0-no)

PALM.FROM<n,12>  = Number representing the time the Alarm is to be set for.  This can be a number of minutes, hours, etc depending on the Alarm Units.

PALM.FROM<n,13>  = Alarm Units. (0 - minutes, 1 – hours, 2 – Days)

PALM.FROM<n,14>  = Repeat Appointment:

0 - No Repeat

1 – Daily

2 – Weekly

3 – Monthly By Day of Week (i.e. Every Tuesday of the 1st week)

4 – Monthly by Appointment Date (i.e. Every 25th of the month)

5 – Yearly by Day of Week (i.e. Every 1st Tuesday of August)

6 – Yearly by Appointment Date (i.e. Every August 25th)

PALM.FROM<n,15>  = Appointment End Date if this is a Repeat Appointment

PALM.FROM<n,16>  = Repeat Frequency.

                                    If Repeat is Daily, then how many days before repeating the appointment.  If two (2) is entered, then the appointment will show up on every other day, If one (1) is entered, then the appointment will show up on every day, and so on.

 

                                    If Repeat is Weekly, then how many weeks before repeating the appointment.

                                   

                                    If Repeat is Monthly, then how many months before repeating the appointment.

                                   

                                    If Repeat is Year, then how many years before repeating the appointment.

PALM.FROM<n,17>  = Repeat On.

                                    If Weekly, then:

                                    0 – Sunday

                                    1 – Monday

                                    2 – Tuesday

                                    3 – Wednesday

                                    4 – Thursday

                                    5 – Friday

                                    6 – Saturday

 

                                    If Monthly by Day, then a day of the month to repeat on

 

                                    All other Repeat types ignore this information.

PALM.FROM<n,18>  = Used only by Repeat Weekly.  This is the day of the week start to repeat the appointment on.

                                    0 – Sunday

                                    1 – Monday

                                    2 – Tuesday

                                    3 – Wednesday

                                    4 – Thursday

                                    5 – Friday

                                    6 – Saturday

PALM.FROM<n,19,-1>         = Exceptions.  This is a list of exception dates when the appointment is repeated.  The appointment will not be repeated on the days listed in this field.  The dates are delimited by sub-values, so you can have as many exception dates as you want.

PALM.FROM<n,20>  = Description of Appointment

PALM.FROM<n,21>  = Notes on the appointment

PALM.FROM<n,22>  = Host Database Record Number.  This information is used by the mvConduit during syncing, but is not saved on the PalmPilot.

 

The PALM.TO variable definition is the same as the PALM.FROM definition.

 

Data Format for To Do List

 

PALM.FROM<n,1>    = Palm Record Id

PALM.FROM<n,2>    = Category Number.  This is a number between 0 and 15, and represents the category this data is to go into.

PALM.FROM<n,3>    = Flagged for Delete.  (1-yes/0-no)

PALM.FROM<n,4>    = Flagged for Archive (1-yes/0-no)

PALM.FROM<n,5>    = Flagged as Changed (1-yes/0-no)

PALM.FROM<n,6>    = Flagged as Secret or private (1-yes/0-no)

PALM.FROM<n,7>    = Date Due

PALM.FROM<n,8>    = Flagged as Completed (1-yes/0-no)

PALM.FROM<n,9>    = Priority (0 –9)

PALM.FROM<n,10>  = Description

PALM.FROM<n,11>  = Notes

PALM.FROM<n,12>  = Host Database Record Number.  This information is used by the mvConduit during syncing, but is not saved on the PalmPilot.

 

The PALM.TO variable definition is the same as the PALM.FROM definition.

 

Data Format for Memo Pad

 

PALM.FROM<n,1>    = Palm Record Id

PALM.FROM<n,2>    = Category Number.  This is a number between 0 and 15, and represents the category this data is to go into.

PALM.FROM<n,3>    = Flagged for Delete.  (1-yes/0-no)

PALM.FROM<n,4>    = Flagged for Archive (1-yes/0-no)

PALM.FROM<n,5>    = Flagged as Changed (1-yes/0-no)

PALM.FROM<n,6>    = Flagged as Secret or private (1-yes/0-no)

PALM.FROM<n,7,-1>           = Notes

PALM.FROM<n,8>    = Host Database Record Number.  This information is used by the mvConduit during syncing, but is not saved on the PalmPilot.

 

The PALM.TO variable definition is the same as the PALM.FROM definition.

 

Sample Program

 

    SUBROUTINE PALM.UPDATE1(PALM.INFO,FROM.PALM,TO.PALM)
    EQU AM TO CHAR(254), VM TO CHAR(253), SVM TO CHAR(252)
    *
    * Created by Nathan Rector, 01/18/01
    *            Natec Systems
    *
    * PALM.INFO<1> = 0- Request list of items to update Palm with
    *                1- Review the Palm data against the database
    *                2- Data deleted from the Palm
    *                3- All data in the palm database was deleted
    *
    * PALM.INFO<2> = Sync Type 0-Fast Sync, 1- Slow Sync, 2-HH to PC, 3- PC to HH
    * PALM.INFO<3> = UserName syncing
    * PALM.INFO<4> = Palm Application syncing (ADDRESSBOOK)
    * PALM.INFO<5> = The last date the palm database was modified
    * PALM.INFO<6> = The date the palm database was created 
    * PALM.INFO<7> = The last date the palm was synced
    *
    * Address Book Phone Labels
    * Work = 0
    * Home = 1
    * Fax = 2
    * Other = 3
    * Email = 4
    * Main = 5
    * Pager = 6
    * Mobole = 7
    *
    ******************************************************************
    *** main program
    ******************************************************************
    OPEN "PALM.DATA" TO TEMP.DATA.FILE ELSE STOP 201, "TEMP.DATA"
    OPEN "CONTACTS"  TO CONTACTS.FILE  ELSE STOP 201, "CONTACTS"
    *
    PROCESSED.LIST = ""
    SYNC.DATE = PALM.INFO<7> 
    PALM.TO = ""
    *
    BEGIN CASE 
      CASE PALM.INFO<1> = 0 AND PALM.INFO<2> = 2 ;* HH to PC 
        * The conduit is transfering all the data from the Palm to 
        * the MV System. 
        * 
        NUM = DCOUNT(FROM.PALM,AM) 
        FOR I = 1 TO NUM 
          PALM.REC.NO = FROM.PALM 
          * 
          PALM.ITEM = "" 
          PALM.ITEM<1> = SYNC.DATE 
          PALM.ITEM<2> = ""
          PALM.ITEM<3> = FROM.PALM  
          WRITE PALM.ITEM ON TEMP.DATA.FILE, PALM.INFO<3> :".": PALM.INFO<4> :".": PALM.REC.NO
          NEXT I 
      CASE PALM.INFO<1> = 0 AND PALM.INFO<2> = 3 ;* PC to HH
        * the Conduit is going to overwrite all the data on the Palm 
        * with data from the MV System
        *
        EXECUTE \SELECT PALM.DATA WITH "" = "\: PALM.INFO<3> :".": PALM.INFO<4> :\.]"\ CAPTURING OUTPUT
        STOP.LOOP = 0 ; TO.PALM = ""
        LOOP
          READNEXT ID ELSE STOP.LOOP = 1
        UNTIL STOP.LOOP DO
          GOSUB 1000
        REPEAT
        * 
        EXECUTE \SELECT CONTACTS "1387" "38281" "76504"\ CAPTURING OUTPUT
        STOP.LOOP = 0
        LOOP
          READNEXT CONTACT.ID ELSE STOP.LOOP = 1
        UNTIL STOP.LOOP DO
          LOCATE CONTACT.ID IN PROCESSED.LIST SETTING JUNK ELSE
              GOSUB 2000
              IF NOT(PALM.DATA = "") THEN TO.PALM<-1> = PALM.DATA
            END
        REPEAT
      CASE PALM.INFO<1> = 0 AND PALM.INFO<2> = 0 ;* Fast Sync 
        * The conduit is looking for a list of records that have not 
        * already been update during the review process.  These are
        * either new records to load into the palm, or records to be
        * deleted from the palm.  Or just updated information to update
        * the palm with.
        *
        EXECUTE \SELECT PALM.DATA WITH MOD.DATE > "\: OCONV(SYNC.DATE,"D4/") :\"\ CAPTURING OUTPUT
        STOP.LOOP = 0 ; TO.PALM = ""
        LOOP
          READNEXT ID ELSE STOP.LOOP = 1
        UNTIL STOP.LOOP DO
          GOSUB 1000
        REPEAT
        * 
        EXECUTE \SELECT CONTACTS "1387"\ CAPTURING OUTPUT
        SELECT TO CONTACT.SELECT
        STOP.LOOP = 0
        LOOP
          READNEXT CONTACT.ID FROM CONTACT.SELECT ELSE STOP.LOOP = 1
        UNTIL STOP.LOOP DO
          * creates the palm data from the contact file 
          * 
          LOCATE CONTACT.ID IN PROCESSED.LIST SETTING JUNK ELSE
              * selects the data from the palm to see if the contact information
              * is on file.  If so, then return the palm record id
              *
              EXECUTE \SELECT PALM.DATA WITH CONTACT.ID = "\: CONTACT.ID :\"\ CAPTURING OUTPU
              IF SYSTEM(11) THEN
                  * get the palm data
                  READNEXT ID ELSE ID = ""
                  PALM.REC.NO = FIELD(ID,".",3)
                END ELSE
                  PALM.REC.NO = ""
                END 
              * 
              * gets the information from the contact file
              *
              GOSUB 2000
              IF NOT(PALM.DATA = "") THEN
                  PALM.DATA<1,1> = PALM.REC.NO
                  TO.PALM<-1> = PALM.DATA
                END
            END
        REPEAT 
      CASE PALM.INFO<1> = 0 AND PALM.INFO<2> = 1 ;* Slow Sync 
        * The conduit is looking for a list of records that have not
        * already been update during the review process.  This process
        * is different from the Fast Sync in that it is request all the
        * date that belongs on the Palm, not just the new records or
        * deleted records.
        *
        EXECUTE \SELECT PALM.DATA\ CAPTURING OUTPUT
        STOP.LOOP = 0 ; TO.PALM = ""
        LOOP
          READNEXT ID ELSE STOP.LOOP = 1
        UNTIL STOP.LOOP DO
          GOSUB 1000
        REPEAT
      CASE PALM.INFO<1> = 1 ;* review changes to Palm information
        * The conduit is asking you to review the changes that have been 
        * done on the palm.  The dynamic array you return will be any 
        * changes you want updated on the Palm. 
        * 
        WRITEV SYNC.DATE ON TEMP.DATA.FILE, PALM.INFO<3> :".": PALM.INFO<4> :".": FROM.PALM<1,1>,1
      CASE PALM.INFO<1> = 2 ;* Deleted From Palm
        * The conduit is notifing you that the record has been deleted 
        * from the palm by the user.  This allows you to mark, update, or 
        * delete any information in the MV System.  Once this process 
        * is done, this record will be deleted from the Palm 
        * 
        EXECUTE \DELETE PALM.DATA "\: PALM.INFO<3> :".": PALM.INFO<4> :".": PALM.FROM<1,1> :\"\ CAPTURING OUTPUT
      CASE PALM.INFO<1> = 3 ;* clear data from file
        * The conduit as requested that the data on the MV System be 
        * cleared or deleted.  This is usually done with the conduit is 
        * syncing with the palm in "Handheld overwrites PC" mode. 
        * 
        EXECUTE \SELECT PALM.DATA WITH "" = "\: PALM.INFO<3> :\.]"\ CAPTURING OUTPUT
        IF SYSTEM(11) THEN
            EXECUTE \DELETE PALM.DATA\ CAPTURING OUTPUT
          END
      CASE PALM.INFO<1> = 4 ;* removed deleted records 
        * The Conduit is notifying the MV System that it is ok to  
        * remove the records the database has marked as deleted.
        * 
      CASE PALM.INFO<1> = 5 ;* Update palm recordId 
        * The Conduit is notoifying the MV System of the new palm record 
        * IDs for the same data in the MV System. 
        * 
        NUM = DCOUNT(FROM.PALM,AM)
        FOR I = 1 TO NUM
          PALM.DATA = SYNC.DATE :AM: FROM.PALM
          WRITE PALM.DATA ON TEMP.DATA.FILE, PALM.INFO<3> :".": PALM.INFO<4> :".": FROM.PALM
          NEXT I
    END CASE
    RETURN 
    ******************************************************************
    *** subroutine
    ******************************************************************
1000* 
    READ PALM.DATA.ITEM FROM TEMP.DATA.FILE, ID ELSE PALM.DATA.ITEM = ""
    * 
    IF PALM.DATA.ITEM<3> = "" THEN
        * create the palm information based on the Contact information
        CONTACT.ID = PALM.DATA.ITEM<2> ; GOSUB 2000
        IF NOT(PALM.DATA = "") THEN
            PALM.DATA<1,1> = FIELD(ID,".",3)
            TO.PALM<-1> = PALM.DATA
          END
      END ELSE 
        TO.PALM<-1> = PALM.DATA.ITEM<3>
      END
1900*
    RETURN 
2000* 
    PALM.DATA = ""
    READ CONTACT.ITEM FROM CONTACTS.FILE, CONTACT.ID ELSE GOTO 2900 
    * 
    PALM.DATA<1,1> = ""  ;* leave blank to create new palm Record
    PALM.DATA<1,2> = "0" ;* category 
    PALM.DATA<1,3> = "0" ;* Delete
    PALM.DATA<1,4> = "0" ;* Archive
    PALM.DATA<1,5> = "1" ;* Dirty - modified 
    PALM.DATA<1,6> = "0" ;* Secret
    PALM.DATA<1,7> = CONTACT.ITEM<2> ;* first name
    PALM.DATA<1,8> = CONTACT.ITEM<3> ;* last name
    PALM.DATA<1,9> = CONTACT.ITEM<1> ;* company name
    PALM.DATA<1,10> = CONTACT.ITEM<9> ;* Phone 1 
    PALM.DATA<1,11> = 5 ;* phone 1 Type 
    PALM.DATA<1,12> = CONTACT.ITEM<10> ;* Phone 2 
    PALM.DATA<1,13> = 2 ;* Phone 2 type 
    PALM.DATA<1,14> = CONTACT.ITEM<24> ;* Phone 3 
    PALM.DATA<1,15> = 7 ;* Phone 3 type 
    PALM.DATA<1,16> = CONTACT.ITEM<26> ;* phone 4 
    PALM.DATA<1,17> = 4 ;* Phone 4 Type 
    PALM.DATA<1,18> = CONTACT.ITEM<25> ;* Phone 5 
    PALM.DATA<1,19> = 6 ;* phone 5 Type 
    PALM.DATA<1,20> = 1 ;* Main Phone # to Display 
    PALM.DATA<1,21> = CONTACT.ITEM<4> ;* address 
    PALM.DATA<1,22> = CONTACT.ITEM<5> ;* City 
    PALM.DATA<1,23> = CONTACT.ITEM<6> ;* state 
    PALM.DATA<1,24> = CONTACT.ITEM<7> ;* Zip 
    PALM.DATA<1,25> = CONTACT.ITEM<8> ;* Country 
    PALM.DATA<1,26> = "" ;* title 
    PALM.DATA<1,27> = CONTACT.ITEM<27> ;* custom1 
    PALM.DATA<1,28> = "" ;* custom2 
    PALM.DATA<1,29> = "" ;* custom3 
    PALM.DATA<1,30> = "Rec#: ": CONTACT.ID ;* custom4 
    PALM.DATA<1,31> = "" ;* Notes  
    PALM.DATA<1,32> = CONTACT.ID
    * 
    PROCESSED.LIST<-1> = CONTACT.ID
2900*
    RETURN 
    END