

  A User's Guide to the Batch Request Format of CATS


The query form has to begin with the keyword "CATS" at the beginning of
a line and to finish with the line starting "CATS END".  Each line is
interpreted as a command unless it starts with a '%' symbol, which
denotes a comment.  Each line may contain several commands with their
arguments, and may be separated by either space(s), a tabulation,
a comma, '=' (equal sign) or carriage return <CR>.  An exception to
this rule is the command 'SOURCES' indicating the beginning of a table
of source parameters to be queried. This command must be the last or
single on a line.

Similarly, the table of sources is terminated by a line starting with
any valid command. Therefore it is forbidden to use a sequence
of symbols as a name prefix of a source inside of a table, which
at the same time also forms a standard command.

The default search window is a circle. If the parameter "BOX" is set
after a comma, the search will be done in a rectangular box.
The units of the circle radius or the box side can be following
(written as) :  sec or arcsec (default), min or arcmin,
a symbol ' (arcmin)  or a symbol " (arcsec).
All these units are angular (not temporal).

The formats of window size can be following:
 window box x=12",y=3.2'      - box of size 12arcsec x 3.2arcmin  (RA x DEC)
 window box 3'                - box of size 3' x 3'
 window circle 3'             - circle with radius of 3'
 window ellipse x=15",y=3'    - ellipse with half-axes 15arcsec and 3arcmin

All commands are case-insensitive.

General commands:
=============================================================================
     HELP                       - Get this document and List Catalogs-Names
-----------------------------------------------------------------------------
     CATS <argument>            - Type of search

     arguments:
     (default)  SELECT          - Selection by parameters (e.g. by RA)
                MATCHing        - Find counterpart
                END             -\
                STOP            -  End of input
                FINISH          -/
                LIST <argument> - List of catalogs

                arguments:            (Only the first character is enough)
                (default)  All        - All available catalogs
                           Radio      - All radio catalogs
                           Infra-red  - All catalogs of Infra-Red sources
                           Objects    - Catalogs of mixed or optical objects
                           X-ray      - X-Ray catalogs

-----------------------------------------------------------------------------
     OUTput <arglist>           - Type of result output:

     arguments:
                INITIAL         -\
                NATIVE          -  Native format of catalogs string
     (default)  TABLE           -  Formatted table
                FITS            -  FITS-format

     (default)  EQUATORIAL      - Table of equatorial coordinates of sources
                GALACTIC        - Table of galactic coordinates of sources

     (default)  SORT            - Enable to sort by Right Ascension order
                FSORT           - Enable to sort by Frequency order
                NOSORT          - Disable to sort

                COMPRESS        -\
     (default)  GZIP            - Compress output file with gzip-programm
                ZIP             -/
                NOCOMPRESS      -\
                NOGZIP          - Disable to compress
                NOZIP           -/

     (default)  UUENCODE        - Use "uuencode" before mailing
                MIME            -       "mmencode" with base64
                SHIP            -   or   "ship"

                SIZE <value>    - Maximum size of file for output,
                                   value in Kbytes
     default value: 250K

                NAME <value>    - User defined output file name for uuencode,
                                  value - character string without any blanks.
----------------------------------------------------------------------------
     EPOCH <value>              - Equinox of coordinates
     EQUINOX <value>            -/
     value: integer

     (default) 1950
----------------------------------------------------------------------------
     CATALOGs <arglist>          - Types or Names of select catalogs:

     arguments:                  (Only the first characters is enough)

     (default)  All              - All available catalogs
                Radio            - All radio catalogs
                Infra-red        - All catalogs of Infra-Red sources
                Objects          - Catalogs of mixed or optical objects
                X-ray            - X-Ray catalogs
        or      <list_of_Catalog_Names>

----------------------------------------------------------------------------
     RA <<argument value> <argument value>>  - Right ascension limits

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/
     (default)  CENTER

     possible format values:  12h35m54s or 12 35 54.0 or 12:35:54 or 12h35'54"
     or float format on hours:  12.583
