This paper is intended as a guide for an individual who is relatively new to programming and is learning to create and deploy an application using Satellite Forms. Since this paper strongly reflects my individual experiences, it may be helpful to give you a brief sketch of my background. (Alternatively, you can skip to the next section.)
I am a physician working full time in a clinical practice in Portland, Oregon. I received a degree in mathematics from Oregon State University, an M.D. from Washington University in St. Louis, and a B.S. in Medical Informatics from Oregon Health Sciences University in 1999. In the Informatics program, I had courses in C++ , Perl, Java, HTML, Unix, computer science and database design. My Master’s Thesis was entitled “The Usefulness of Handheld Computers in a Surgical Group Practice,” and it utilized a flat-file database program on a Windows CE device.
I decided to develop a similar program on the Palm using a relational database, and, after examining the alternatives, selected Satellite Forms as my development tool. Eighteen months and thousands of lines of code later, the product is nearing completion. There were many obstacles along the way, usually due to a simple lack of knowledge or understanding, but eventually I was able to find a solution. This paper describes some of the areas that a new developer might not find intuitively obvious.
I have tried to create an
objective document. For many reasons, this
is difficult to do and still impart the necessary information to the user. Therefore, I will place items of personal
choice at the bottom of the sections and set them off with italics, so the
reader can clearly see my biases.
You can view my final product, Pocket Practitioner, on the web at http://www.pocketinformatics.com. All links described in this paper are available at http://www.pocketinformatics.com/satforms. The product, and this guide, will continue to evolve. If you notice errors, please contact me, as I will update it periodically.
Jon Blackman, M.D., M.S.
In simplest terms, the Palm is a small computer, with a processor, memory and applications. In turn, all applications are stored in memory as either PRC files or PDB files.
PRC (Palm Runtime Component) files are the programs of the application.
PDB (Palm Database) files are the databases of the application. All Palm database elements are stored in this format.
To create an application for the Palm, you create a program on the desktop using a development tool, convert it to a PRC, and upload it to the handheld. Likewise you create desktop databases, convert them to PDBs, and upload them as well. Your application is typically registered with the Palm HotSync program, and that function is also taken care of by your development tool.
An application may also have a program on the desktop that stores and manipulates the information in the databases. The software connection of the desktop application to the Palm is called the conduit, and is either written manually or included with the development tool.
Once you
have made the decision to write a program on the Palm, you are confronted with
a wide variety of programming tools and languages. One place to start is in the Developer Tools section of the
PalmOS web site http://www.palmos.com/dev/tech/tools/.
There are a
wide range of programs listed at this site, some using C/C++, some using Visual
Basic, and others using Java, HTML or simple scripting. The new user should consider looking at all
of them and finding the language and tool set with which he/she is most
comfortable.
I chose Satellite Forms for the following reasons:
· I felt that I could learn Visual Basic, but I was not sure that I would be able to ever master C/C++ to the point that I could complete an application.
· A SF application can mimic a native Palm application with its use of controls, filters and coding.
· SF supports a relational database.
· SF includes a conduit for Microsoft Access.
Once you
have decided to use Satellite Forms for your application, you are confronted by
the fact that you need to be able to program to do anything other than simple
form-building. If you know the syntax
for any programming language, the subset of Visual Basic used by SF is
relatively easy to pick up. If you do
not know how to program, you may need to take an introductory class or you can
try to pick it up on your own.
I had not
had exposure to Visual Basic before I started my project. I felt I needed to learn this in some degree
of depth, so I purchased Visual Basic
6.0 and worked through the lessons in
Microsoft Visual Basic 6.0 Professional Step by Step. I
then read the pertinent sections of
SAMS Teach Yourself Palm Programming in 24 Hours by Gavin
Maxwell. These two books allowed me to
get started. Over the course of the
next year, I also looked through the programming sections of Running Microsoft
Access 97, Running Microsoft Access 2000, The Microsoft Access 97
Developer’s Handbook, Database Programming with Visual Basic 6 by
Evanelos Petroutsos, and the O’Reilly book DAO Object Model by Helen
Feddema.
Satellite Forms is a big program, and for someone new to programming, it can be intimidating.
Start by reading the Satellite Forms Developer’s Guide. If you do not have it in printed form, take the time to print it out fully and place it in a binder with tabs for each chapter. Read through it front to back, skimming those sections that do not seem pertinent.
With the exception of some of the reference material, I have read every word of the Developer’s Guide. Some sections I have read 10-15 times, and I refer to the Scripting Language Reference constantly. For me, having this in a printed format was essential.
There is no better way to get started than by following the chapters Creating a Satellite Forms Application and Using Satellite Forms on Handheld Devices. When you have completed the application, go through the steps to synchronize it with your desktop application. If you have Access, follow the tutorial Using Satellite Forms with Microsoft Access. If you use Visual Basic 6, you can do so by changing the code appropriately.
I am assuming that the new programmer will be using an Access database. If you use another program, then you may be able to use similar concepts to create a successful conduit.
There are a number of sources to find help, other than the included documentation.
· SAMS
Teach Yourself Palm Programming in 24 Hours by Gavin Maxwell. This
book is a staple, but it is quickly becoming outdated.
· The PUMATECH web site
has a number of articles and an extensive list of FAQs. All developers should spend some time at
this site and examine every section.
· SF Talk. http://webboard.mediastorm.net:80/~sf-talk This is a lively developers forum that is
an essential community for most Satellite Forms developers. Frequently a user can post a question and have an answer the same day. It is helpful to observe the forum for a
while to observe the etiquette. You can
view the forum on the web or you can have the messages sent to you by email.
The Satellite Forms Developer’s Guide is generally well written, but there are a number of concepts that might not be intuitive to a new developer.
When the user presses the HotSync button on the Palm cradle, it is picked up by the HotSync application, which is usually loaded in memory with its icon present in the system tray. Each application is registered with HotSync, and when the appropriate signal is received, the HotSync application broadcasts an event specific to each application. This signal can be picked up by the application if its ActiveX control is active (open on the desktop, or open and minimized in the system tray).
Therefore, the desktop application must be opened before the HotSync button is pressed for data to transfer between the handheld and the desktop. It is possible to create a VB6 application that loads on startup and then minimizes itself, just leaving an icon in the system tray. Code for this is available in the PUMATECH FAQs.
If you examine the HotSync event carefully, and read through the documentation, you begin to get a feel for what is happening. The HotSync event picks up a sign to transfer a file, places the request in a queue, gets another request, places that in the queue, etc. Eventually the files are all transferred, the desktop application manipulates the data and the process is repeated, transferring files back to the Palm.
When you initially develop your application, you will use a Creator ID in the Project Properties of SMSF (Enterprise) or SMSD (Standard). When you test your application, you will load the SDK (Software Distribution Kit) engine on your handheld, and it will work with the default creator string.
When you deploy your application , you will use your own Creator ID (one for each of your projects) that you get from the PalmOS Creator ID Database. That Creator ID is registered with the HotSync application when you use the RDK (Re-distribution Kit) Install Utility. You will also load the RDK engine on your user’s handheld.
During the HotSync event, you will test for the Creator ID by using the Satellite Forms ActiveX method Creator Sting and exit the HotSync subroutine if it does not match your Creator ID.
When you perform a Save As in the App Designer, you may be surprised by the number of files that suddenly appear. In addition, you may use other files, so it can be confusing.
· PRC (Palm Runtime Component) As mentioned before, these are the native Palm programs that are uploaded to the handheld. You will have one in your project and others in the Redist folder.
· PDB (Palm Database). These are the native Palm databases that are uploaded to the handheld. You will have one for every DBF or MDB file you create.
· DBF (dBase 5 file). These are transfer files in dBase 5 format.
· DBT (dBase 5 table) These are files created when you have a memo field created in dBase 5. The DBF has a pointer to this file. Note that there may be a DBF and a DBT file associated with a PDB file. When you distribute these files, you need to make sure to place them in the same directory as the corresponding DBF file.
· MDB (Microsoft Database) These can either be transfer files or application files.
· PDA (Palm Data Application) This is the desktop equivalent of the PRC for your application. You will have one for your project.
· SFA (Satellite Forms Application) This is the file you open in App Designer. You do not usually distribute this with your application.
· ICM This is a new file used only by the server product.
· INI (Initialization file) This is a configuration file used by the RDK Install utility.
Since this article was written, Microsoft has released
Service Pack 5 for Jet 4.0. This allows
Microsoft Access 2000 to read and write dbf files, and goes a long way toward
resolving this issue. I will keep the
article as is for now for historical interest, so users can see how this
problem has evolved. However, if you
install SF5 on all machines using Access 2000, you should be ok.
http://support.microsoft.com/support/kb/articles/Q263/5/61.ASP
http://support.microsoft.com/support/kb/articles/Q230/1/25.ASP
Microsoft has a number of data access technologies, and it recently created a unifying installation program known as the Microsoft Data Access Components (MDAC) setup program. MDAC consists of the following modules:
· ODBC
· OLE DB
· ActiveX Data Objects (ADO)
· Other components
Installing MDAC 2.1 or newer installed a new major version of the Microsoft Access ODBC driver. This driver uses the Microsoft Jet 4.0 database engine, which allows access to Microsoft Access 2000 format databases as well as previous Access formats, which used the Microsoft Jet 3.5 database engine. However, according to Microsoft (Microsoft Library Article ID: Q237994), “Installing the updated Access ODBC driver can break existing, installed ODBC applications that use the Access ODBC driver, forcing the developer to re-code the application in some cases.” Most pertinent to Access 97 users, “The dBase ODBC driver that ships with MDAC 2.1 is read only unless BDE (the Borland Database Engine) is installed.”
MDAC 2.5 is installed with Access 2000 and is included in the operating system of Windows 2000.
If you have Access 97, you will need to use DBF transfer files. The good news is that you can use Access 97 with any version of MDAC, as the necessary elements of the BDE are included in the application.
If you have Access 2000, you will need to use MDB transfer files or DBF transfer files plus the BDE. (In other words, Microsoft did not renew its licensing agreement with Borland.)
As noted in the Microsoft Article, ACC2000: Using dBase Data with Access 2000 and Jet (Article ID: Q230125), “There may be incompatibilities with certain versions of BDE. The symptoms of the incompatibilities may vary, depending on the version of the BDE. Version 5.01 of the Borland Database Engine is recommended. Contact Inprise Inc or a third-party vendor to obtain the BDE. Obtain licensing and run-time distribution requirements for the BDE from Inprise.”
If your product uses Access 97 and DBF transfer files, and your user upgrades to Access 2000, the application will be broken, and you will need to write another version using MDB transfer tables (and make sure that you have a mechanism to restore data). For this reason, it is preferable to use the Access 2000 format unless you have a compelling reason to do otherwise.
Although it is possible to use MDB transfer files in some circumstances with Access 97, this is strongly discouraged. Certain combinations of data access technologies and configurations may work, but others will not, and this configuration is not supported by PUMATECH.
If this seems confusing, that is because it is confusing. I have spent a year wrestling with this issue, determining how to distribute and maintain my app for users with either Access 97 or Access 2000.
· One solution would be to write two programs, one for 97 and one for 2000 and devise an upgrade strategy.
· Another solution might be to write one program in Access 2000 format, purchase Borland C++, write a program to install the BDE on the user’s computer, and distribute it with your application.
· A third solution would be to use an Access 97 runtime with an install script that allows the program to run in its own “sandbox,” unaffected by changes in operating systems or programs. This is appealing since the Access 97 runtime is about 10 MB compared to the Access 2000 runtime of 140 MB. This would allow you to use your Satellite Forms application in all environments (95, 97, ME, NT, 2000) and would not require adding MDAC or the BDE.
· A fourth solution would be to do the same with an Access 2000 runtime, but this would require adding MDAC 2.5.
One source for install scripts that will allow the “sandbox” functionality is Sagekey Software at http://sagekey.com. (Highly recommended)
Extensions are valuable additions to SF, although they do take getting used to. The documentation is often scanty, but most SF extensions have associated sample projects that demonstrate their use. The development community has a number of very useful extensions for free or for a small charge. The only advice here is to dig in, figure it out, and use them as needed. Gavin Maxwell’s book, Teach Yourself Palm Programming in 24 hours, is also helpful.
POSE (Palm Operating System Emulator) is a Palm emulator that runs on your desktop computer. It looks and acts just like a Palm device, except that you enter text by your keyboard or mouse. Although you can use your own Palm device to download and test programs, POSE has a number of advantages:
· It is faster.
· If you crash the emulator, no problem. Just start it up again. This way you do not have to worry about losing personal data while testing your program.
· You can test multiple versions of the Palm OS to ensure that your program functions well in all environments.
· You can use Gremlins, which is a program within POSE, that randomly enters data into the Palm. This helps ensure that your program does not crash under unusual circumstances.
One of the first stops for any Palm developer is the PalmOS Developer’s Site http://www.palmos.com/dev/ . You will want to sign up for the Solution Provider Program and enter the Provider Pavilion. There you will find all the information you need to download POSE. Just keep in mind that you have to download both the emulator and a Palm operating system.
The documentation for POSE is lengthy and difficult to read. Fortunately, Gavin Maxwell created a simple document that allows one to set it up in a matter of minutes. You can find this document at PalmDataPro.com http://www.PalmDataPro.com , where you can also find a large selection of SF extensions for sale.
Sometimes we need to step back a bit to see the big picture. The application that you are developing will probably consist of two applications, one on the handheld and one on the desktop.
The handheld application can be created in its entirety with Satellite Forms. You create it, distribute the files, upload them to the handheld, and you are done. In this case, you may need a backup utility to recreate your data in case your unit crashes or becomes damaged.
Most of the time, the handheld application synchronizes with a desktop application. For most beginning programmers, and many advanced programmers, this is accomplished with either Microsoft Access or Microsoft Visual Basic.
If your user has a copy of Access, you write your program in code as described in the SF tutorial, and distribute the MDB database as part of your install. You may want to secure the database, and hide your code, by creating an execute-only program. In this case, you would save your program as an MDE database.
If your user does not have Access, you can purchase the
Developer’s Edition which allows you to distribute a runtime version.
You may chose to write your application in Visual Basic, which works whether or not your user has a copy of Access. It has the advantage of being a smaller program, with a runtime size of about 6-8 MB. With VB6, you can also start the application when the computer boots up and then minimize it to the system tray, allowing the user to HotSync without manually opening the desktop program.
Now that you have written your application, you need to be able to get it to your users. You may also need to add a few elements for security and authentication.
If you are going to distribute your product within your own organization, you may wish to use the two-disk method mentioned in the SF documentation. (Actually you need three disks-one for your application as well as the two Redist disks.)
If you are distributing your product over the Web or on CDs, you probably want to use an install program. The two most popular programs are InstallShield and Wise InstallBuilder. InstallShield is said to be more capable, more similar to the C language, and more expensive. InstallBuilder is more similar to Visual Basic and seems to be popular with SF developers.
I have not looked at InstallShield. InstallBuilder was less than half the cost and was recommended by a friend. I purchased it and had it functioning in less than a day, with only one call to technical support. Curiously, when you create your INI file, you cannot have comments above the term “[Installer]”.
If you are using either product with a runtime version of
Access, once again I would recommend checking out Sagekey Software http://sagekey.com. They sell scripts that
make the install incredibly easy, and you can create runtime applications that
will not break if your users change operating systems or applications. Read through the site documentation for more
information.
When you distribute your application to another computer, it will likely be in another directory than the one you used for development. Therefore you will need to relink the DBF or MDB transfer files and reestablish the path to the files in your HotSync code.
An example of re-linking code can be found in Article 181076
in the Microsoft Knowledge Bank entitled ACC: How
to Relink Back-End Tables with Common Dialog Control.
Path names to transfer files in your HotSync code should be relative to the path of the directory in which the transfer files reside.
Example:
Dim TableFilename_WRKSITES As String
If you are distributing your software over the Web, you may consider giving your trial user a full version and writing a timeout function with authentication keys.
A timeout function allows you to specify the length of time an application will function. Place your script in AfterAppStarts, initialize it when the program is installed, and start counting down the days.
If you give your user an authentication key, it will usually be inserted into the timeout function to allow continued use of the product. Typically, the user will purchase the product and send you the User Name of the handheld (ex: “My Palm”). You can make a key based on this name and send it back to the user. The user types the key into an edit field and the application stores it in a table. In the HotSync code, the GetUserName method will obtain the User Name and retrieve the key from the table. Perform your logic in AfterAppStarts and bypass the timeout function if there is a match.
There are other ways to create an authentication key, and you are obviously free to chose any method that works for you. Also, more specific details are not given here to maintain the security of the method.
When you distribute your program, keep in mind that you will be updating it from time to time. You should have your update system in mind, and preferably tested, before you distribute your final product.
If you are developing your application to sell on the
web, and are unsure of how to get started, you might want to read the companion
paper “Getting
Started with Selling Online.”