.help sesame Mar12 votools
.ih
NAME
sesame -- Resolve a target name into a coordinate position
.ih
USAGE
sesame <target>
.ih
PARAMETERS
.ls target
List of objects to be resolved.  Targets may be specified as a
comma-delimited list string or in an @file to resolve multiple targets.  When
the \fIrange\fR parameter is non-null, this will be the root part of the
target name.
.le
.ls range = ""
A range string used to expand the \fItarget\fR parameter to a list of names
to be resolved (e.g. if \fItarget\fR is "ngc" then \fIrange\fR may be
specified as "1-100" to create a list of the first 100 NGC objects).
.le
.ls verbose = yes
Print coordinates to the stdout?  If enabled the sexagesimal coordinates
of the resolved target will be printed to the STDOUT where they may be easily
scanned into variables in a script.  In all cases, the output parameters 
below are updated with the target information once the task has completed.
.le
.ls long = no
Print long-form output to the stdout?  If enabled the target name,
sexagesimal coordinates, position error (in arcsec) and object type are
printed on the output line.
.le
.ls pos = ""
A sesagesimal string of the J2000 RA/Dec position (output).
.le
.ls ra = 0.0
J2000 RA of the object in decimal degrees (output).
.le
.ls dec = 0.0
J2000 Declination of the object in decimal degrees (output).
.le
.ls ra_err = 0.0
Error of the RA position in arcsec (output).
.le
.ls dec_err = 0.0
Error of the Dec position in arcsec (output).
.le
.ls otype = ""
Object type (output).
.le
.ls status = ""
Status return code of the web service (output).
.le

.ih
DESCRIPTION

The \fBSESAME\fR task invokes the Sesame name resolver service from CDS to
convert an object identifier (e.g. catalog name) to an ICRS coordinate pair.
The service will first try to resolve the object using the NED database, and
if not found will use the Simbad database,  the VizieR database is used to 
resolve the coordinates as a final option.  The \fItarget\fR parameter may
be specified as a comma-delimited list or in an @file to resolve multiple
target names.  If the \fIrange\fR parameter is set, it may contain a range
string that will be expanded to append numeric values to the \fItarget\fR
value (e.g. to dynamically create catalog names).

If the \fBverbose\fR parameter is set the ra/dec coords are written to the
STDOUT where they may be easily scanned into script variables.  If the
\fIlong\fR parameter is enabled, all known information about the object is
printed (as name, ra, dec, ra_err, dec_err and object type).

In cases where only a single object is resolved the \fBpos\vR, \fBra\fR,
\fBdec\fR, \fBraw_err\fR, \fBdec_err\fR, \fBotype\fR, and \fBstatus\fR
parameters are updated with the resolved values.  The \fRstatus\fR
parameter will be zero is successful, non-zero is the object could not be
resolved or the service could not be reached.

.ih
EXAMPLES
1. Find the coordinates of M51 (i.e. the dev$pix image):

.nf
  votools> sesame m51
  13:29:55.72 +47:13:53.4

  votools> sesame m51 long+
  m51 13:29:52.69 +47:11:42. 0. 0. Sy

  votools> sesame m51
  votools> lpar sesame
         target = "m51"           Target name to resolve
       (verbose = no)             Print position to stdout?\n
           (pos = "13:29:55.72 +47:13:53.4") Position (sexagesimal string)
            (ra = 202.4821936)    Resolved RA (J2000 decimal degrees)
           (dec = 47.2315089)     Resolved DEC (J2000 decimal degrees)
        (ra_err = 134.)           Error on Resolved RA (arcsec)
       (dec_err = 134.)           Error on Resolved DEC (arcsec)
         (otype = "GPair")        Resolved object type description
        (status = 0)              Resolved DEC (J2000 decimal degrees)
          (mode = "ql")           
.fi


2. Create a local copy of the Messier catalog.

.nf
    votools> for (i=1; i < 100; i=i+1) {
    >>>          printf ("m%d\n", i) | scan (s1)
    >>>          sesame (s1, verb-)
    >>>          printf ("m%d  %s  %s\n", i, sesame.pos, sesame.otype)
    >>>      }

	or

    votools> sesame m range="1-110" long+ | fields STDIN "1-3"
.fi

.ih
REVISIONS
.le
.ih
SEE ALSO
voclient
.endhelp