PathAway Database Tools 3.1

This document describes the tools available for converting to and from PathAway database format.

The Command line converter is run from the command line prompt. It is assumed the user is knowledgable of command line commands. The Windows DLL is for developers familiar with programming Windows DLLs in C or C++.

Contents

Release Notes: - Description of changes.
PWDBConvert - Command Line DB Converter for Palm OS
PWDBWMConvert - Command Line DB Converter for Windows Mobile (CE)
PWDBLib.DLL - DB Converter DLL Programmer APIs
CAL FILE Format - Calibration (.CAL) file format definition.


Release Notes:

3.10.06 - Dec 13 2004
-
FIXED: missing Description field when converting PDB Palm Databases. (interim problem)

3.10.05 - Oct 15 2004
-
Modifed parameter in PDBExport to return the name of the file created.

3.10b04 - Aug 27 2004
- Added Windows Mobile conversion utilities.
If Converting From PathAway format, and the export file name field is left blank, the default ExportFilename extensions are now:
Tracks: .pwt
Routes: .pwr
Points: .pwp

Previously, the default extension for all export databases was .csv.

3.10b01 - June 10 2004
- Added Windows Mobile conversion utilities.

(3.00)
- Creates PathAway 3.0 Format Files
- Added Track2 and Route2 database types for converting to PathAway 2 format.
- Added Header to .CAL format.

(2.08)
- now strips leading and trailing blanks in data fields,
- added support for fixed field length data types. Source=FIXED, FieldLen parameter defines length of each field. CAL file required. See CAL FILE Format .
- added OZIPCX5.CAL, and OZITrack5.CAL
sample converter definitions for OZIExplorer output tracks.


PWDBConvert

Command Line DB Converter for Palm OS

PathAway Database Batch Converter converts Track/Route and Point databases to and from PathAway Palm OS format.

All PathAway databases are backed up in the user's Backup folder. This folder is usually found in the C:\Palm\<UserName>\Backup folder. Where <UserName> is an 8 character name of the user's Palm user name, as found on the device. Note, All PathAway databases have a .pdb file extension.(note these parameters have changed from 1.0, see EleFormat field)

Command Line Parameters:

PWDBConvert [ImportFileName], [ExportFileName], [CalFileName], [PalmFileType], [CSVFileType], [CSVFieldCount], [LatPos], [LongPos], [ElePos], [UTCPos], [NamePos], [IconPos], [DescPos], [EleFormat]

or if using a format definition file (CAL File) the following command line is used: See CAL FILE Format for a description

PWDBConvert [ImportFileName], [ExportFileName], [CalFileName]

[ImportFileName]: full path to import filename. Operation converts From Palm format if this is a PDB file

[ExportFileName]: full path to export File name. Operation converts To Palm format if this is a PDB file. If Converting From PathAway format, and this field is left blank, the default ExportFilename extensions are:
Tracks: .pwt
Routes: .pwr
Points: .pwp

[CalFileName]: full path to Calibration file. Must have .cal extension.

The following optional command line parameters override the entries in the .Cal file.

[PalmFileType]: File Type: "Point", "Route", or "Track". Applies to importing to PDB only

[CSVFileType]: CSV File Type: "Comma", "Garmin", "Tab". (see CSVFormatType below for further explanation)

[CSVFieldCount]: Total number of fields in CSV (Character Separated) file.

[LatPos],[LongPos],[ElePos],[UTCPos],[NamePos],[IconPos],[DescPos]: Field Position in each record of CSV file. 0 is first position

[EleFormat]: Elevation Format. "Feet" or "Metres"

The Following is an example of a set of commands to convert the samplePts.csv file into PathAway format. The PWDBConvert.exe file and the samplepts.csv and samplePts.cal file are assumed to be stored in the C:\PathAway folder:

C:\>CD \PathAway
C:\PathAway>PWDBConvert samplePts.csv

The PathAway file is called samplePts.pdb. From Windows explorer, this can be transferred to the device, by installing using the Palm Install tool.


PWDBWMConvert

Command Line DB Converter for Windows Mobile (CE)

