diff options
| author | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
|---|---|---|
| committer | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
| commit | fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 (patch) | |
| tree | bdda434976bc09c864f2e4fa6f16ba1952b1e555 /vendor/voclient/doc/vosesame.html | |
| download | iraf-linux-fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4.tar.gz | |
Initial commit
Diffstat (limited to 'vendor/voclient/doc/vosesame.html')
| -rw-r--r-- | vendor/voclient/doc/vosesame.html | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/vendor/voclient/doc/vosesame.html b/vendor/voclient/doc/vosesame.html new file mode 100644 index 00000000..7104e743 --- /dev/null +++ b/vendor/voclient/doc/vosesame.html @@ -0,0 +1,320 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of VOSESAME</TITLE> +</HEAD><BODY> +<H1>VOSESAME</H1> +Section: User Commands (1)<BR>Updated: July 2007<BR><A HREF="#index">Index</A> +<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +vosesame - call the Sesame name resolver service +<P> +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>vosesame</B> [-<I>adefhinstACHT</I>] [<I>file</I> | <I>target</I> ] [ ... ] +<P> +<A NAME="lbAD"> </A> +<H2>OPTIONS</H2> + +The <I>vosesame</I> task accepts the following options: +<DL COMPACT> +<DT><B>-h, --help</B> + +<DD> +Print a help summary to the terminal and exit. No processing is done +following this flag. +<DT><B>-q, --quiet</B> + +<DD> +Quiet mode (suppress warning output). +<DT><B>-v, --verbose</B> + +<DD> +Verbose output. Normally used to print warnings when an object could not be +resolved. +<DT>The following flags may be combined as a single option to indicate the<DD> +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. +<DT><B>-a, --all</B> + +<DD> +Output all available information about the object. +<DT><B>-d, --decimal</B> + +<DD> +Output the position as J2000 decimal degrees. This is the default output if +no format flags are specified. +<DT><B>-e, --errors</B> + +<DD> +Output the estimated position errors. +<DT><B>-n, --name</B> + +<DD> +Output the object name. +<DT><B>-t, --type</B> + +<DD> +Output the object type. +<DT><B>-s, --sex</B> + +<DD> +Output the position as sexagesimal RA and Dec. +<P> +<DT>Control Flags:<DD> +<DT><B>-f, --force</B> + +<DD> +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. +<DT><B>-o <name> or --output=<name></B> + +<DD> +Specify the output file. The default is to write the results to the +standard output. +<DT><B>-p <ra,dec> or --pos=<ra,dec></B> + +<DD> +Specify a comma-delimited input position. This option can be used to +convert input sexagesimal or floating-point values using the formatting +options. +<P> +<DT>Formatting Flags:<DD> +<DT><B>-A, --ascii</B> + +<DD> +Print the results as a whitespace delimited ascii table. +<DT><B>-C, --csv</B> + +<DD> +Print the results as a comma-separated-value (CSV) table. +<DT><B>-F, --format</B> + +<DD> +Format ASCII results using fixed-width columns. +<DT><B>-H, --header</B> + +<DD> +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. +<DT><B>-I, --init_cache</B> + +<DD> +Initialize the resolver cache directory. +<DT><B>-T, --tsv</B> + +<DD> +Print the results as a tab-separated-value (TSV) table. +<P> +</DL> +<A NAME="lbAE"> </A> +<H2>DESCRIPTION</H2> + +The <I>vosesame</I> task provides a command-line interface to the +<I>Sesame</I> 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 <I>Sesame</I> 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. +<P> + +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 <I>-v</I> verbose flag is set, otherwise no +output will be printed for the failed request. +<P> + +The <I>OPTIONS</I> 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 <I>-C</I> flag), tab-separated-values (TSV, +the <I>-T</I> flag), whitespace-delimited values (the <I>-A</I> default), +and may include an optional head (the <I>-H</I>) 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. +<P> +<A NAME="lbAF"> </A> +<H2>VOCLIENT DAEMON PROCESSING</H2> + +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate <I>voclientd</I> 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. +<P> +<A NAME="lbAG"> </A> +<H2>OBJECT CACHING</H2> + +The <B>Sesame</B> 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. +<P> + +The <B>vosesame</B> 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 +<B>VOC_NO_CACHE</B> environment variable is defined. The <I>-f</I> +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. +<P> +<A NAME="lbAH"> </A> +<H2>RETURN STATUS</H2> + +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. +<P> +<P> +<A NAME="lbAI"> </A> +<H2>EXAMPLES</H2> + +<P> +<DL COMPACT> +<DT>1)<DD> +Print the coordinates of NGC4456, first in decimal degrees and +then as sexagesimal values: +<P> +<PRE> + % vosesame ngc4456 + 186.960000 -30.120000 + % vosesame -s ngc4456 + 12:27.8 -30:07 +</PRE> + +<P> +<DT>2)<DD> +Print the sexagesimal coordinates of multiple objects, include the type: +<P> +<PRE> + % 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 +</PRE> + +<P> +<DT>3)<DD> +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: +<P> +<PRE> + % 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 + : : : : +</PRE> + +<P> +<DT>4)<DD> +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: +<P> +<PRE> + % 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 + : : : +</PRE> + +<P> +<DT>5)<DD> +Interactively resolve coordinates by enterying object names on the +standard input: +<PRE> + + % vosesame -a + m98 + m98 12:13:48.37 +14:53:57.9 183.45154 14.89944 10.0 10.0 LINER + [EOF] + +</PRE> + +Type the EOF character (typically Ctrl-D or Ctrl-Z) to quit. +<P> +<P> +<DT>6)<DD> +Print the sexagesimal and decimal values for multiple user coords: +<PRE> + + % vosesame -sd -p 12:30:0.0,-45:00:0.0 -p 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 + +</PRE> + +<P> +<P> +</DL> +<A NAME="lbAJ"> </A> +<H2>BUGS</H2> + +The Sesame service can sometimes respond without resolving the object. In +this case all values are returned as zero or a null string. <I>Vosesame</I> +will sense this as a non-response and not print a result. If the +<I>verbose</I> flag is set a warning message will be printed. +<A NAME="lbAK"> </A> +<H2>Revision History</H2> + +June 2007 - This task is new. +<A NAME="lbAL"> </A> +<H2>Author</H2> + +Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), July 2007 +<A NAME="lbAM"> </A> +<H2>SEE ALSO</H2> + +voclient, voclientd, voregistry, vodata +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">OPTIONS</A><DD> +<DT><A HREF="#lbAE">DESCRIPTION</A><DD> +<DT><A HREF="#lbAF">VOCLIENT DAEMON PROCESSING</A><DD> +<DT><A HREF="#lbAG">OBJECT CACHING</A><DD> +<DT><A HREF="#lbAH">RETURN STATUS</A><DD> +<DT><A HREF="#lbAI">EXAMPLES</A><DD> +<DT><A HREF="#lbAJ">BUGS</A><DD> +<DT><A HREF="#lbAK">Revision History</A><DD> +<DT><A HREF="#lbAL">Author</A><DD> +<DT><A HREF="#lbAM">SEE ALSO</A><DD> +</DL> +<HR> +This document was created by +<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 19:30:04 GMT, April 15, 2013 +</BODY> +</HTML> |