hrsh2csv(1) hrsh2csv(1)
NAME
hrsh2csv - converts PDB files created by Hours into CSV format
SYNOPSIS
hrsh2csv [options] pdbfile
DESCRIPTON
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 hand-
held 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 appli-
cations.
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 out-
put, but can be redirected to a file using the --output option.
OPTIONS
--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 char-
acters 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 col-
umn. 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 ini-
tialized. 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 out-
put. 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 mes-
sages by using this option. However, critical errors that may
have caused the program to stop from conversion will be written.
DIAGNOSTICS
There are two kinds of output that may be issued on stderr. Error mes-
sages 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.
BUGS
hrsh2csv can convert only one file at a time. Currently it is not pos-
sible 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.
AUTHOR
Peter Novotnik <peternov1@gmx.de>
FURTHER REFERENCES
As already mentioned hrsh2csv is a part of the Hours project. The offi-
cial web page for this project is http://hours.sourceforge.net where
you can get the latest version of this program and may find more docu-
mentation.
SEE ALSO
pilot-link(7), pilot-xfer(1), strftime(3)
hrsh2csv(1)