PathAway Database Batch Converter copies PathAway for Windows Mobile Database Track/Route and Point databases to and from the Windows Mobile Device. This utilitity operates directly on the device. Before running ensure the device is connected via ActiveSync. Databases are stored on the Windows mobile device in PathAway WM database format. This utility allows you to copy the databases on the device to the PC format in the desired format. By default, the databases are converted into Comma Delimited text format with the following extensions:
Tracks: .pwt
Routes: .pwr
Points: .pwp

Command Line Parameters:

PWDBWMConvert <Command> <PCFolderName> ,[<DeviceFolderName>]

<Command>:
dir - Compare folder on PC to Databases on device.
CopyToDevice - Copy databases from PC to Device.
CopyFromDevice - Copy databases from Device to PC.

<PCFolderName>
The folder on the PC that contains the PathAway Databases. If this entry is blank, the current folder is used.

[<DeviceFolderName>]
The folder on the device that contains the PathAway Databases. If this entry is blank, the default device storage path is \My Documents\PathAway.

Examples:

The Following is an example of a set of commands to copy the samplePts.pwp file into PathAway format on the device. The PWDBWMConvert.exe file is assumed to be stored in the C:\PathAway folder. The samplepts.pwp file are in the C:\PathAwayDB folder. The default device storage path is \My Documents\PathAway which can be ommitted:

C:\>CD \PathAway
C:\PathAway>PWDBWMConvert CopyToDevice C:\PathAwayDB\SamplePts.pwp

The PathAway Database SamplePts will be converted and transferred to the Windows Mobile device. It can be viewed in the PathAway "Points Database" screen under the name SamplePts.

To copy all the databases from a folder on your PC to the device, simply enter the command.

C:\>CD \PathAway
C:\PathAway>PWDBWMConvert CopyToDevice C:\PathAwayDB



PWDBLib.DLL

DB Converter DLL Programmer APIs

The plugin DLL is a C/C++ language interface DLL. Note if a .CAL file is used, the parameters are overrides, so use the default parameters to leave them unchanged.

Palm OS Commands

PWDBImport
PWDBExport

Windows Mobile Commands

PWDBCEEnum
PWDBCECopyToDevice
PWDBCECopyFromDevice


Palm OS Commands

PathAway Database Batch Converter converts Track/Route and Point databases to and from PathAway Palm OS format.

All PathAway databases are backed up in the user's Backup folder. This folder is usually found in the C:\Palm\<UserName>\Backup folder. Where <UserName> is an 8 character name of the user's Palm user name, as found on the device. Note, All PathAway databases have a .pdb file extension.(note these parameters have changed from 1.0, see EleFormat field)

 


PWDBExport

  Convert from PathAway Palm OS .pdb format to destination format such as CSV (Character Separated) File.
 

PWInt32
PWDBExport(
char *PalmDBName,
char *FileName,
char *CalFileName,
PWInt16 CSVFormatType,
PWInt16 EleFormat,
PWInt16 CSVFieldCount,
PWInt16 *CSVPosArray
);


Parameters
  PalmDBName
   

[in] [in] Palm Database name to import from.

  FileName
   

[in] full path to export to. If NULL. If NULL <PalmDBName>.<ext> will be created.
**New Oct 15 2004** If the filename pointer is passed but it is a NULL string, then the name of the file created will be copied into this string. The fileName must be a 256 character null terminated string buffer.

  CalFileName
   

[in] full path to Calibration file. Must have .cal extension. If NULL, optional parameters are used

  CSVFieldCount
   

[in] Total number of fields in CSV (Character Separated) file.

  CSVFormatType
   

[in] CSV File Type, default=-1. This is an optional parameter that can be overridden by entries in the .Cal file.

Value Name Description
0
DELIMITED_COMMA Comma Delimited. Strings may or may not be in quotes.
1
DELIMITED_TAB TAB character (9) Delimited. Strings may or may not be in quotes.
2
GARMIN_TAB GARMIN TAB Delimited format

 

  EleFormat
    Elevation Format. 0="Feet" or 1="Metres", default=-1. This is an optional parameter that can be overridden by entries in the .Cal file.
