Thoth, v. 5.2

Software Documentation

An introduction to Thoth, as well as more detailed documentation, can be found here.

System Requirements

Thoth is an all-Java software implementation. There are no software dependencies on other
astronomical packages or libraries. However, you will need to have a recent version of the
Java Runtime Environment (JRE) installed on your machine. This version of Thoth was compiled
with javac 1.6.0_65.

Thoth can be installed and run on any machine with the JRE installed. This includes, but is
not limited to, machines running Mac, Windows, Linux, and Solaris operating systems.

Software Download

Download platform-independent Thoth in the preferred package from here:

Customizing Thoth's Database Settings

To use Thoth, you will need to set up a default database connection. To do
this, you need to download the following files and then copy
them to your home directory (which is a location that is looked up by
the software and commonly denoted as ~/ on non-Windows machines):

These are plain-text files, which you can edit as needed (more on that
below). The first
file gives an example of how to connect to four different databases.
If the first file is to contain passwords, then file permissions must
be set so that only the user can view its contents.
The database connections are numbered in the first file for differentiation.
The second set of files (thoth.query.*.properties) contain canned database queries organized
under different names (denoted by the wildcard character *).
The names can be changed to those that make sense to the user. The
idea behind the second set of files is that users will want to create
a similar set containing commonly-used queries for all of their own databases.

The first time Thoth is executed, it will create a hidden
directory in the user's home directory, called ".Thoth".
Once this has been done, the user may choose to move
thoth.run.properties and thoth.query.*.properties to ~/.Thoth
as a means of decluttering ~/. Note that upon start up of a new Thoth
session, the aforementioned properties files are, by default, loaded
from the user's ~/.Thoth hidden directory. Thoth also makes, by
default, a database
connection to ~/.Thoth/thoth.db (a SQLite scratch database
created by Thoth, the purpose of which is discussed in the software
documention), which is a connection that does not
need to be listed in the thoth.run.properties file.

The thoth.run.properties file contains database-connection settings.
You need to know the name of the database to which you want
to connect, your database account
name, and password if required. In the example thoth.run.properties
file above, none of the database connections actually require a password,
and only two of the database connections acturally require an account name.
Specific differences in specifying the database URL for Windows are
explained at the end of the Windows section below.

