path: root/vendor/voclient/doc/OLD/vosesame.man

." @(#)vosesame.1 1.0 June-07 MJF
.TH VOSESAME 1 "July 2007" "NVO VO-CLI Project"
.SH NAME
vosesame \- call the Sesame name resolver service
.SH SYNOPSIS
\fBvosesame\fP [\-\fIadefhinstACHT\fP] [\fIfile\fP | \fItarget\fP ] [ ... ]

.SH OPTIONS
The \fIvosesame\fP task accepts the following options:
.TP 8
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.
.TP 8
.B \-q, --quiet
Quiet mode (suppress warning output).
.TP 8
.B \-v, --verbose
Verbose output.  Normally used to print warnings when an object could not be
resolved.
.TP 0
The following flags may be combined as a single option to indicate the
desired output fields.  The order of the flags implies the order of the
output values, e.g. "-dnt" prints the decimal position, name and type in
that order.
.TP 8
.B \-a, --all
Output all available information about the object.
.TP 8
.B \-d, --decimal
Output the position as J2000 decimal degrees.  This is the default output if
no format flags are specified.
.TP 8
.B \-e, --errors
Output the estimated position errors.
.TP 8
.B \-n, --name
Output the object name.
.TP 8
.B \-t, --type
Output the object type.
.TP 8
.B \-s, --sex
Output the position as sexagesimal RA and Dec.

.TP 0
Control Flags:
.TP 8
.B \-c <ra> <dec>  or \-c <ra>,<dec>  or \--coord-<ra>,<dec>
Specify a coordinate to be explicitly used.  If set an RA and DEC are
expected as either the next argument if they are a comma-separated string,
or as the next two arguments.  Values may be input as floating point 
decimal or sexagesimal strings.  Upon receipt, the task will create an
artifical record for the object and output the values requested with the
output flags described above.  Multiple \fI-c\fP options may be specified
may be specified and mixed with object names, user coordinates are processed
before the object names are resolved in the order they occur on the command
line.
.TP 8
.B \-i, --invert
Invert the sense of the search and print only objects which cannot be
resolved to coordinates.
.TP 8
.B \-f, --force
Force the object(s) to be resolved even if it is cached.  This option will
cause the task to call the Sesame service rather than output a previously
cached value, however the result will still be cached unless the VOC_NO_CACHE
environment variable is defined.
.TP 8
.B \-o <name>  or  --output=<name>
Specify the output file.  The default is to write the results to the
standard output.

.TP 0
Formatting Flags:
.TP 8
.B \-A, --ascii
Print the results as a whitespace delimited ascii table.  If an output file
is specified it will have a ".txt" extension appended automatically.
.TP 8
.B \-C, --csv
Print the results as a comma-separated-value (CSV) table.  If an output file
is specified it will have a ".csv" extension appended automatically.
.TP 8
.B \-H, --header
Print a table header.  The table header will be a single line beginning with
a '#' character to indicate a comment, and followed by the name of each 
column in the specified format.
.TP 8
.B \-T, --tsv
Print the results as a tab-separated-value (TSV) table.  If an output file
is specified it will have a ".csv" extension appended automatically.

.SH DESCRIPTION
The \fIvosesame\fP task provides a command-line interface to the
\fISesame\fP name
resolver service at CDS that convert a familiar object name to the J2000
coordinates required by VO services. Additional information
such such as the object type is also available.  The \fISesame\fP service
queries NED, Simbad and Vizier databases for this information.  If no 
flags are provided, the default output is simply the RA and Dec of the
object in decimal degrees (this is what most VO services expect), however
command-line flags provide a method to specify the desired output and
the order in which they are printed.
.PP
Object names may be specified on the commandline individually (multiple
arguments are allowed), as the name of a file containing a list of
objects to be resolved, or both.  If no object or file names are given on
the command line the task will read from the standard input, allowing the
task to be used as a command filter or interactively from the keyboard.
Files containing object names are assumed
to list the name of one object-per-line where whitespace in the object name
is allowed on the line (e.g. "M 51").  From the command line, most shell
interpreters will require that the whitespace be escaped (e.g. "M\ 51") 
so it is interpreted properly.  A warning will be printed if an object name
cannot be resolved and the \fI-v\fP verbose flag is set, otherwise no 
output will be printed for the failed request.
.PP
The \fIOPTIONS\fP section describes the formatting options available. 
For each of these options, the order in which it appears controls the order of
where it appears in the output string for the object.  Output format 
flags control how the values are printed. Supported formats include
comma-separated-values (CSV, the \fI-C\fP flag), tab-separated-values (TSV, 
the \fI-T\fP flag), whitespace-delimited values (the \fI-A\fP default), 
and may include an optional head (the \fI-H\fP) flag) that precedes the
output with a line of text listing the output colums where the first
character of the header is a '#' to indicate a comment.