Value Name Description
0
ELEVATION_FEET Elevation is expressed in FEET above sea level
1
ELEVATION_METRES Elevation is expressed in METRES above sea level

  CSVPosArray
   

[in] Field Position in each record of CSV file. 0 is first position, Pass NULL for default. This is an optional parameter that can be overridden by entries in the .Cal file.
[0]=LatPos,
default=0
[1]=LongPos,
default=1
[2]=ElePos,
default=2
[3]=UTCPos,
default=3
[4]=NamePos,
default=4
[5]=IconPos,
default=5
[6]=DescPos
default=6

Return Values
 

0 indicates success. Otherwise a negative number indicating failure. [Error codes to be defined]

Remarks
   
   



PWDBImport

 
Convert source format such as CSV (Character Separated) File to PathAway Palm OS .pdb format.
 

PWInt32
PWDBImport(
char *FileName,
char *PalmDBName,
char *CalFileName,
PWInt16 PalmDBType,
PWInt16 CSVFormatType,
PWInt16 EleFormat,
PWInt16 *CSVPosArray
);


Parameters
  FileName
   

[in] full path to filename to import from.

  PalmDBName
   

[in] Palm Database name to export to. Will be a .pdb extension. If NULL <Filename>.pdb will be created.

  CalFileName
   

[in] full path to Calibration file. Must have .cal extension. If NULL, optional parameters are used

  PalmDBType
    Palm Database Type
Value Name Description
0
PWDBTYPE_POINT Point Database
1
PWDBTYPE_TRACK Track Log Database
2
PWDBTYPE_ROUTE Route Database
0x41
PWDBTYPE_TRACK2 PathAway version 2 Track Database
0x42
PWDBTYPE_ROUTE2 PathAway version 2 Route Database

 

  CSVFormatType
   

[in] CSV File Type: (see CSVFormatType below for further explanation), default=-1. This is an optional parameter that can be overridden by entries in the .Cal file.

Value Name Description
0
DELIMITED_COMMA Comma Delimited. Strings may or may not be in quotes.
1
DELIMITED_TAB TAB character (9) Delimited. Strings may or may not be in quotes.
2
GARMIN_TAB GARMIN TAB Delimited format

  EleFormat
    Elevation Format. 0="Feet" or 1="Metres", default=-1. This is an optional parameter that can be overridden by entries in the .Cal file.
Value Name Description
0
ELEVATION_FEET Elevation is expressed in FEET above sea level
1
ELEVATION_METRES Elevation is expressed in METRES above sea level

  CSVPosArray
   

[in] Field Position in each record of CSV file. 0 is first position, Pass NULL for default. This is an optional parameter that can be overridden by entries in the .Cal file.
[0]=LatPos,
default=0
[1]=LongPos,
default=1
[2]=ElePos,
default=2
[3]=UTCPos,
default=3
[4]=NamePos,
default=4
[5]=IconPos,
default=5
[6]=DescPos
default=6

Return Values
 

0 indicates success. Otherwise a negative number indicating failure. [Error codes to be defined]

Remarks
   
   



Windows Mobile Commands

The Converter copies PathAway for Windows Mobile Database Track/Route and Point databases to and from the Windows Mobile Device. This utility operates directly on the device. Before running ensure the device is connected via ActiveSync. Databases are stored on the Windows mobile device in PathAway WM database format. This utility allows you to copy the databases on the device to the PC format in the desired format. By default, the databases are converted into Comma Delimited text format with the following extensions:

Database Type Default Extension
Tracks .pwt
Routes .pwr
Points .pwp

 


PWDBCEEnum

  This function reports the differences between the Database stored in the specified folder on the device with the folder on the PC.
 

PWInt32
PWDBCEEnum(
char *pPCPath,
char *pStoragePath,
PWUInt32 flags,
void **pResultArray
);


Parameters
  pPCPath
   

[in] Pointer to Full path to Folder on the PC to Compare with. ie. C:\PathAwayDB.

  pStoragePath
   

[in] Pointer to Full path to Folder on the Device to Compare with. ie. \My Documents\PathAway

  flags
   

