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:
-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.
-p <ra,dec> or --pos=<ra,dec>: Specify a comma-delimited input position. This option can be used to convert input sexagesimal or floating-point values using the formatting options.
Formatting Flags:
-A, --ascii: Print the results as a whitespace delimited ascii table.
-C, --csv: Print the results as a comma-separated-value (CSV) table.
-F, --format: Format ASCII results using fixed-width columns.
-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.
-I, --init_cache: Initialize the resolver cache directory.
-T, --tsv: Print the results as a tab-separated-value (TSV) table.

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

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

This document was created by man2html, using the manual pages.
Time: 19:30:04 GMT, April 15, 2013