Problem:        How To use the SFConvertPDB utility

Solution:        SFConvertPDB is a commandline utility included with Satellite Forms 7.0 that enables you to convert database files from PDB format to/from DBF or MDB format, on the desktop PC.  It does not require a Palm HotSync or Microsoft ActiveSync session to be active, as it runs entirely on the PC.  This provides a handheld-platform-independent PC based mechanism to convert data to & from PDB files, for use with Satellite Forms applications on the PalmOS platform and on the PocketPC platform when using PalmDB database tables.

Updated July 11, 2007 to include new -CreateFlag parameter and table flag details.

A. Overview

SFConvertPDB enables you convert Satellite Forms table data from:

• PDB table to dBase DBF table
• PDB table to MS Access MDB table
• dBase DBF table to PDB table
• MS Access MDB table to PDB table

The SFConvertPDB utility does not make any assumptions or have any requirements about how you get the PDB database file to the PC, whether it be via PalmOS HotSync, Microsoft ActiveSync, TCPIP, Bluetooth file transfer, memory cards, server synchronization tools, etc.  It does not deal with the movement of the PDB file to/from the PDA; rather it deals with converting the data between PDB <--> MDB/DBF on the desktop PC only.  This makes it very flexible, and enables it to be integrated into a PDA synchronization system regardless of how that system moves the PDB file back and forth from the PDA to the PC.

SFConvertPDB is an EXE executable program, rather than an ActiveX control or DLL.  To integrate SFConvertPDB into your synchronization system, your sync application must be capable of launching an EXE application.

SFConvertPDB operates via commandline switches, in which you supply the required information about which database file to convert, and how to convert it.  If you are familiar with the use of the SatForms HotSync OCX control to move data back and forth at HotSync, you will find most of these parameters to be familiar.  If you have used the RDKInst or CeRDKInst utilities for commandline installation of files and/or conduit registration, you will find the use of the SFConvertPDB utility familiar as well.

B. Usage

Usage: SFConvertPDB [commandline switches]

-[PDBtoPC|PCtoPDB]: Specifies whether you want to convert from a PDB database to a DBF/MDB database [use -PDBtoPC], or from a PC DBF/MDB database to a PDB [use -PCtoPDB].  You may specify only one of these conversion options, not both.

-filename \path\to\PC_database_file.[DBF|MDB]: You must supply the path and filename of the PC DBF or MDB database file which you wish to convert to or from PDB.  You do not specify the PDB file even when converting from PDB to DBF/MDB: rather, you always supply the PC database filename ending in .DBF or .MDB.

-creatorid CRID: Where CRID is the four-character unique creatorID used by your application (and which should be registered with PalmSource  via their creatorID registry on their website), as defined in the Project Properties settings screen in App Designer.  You must supply the correct case sensitive characters, which cannot include spaces.  When testing with the SatForms SDK runtime engine used by App Designer, the creatorid is SMSF.  This parameter is needed in order to generate the correct PDB table name for conversion, as the creatorid is incorporated into the PDB table name.  The default creatorid if none is supplied is SMSF.

-SDDI_DLL DLLfilename: You must specify the correct SatForms SDDI DLL to perform the conversion.  At the present time, the only conversion supported is for SatForms PalmDB (PDB) databases, so you should always specify the SDDI_PalmDB.DLL.  This parameter is optional, and if you omit it, the default of -SDDI_DLL SDDI_PalmDB.DLL will be used.

-VersionMajor VV: Where VV is the major version number of your application, as defined in the Project Properties settings screen in App Designer.  The allowable values are from 0 - 99.  This parameter is needed in order to generate the correct PDB table name for conversion, as the major and minor version numbers are incorporated into the PDB table name.  This parameter is optional, and if you omit it, the default value of 0 will be used.

-VersionMinor vv: Where vv is the minor version number of your application, as defined in the Project Properties settings screen in App Designer.  The allowable values are from 0 - 99.  This parameter is needed in order to generate the correct PDB table name for conversion, as the major and minor version numbers are incorporated into the PDB table name.  This parameter is optional, and if you omit it, the default value of 0 will be used.

-CreateFlag n: Where n specifies the desired table flag[s] to set on the PDB table when it is created by SFConvertPDB.  The allowable values are any positive integer, corresponding to the combination of desired table flags.  Certain PDB table behaviours can be set via this numeric flag value, including Backup, Read-Only, and NoAutoCommit flags.  The table flags cause the SatForms runtime engine to treat the table differently on the PDA.  For a more detailed reference about table flags, see section G: Table Flags below. This new parameter was added with SFConvertPDB version 7.0.1.040 and higher and is not supported in previous versions.  This parameter is optional, and if you omit it, the default value of 0 will be used.

-quiet: This parameter instructs SFConvertPDB to not display any popup error messages when performing the conversion.  The exit code of SFConvertPDB can be queried to determine if the conversion was successful or not, making it suitable for calling from sync applications or batch files.  When run interactively, you would not likely use the -quiet switch so that you could see error messages pop up if there are conversion problems.

