Appendix D: Debugging problems after upgrading from J-Bird 0.5.0 or less

Introduction

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% is defined.
  • 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

1. Copy the file named J-Bird.prefs to the new data directory.
2. Copy the file named mckoidb.conf to the new data directory. (Later, you will edit the contents of the file.)
3. 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.
4. Copy the file named J-Bird-state.ser to the new data directory.

Modifications to make

1. 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:
     • 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"
     Replace YOUR_ID with your ID. Be sure to include the double quotes if the path includes a space.
   • Add the key/value pair "NextRun = Run" on its own line.
2. 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.
3. 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.
   • 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.
   If you do not know the version number from which you upgraded, you can guess and hope for the best.