The thoth.query.*.properties files above contain common database queries for
the operations database of the Palomar Transient Factory
(http://ptf.caltech.edu/iptf/),
as an example.
You can edit these files and replace the queries with your own favorites. Each new query
added MUST have a unique name, which can be arbitrarily specified.
You can also create new thoth.query.*.properties files, where * is an
arbitrary name. When Thoth is executed, the names are used to name
the tabbed panes in which the canned queries are organized.

General Installation and Execution Instructions

Except for Thoth packaged as a double-click Mac application or as a
double-click Windows application, Thoth is launched via the Thoth.csh
script on UNIX-based machines, which contains

For Windows machines, there is a Thoth.bat file, which is similar in
functionality to the UNIX-based Thoth.csh file.

If you will be using Thoth.csh or Thoth.bat to launch the software, you must set
the following environment variables:

THOTH_ARCH
THOTH_HOME
PATH

Common settings for THOTH_ARCH are "MAC", "WIN", "LINUX", or
"SOLARIS". THOTH_HOME must be set to the directory containing the
file Thoth.jar. The PATH setting must be augmented with the same
location as THOTH_HOME.

If the platform-specific instructions below do not work for your particular
machine, you might try modifying Thoth.csh (or Thoth.bat in the case
of Windows) to include the required environment settings
at the very top of the file.

If, when running Thoth, you get out-of-memory errors, you might try modifying
-mx4096M to a larger value (this specifies the
heap size). For Mac users running Thoth as a double-click application, you
can similarly edit the -Xmx4096M specification in
"/Applications/Thoth.app/Contents/Info.plist" to
allocate more memory.

The platform-specific instructions below are written for uncompressing and
expanding the downloaded *.tar file via the "tar" command.
If you prefer to download the *.zip file, the "unzip" command should be
used instead to uncompress and expand the file.

Platform-Specific Installation and Execution Instructions

Mac

You have the options of installing Thoth as a double-click
application, a command-line application, or both.

Double-Click Application

The easiest way to install Thoth on a Mac is to download the *.dmg file, double click on it to
bring up the Thoth folder (if it doesn't open up by itself), open up another Finder window and
change directories to the Applications folder, and then drag the Thoth icon to the Applications folder.

This method of Thoth installation will result in a double-click Mac application, which you can
add to your dock for convenient access to Thoth as a single-click application.

Finally, if you want to install Thoth in a location different from /Applications or
you want switch GUI options in the *.dmg package that you downloaded,
then you will need to change Thoth's environment settings.
To change Thoth's environment settings, you simply do the following:

Drag Thoth icon to your home directory (commonly denoted as ~/);

Edit the settings in "~/Thoth.app/Contents/Info.plist"
as appropriate (search for the dictionary with key "LSEnvironment" at the end of this file,
and make your changes there); and then

Drag Thoth icon to your installation directory of choice.

On newer Macs, the following error may be displayed upon attempting to install the software: "Thoth" is damaged and can't be opened. However, the file is not damaged (and one can verify the MD5 checksum), and should work just fine after the security settings are (temporarily) loosened. To do this, change your

System Preferences > Security & Privacy > General

to "Allow apps to be downloaded from Anywhere".

You may have to do the following terminal fix to get the "Anywhere" option back, as it disappeared from
a later Mac OSX version:

Windows

The easiest way to install Thoth on a Windows machine is to download the zip file,
double click on it to bring up the WinZip extraction tool, then click on the
extract button and save the Thoth files in a directory of your choice (e.g., C:\Thoth).

Normally, the user will double click on the Thoth.exe binary
executable to run Thoth, which is located in the installation
directory. The user can create a shortcut to Thoth.exe
and place it on the desktop for convenience in running the software
each time. This is the preferred method of running Thoth, and
requires no additional installation steps (as the runtime environment
and Java location is fully determined Thoth.exe).

If you plan to run Thoth.bat instead of Thoth.exe as an
alternate means of launching Thoth, you must set up the environment
for Thoth, and this is described further below in this section.

System requirements for Thoth: you must have java installed (version 1.6.1_65 or
greater). To find this out, type the following command in a Command-Prompt
window:

If your java version is less than 1.6.1_65, you must first download and
install the JDK from www.sun.com.

Now, you need to set up your environment (only if you will run
Thoth.bat instead of Thoth.exe).
Add the installation subdirectory to your path using the following steps:

Bring up the following menu:

Start > Control Panel > System > Advanced > Environment Variables

Under "System variables", look for the "Path" variable, click on it,
then hit the "Edit" button, and then add

;C:\Thoth\Thoth_v5.2

to its current setting (assuming that is where you installed the Thoth package).
Note the use of the beginning semi-colon delimiter and backslashes ("\")
in the path.

Under "User variables for Administrator", hit the "New" button to add
the following required variable:

Variable Name: THOTH_HOME
Variable Setting: C:\Thoth\Thoth_v5.2

Under "User variables for Administrator", hit the "New" button to add
the following required variable:

Variable Name: THOTH_ARCH
Variable Setting: WIN

Execution instructions:

You can run Thoth simply by double-clicking on the "Thoth.exe" file
in a Windows Explorer window.

You can also run Thoth by double-clicking on the Windows batch file "Thoth.bat"
in a Windows Explorer window (this is not recommended as the normal
runtime method, but can be useful if more memory needs to be allocated
by increasing the memory parameters in Thoth.bat).

You can also run Thoth from either a Command-Prompt window or a Cygwin window:

From a Command-Prompt window:

Thoth.bat

From a Cygwin window:

source Thoth.csh

It is also possible to run Thoth from a C shell or Korn shell window
(provided that you have the shell of interest installed),
but you must first take care to set up the environment properly.

Finally, it is noted that the Windows file system uses the backslash
character (\) to delimit a directory/filename tree. Since Java uses
the backslash character as an escape charactor, a double backslash
must be used as the delimeter on Windows in Java input files.
In the example thoth.run.properties
file above, which is set up for UNIX-type file systems, the change in
the database URL for Windows would look something like the following:

databaseUrl2=jdbc:sqlite:C:\\Databases\\russ.db

which indicates the SQLite database russ.db is located on the C: drive at