Example usage for common conversion scenarios:

1. Converting the database file C:\MyApp\Data\EMyAp0102_MYTABLE1.PDB to C:\MyApp\Data\MyTable.DBF:

SFConvertPDB -PDBtoPC -filename C:\MyApp\Data\MyTable.DBF - creatorID MyAp -VersionMajor 1 -VersionMinor 2

Result: the C:\MyApp\Data\MyTable.DBF is created containing the records from EMyAp0102_MYTABLE1.PDB.

2. Converting the database file C:\MyApp\Data\EMyAp0102_MYTABLE1.PDB to C:\MyApp\Data\MyTable.MDB:

SFConvertPDB -PDBtoPC -filename C:\MyApp\Data\MyTable.MDB - creatorID MyAp -VersionMajor 1 -VersionMinor 2

Result: the C:\MyApp\Data\MyTable.MDB is created containing the records from EMyAp0102_MYTABLE1.PDB.

3. Converting the database file D:\Server\Data\tNames.DBF to D:\Server\Data\EMyAp0200_TNAMES.PDB:

SFConvertPDB -PCtoPDB -filename D:\Server\Data\tNames.DBF - creatorID MyAp -VersionMajor 2 -VersionMinor 0

Result: the D:\Server\Data\EMyAp0200_TNAMES.PDB is created containing the records from tNames.DBF.

4. Converting the database file D:\Server\Data\tNames.MDB to D:\Server\Data\EMyAp0200_TNAMES.PDB:

SFConvertPDB -PCtoPDB -filename D:\Server\Data\tNames.MDB - creatorID MyAp -VersionMajor 2 -VersionMinor 0

Result: the D:\Server\Data\EMyAp0200_TNAMES.PDB is created containing the records from tNames.MDB.

5. Converting the database file D:\Server\Data\tNames.MDB to D:\Server\Data\EMyAp0200_TNAMES.PDB with a -CreateFlag value of 64 to indicate NoAutoCommit table flag:

SFConvertPDB -PCtoPDB -filename D:\Server\Data\tNames.MDB - creatorID MyAp -VersionMajor 2 -VersionMinor 0 -CreateFlag 64

Result: the D:\Server\Data\EMyAp0200_TNAMES.PDB is created containing the records from tNames.MDB and has the NoAutoCommit table flag set.

6. Converting the database file D:\Server\Data\tNames.MDB to D:\Server\Data\EMyAp0200_TNAMES.PDB with a -CreateFlag value of 7 to indicate Backup + Read-Only + Autoname table flags:

SFConvertPDB -PCtoPDB -filename D:\Server\Data\tNames.MDB - creatorID MyAp -VersionMajor 2 -VersionMinor 0 -CreateFlag 7

Result: the D:\Server\Data\EMyAp0200_TNAMES.PDB is created containing the records from tNames.MDB and has the Backup + Read-Only + Autoname table flags set.

C. Integration into a PocketPC synchronization system using PocketPC PDB tables

Starting with Satellite Forms 7.0, it is possible to use PalmDB (PDB) tables with PocketPC applications, and there are several advantages in doing so instead of using Microsoft Compact Database CDB format tables.  In order to build a successful PocketPC data synchronization system when using PDB tables, integrated with your desktop PC database system, you need to be able to handle these four actions:

• conversion from your PC database table to a PDB database table
• transferring a PDB table from the PC to the PDA (download data to the PDA)
• transferring a PDB table from the PDA back to the PC (upload data to the PC)
• conversion from a PDB table to your desktop PC database table

The SFConvertPDB utility provides the means to convert PDB <--> DBF/MDB on your PC.  The action of transferring PDB files between the PDA <--> PC can be achieved in multiple ways.  Two of those file transfer methods include using the Satellite Forms ActiveSync OCX, or using the Satellite Forms CeRemote.DLL.

When using the SatForms ActiveSync OCX, the functions FileGetFromPPC and FileSendToPPC can be utilized to transfer PDB tables to/from the PocketPC.  This is in contrast to the DatabaseFromPPC and DatabaseToPPC functions that are used with CDB database tables.

A typical data synchronization flow using the SF ActiveSync OCX to retrieve a PDB database table from the PocketPC, then send an updated PDB table back to the PPC, would go something like this:

• retrieve the PDB table from the PPC using FileGetFromPPC
• convert the PDB table to MDB/DBF using SFConvertPDB
• manipulate that data in your PC database, creating an updated DBF/MDB
• convert the updated DBF/MDB table to PDB using SFConvertPDB
• download that updated PDB to the PPC using FileSendToPPC

When using the SatForms CeRemote.DLL to transfer files, the functions GetFile and SendFile can be utilized to transfer PDB tables to/from the PocketPC.  This is in contrast to the GetTable and SendTable functions that are used with CDB database tables.

