.\" @(#)votinfo.1 1.0 Feb-2013 MJF
.TH VOTINFO 1 "Feb 2013" "VOClient Package"
.SH NAME
votinfo \- Get information about a VOTable

.SH SYNOPSIS
\fBvotinfo\fP [<opts>] votable.xml

.SH OPTIONS
The \fIvotinfo\fP task accepts the following options:
.TP 6
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.

.TP 6
.B \-b,--brief
Print only brief output about the table.
.TP 6
.B \-d,--description
Print the toplevel <DESCRIPTION> element of the VOTable.
.TP 6
.B \-i,--info
Print all <INFO> elements in the VOTable. Parameters are printed as 
\fIname=value\fP pairs,, if there is no output it is
implied there are no <INFO> elements in the document.
.TP 6
.B \-n \fIWHAT\fP,--numberOf \fIWHAT\fP
Get number of elements specified by \fIWHAT\fP.  The \fIWHAT\fP must be a
valid VOTable element name.
.TP 6
.B \-p,--param
Print all <PARAM> elements in the VOTable.  Parameters are printed as
\fIname=value\fP pairs, if there is no output it is implied there are no
<PARAM> elements in the document.
.TP 6
.B \-q,--query_status
Get the 'QUERY_STATUS' <INFO> value, a value of zero is returned of the 
value is OK, or one if it is an ERROR.
.TP 6
.B \-s,--size
Print the table size as <nrows> and <ncols> values.  In a multi-RESOURCE
VOTable only results for the first table are returned.
.TP 6
.B \-v,--verbose
Print verbose otuput.
.TP 6
.B \-w,--warn
Print VOTable parser warning messages.


.SH DESCRIPTION
The \fIvotinfo\fP task is used to either print a summary of a VOTable's
structure, or to get specific attributes of a VOTable (e.g. the size of
a table, number of parameters, etc).  The \fI-n WHAT\fP flag is used to query 
for the number of \fIWHAT\fP elements in the document, allow values of WHAT
include:

.in 15             
.I param	
number of <PARAM> elements
.in 15             
.I info		
number of <INFO> elements
.in 15             
.I rows		
number of table rows
.in 15             
.I cols		
number of table cols
.in 15             
.I resources	
number of <RESOURCE> elements

.PP
The VOTable <PARAM> elements may be printed using the \fI-p\fP flag,
similarly <INFO> elements can be printed using \fI-i\fP.

If no input file is specified the VOTable will be read from the stdin,
results will be written to stdout unless the \fI\-o\fP (or \fI\--output\fP)
names an output file.  The task will only process a single VOTable and may
not be used to convert multiple files in a single call.

.SH RETURN STATUS
On exit the \fBvotinfo\fP task will return a zero indicating success, or a
one indicating an error.

.SH EXAMPLES
.TP 4
1)  Print verbose summary information about a VOTable

.nf
    % votinfo -v test.xml
.fi
.TP 4
2)  Print the <PARAM> elements in a table, then get a count

.nf
    % votinfo -p test.xml
    % votinfo --numberOf=param test.xml
.fi
.TP 4
3)  Determine whether a VOTable contains a successful result

.nf
    % votinfo -q test.xml
.fi

A zero indicates 'OK', a one is an 'ERR', and -1 means that an <INFO> with a 'QUERY_STATUS' was not found

.SH BUGS
The task doesn't always work intuitively with multi-resource VOTables.
.SH Revision History
Feb 2013 - First public release
.SH Author
Michael Fitzpatrick (fitz@noao.edu), Feb 2013
.SH "SEE ALSO"
votget, votget, votpos, votsort, votstat