From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- vendor/voclient/doc/OLD/vosesame.html | 348 ++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 vendor/voclient/doc/OLD/vosesame.html (limited to 'vendor/voclient/doc/OLD/vosesame.html') diff --git a/vendor/voclient/doc/OLD/vosesame.html b/vendor/voclient/doc/OLD/vosesame.html new file mode 100644 index 00000000..f15a2e57 --- /dev/null +++ b/vendor/voclient/doc/OLD/vosesame.html @@ -0,0 +1,348 @@ +Content-type: text/html + +Manpage of VOSESAME + +

VOSESAME

+Section: User Commands (1)
Updated: July 2007
Index +Return to Main Contents

+ + +

NAME

+ +vosesame - call the Sesame name resolver service + +

SYNOPSIS

+ +vosesame [-adefhinstACHT] [file | target ] [ ... ] +

+ +

OPTIONS

+ +The vosesame task accepts the following options: +

-h, --help + +: +Print a help summary to the terminal and exit. No processing is done +following this flag. +
-q, --quiet + +: +Quiet mode (suppress warning output). +
-v, --verbose + +: +Verbose output. Normally used to print warnings when an object could not be +resolved. +
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. +
-a, --all + +: +Output all available information about the object. +
-d, --decimal + +: +Output the position as J2000 decimal degrees. This is the default output if +no format flags are specified. +
-e, --errors + +: +Output the estimated position errors. +
-n, --name + +: +Output the object name. +
-t, --type + +: +Output the object type. +
-s, --sex + +: +Output the position as sexagesimal RA and Dec. +
+
Control Flags:: +
-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 -c 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. +
-i, --invert + +: +Invert the sense of the search and print only objects which cannot be +resolved to coordinates. +
-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. +
-o <name> or --output=<name> + +: +Specify the output file. The default is to write the results to the +standard output. +
+
Formatting Flags:: +
-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. +
-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. +
-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. +
-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. +
+

+ +

DESCRIPTION

+ +The vosesame task provides a command-line interface to the +Sesame 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 Sesame 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. +

+ +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 -v verbose flag is set, otherwise no +output will be printed for the failed request. +

+ +The OPTIONS 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 -C flag), tab-separated-values (TSV, +the -T flag), whitespace-delimited values (the -A default), +and may include an optional head (the -H) 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. +

+ +

VOCLIENT DAEMON PROCESSING

+ +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate voclientd 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. +

+ +

OBJECT CACHING

+ +The Sesame 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. +

+ +The vosesame 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 +VOC_NO_CACHE environment variable is defined. The -f +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. +

+ +

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. +

+ +

EXAMPLES

+ +

1)

+Print the coordinates of NGC4456, first in decimal degrees and +then as sexagesimal values: +

+        % vosesame ngc4456
+        186.960000 -30.120000
+        % vosesame -s ngc4456
+        12:27.8     -30:07
+

+ +

2)

+Print the sexagesimal coordinates of multiple objects, include the type: +

+        % 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
+

+ +

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: +

+        % 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
+           :      :         :        :
+

+ +

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: +

+        % 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
+         :      :           :
+

+ +

5)

+Interactively resolve coordinates by enterying object names on the +standard input: +

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

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

6)

+Print the sexagesimal and decimal values for multiple user coords: +

+
+        % 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
+
+

+ +

BUGS

+ +The Sesame service can sometimes respond without resolving the object. In +this case all values are returned as zero or a null string. Vosesame +will sense this as a non-response and not print a result. If the +verbose flag is set a warning message will be printed. + +

Revision History

+ +June 2007 - This task is new. + +

Author

+ +Michael Fitzpatrick (fitz@noao.edu), July 2007 + +

BUGS

Revision History

+ +June 2007 - This task is new. + +

Author

+ +Michael Fitzpatrick (fitz@noao.edu), July 2007 + +

Index

NAME: +
SYNOPSIS: +
OPTIONS: +
DESCRIPTION: +
VOCLIENT DAEMON PROCESSING: +
OBJECT CACHING: +
RETURN STATUS: +
EXAMPLES: +
BUGS: +
Revision History: +
Author: +
SEE ALSO: +
BUGS: +
Revision History: +
Author: +
SEE ALSO: +

+This document was created by +man2html, +using the manual pages.
+Time: 20:46:31 GMT, May 21, 2009 + + -- cgit

VOSESAME

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

VOCLIENT DAEMON PROCESSING

OBJECT CACHING

RETURN STATUS

EXAMPLES

BUGS

Revision History

Author

SEE ALSO

BUGS

Revision History

Author

SEE ALSO

Index