|
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)
|