.SH VOCLIENT DAEMON PROCESSING
All VO-CLI tasks are built upon the VOClient interface an rely on a 
separate \fIvoclientd\fP process to provide the VO functionality.  The
voclientd task is distributed as part of VO-CLI and will be started
automatically by each task if it is not already running.  If problems
are encountered, you may want to manually start the voclientd in a separate
window before running the task so you can monitor the output for error
messages.

.SH OBJECT CACHING
The \fBSesame\fP service at CDS is normally fairly reliable, however there
are times when it is either unavailable, or simply returns a null result 
without indicating an error.  Additionally, the access time is on the
order of ~1 sec/object and so resolving many objects creates an overhead
for applications using this service.
.PP
The \fBvosesame\fP task's only function is to resolve objects, however it
still uses the object caching capability in the VOClient interface.  Once
an object is resolved, it will automatically be cached unless the
\fBVOC_NO_CACHE\fP environment variable is defined.  The \fI-f\fP
command-line option can be used to override any existing cached values and
force the Sesame service to be invoked.  The object cache may be initialized
completely by deleting the $HOME/.voclient/cache/sesame directory.

.SH RETURN STATUS
If all objects were successfully resolved the task will exit with a 
status code of 0.  If one or more of the objects failed to be resolved for
any reason, the exit status will be the number of unresolved objects.


.SH EXAMPLES

.TP 4
1)
Print the coordinates of NGC4456, first in decimal degrees and
then as sexagesimal values:

.nf
	% vosesame ngc4456
	186.960000 -30.120000
	% vosesame -s ngc4456
	12:27.8     -30:07
.fi

.TP 4
2)
Print the sexagesimal coordinates of multiple objects, include the type:

.nf
	% vosesame -st m31 m51 m99
	00:42:44.31 +41:16:09.4 LINER
	13:29:52.36 +47:11:40.8 Seyfert_2
	12:18:49.51 +14:25:00.4 HII_G
.fi

.TP 4
3)
Print the decimal coordinates of those same objects listed in 
the file 'myobjs.txt', output as CSV, include a header, and print 
the id, coords, and type:

.nf
	% vosesame -CHndt myobjs.txt
	#Name,DRA,DDEC,Type,
	m31,10.684625,41.269278,LINER
	m51,202.468208,47.194667,Seyfert_2
	m99,184.706333,14.416778,HII_G
	   :      :         :        :
.fi

.TP 4
4)
Extract the object names from column 17-25 of a file and pipe the
list to vosesame to create a new table of id, ra and dec:

.nf
	% cut -c17-25 data.txt | vosesame -ns
	m51 13:29:52.36 +47:11:40.8
	m23 17:57:00.00 -18:58:59.9
	m67 08:51:17.99 +11:48:00.0
	 :      :           :
.fi

.TP 4
5)
Interactively resolve coordinates by enterying object names on the
standard input:
.nf

	% vosesame -a
	m98
	m98 12:13:48.37 +14:53:57.9 183.45154  14.89944 10.0 10.0 LINER
	[EOF]

.fi
Type the EOF character (typically Ctrl-D or Ctrl-Z) to quit.


.TP 4
6)
Print the sexagesimal and decimal values for multiple user coords:
.nf

	% vosesame -sd -c 12:30:0.0 -45:00:0.0 -c 187.5 2.05
	12:30:00.0 -45:00:00.0  12.500000 -45.000000
	12:30:00.0  02:03:00.0 187.500000   2.050000

.fi


.SH BUGS
The Sesame service can sometimes respond without resolving the object.  In
this case all values are returned as zero or a null string.  \fIVosesame\fP
will sense this as a non-response and not print a result.  If the
\fIverbose\fP flag is set a warning message will be printed.
.SH Revision History
June 2007 - This task is new.
.SH Author
Michael Fitzpatrick (fitz@noao.edu), July 2007
.SH "SEE ALSO"
voclient(1), voclientd(1), vodirectory(1), vodata(1)
.SH BUGS
The Sesame service can sometimes respond without resolving the object.  In
this case all values are returned as zero or a null string.  \fIVosesame\fP
will sense this as a non-response and not print a result.  If the
\fIverbose\fP flag is set a warning message will be printed.
.SH Revision History
June 2007 - This task is new.
.SH Author
Michael Fitzpatrick (fitz@noao.edu), July 2007
.SH "SEE ALSO"
voclient(1), voclientd(1), vodirectory(1), vodata(1)