Next: The SX Query Language
Up: The SX Online Manual
Previous: Introduction and Overview
Subsections
If you have UPD, the sxQT can be activated by simply typing 'setup sxQT' in
the csh or tcsh. If you have to install it manually, there is a README file
included with it that explains all the details.
The sxQT may be installed in a central location since every user will
have their own configuration files saved in their home directory, so
there is no need to install sxQT for every user separately.
If you invoke the sxQT with an invalid command line switch, you get the message
Usage: sxQT [-nosxwm] [-version]
-nosxwm : do not use the sxQT Window Manager
-version : print the current QT version
The -version switch just prints the current version of the Query
Tool and exits. If you invoke the sxQT with the -nosxwm switch,
all windows will be displayed using your current window manager and no
main sxQT canvas window will be present.
When the sxQT is started up, it will first display the main window that serves
as a canvas for other windows that the user may open. This provides a
self-contained windowing environment that allows you to put all the SX windows
away with one click, and avoids the possibility of losing any of the SX
windows behind other windows. As mentioned above, you may choose to use your
own windowing environment for the SX if you don't like this setup.
By default, a user authentication or login window for the default SX server is
opened within the canvas for convenience so you can immediately connect to the
server and run queries. If you invoke the sxQT for the very first time, you'll
get an error message stating that no configuration files have been found, but
that a new one has been created. You can dismiss this message by clicking
OK and continue. This message will not be displayed again (unless your .sx
configuration files have been removed from your home directory).
Figure:
The sxQT main window with default login window within.
|
In the title of the sxQT you can see the current version you are using.
The main window has four menus:
- Connect
- Open new sessions to other servers or the same server
that you have connected to at startup, enabling you to submit several
queries in parallel. Also, you can set basic configurations here if
you were to register a new service. And, last but not least, the Quit
option is here to terminate sxQT.
- Config
- There is only one item in this menu : Options...
. The options you can set here are described in the Options section below.
- Window
- The Window menu displays a list of your current sessions.
Selecting one of them will make that the active window and bring it to the
front.
- Help
- Various help topics can be accessed through this menu
(including this document). The help is displayed in HTML in a netscape window.
The login window prompts you for username and password. The last
user's name who has used the sxQT from your home directory is
displayed, so you can usually just hit Enter for username. The password you
need to enter is the one you were issued by Fermilab. Contact your
local data guru to obtain a password if you don't have one yet. See
the introduction for more details.
The Login window has a pulldown menu at the bottom for selecting the
current Server Site. There are several sites listed on it currently,
with Fermilab being the default selection. You can change your site
selection before logging in using this menu. You can log in to several
sites simultaneously by invoking the Connect..New Connection menu item.
Once the username+password information is entered, i.e. you hit return
after entering your password, the sxQT sends the information to the
Query Agent which performs the authentication check locally at the
server site. This allows authorized SX users to login and use the QT
from any remote system that has the Query Tool installed. To ensure
secure login, no passwords are actually transmitted over the network.
Upon successful authentication and login, the login window will
disappear and be replaced by the sxQT query window.
If the login is unsuccessful after several attempts or if there is
some other problem, the login process can be aborted, and the window
closed, by simply clicking on the SDSS logo on the left side or on the
close window icon (X) in the login window's title.
If there is an error at login, it will usually be either an invalid
username or password, or that the server is not available. Try choosing
another server if the problem persists. See below for what to do if the server
is not available, and the procedure for reporting problems (including bugs).
Figure:
sxQT query window after login.
|
Upon successful login the query window will pop up. The title-bar of the query
window shows which server it is connected to. The query window has
the following menu items:
- File
- Here you have the standard file manipulation options like
start a new query, load, save, save under another name, insert and
reload query files. The query window can be closed by invoking the Close
command from this menu. The last 6 queries that have been opened are
displayed at the end of the menu and can be reopened quickly using this menu.
All the example files may be accessed through the fast links provided here.
- Edit
- Standard text editor options are available here like undo, cut,
copy and paste, as well as goto line, find and replace functions.
- Tools
- There are two tools that extend the capabilities of the QT,
the Match data file and the OID list from data file tools.
They are described in greater detail below.
- Output
- Allow selection of a local or remote output file, as
well as a remote socket for output. A local file resides on the file
system on the machine where you run your sxQT. A remote file is
created on the server host (e.g. Fermilab)'s file system. The remote
socket can be specified by the host name and port number of the machine,
and it is required that actually there is a listener on that socket.
- Server
- The Server menu allows you to monitor the server connection. You
can Check the server connection, and if it is lost for any reason,
use the Reconnect selection to reestablish the server connection.
You can also force a Disconnect from the server or get the CVS version
number for that server using Get Server Version.
- Help
- This is the same help menu as in the main window. The help is so important
that we felt it should be available in every window.
There is a toolbar below the menu bar that includes the action buttons
to load, edit and run a query, and interaction with the current server.
The current query file name also appears to the right of the
toolbar. The toolbar has the following items:
- New Query - clears the text window for a new
query. If the current query has not been saved, you are prompted to save
it.
- Load Query - loads a query from a file
in your default directory. A file selection dialog pops up.
- Save Query - saves the current query to
the current file, or if no file has been named, a file selection dialog pops
up to allow you to specify which file to save to.
- Cut - cut the selected text from the
text window and save it in a buffer.
- Copy - copy the selected text from the
text window and save it in a buffer.
- Paste - insert the text saved with a cut
or copy into the text window at the current location.
- Undo - undoes the last edit operation.
This command is not robust at present and has a limited memory.
- Check Syntax/Analyze Query - submits the
query to the server for analysis. The server performs a syntax check and if
there is no syntax error, returns a rough cost prediction for the query. The status display changes to WAITING.
- Launch Query - launches the query
execution. If no analysis has been done prior to launching, an abbreviated
(and often wrong!) cost prediction is returned before the query starts running.
The status display changes to RUNNING.
- Pause
(Suspend/Resume) Query - suspends the query execution when pressed once, and
resumes it when pressed again. The status display changes to SUSPENDED
while the query is paused.
- Stop/Abort Query -
aborts the current query. If the query is waiting to be launched, it is
deleted and the status immediately changes to IDLE. If the query is
active (running), then the status display first changes to ABORTING and
then to IDLE when the abort operation is completed. This can take a
few seconds for a complex query, especially if there is output that needs to
be emptied from the stack.
- Server Connection (available v2.0.1) - The symbol on this button is green when
the server connection is up, and it automatically turns to red
(
)
if the connection is broken for any reason. If you click on it when it is
green, it tests the server connection and displays a message accordingly. If
you click on this button when it is red (connection down), the sxQT attempts
to reestablish the server connection and the status changes to green again if
successful.
A large text window for entering the query in the SXQL query language
appears below the menu and toolbars.
An information bar immediately below the textedit window that shows
the current output file/target selection (also whether local or remote
or socket), and query progress information like the number of minutes
and seconds that have elapsed since the query was launched, and the
number objects returned by the query so far, and a text status
indicator that shows the current state of the query (RUNNING,
ABORTING, WAITING, SUSPENDED or IDLE). The status field also changes
color to highlight the status change.
At the bottom there is a progress bar that shows the percentage of the
query search that has been completed so far.
If a query has been submitted for either syntax checking or launch, an
information subwindow will pop up. If the Syntax-check button was used,
the cost prediction information is detailed and more accurate. If the Launch button was used, an abbreviated analysis without a reliable
cost-prediction is performed and displayed. The query analysis and
cost-prediction appear on the left of this subwindow, and on the right a
scrolling output preview window shows the last few lines of the query output
as it comes in. This output preview can be turned on or off using the Options menu. If preview is turned off, the preview window remains blank as
the query executes even though the count of objects returned by the query is
updated as usual.
Figure:
sxQT query window appearance when a query is in progress (about 25% done)
|
There are 2 ways to build a query:
- Load it from an existing file using the Load selection
from the File menu or by pressing the load button in the menu bar.
You can load the last 6 queries directly through their names in the File menu.
- Enter a new query by typing it in in the main window.
Files containing SXQL queries must have the ".sxql" extension, and the
sxQT looks for them in the default directory that can be set using the
Config menu. Once created, a query remains in the window until
replaced by another query, and can be resubmitted.
Queries may have comments in them. There are three comment characters
accepted by the sxQT, '#' '//' and '-' . These can be put anywhere
on the line and text following these characters will be ignored upon
query submission.
The directory that contains the sxQT application also contains a few sample
queries in the ``examples'' subdirectory.
These files are names queryN.sxql, where N
is the number of the sample query. This probably won't be your default
query directory, but you can change directory to it using the Options
selection in the Config menu. You won't be able to write or modify
the files in this directory, but you can load the sample queries directly
and run them. Most of them have comments included in them describing what they
do.
Once a query has been entered, it can be saved to a file by choosing
Save or Save as from the File menu or by clicking on
the Save button at the tool bar. If requested, enter the
filename.
A query can be submitted by pressing either the check or submit
buttons. If there is a selection (text has been highlighted), only the
selection will be sent to the server. This enables you to have several
queries in each file and to select them as you want by highlighting the
query to be selected.
If you don't have an active selection, the content of the whole text
window will be sent.
If there is a weird syntax error message, maybe you have a selection
that you have forgotten about. At any rate, the cursor should jump to
the location of the error.
A query is checked for syntax and a cost prediction estimate will be
returned if the button is pressed on the
tool bar. After syntax error messages the cursor should jump to the
position where the error has occured.
The Query Cost predicition window will pop up and the state of the
window will change into WAITING. The cost prediction is a
summary of how many objects the query needs to scan and how much time
it will take. The other information available is the number of DBs,
the number of containers and the number of objects that this query
will touch. This is not necessarily the number of objects returned by the query, but it does affect the time required to
execute the query. Time estimation may be off for some cases, usually
the query actually takes less time than predicted.
To start the query, you need to hit the button. The
query window status switches to RUNNING. To abort a query at any time,
hit the button and
the status will change back to IDLE after the query is aborted. This
may take a few seconds (see ``Aborting Queries'' section below).
It is possible to bypass the syntax-check and query analysis and launch the
query immediately by clicking on the
button directly
instead of first using the
button.
Syntax errors will be reported of course and there will be some
cost prediction, altough an incomplete and less detailed one.
The query window status switches to RUNNING.
Once a query has been started and the state is RUNNING, it can
be aborted using the button. A confirmation
window will pop up before the abort is actually issued (you can use
the Options selection in the Config menu to stop this
confirmation from appearing every time). It may take a few seconds
or more for the abort to be completed because output pending on the
stack must be flushed before the query can be deleted. The status
will say ABORTING as long as the abort is in progress, and will
return to IDLE when the abort is completed.
The results of a query can be directed back to a target of your
choice. The targets can be set through the Output menu. The
available targets are
- local
- A local file, usually a .tbl file with the same base name
as your query. If you did not give a name to your query yet and hit
the launch button, you will be asked for an output file name.
There is a preview window just next to the cost prediction that will
show the last 10 lines of output saved to the local file.
This is only available for local output.
- remote
- A remote file on the server. Generally, a remote file
will cause the query to be completed faster because the query output
is not sent over the network but written to a file local to the query
agent (sxServer). However, care must be taken to ensure that very
large output files are not created at the server site unless there is
adequate disk space available.
- socket
- A remote socket given by a hostname and a port
number. This can be the address of an Analysis Engine to wait for and
analyze the data as soon as it comes through the net.
Currently only ASCII-format output is possible. In the future, binary/FITS
output formats will be supported.
If the same output file is used for successive queries, you will be
asked for confirmation if you want to overwrite the output file or not.
This feature can be turned off or on using the Options selection
in the Config menu (there is a "Allow output file to be overwritten"
parameter).
You always see whether the connection to the server is still alive by
looking at the rightmost button on the tool bar. If it is a green line
, you have an active connection. If you
lose connection, you're notified by an error message and the symbol
turns red with a break in the middle
By clicking on this button, you either check the connection (you'll
get an OK message if it is ok) or you can reconnect if the connection
has been lost.
The Server menu also allows you to check whether the server connection
is still operational or not. If the connection to the server is lost, then
you can reconnect using the appropriate selection too.
Resubmitting the query will also attempt to reconnect if connection
has been lost.
The following options can be set in the Config..Options menu:
- Default Query Directory
- The default directory to read queries
from. The behaviour of the directory dialog box (for loading and
saving files) is to always show the last visited directory, but at
startup this directory will be displayed).
- Default Output Directory
- The default directory to put your
output files to (which might get quite large.)
- Confirm Abort Query
- Query Abortion requires confirmation. You
can switch the confirmation window off here, pushing the STOP
button will abort your query immediately.
- Allow Output File to be Overwritten
- If you don't set the output
file, a default filename is found (the query file name with .tbl
extension). If this option is turned off, you will be asked for
confirmation if the output file is to be overwritten every time you
submit a query.
- Preview Query Output
- Enable/disable the preview window which
shows the last dozen results from the server (if the output target is
a local file.)
- Get Documentation from WWW
- Toggles between the WWW
documentation and the local documentation at $SXQT_DIR/doc/www. The web documentation should be the most recent
one, but if you have a bad connection, you might want to read locally.
- Font type
- Select the font to use in the query display window, Courier is a fixed width font, Helvetica is variable width.
- Font size
- Set the font size for your screen.
For the changes to take effect, you need to push the Set button.
Figure:
sxQT Copnfiguration Window
|
The first thing to do when you suspect something is hanging is to check the
server connection. It may be down. If so, then you should abort the query
and resubmit (which will automatically reconnect you to the server), or use
Connect from the Server menu to reestablish the connection. If
the server query processing is actually hung (due to a bug), then the best
thing to do is to use the server disconnect option from the Server menu, or
(available v2.1) use the disconnect(reconnect) button from the toolbar. This
will cause the sxQT to attempt to kill the current server session, after which
you can reconnect to the server if you wish, or quit the sxQT entirely by
selecting the Quit option from the top-level Connect menu.
Again, first check the server connection. If it says the connection is OK,
then you should proceed in the same way as described above when the query
abort hangs.
When the SX server crashes or goes down for any reason, there is a script that
monitors the server all the time and restarts it within 30 seconds if it
dies. So you should retry the connection in a few seconds, and if after 30
seconds the server is still down, then either the script that restarts it is
not running or sdssdp4 is down. In that case, send email to
sxadmin@sdssdp4.fnal.gov.
If you are sure that it is your query that causes termination of the
connection (i.e. you crash the server), please use the SDSS bug report
system to report the bug (see below).
Initially, bug reporting should be coordinated through the SDSS data
gurus so that the same bugs are not repeatedly reported by different
people. Bug reporting for SX bugs has been incorporated into the SDSS
Bug Reporting system ,the SDSS Bug Database
at
http://www.astro.princeton.edu:81/cgi-bin/gnatsweb.pl
After logging in, use the Create button to create a new bug
report. Select 'sx' under category and enter the fields as you see
fit.
There are 3 categories for SX bugs listed there: sx, sx-schema and
sx-server. Select the one you think is closest to the bug you are
experiencing and fill out the report. If the error occurs during
analysis phase, select sx, if it is a random crash in the middle of
the run, select sx-server. If unsure, select sx.
The advantage of using the bug report system is that you'll get notified
if the bug has been fixed automatically and the visibility is much higher.
If you have a problem please try to find every information about it in
the documentation and online at http://www.sdss.jhu.edu/
If you still require help or assistance, please contact Peter Kunszt
at
kunszt@pha.jhu.edu
or Ani Thakar at thakar@pha.jhu.edu
- Syntax error at line..
- The way you use the SXQL syntax is not valid
there may be many reasons for it. The following are the most common:
- Logical operator ordering.
- Mismatched parenthesis.
- Forgotten keyword (SELECT FROM WHERE)
- Macro usage incorrect (PROX, POLY, etc)
- Invalid name at..
- The variable name has not been
recognized. Please look it up under Help..Classes.
- File filename does not exist!
- The specified file (for loading
for example) is nonexistent.
- You HAVE to set an output file
- At this point, you need to
specify an output file name.
- ProxList doesn't support remote file output.
- The proxlist
server does not support the remote output option. Choose a file
to save your results in.
- ProxList server only handles MATCHLIST queries.
- Please
use the
Match File... from the Tools menu. There is no #MATCHLIST line in your query. To generate one, use the Tools...Match File menu.
- No query to submit
- The query you submitted is empty. Check for
accidentally highlighted sections if you're sure it's not.
- Suspend/Resume Query gave an error! ..
- There has been an error at suspend/resume. Try again.
- Query Aborted, output socket lost
- If you specified a remote
socket for output, and the output socket connection has been lost,
this is the error message you get. You need to restart the output
connection and your query.
- You need to be connected to the ProxList server.
- You tried a
nonprox query on the ProxList server. Reconnect to a proper server if
you connected to ProxList accidentally.
- No such path/file, ..
- The file dialog box does not find the
specified file.
- User unknown
- You misspelled your username
- FIRST login: change password
- You are required to
change your password that has been assigned to you by the
administrator. She should've told you how.
- Incorrect password, please reenter
- The authentication failed, please reenter your password
- Unable to connect to Port Daemon - Check configuration
- The port
daemon given in the site file is not up or is not configured
correctly. Please contact the administrator of the site you tried to
connect to or try to connect to another server.
- Error from Port Daemon: LOOKUP ... Cannot find ...
- The name of
the server is not listed in the port daemon. The server
might be down, or your configuration is false. Please contact the
administrator for the correct values.
- Something went wrong. Try Again
- Some other error has been returned. This usually is a communication
glitch that happens sometimes. Just reenter your name/password/server.
If it persists, restart the sxQT. If it still persists, contact administrator.
- Too many open queries. Close one before starting new
- There is a
limit to how many simultaneous query window you may have.
- No such directory
- There is no directory with the name you have
specified under the 'Default Query Directory' option.
- Invalid configuration file deleted
- The Port Daemon
configuration file was invalid and has been deleted / recreated with
default values.
- Please fill all values
- You have to specify everything in the
Port Daemon configuration fields.
- We need the configuration.
- There has to be some port daemon
info.. don't leave the fields blank.
- Site configuration file not found
- The site list that comes with
the sxQT could not be located. Check your installation and eventually
reinstall.
- Site file .sxSites is corrupt; line1 == ..
- The site list file
is corrupted, edit and correct or reinstall sxQT.
- site file not found, creating new one ...
- This error message
appears at the very first startup of the sxQT (or if you delete the
.sxSite file from your home directory), it only means that from
now on you have a .sxSite file in your home directory. No action
needs to be taken.
- No netscape in your path, please correct
- netscape could not be
started. Either you did not install it or it is not in your
path. Netscape is used as the help browser.
- Connection to Server Lost!
- The server connection has been lost,
possibly due to a fatal error at the server site. You can try to
reconnect and resubmit your query.
- Connection to server failed. It might be down.
- If it persists,
contact administrator The server is not responding. If there is a
crash, the server restarts itself automatically whithin a minute. If
you cannot log in for, say, more than 10 minutes, drop an email to
sxadmin@sdssdp4.fnal.gov.
- Connection to server failed. Reason given:..
- The sever refused
connection with an error message, usually an authentication problem.
If the problem persists (even after restarting the sxQT), contact
sxadmin@sdssdp4.fnal.gov.
Next: The SX Query Language
Up: The SX Online Manual
Previous: Introduction and Overview
© The Johns Hopkins University 2000
Generated by Ani Thakar at 2001-05-31
