hrsh2csv

hrsh2csv − converts PDB files created by Hours into CSV format

hrsh2csv [options] pdbfile

hrsh2csv is a program which can be used to convert PDB files created by the Hours application for Palm into CSV (comma separated value) files. CSV files can be opened/viewed by many popular spreadsheet applications such as OpenOffice or Gnumeric.

hrsh2csv should be regarded as the second half of the Hours project (http://hours.sourceforge.net) which consist of a Palm application and this converter. While you’re collecting data on the fly with you handheld you’ll finally want to work with it on the desktop. After using pilot-link or coldsync to retrieve databases from your handheld, you can then use hrsh2csv to parse the Hours databases and convert them into the CSV format which is a more readable format for desktop applications.

Hours databases have a creatorID of ’HRSH’ and a typeID of ’DATA’. PDB files named like databasename-HRSH.pdb were probably generated by the Hours application, however, the proper idetification of the database is done by the creatorID and typeID.

Currently there are three different database versions which are all handled by the hrsh2csv converter. To find out the database version use the −−dbversion option on a pdbfile. While V15, V16 and V18 labels are used in the Hours terminology, hrsh2csv keeps on calling the versions 0, 1 and 2 respectively. Depending on the version the ouput will have a different number of columns.

hrsh2csv understand many command line options to let you customize the output. By default the output of the conversion goes to standard output, but can be redirected to a file using the −−output option.

−−help

Display a list of available options and exit.

−−version

Display the program version and exit.

−−dbversion

Parse pdbfile and print the database version (0, 1 or 2) if the file holds a valid Hours database.

−−dbinfo

Parse pdbfile and print the following database information in the specified order and exit:

− database name − database type − database creator − number of records in database − database version

The database does not need to be of creatorID ’HRSH’ and of type ’DATA’ to print this information. However further parsing and converting is possible only on Hours databases.

−−banner

Print a small banner with the name of the database after the conversion.

−−no-header

Don’t print column titles.

−−only-ascii

Process records descriptions and replace all non-pritable characters with a blank.

−−keep-dots

By default the character with the value 0x95 is replaced with a ’-’. Specifying this option will suppress the replacement. The output may then contain raw 0x95 bytes even though the −−only-ascii option may have been specified. This options is useful for further processing of the data.

−−keep-newlines

By default newlines in records’ descriptions are replace with a blank. To suppress this replacement use this option. It is strongly recommended not to use this option unless you know what you are doing.

−−date FORMAT

hrsh2csv uses the strftime function to produce to the date column. By using this option you can override the program’s default FORMAT which is %F. Note that only the tm_mday, tm_mon and tm_year members of the struct tm that is passed to the strftime function gets initialized. The tm_isdst member is set to -1, all other uninitialized members are set to zero. Also note that the internal date buffer is limited to 32 characters.

−−time FORMAT

hrsh2csv uses strftime function also to print the begin and end time columns. Using this option you can override the default FORMAT which is %H:%M. Note that only the tm_hour and the tm_min members of the struct tm which is passed to strftime gets initialized. tm_isdst member is set to -1, all other uninizialized member are set to zero. Note that the internal time buffer is limited to 16 characters.

−−total-time FORMAT

This format is used by hrsh2csv to print the total values, like the total time, the break time and the total time minus the break. By default it is set to %H:%M. This time the FORMAT understands the following interpreted sequences:

%% a literal %
%H hours (greater or equal 0)
%M minutes (0 ... 59)

−−dont-enclose-values

By default hrsh2cvs encloses the converted values with double quotes to excatly define where a value starts and where it ends. You can turn those quotes off by specifying this option on the command line. It is not recommended to use this option if you’re not sure what you are doing.

−s, −−separator STRING

STRING is used to separate the values in a row. By default ‘,’ is used, but you may specify whatever you want. It is save to enclose the string with single or double quotes at the command line. To enter the tab character press CTRL+V followed by the Tab key. The same applies to other control sequences.

−o, −−output file

By default hrsh2csv prints the converted data to standard output. Using this option you can redirect that output to file. If the file already exists it will be overriden.

−q, −−quiet

While converting a database hrsh2csv prints some information and logging messages to standard error. You can suppress that messages by using this option. However, critical errors that may have caused the program to stop from conversion will be written.

There are two kinds of output that may be issued on stderr. Error messages begin with ‘error:’, all other output is pure information that may be suppressed with the −−quiet option. The following error messages may be issued on stderr:

Not a PDB database.

The input file does not appear to be a valid PalmPilot PDB file at all. This means that either the file is corrupted or it is not a backed up Palm database file.

Invalid param.

An internal error has occured. If you ever see this you should make a bug report.

fseek() failed.

This is also an internal error which can occur if the file to be converted is corrupted.

Not an Hours database.

Although the file to be parsed seems to be a valid PDB file it seems not to be a valid Hours database as specified in the file header. The creatorID of the database is not ’HRSH’ or the typeID of the datbase is not ’DATA’.

Cannot handle database version of NUM.

This message indicates that you are using an old converter which cannot handle the database version NUM. You should install the latest version of this program that comes with Hours.

hrsh2csv can convert only one file at a time. Currently it is not possible to define more files to be converted at once.

At this time it is not possible to tell hrsh2csv to leave out specific columns.

Some characters available on Palm driven handhelds are not printable, however, hrsh2csv does not remove them by default. You can specify the --only-ascii option at the command line to have those characters replaced with a blank. Not that some some csv-parsers may have problems with non-printable characters.

While the description of Hours records are multilined and may contain newlines characters, hrsh2csv replaces them with a blank by default to ensure the output is valid as specified by the csv format. Thus, after conversion the description will be entirely in one line and loses its format.

In the situation where hrsh2csv finds records that have no begin or no end time specified, as this is allowed by the Hours application, it will leave out the computation of the total values.

Peter Novotnik <peternov1@gmx.de>

As already mentioned hrsh2csv is a part of the Hours project. The official web page for this project is http://hours.sourceforge.net where you can get the latest version of this program and may find more documentation.

pilot-link(7), pilot-xfer(1), strftime(3)