STARCAT Commands

aBlankLine

Insert a blank line within the output file.

This option allows you to specify the list of fields to be collected in the ASCII file. The file name is defaulted to the name of the catalogue with the extension is .lis. These defaults can be overwritten. Each selected field will represent one column in this file. The name of each field will become the name of the corresponding column. The columns are aligned and separated by the | character. If you choose and file name with an exntension of .tab then the output columns will be TAB separated.

To stop the output, use ASCII_out or CloseFiles.

Back

Move back one catalogue or menu in the history list.

BackFind

To review the records previously retrieved from the database. Warning, STARCAT buffers these retrieved records and although the buffer size is large, it is limited.

Examples

Compare two or more adjacent records by toggling between them.
Scanning until a record of interest is spotted, then stopping the scan and BackFind to it.

Backpage

Used to display the previous page of records in List display format.

Backrec

Position the record pointer back one record in the page. The pointer will not go past the first item on the page.

Catalogue

Selects a new menu or a new catalogue. This function is context sensitive. For example, once in hst, users could directly type the name of the catalogue to.

If you get a message like:

    Catalog entry is ambiguous or does not exist - science

it means that there one of three things.

There is no such catalogue; check the spelling of the name entered.
There is more than one catalogue of the same name among the different archives; specify the desired archive by adding @<archive_name>.
Because STARCAT does name completion, the name entered does not provide a unique entry in the list of catalogues (for example, Catalogue exp has 2 entries: exp@hst and exposures@cfht); enter a fully qualified name.

Examples

Catalogue cfht, load the CFHT menu.
Catalogue science@hst, load the HST science screen.
Catalogue stellar@astrocat, load the stellar submenu of astrocat.

Center

This feature allows to query a catalogue by specifying a center coordinate and a searching radius. Several coordinate systems are available and for some, an equinox can be specified. In addition, one can enter any name for the particular object you are interested in and STARCAT will query the SIMBAD database for the coordinates, which will then be used for STARCAT query.

A small window appears where one can change.

The coordinate system and equinox
The central position ( both alpha AND delta need to be specified, the sign of delta is mandatory) and the radius or
The SIMBAD name.

The entry is carried out like any other STARCAT interactive qualification using arrow keys and terminated by CTRL Z.

Choosing the Coordinate System

Type either G, S, E, B or J to use the proper coordinate definition:

G for galactic coordinates. Position is assumed to be in degrees for both longitute and latitude.
S for supergalactic coordinates. Position is assumed to be in degrees for both longitute and latitude.
E for ecliptic coordinates. The equinox can also be specified in this case. The default assumed for the equinox is 2000. Position is assumed to be in degrees for both longitute and latitude.
B for Equatorial coordinates based on FK4. The equinox can also be specified in this case. The default assumed for the equinox is the catalogue's. Position is assumed to be in degrees for the declination and hour.decimal or hour minutes [seconds] for the right ascension.
J (Default) for Equatorial coordinates based on FK5. The equinox can also be specified in this case. The default assumed for the equinox is the catalogue's. Position is assumed to be in degrees for the declination and hour.decimal or hour minutes [seconds] for the right ascension.

Specifying Positions

Depending upon the coordinate system chosen, the position specified will be either a longitude and latitude or a right ascension and declination.

The syntax to specify the position can be either

longitude and latitude, where both are expressed in degrees.
Right Ascension and Declinationare expressed respectively in hours and degrees.

The sign between the two expressions is mandatory. Moreover, degrees and hours can be expressed in either decimal or sexagesimal form.

Using SIMBAD to Get Coordinates

If you want to search by position for an object but you don't have the coordinates handy you can query the SIMBAD database for the coordinates. Instead of entering the central position simply enter the name of the object in the SIMBAD Name field. STARCAT will then ask SIMBAD for the coordinates of this object and use these coordinates for the query.

Examples

