
               SDSS Query Tool and SDSS Tools v2.3.18 download
	       ===============================================

This page contains the tarballs for the SDSS Query Tool (sdssQT) and the
SDSS Tools (sdssTools) package. The following files are available:
     sdssQT+Tools.tar.gz - the Query Tool and Tools in one tarball;
     sdssQT.tar.gz              - the SDSS Query Tool (see below);
     sdssTools.tar.gz ;       - the SDSS Tools package (see below).

----------------------------------------------------------------------------

                             The SDSS Query Tool
			     -------------------

Requirements
------------

sdssQT runs on any platform that has tcl/tk version 8.0.  If you don't have
tcl/tk 8, you can download the latest version for your platform from
http://dev.scriptics.com/.  sdssQT consists merely of standard tcl code, no
additional installation is necessary.  Windows is OK (see below), Mac not
tested but should work fine (famous last words!).


Environment
-----------

UNIX:

You need to have the HOME environment variable set to your home directory
and you need  the variable SDSSQT_DIR (or SXGUI_DIR) to point to the sdssQT
directory.
PATH needs to include the directories of

   * wish
   * sdssQT
   * netscape

sdssQT expects the executables 'wish' and 'netscape' to be in the path and
to correspond to the correct versions. To test whether you have these
programs in your path, simply use the 'which' command :

> which netscape

This should give you the path of the executable for netscape, if any. If you
get 'command not found', you should update your PATH environment variable
for it.  sdssQT resides in the sdssQT/bin directory.   So if you decide to
install sdssQT into /usr/local/sdssQT add /usr/local/sdssQT/bin to your
path.


WINDOWS:

For Windows you need to set your following environment variables as
indicated:

 <variable name>                           <action>

      PATH       include the path for the sxQT\bin directory, making sure
                 that you use the DOS "\" NOT the UNIX "/".

       HOME      set this to the directory that the .sxSite and .sxSites
                 files should be written to. In this case use the UNIX "/".

   SDSSQT_DIR    set this directory to where sdssQT is installed.  Again,
                 use the UNIX "/"(e.g. c:/Programs/sdssQT).

The reason for using the back slash ("\") for PATH and forward slash ("/")
for the other two variables is that PATH is interpreted by the Windows OS
whereas HOME and SDSSQT_DIR are interpreted by Tcl/Tk, which does not handle
the back slash by default.

For Windows versions earlier than Windows 2000 set the environment variables
in autoexec.bat

For Windows 2000 or later, do NOT attempt to modify autoexec.bat!  This
could make your Windows OS unusable.  Instead, select the following menu
options:

Start --> Settings --> Control Panel --> System --> Advanced --> Environment
Variables

Remember that you will need to restart Windows after you modify the
environment variables for the changes to take effect.


Installing sdssQT
-----------------

UNIX:

No special installation needed, just copy the sdssQT wherever you want.  If
all environment variables have been updated correctly, just type sdssQT to
run it.

There will be no problem with multiple users running the program since each
user will have his/her configuration files in the directory pointed to by
the $HOME environment variable.


WINDOWS:

Rename bin\sdssQT into bin\sdssQT.tcl and make a shortcut to it on your
desktop.   This way you can simply double-click on it to run.  If you modify
your environment variables, you will need to reboot first (as usual).


FIRST-TIME STARTUP

If you start sdssQT for the first time, the QT generates its local  settings
for you. Each user gets their own '.sx...' files in their home directory.
Then you can proceed to enter your username and password.   For SDSS public
data (such as the EDR), the username/passwd is sdss/sdss or gues/archive.
If you are a collaboration user wishing to access private data, send email
to jen_a@fnal.gov to get your username and password.


FILES

Every user needs the SDSSQT_DIR environment to be set to the sdssQT
directory path.  User customization is saved in the users $HOME directory:

 $HOME/.sxconfig         Configuration options
 $HOME/.sxPDconfig       Port Daemon host/port, server id
 $HOME/.sxSite           Latest site you connected to
 $HOME/.sxSites          Parameters for all currently available


COMMAND-LINE SWITCHES

There are currently two useful command line switches, -nosxwm which will
cause all the windows to be managed by your window manager instead of the
sdssQT canvas (some people like this better...); and -debug which puts the
sdssQT in debug mode and spews verbose debug output to the standard output.


PROBLEMS

The server status can be checked anytime by selecting "Check Connection"
form the Server menu. If you are unsure about the server, check this first.
There are queries that do take long to analyze.

If your query consistently 'disconnects' the server, report the query that
caused it to the bug database. Also, scan it for syntax - you might be able
to fix the problem yourself. Please, do report such queries.  Use the SDSS
bug report system (GNATS) at
http://www.astro.princeton.edu:81/cgi-bin/gnatsweb.pl.

If you get an error message stating that the server is down, "Contact
administrator", please wait for 2 minutes. The Server should be restarted if
it has crashed.  If you are sure that it was your query that has crashed it,
report it through the bug reporting system.

Happy Querying!  More info is available at http://www.sdss.jhu.edu/

----------------------------------------------------------------------------

              Binary and FITS Output from SDSS using sdssTools
	      ------------------------------------------------

The sdssQT provides a way to obtain query output in both ASCII (default) and
binary mode. In order to convert either ASCII or binary output to FITS, you
can redirect the output to one of the SDSS analysis tools available from the
SDSS downloads web page.   The procedure for installing the sdssTools
package and running the utilities available in it is described below.

----------------------------------------------------------------------------

Installing sdssTools
--------------------

  1. In order for everything to compile, you need to set the CC environment
     variable to your ANSI C compiler. Usually, this is already set (cc for
     unix, gcc for linux) just check with echo $CC.

  2. The FITS routines require CFITSIO to be installed. You can get CFITSIO
     from http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html.
     Be sure to set the environment variable CFITSIO_DIR to the directory
     where CFITSIO has been installed. If you don't need the FITS interface,
     just build with the nofits target (see below).

  3. Invoke

          make <platform>

     where <platform> may be any of sdss,linux, solaris, osf, irix. sdss
     will install the makefiles intended to be used with sdssmake, the other
     keywords install the makefiles for the respective platform to be used
     with make.

     There is no reason why sdssTools should not compile on other platforms,
     but these are the platforms for which we have Makefiles. See the src
     and app directories and generate Makefiles for your platform if yours
     is not in the list (and you don't want to use sdssmake.) After that,
     invoke either sdssmake or make. The following targets are accepted:
          all         compile and link everything
          clean     delete .o files, libraries and executables
          nofits    compile and link without the fits dependency


Using sdssTools
---------------

Currently, these are the utilities available in sdssTools/bin after make has
completed:

        sdssAsciiEcho [-f filename] [-p port]

Waits on a port (defaults to 8010) to accept a connection from the SDSS
server. In the sdssQT, the output can be sent to a socket using the
Output..Remote socket.. menu item. Specify your host and port where the
sdssAsciiEcho is running. Every line it receives from the SDSS server are
sent to stdout or to the file if the -f option was specified.

        sdssFitsEcho filename [-p port]

Same as sdssAsciiEcho except that a binary FITS table is created as the
output. CFITSIO needs to be installed for this to work.


Reporting Bugs
--------------

Please use the usual bug reporting system on GNATS to report bugs on
http://www.astro.princeton.edu:81/cgi-bin/gnatsweb.pl

----------------------------------------------------------------------------

Documentation suggestions to:

Dennis Dinge (ddinge@pha.jhu.edu), Ani Thakar (thakar@pha.jhu.edu)
Last updated: Jan 3, 2002