-----------------------------------------------------------------------------
     DEClination <<argument value> <argument value>> -  Declination limits

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/
     (default)  CENTER

     possible format values:  12d35m54s or 12 35 54.0 or 12:35:54 or 12d35'54"
     or float format on degrees:  12.583
-----------------------------------------------------------------------------
     GLON <<argument value> <argument value>> -  Galactic longitude limits

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/
     (default)  CENTER
-----------------------------------------------------------------------------
     GLAT <<argument value> <argument value>> -  Galactic latitude limits

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/
     (default)  CENTER

     possible format values:  12d35m54s or 12 35 54.0 or 12:35:54 or 12d35'54"
     or float format on degrees:  12.583
----------------------------------------------------------------------------
     FLUX  <<argument value> <argument value>>  Flux density limits in mJy

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/

     value: float
     (default)  nolimits
-----------------------------------------------------------------------------
     SPIndex <<argument value> <argument value>> - Spectral index limits

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/

     value: float
     (default)  nolimits
----------------------------------------------------------------------------
     FREQuency <<argument value> <argument value>> - Frequency limits in MHz

     arguments:
                MIN               -\ Minimum value
                 >                -/
                MAX               -\ Maximum value
                 <                -/

     value: float
     (default)  nolimits
----------------------------------------------------------------------------
     WINDOW <<form> <<[argument] value> <[argument] value>>> - Search window
                                                          (Only for matching)
     forms:
     (default)   CIRCLE           - Circle (only one value is permitted)
		 BOX              - Box     with half-sizes
                 ELLIPSE          - Ellipse with half-axes

     arguments:
		 X                - Radius (or half size of BOX) along RA
		 Y                - Radius (or half size of BOX) along DEC

     value: float
     possible format of arcmin and arcsec values:
                                             35' or 35.0m  or 5.4" or 54s
----------------------------------------------------------------------------
     SOURCEs:                     - Beginning of sources list
                                           (Only for matching)
     <name1 values>
     <name2 values>
     ...
     <nameN values>

%   An example of sources Table:
%
object_1  02h02m01.2s 31d47m15   1950
object_2  12 35 54    13 47 15   1950
object_3  12:35:54    13:47:15   2000
object_4  123.45678  -5.4321     2000
%
%
   The name must not have any blanks.
Length of string must less of 80 characters.
If the values of RA / DEC in a row in angular degrees, the presence
of the last column (equinox) is mandatory (the row with "object_4").
In the old notations 1950 be implied as default.
-----------------------------------------------------------------------------
     LOG   <argument>           - Switch to Log:

     arguments:
     (default)  ON              - Include full protocol to Log-Mail
                OFF             - Log-Mail with syntax report only
============================================================================

   The resulting output is provided in the same formats as in the
other forms of access to CATS, namely:
the usual table format, the FITS TABLE format, and PostsScript for figures.
All of them may be delivered in compressed or non-compressed forms.
A binary format of output data (e.g. when compression was requested) is
first transformed to ASCII by one of the standard UNIX convertors which may
be selected by the user (uuencode, mime or ship) and then
sent to the user's address with the operations report.
  It is possible to specify a maximum size of an email returned to the user.
When errors occur, the report consists of a protocol of the automatic analyzer
of the requested operations, including instructions with syntax rules for the
CATS batch request via e-mail.

  To avoid infinite email loops, e.g. when illegal return addresses
were given, or when a reply is impossible, requests will not be processed
for "users" with names uucp, root, Mailer-Daemon, etc.

1) A simple example of the mail letter with the 'selection' task:

mail -s "" cats@sao.ru

cats select
 ra min=12:30 max=12:40:15.
 dec > 0 < 5' 46"
 catalogs r epoch=1950  flux > 0.5
 out ship, size=50
cats end

2) A simple example of the mail letter with the 'matching' task:

mail -s "" cats@sao.ru

cats match catalogs a
 window box x=30" y=20'
 sources:
 s1 02:02:00    +31:23:16   1950
 s2 02:23:10     34:03:00   1950
 s3 21:26:33.9  -18:34:33.0 1950
cats end