[in] Comparison flags. [None. Must be 0.]

  pResultArray
   

[out] Unallocated Address of a pointer to hold the resulting Comparison table. [Unimplemented].

Return Values
 

0 indicates success. Otherwise a negative number indicating failure. [Error codes to be defined]

Remarks
   
   




PWDBCECopyToDevice

  This function reports the differences between the Database stored in the specified folder on the device with the folder on the PC.
 

PWInt32
PWDBCECopyToDevice(
char *pPCPath,
char *pStoragePath,
PWUInt32 flags
);


Parameters
  pPCPath
   

[in] Pointer to Full path to Folder on the PC to Copy From. ie. C:\PathAwayDB.

  pStoragePath
   

[in] Pointer to Full path to Folder on the Device to Copy To. ie. \My Documents\PathAway

  flags
    [in] Comparison flags.
Value Name Description
1
DBCOPY_OVERWRITE Overwrite All Files
2
DBCOPY_UPDATENEW Copy only new or updated files

Return Values
  0 indicates success. Otherwise a negative number indicating failure. [Error codes to be defined]
Remarks
   
   




PWDBCECopyFromDevice

  This function reports the differences between the Database stored in the specified folder on the device with the folder on the PC.
 

PWInt32
PWDBCECopyFromDevice(
char *pStoragePath,
char *pFindName,
char *pPCPath,
PWUInt32 flags
);


Parameters
  pStoragePath
   

[in] Pointer to Full path to Folder on the Device to Copy From. If NULL, defaults to \My Documents\PathAway

  pFindName
   

[in] Name of database to copy to PC. If NULL, All databases will be copied

  pPCPath
   

[in] Pointer to Full path to Folder on the PC to Copy To. ie. C:\PathAwayDB.

  flags
    [in] Comparison flags.
Value Name Description
1
DBCOPY_OVERWRITE Overwrite All Files
2
DBCOPY_UPDATENEW Copy only new or updated files

Return Values
  0 indicates success. Otherwise a negative number indicating failure. [Error codes to be defined]
Remarks
   
   


 



CAL FILE Format

In place of command line parameters, or DLL function parameters, the configuration
of the file to import or export can be specified in a file of the same name with a .cal
extension. See samplePts.csv and samplePts.cal for an example.

Command Line Parameters:
PWDBConvert [ImportFileName],[ExportFileName],[CalFileName]

The [CalFileName] can be omitted if it is the same name as the import file name. The software will automatically look for a .cal file with the same name.

Source=[Delimited], [Comma], [Tab], [Garmin], [Fixed]
FieldCount=
[# fields in CSV Record]
FieldLen=
[fixed field length of each field in order. Comma delimited ie. 4,10, 20,16]
Delimited=[Delimited format character] use \ for control characters. ie. \t for tab
Latitude=
[field position]
Longitude=
[field position]
Elevation=
[field position]
Time=
[field position]
Name=
[field position]
Icon=
[field position] or [iconDBname:icon (can use same icon for all points)]
Desc=
[field position]
LocFormat=
[CompressedStr], [Degrees], [Numeric], [DegNoSpace],
PalmDBType=
[Point], [Route], [Track], [Route2], [Track2]
DefaultIcon=1..4 or [iconDBname:icon]
Header=
[Quoted multi-line string containing the header of the output file]

PalmDBType Parameters

Point: WayPoint database type
Route: Route Database Type
Track: Tack Log Database Type
Route2: PathAway version 2 Route database
Track2: PathAway version 2 Track database

LocFormat Parameters

Degrees: [NS]dd mm.##, [EW]dd mm.##, (where ## is decimal minutes), or,
[NS]dd mm ss.##, [EW]dd mm ss.##, (where ## is decimal seconds)
DegNoSpace: [NS]ddmm.ss, [EW]dddmm.ss
Numeric: d.nnnnnn, where positive values are northern and eastern hemispheres
CompressedStr: 6 character degrees latitude: ddmmss, 7 character degrees longitude:. dddmmss (Works for North-Western Hemisphere only)