|
ObjectivesWe'll look at the following:
Before reading this chapter you should have a working knowledge of the CASL database operations as covered in earlier database related chapters. Information about the dbfile object is given in the CASL Language Manual. Information about the cdb file format, and the CondReg and RemCond utilities are given in the CASLide Manual. ### rough, but more informative than current CASLide and Language Manuals. Maybe add troubleshooting section?? The CASL ConduitBoth normal CASL and CASLpro come with a CASL conduit that serves as a common conduit for all CASL databases. The way that the database files are defined, your PRC file is set, and the conduit is registered (with Windows registry), defines how the CASL conduit will behave with each database. The following configuration settings are possible with the CASL conduit:
Note: The CASL conduit only works with Windows. For other platforms you'll need to write your own conduit. See www.palmos.com for conduit development options. There are also many instances where the Palm Memopad conduit, or Palm backup conduit can be used to get CASL data on a PC. We'll look at each of these configuration properties one at a time. Conduit Settings Using Dbfile ObjectThe CASL conduit will only perform a HotSync operation on a CASL database file defined using the dbfile object. From the CASLide Manual, a dbfile definition has the following syntax: dbfile name; { field field_var, …. } { sync_pref orientation; } { data_source_name string_expression; } end; For example, a dbfile definition might look like this: dbfile dbMydata; field sField1; field sField2; sync_pref merge; data_source_name "myODBClink"; end; The variables sField1 and sField2 must have been previously defined, and the type declarations must be consistent with the field definitions of the ODBC data source, for example: variables; string sField1; string sField2; end; Synchronization Preferencesync_pref defines the type of synchronization, which will be performed between your PDA and the PC application.
Database formatdata_source_name is optional. By leaving the data_source_name specification out of the dbfile definition, you'll be specifying that your CASL database will be saved on the PC using the CASL database format. This is a text file with header information, followed by data record information in a comma separated value (csv) format. For details, see the cdb format specified in the CASLide Manual. By specifying a data_source_name, your CASL database will be saved on the PC using the ODBC object format. When specified, data_source_name defines the name of the ODBC link you have created on your PC. This allows you to synchronize with databases that support the ODBC object, such as Access, SQL Server, Oracle, or an Excel spreadsheet. The DSN string can be up to 31 characters long and may contain spaces. If an equals sign is found in the data_source_name string then it is assumed that the string is the full connect string. If not then it will be used as a DSN name in the default connect string "DSN=<name>;UID=;PWD=". You will need to use the full connect string syntax if you have password protected your PC database as is common, for example, with Access databases, "DSN=myODBClink;UID=username;PWD=myPassword". For more information about DSN connect strings, see Chapter 5 in the Microsoft ODBC SDK Programmer's Reference. Conduit Settings Using PRC SettingsFor the HotSync operation to use other than the default Application Name and Hotsync Folder, the creator ID of all CASL database must be set to use that of its application. This is done with the CASLide menu option Project | PRC Settings. You check the "Database creator ID" option under the textbox where you enter your program's creator ID. This option is only available with CASLpro. Conduit Settings Using CondRegBefore the CASL conduit can perform a HotSync operation, the CASL conduit file must be copied to the user's HotSync path, and it must be registered with the Palm HotSync manager. For a PC with the CASLide installed, these tasks have been done by the CASL installation program, for all other PC's the CondReg.exe utility performs the necessary copy and registration tasks. CondReg.exe requires the CASL conduit dll file, CASLcn20.dll, to be available. You should also ensure that two standard Microsoft files, MFC42.DLL and MSVCRT.DLL, are also installed in the user's Windows folder. These files are generally present. All these files are located in your ".\CASLxx\" folder, where xx is the version number. The full path will depend on your installation, but it's default location would be in the form of, "C:\Program Files\CASLsoft\CASLxx\". The syntax of CondReg is as follows: CondReg DLLpath -Appname "name" -CreatorID id -Directory "dir" CondReg.exe is used from the DOS prompt, the Start | Run line, in a command line in a Windows shortcut, or in a batch file. An example of a command string which might be used for a normal CASL database, or a default CASLpro database: CondReg "C:\temp" An example of a full command string which might be used for a CASLpro database: CondReg "C:\temp" -Appname "My App" -CreatorID FRED -Directory "My App Folder" NOTE: When specifying the DLLpath, there is no trailing backslash. If the path name contains spaces, then it will need to be enclosed in quotes. In both cases, this command will copy the CASLcn20.dll file from "C:\temp", and create a HotSync Registry entry. Before the new settings can take effect, the HotSync manager must be restarted (exited and restarted). The details of the HotSync registry entry are explained below. Creator IDSpecifying a, -CreatorID id, option on the CondReg command string will only make sense if you have a registered version of CASLpro, and you've checked the "Database creator ID" option on the PRC Settings dialog box. When using this option you'll want "id" to be your program's creator ID. Application NameSpecifying a, -Appname "My App", option on the CondReg command string will only make sense if you have a registered version of CASLpro, and you've checked the "Database creator ID" option on the PRC Settings dialog box. When using this option you'll want "My App" to be the program name that's displayed during a Hotsync operation, and in the Custom window of the Palm Hotsync manager. During a Hotsync operation, the Hotsync progress dialog displays "Synchronizing My App" while synchronizing your application's databases. If you don't use this option, or it's unavailable, "CASL" is displayed during a Hotsync operation, and in the Custom window of the Palm Hotsync manager. During a Hotsync operation, the Hotsync progress dialog displays "Synchronizing CASL" while synchronizing CASL databases. Tip: After restarting the HotSync manager, checking your Custom window of the Palm HotSync manager is a good way to determine if CondReg performed properly. HotSync FolderSpecifying a, -Directory "My App Folder", option on the CondReg command string will only make sense if you have a registered version of CASLpro, and you've checked the "Database creator ID" option on the PRC Settings dialog box. When using this option you'll want "My App Folder" to be the subfolder under the user's HotSync folder where databases are read from and written to during the Hotsync operation. The full path specification will be of the form, "C:\Palm\user\My App Folder\", depending on each PC's individual configuration. Be careful not to use the same folder name for applications with different creator ID's. If you're synchronizing to an ODBC source, it can be considered a temporary folder and is not the location of the PC database itself, which is defined by the ODBC DSN link. If you don't use this option, or it's unavailable, the "Casl" subfolder under the user's HotSync folder is used. The full path specification will be of the form, "C:\Palm\User\Casl\", depending on each PC's individual configuration. Installing a CASL database onto a Palm deviceFor installing a CASL formatted database file from your PC to a Palm device for the first time, you use the CDI extension. The CDI files must be located in the HotSync folder that's registered with the HotSync manager for your application. The CASL conduit will install database files with this extension onto a user's Palm device. There are more details about this in the CASLide Manual. CASL Desktop Companion for Palm OS ApplicationThe easiest way to provide a desktop version of your Palm OS application is to compile your CASL program for the Windows target platform, and use the CASL database format. The Windows targeted application is compiled to pseudo-code, which is interpreted by the CASL runtime, CASLwin.exe. CASLwin programs can easily access a CASL formatted database. If you use this strategy your installation program will also need to install the Windows version of your CASL program, the CASLwin.exe runtime, and the runtime's associated dll files. For details you can refer to the CASLide manual. A more sophisticated strategy would be to create a Windows version by using RAD Tool which supports ODBC access, such as Visual Basic or Delphi. Your Windows application could be easily programmed to access the ODBC database, or there are 3rd party ActiveX objects, which allow access to the CASL database format. SingeDB is one such object, provided by LFS Informatica, http://www.singera.com/Palm/. As the CASL database format is basically a text-based csv format, manually coding access isn't that difficult either. The userpath and datapath FunctionsWhen you have a desktop companion application, it's important to share the same database. This is done by using the userpath function when accessing a CASL database on the PC. However, there can be a subtle problem with this. On a PC that has more one than one CASL database residing, the return string of userpath("username") could be 2 possibilities based on the last HotSync path. In most cases a CASL program expects its databases to be in the CASL HotSync path, "c:\palm\user\casl\", but there are cases where with CASLpro a CASL program's databases can have the program's creator id, and its data HotSync path can be, "c:\palm\user\myapp\". Depending on the last HotSync path for the username passed to the userpath function, userpath will return either "c:\palm\user\casl\" or "c:\palm\user\myapp\". What's important for a casl program is the prefix path information, the "c:\palm\user\" root. with this information, each program, because it's known by the programmer, knows it's intended database folder. therefore the return value of userpath is still very informative, in that the path root information is always accurate. Rather than use the userpath function to access CASL databases in the HotSync folder on the PC, it's suggested instead that the datapath function defined below be used. It exploits the accurate information returned by userpath, and with it creates the actual data path for the calling program. # datapath takes 2 parameters: # # username: this is same meaning as parameter used by userpath. # # datafolder: this is the same string that is used as the -Directory parameter passed # to CondReg, in other words it's the folder where the app's data is stored, or it # is the string "casl" for the default location casl app's store their data, or if # it's an empty sttring, this has the same meaning as "Casl". note: in windows, # a path string is case insensitive. # # returned is the path, "c:\palm\user\datafolder\". if the "c:\palm\user\" root is # not found, or if running on palm, then the empty string "" is returned. function datapath(string username, string datafolder) as string; variables; string path; numeric i; numeric p; end; if datafolder=""; datafolder="Casl"; end_if; path=userpath(username); # path is now of form, "c:\palm\user\xxx\" or "" # find char position of 3rd back slash p=0; # current char position i=0; # 1-based count of back slashes while i<3 and p<>-1; # i=3, at 3rd back slash p=find("\\",path,p+1); # 2nd back slash needed to delimit 1st i=i+1; end_while; if p=-1; # not found, either running on palm, or unexpected error datapath=""; else; # ok, found 3rd slash, parse path prefix, and append to datafolder datapath=left(path,p+1)+datafolder+"\\"; end_if; end; ### future version of sample apps needs to have datapath.cpk file in library folder (or maybe it will be a native casl command) CASL Conduit Merge AmbiguitiesWhen the CASL conduit performs a merge operation, it looks at the record status on each platform and takes appropriate action. CASL database files have a unique record id, and status field to keep track of a record on each platform, and its status. Possible record status values include: not modified, modified, tagged for deletion, and new. The not modified, tagged for deletion, and new status indicators are handled by the CASL conduit in a straight forward way, implied by the status indicator's name. However, handling the modified status indicator can lead to ambiguities. The modified status will result in the corresponding record on the other platform being replaced with the modified record. However, consider the case where the record on each platform has been modified between Hotsync operations. In this case each record will have a modified status indicator. Which record should be replaced? The way the CASL conduit handles this situation is to duplicate the record. It is then the programmer's responsibility to resolve the ambiguity when the program starts up the next time. As the CASL search command, which allows random access to a database file, assumes all records will have a unique key field value (the first field), it's advisable to resolve duplicate records into a single record. One way to do this is at program startup you can single step through the whole database and check for duplicate field values. Since all records are sorted by key field values, duplicate key field values will be adjacent to each other. If duplicates are detected, a means must be provided to resolve this. In the example code below, the user is queried to choose the record which will be kept. The record not chosen will be removed. As is the case for many database applications a selector is used to display all key field values on a form which could be described as a list view. Often a form like this is used to allow the user to select a record. This was the case in the Password sample application from where the source code below comes. You'll see in this function that there are 2 activities which are fulfilled while single stepping through the database:
For background, some of the global variables and the dbfile object are defined first. variables; # db fields string sAccount; string sUser; string sPassword; string sNote; # name of password db file string sDBName="pwPass"; # 1-based number of records numeric nNumRec; # selector slKeys defined with bound sKeys array with 16 elements, # defined in cff file, Password.cff # abort flag, disables program if problem with db numeric fAbort; # rename flag if created new cdb file on windows, will # rename cdb to cdi so will install on palm on next hotsync numeric fRenameCDI; end; # DB FILE DEFINITION dbfile dbPassword; field sAccount; field sUser; field sPassword; field sNote; sync_pref merge; # 2-way hotsync end; # assumes password db already open, # starts at top of db, and reads all records, loading # key field values into selector, and assigning # number of records, nNumRec # check for duplicates and user removes unwanted duplicate, # check for too many records and extras are removed, # forces redraw of selector with new contents function ffStartupSelector as numeric; variables; string prevkey; string prevuser; string prevpassword; end; # read all records and load into list view selector, # remove duplicate records, records which exceed max # allowed # set cdb pointer to start of cdb file seek_start dbPassword,0; # init previous record data for duplicate record check prevkey=""; prevuser=""; prevpassword=""; # init loop variables errorcode=ce_no_error; nNumRec=0; # attempt to read first record get_fields dbPassword; # loop through all records until eof while errorcode=ce_no_error; # deal with current record if prevkey=sAccount; # duplicate record, ask user which to keep if message_box(1,"Resolve duplicates", sAccount+":"+char(10)+ "1 = "+prevuser+", "+prevpassword+char(10)+ "2 = "+sUser+", "+sPassword,"Keep 1","","Keep 2")=0; # keep record 1, remove record 2 from cdb remove dbPassword; else; # keep record 2, remove record 1 from cdb # go back to record 1 search dbPassword,prevkey; remove dbPassword; # reread record 2 get_fields dbPassword; # remember current record for next time prevkey=sAccount; prevuser=sUser; prevpassword=sPassword; end_if; else; # new unique record # before adding key to array, see if too many records if nNumRec=16; # too many records, must remove data from cdb and # not add key to array # creating records up to limit on both palm and # pc between hotsync's could result in merged # cdb file with too many records, to avoid # key array out of bounds error, extra records # are removed sml_ShowMsg(2,"Too many records. "+sAccount+ ", "+sUser+", "+sPassword+" must be deleted."); remove dbPassword; else; # add new record key to array sKeys[nNumRec]=sAccount; nNumRec=nNumRec+1; # remember current record for next time prevkey=sAccount; prevuser=sUser; prevpassword=sPassword; end_if; end_if; # attempt to read next record get_fields dbPassword; end_while; # check for unexpected error at loop termination ffStartupSelector=errorcode=ce_eof; # setup selector display to fit number of records, # ok to do even if error with reading whole db if nNumRec=0; # no records, hide selector hide slKeys; else; # set default selection to element 0 slKeys.selected=0; # set list size to number of records slKeys.list_size=nNumRec; # 1-based size # force redraw of selector hide slKeys; # both hide/show needed for sel redraw on palm show slKeys; end_if; end; RemCondThe utility RemCond.exe is used to remove a CASL HotSync conduit registry entry. The syntax is as follows: Remcond -CreatorID id -KeepDLL
|
[ Top ] © 2001, Feras Information Technology. All rights reserved. |