Retrieve all objects located around a point whose Galactic coordinates are 90 degrees of longitude and 4.78 degrees of latitude in a circle of 1 degree of diameter:
Central Position : G90+4.78
Radius (Degrees) : 0 30
Retrieve all objects around supergalactic pole in a circle of 3 degrees 30 minutes:
Central Position : S0+90.
Radius (Degrees) : 3.5
Retrieve all objects in the neighbourhood of the Orion Nebulae. We suppose you know only the 1950 equatorial coordinates.
Central Position : B1950 5 33 30 -5 20
Radius (Degrees) : .5

This example could also have been type differently (in prompt mode):
Central Position : 5 33 30 -5.6666 B1950
Radius (Degrees) : 0 30
Retrieve entries within a 10 arcminute radius of the Red rectangle.
SIMBAD Name: Red Rectangle
Radius (Degrees): 0 10

When a BackFind, FindNext, List or a Scan is executed, the distance to the center is displayed for each record retrieved.

Change Pswd

This command allows you to change your archive password. Please note that the archive password are site dependant and you must register to CADC or register to ESO/ST-ECF before to submit requests for off-line data.

Closefiles

Close the current opened output file. This can be useful if you want to open a new one without having to leave the current catalogue.

Note that the output files are automatically closed when leaving the catalogue.

Doc

The STARCAT documentation system is accessed via WWW using NCSA Mosaic or University of Kansas lynx.

The documentation system is context senstive, i.e., when you ask for documentation using the Doc command you will receive documentation relevent to your current context.

Exit

There are 4 different Exit commands.

Exit or CTRL/z from a STARCAT menu terminate the program.
Exit from a catalogue, return the user to the previous catalogue or menu.
Exit from Utilities return the user to the previous menu.
Exit from List or Output return the user to the catalogue.

FindNext

Fetch the next record matching your qualifications. The actual number of records retrieved so far is displayed in the left corner of the title window. When all possible records satisfying the conditions have been retrieved, the total number of records retreived is displayed. Subsequent use of that command after the end of the search will display the following error message at the bottom of the screen: No more data.

FITSTable

This option allows you to specify the list of fields to be collected in a FITS ASCII table file. The file name is defaulted to the name of the catalogue with the extension is .fits. The default can be overwritten.

To stop the output, use FITSTable or CloseFiles.

Forward

Move forward one catalogue or menu in the history list.

Help

Help on the available commands. The help system is accessed via WWW using NCSA Mosaic or University of Kansas lynx.

The help system is context senstive like the Doc command.

Home

Go to the top-level STARCAT menu.

List

An alterntive mode of display catalogue records instead of a single record at a time. The records are displayed in tabular form grouped by pages, where the number of columns displayed is limited by the width of the screen. The user can toggle back to the default catalogue window using Exit. Within the page, the record pointer (a ">" in the leftmost column) will show the current record, i.e. the record you look at when you toggle back.

SelColumns allows the user to select which columns will be displayed in the table.

LaTeX

This option allows you to specify the list of fields to be collected in a LaTeX file after you choose a file name. The file name is defaulted to the name of the catalogue with the extension is .tex. The default can be overwritten.

Mark

This command sends the record displayed on the screen to the STARCAT retrieval tool for inclusion into an eventual archive request.

More about the retrieval tool.

MarkAll

This command is similar to Mark except that all records retrieve (and sitting in the STARCAT retrieval buffer) are sent to the STARCAT retrieval tool for inclusion into an eventual archive request.

More about the retrieval tool.

Menu/Prompt

In Menu mode, the commands are listed at the bottom of the screen and can be selected either by moving the cursor through them and pressing the CR; or by typing the associated key displayed after the command name.

In Prompt mode, commands must be typed. STARCAT has command completion on input allowing the user to type the minimum unique match for a command.

MIDASTable

This option allows you to specify the list of fields to be collected in a MIDAS table file. The file name is defaulted to the name of the catalogue with the extension is .tbl. The default can be overwritten.

