Appendix D: Debugging problems after upgrading from J-Bird 0.5.0 or less
A large change in J-Bird was implemented in version 0.5.1. Although you should
be able to upgrade J-Bird without difficulty, there is a chance that problems
will occur. This page describes the change that was made to J-Bird, and it
explains how to make the transition manually if that proves to be necessary.
In J-Bird 0.5.1, data that J-Bird creates were moved from the directory
in which the software resides to a separate directory. This change was
necessary to be able to provide J-Bird in native package formats
for Mac OS X (.dmg image file) and Linux (in the future). It is more
consistent with standards for software packages on all types of systems.
If you upgrade J-Bird from a version that is 0.5.0 or older, the transition
should be made for you when J-Bird you run for the first time after the upgrade.
A directory should be created for your data. The database and files that
contain your preferences should be copied to the new data directory. And,
the configuration files should be modified to reflect the move.
The transition was tested under a wide variety of circumstances prior to
the release of J-Bird 0.5.1. This page is intended to provide documentation
to user for whom the upgrade fails. It describes changes that are made in
a manner that should allow you to check to see if they were successful. If
the changes were not made, this page should describe them in a manner that
allows you to make them manually.
Sign of trouble
When you upgrade from a version that is 0.5.0 or older, J-Bird should just work
as it always has. If it does not, something is wrong. The most likely
incorrect behavior is: you launch J-Bird, and it presents to you a screen for
building the master species list. Quit J-Bird and work through this page.
The new data directory
The data directory is usually stored somewhere in your home directory tree.
The exact location depends whether you have a Mac, a Windows computer or a
Unix/Linux computer. Default locations are listed below.
- Mac OS X - /Users/YOUR_NAME_HERE/Library/Application Support/J-Bird.
- MS Windows.
- %APPDATA%\J-Bird on systems on which %APPDATA%
- On other systems, it will be installed in a subdirectory
of your home directory that is named
Application Data\J-Bird. On Win 98 systems it is
usually C:\WINDOWS\Application Data\J-Bird.
- Unix/Linux - ~/.J-Bird.
If that directory does not exist, create it.
Where to find the old software and data directory
On Linux and MS Windows, the old software and data directory is be the
same as the new software directory. On Mac OS X, they differ: the old
directory will have been created by the old installer whereas the new
software directory will be a Mac OS X package. The location of the software
directory also depends on whether you accepted the default location when
you originally installed J-Bird. Default locations are given below.
- Mac OS X - ~/J-Bird.
- MS Windows - assume that the system disk is C:. The installer
is likely to suggest one of the following:
- C:\Program Files\J-Bird,
- C:\Documents and Settings\yourhome\J-Bird.
- Unix/Linux - ~/J-Bird.
Things to move from the old software directory to the new data directory
- Copy the file named J-Bird.prefs to the new data directory.
- Copy the file named mckoidb.conf to the new data directory. (Later, you
will edit the contents of the file.)
- Copy or move the directory named mckoidb and all of its contents. On
Macs and Windows computers, this is most easily accomplished by dragging the
folder and dropping it on the new data directory. Linux users can use
the mv command.
- Copy the file named J-Bird-state.ser to the new data directory.
Modifications to make
- Edit the J-Bird.prefs file that is in the new data directory. The file
contains keyword/value pairs that are separated by an equals sign.
Edit the value of JDBCURL to contain the full path of the mckoidb.conf
file. The existing value should be "jdbc:mckoi:local://./mckoidb.conf",
change "./mckoidb.conf" to a full path. The following are defaults:
Replace YOUR_ID with your ID. Be sure to include the double quotes if
the path includes a space.
- Mac OS X - "jdbc:mckoi:local:///Users/YOUR_ID/Library/Application Support/J-Bird/mckoidb.conf"
- Unix/Linux - "jdbc:mckoi:local:///home/YOUR_ID/.J-Bird/mckoidb.conf"
- MS Windows - "jdbc:mckoi:local://C:\Documents and Settings\YOUR_ID\Application Data\J-Bird\mckoidb.conf"
- Add the key/value pair "NextRun = Run" on its own line.
- Edit the mckoidb.conf file that is in the new data directory. The file
contains keyword/value pairs that are separated by equals signs. If the file
does not contain a line that is "root_path=configuration", add it to the file.
- Create a plain text file named VERSION that contains the number of the
version from which you upgraded. For example, if you upgraded from version
0.4.6, the file would contain only the string 0.4.6.
If you do not know the version number from which you upgraded, you can guess
and hope for the best.
- On Mac OS X, there must be an easy way to do this with a
simple editor, but I honestly don't know what it is.
Personally, I use the Linux/Unix method on OS X. Sorry.
- On Linux/Unix this is most easily accomplished with the
command "echo old.version.number > VERSION",
where old.version.number is replaced with the appropriate
version number. This can also be done on Mac OS X by users
who are familiar with the command line there.
- On Windows this is probably most easily accomplished using the
NotePad text editor. Fire it up, put in the version number
and save as a file named VERSION in the new data directory.
Last updated 23 May 2006