A typical data synchronization flow using the CeRemote.DLL to retrieve a PDB database table from the PocketPC, then send an updated PDB table back to the PPC, would go something like this:

• retrieve the PDB table from the PPC using GetFile
• convert the PDB table to MDB/DBF using SFConvertPDB
• manipulate that data in your PC database, creating an updated DBF/MDB
• convert the updated DBF/MDB table to PDB using SFConvertPDB
• download that updated PDB to the PPC using SendFile

A sample PocketPC synchronization tool written in Visual Basic 6 called SatSyncPPCPDB is provided in the Samples folder of the Satellite Forms installation.  This SatSyncPPCPDB sample application demonstrates the use of the CeRemote.DLL and SFConvertPDB utility to sync PDB data back and forth between the PC and PocketPC.

D. Integration into a PalmOS synchronization system

Satellite Forms has used PalmDB (PDB) format database tables for many generations, and synchronization between the PalmOS handheld and PC DBF/MDB databases has been enabled through the Satellite Forms HotSync conduit and the Satellite Forms HotSync OCX.  The SatForms HotSync OCX provides functions for sending PC database data to PDB tables on the PDA, and retrieving PDB data from the PDA to the PC database tables at HotSync, via the CopyTableToPalmPilot and GetTableFromPalmPilot functions.  For most SatForms developers, this synchronization system is ideal, and no other options are needed.

However, some SatForms PalmOS application developers need to synchronize data without relying on Palm HotSync as the data transfer mechanism.  Palm HotSync does have its limitations, not the least of which is that it only supports the synchronization of a single Palm device at a time: simultaneous HotSync synchronization of multiple devices is not possible on a single PC.  It is for that reason that the SFConvertPDB utility may be of interest to SatForms PalmOS application developers in addition to SatForms PocketPC PDB app developers.

Let's consider an example using the File Transfer Protocol (FTP) to transfer PDB database files back and forth between a TCPIP-connected PalmOS device (for example a Palm Treo smartphone or TX PDA) and a PC database server.  A typical data synchronization flow using FTP to transfer the PDB files would go something like this:

• upload the PDB table from the PDA to PC server using FTP (for example with the PalmDataPro SF-FTP extension)
• convert that PDB table on the server to DBF/MDB using the SFConvertPDB utility
• manipulate that data in your PC database, creating an updated DBF/MDB
• convert the updated DBF/MDB table to PDB using SFConvertPDB
• download that updated PDB table to the Palm PDA using FTP (via SF-FTP extension)

E. Installation of components needed by SFConvertPDB

SFConvertPDB relies on several Satellite Forms components included in the Satellite Forms Runtime for PalmOS (not to be confused with the SatForms PalmOS runtime engine).  Installing the Runtime package is the easiest way to ensure that all of the necessary components needed by SFConvertPDB are installed and registered correctly.  See the article How To Install the SatForms Runtime for Palm silently for tips on how to install the runtime without any installation UI on end users' computers.  Note that this runtime needs to be installed on any computer that will use the SFConvertPDB utility, regardless of whether that computer syncs with PalmOS devices, and/or PocketPC devices, or does not perform any device synchronization at all.

F. SFConvertPDB Error Codes

G. Table Flags

One of the properties of a Satellite Forms table PDB is the Table Flag value.  The Table Flag is a numeric value that determines special behaviours of that table when it is in use on the PDA by the Satellite Forms runtime engine.  For example, one of the possible table flag values indicates that the table is Read-Only, and the runtime engine therefore prevents any modifications/additions/deletions to the data in the table.

The Table Flags for each table PDB can be specified using the -CreateFlag parameter of the SFConvertPDB utility.  Each table can have different flags as they are assigned on a per-table basis.  The current supported table flags include:

Some table flag values can be combined, while others must be exclusive.  For example, the Backup, Read-Only, and Autoname flags can all be present on a given table, and you would specify all of those flags by adding their flag values together ([Backup] 1 + [Read-Only] 2 + [Autoname] 4 = 7).  The Read-Only and NoAutoCommit flags must be exclusive to each other: do not combine them together.

H. Conclusion

The SFConvertPDB utility is a flexible tool that can be used as an important component in a PalmOS or PocketPC PDB data synchronization system.  Because SFConvertPDB operates on the PC and does not rely on any specific PDA <--> PC data transport layer or protocol, it can be integrated into a wide variety of synchronization scenarios including PalmOS HotSync, Microsoft ActiveSync, TCPIP, Bluetooth file transfer, memory cards, server synchronization protocols, and more.

Keywords:      SFConvertPDB, convert, conversion, PDB, CDB, HotSync, ActiveSync, sync, synchronization, transfer, TCPIP, FTP, DBF, MDB, database, CreateFlag, flag, NoAutoCommit, Read-Only

KB ID: 10038 

Updated: 2007-07-11

Satellite Forms KnowledgeBase Online

Satellite Forms Website Home