The format and unit for each field will be carried along in the MIDAS table if they are known in the database. The name of the field will become the name of the column. Note that all position fields (right-ascension, declination, ...) displayed in the form HH MM SS.[ddd] or DD MM SS.[ddd] will be translated in decimal degrees in the MIDAS table.

N.B. Users are always requested to give the maximum number of records they are planning to retrieve. Records retrieved beyond that number will not be taken into account. A message will be displayed when this number is reached.

To stop the output, use MIDASTable or CloseFiles.

Modquery

Allows one to edit the SQL query generated for retrieving the records from the database.

Edit the SQL text (CTRL-K or CTRL-G displays the on-line editing facilities) and terminate with the <Return> or with CTRL-Z key. Use CTRL-C to remove your changes and to recreate the original query.

Expressions enclosed in parenthesis are allowed - and even advised!

A qualification is written [table].field. The allowed operators are:

the arithmetic + - * / four operators between fields
and, or logical operators
<, <=, =, >, >=, != relational operators
functions abs(num), substring(str, pos, len)
aggregate functions min max sum avg(field).
special sorting can be obtained by specifying by table.field after the where clause.

Example: original query:

Select hr,hd,i,r_a,dec,dm,name,d,var,vmag,bmv,umb,rmi,rvel,n_rvel,pma,pmd,plx,
n_sp,sp,lii,bii,vsini,dmag,sep,comp,ncomp,rem from hr where sp LIKE "[OB]%"

with ModQuery it is possible to append order by vmag desc. This will sort the O and B stars of the HR catalogue so the faintest will appear first.

Please note that the modifications will only be valid for subsequent FindNext or Scan commands. The Unqualify, Restart, Qualify and Center commands will undo the modifications.

Used to display the next page of records in List display format.

NextRec

Position the record pointer to the next record on the page. The pointer will not go beyond the last record on the page.

OutFile

Used to select the type of output file to store records retrieved from the database. This mode allows the user to select columns and format for output.

Plotcat

Provides plotting capabilities for any two numeric fields retrieved from a catalogue. (e.g, right ascension vs declination, date vs temperature, color index vs color index, ...). Warning, STARCAT buffers these retrieved records and although the buffer size is large, it is limited.

Plotting is done in one of three ways:

The user identifies with field is to be used to construct an histogram with a +.
The user identifies which field is to be used to construct a sequence with a Y.
The user identifies which fields are to be used for the X and Y axes (using X and Y.

More than one PlotCat can be executed without having to re-do a Scan. e.g., using different pairs of fields.

PreView

Preview displays the preview data associated with the record displayed in the window. This command is context sensitive and will only be available in the query menu if the current catalogue has associated images or spectra.

For more information about the preview system.

Qualify

Used to qualify fields for database retrieval.

In menu mode the cursor is placed in the first field of the catalogue. To move to the desired field, use the arrow keys. When the cursor is positioned, enter one of the logical operators listed below followed by your qualification. If you do not enter a relational operator, equality is assumed. The qualification can be longer than the underlying field.

When the qualification is complete, leave the field by pressing one arrow key or the return key. The cursor will then go to the next field. If the qualification was improper for the type of field, an error message will be displayed and the cursor will go back to the incorrect input. When all constraints are entered, leave the qualify mode by hitting CTRL Z.

Example

In the ``HR'' catalogue, we can look for all stars of type O or B by doint the following:

Move with arrow keys to the sp field.
Then type =[OB]*.
Exit from Qualify mode with CTRL-Z.
Scan or FindNext to retrieve the matching records.

In prompt mode, field constraints can be entered by typing 4 tokens:

The command name Qualify.
The field name.
A relational operator (see table below).
A value.

In either mode, field qualifiers may be edited individually by using the Delete key to remove characters at the left hand side of the cursor. CTRL-U will remove all the characters at the left hand side of the cursor and CTRL-V will remove all characters at the right-hand side of the cursor. CTRL-A can be used to toggle between insert/replace mode.

All field qualifiers are removed by using Unqualify.

Numeric fields

This table contains the the valid operators for use on numeric fields.

	Operator	In Numeric fields	Example

	=		strict equality (def)	=10
	==		strict equality		==10
	!=		inequality             	!=3
	>=		greater or equal       	>=3
	>		strictly greater       	> 5
	<=		smaller or equal       	<=32
	<		strictly smaller       	<10.3
	..		range of numbers       	1..5
	,		range of values        	1,5,18
	&&,AND		in the same field   	1..5 && !=3
	|,OR		in the same field   	1..5 | 8,10
	[]		N/A
	~		same as =		~2

Alphanumeric field

This table contains the the valid operators for use on alphanumeric fields.

	Operator	In Character fields	Example

	=		allow `wildcarding'	=NGC*3532
	==		look for string as is	==ESO*
	!=		inequality      	!=M 87
	>=		greater or equa 	>= A
	>		strictly greater  	>  M 51
	<=		smaller or equal  	<= B*
	<		strictly smaller  	<  NGC
	..		N/A
	,		N/A
	&&,AND		N/A
	|,OR		N/A
	[]		n alternative chars	=[OBA]*
	~		Ignore case		~sM?tH*

* Replaces 0 to N alphanumeric characters
? Replaces 1 alphanumeric character

Date fields

Date fields use the same numeric field operators described above. The format however is different. Any of the following could be used to formulate a qualification using spaces, / (slash), . (dot) or - (hyphen) as field separators:

	YY or YYYY	year.
	MM 		month number.
	MMM		month name (alphabetic).
	DD		day of the month.
	DDD		day of the year with leading zeros.
	WWW		weekday name (alphabetic).
	hh		hour of the day (00..23)
	mm		minutes
	ss		second

Coordinate fields

Coordinate fields use the same numeric field operators described above. The format however is different:

	HH [MM [SS[.SS]]] [-+]DD [MM [SS[.SS]]]

Be warned that the minimum and maximum precision is catalog dependant. The user will have to experiment until the qualification works.

ReadFile

Take commands from a file. All commands in the file must be Prompt mode type commands, ie., no interactive commands.

Reqtool

Reqtool is the STARCAT retrieval system. It has four functions.

Accumulates datasets marked with the Mark and MarkAll commands.
Allows the user to edit the datasets marked.
Allows the user to submit a request to an archive centre.
Allows the user to browse and edit previously submitted requests.

For more information about the STARCAT retrieval system.

Req Status

This command allows you to get information on submitted request from a specified archive centre when working an ASCII terminal. If you are running on a workstation, use Reqtool for more complete information.

Restart

Rewind the current query to be start. Use FindNext or Scan begin viewing the sequence of records.

This is particularly useful when user wants to know the number of records matching a qualification before executing another command.

Scan

Scan is equivalent to FindNext repeatedly executed until no more records are found. It can be stopped by pressing any key. Scanning can be resumed by selecting Scan again. Viewing records one by one can also be achieved with FindNext, even after an interrupted scan.

Selcolumns

Allow the user to select columns of a catalogue which will be included in the List display.

By default, all of the fields in the catalogue are selected for output. To restrict the number of fields do the following:

C to clear all selected fields.
A to select all the fields again.
X to select the field on which the cursor is located.
spacebar to deselect the field on which the cursor is located.

During the interactive field selection for ASCII output file, a small window will appear on the upper left part of the screen and will inform the user on the current length of each record, taking into account the individual length of each selected field.

In the Prompt mode and in particular for the Readfile command this works somewhat differently. The commands are here:

clear to clear all the fields.
all to select all the fields.
field name to select one field.
field name to deselect one field.

cadc@dao.nrc.ca