.help colbyname Mar12 votools
.ih
NAME
colbyname -- Identify VOTable column by NAMED attribute
.ih
USAGE
colbyname input name
.ih
PARAMETERS
.ls input
The input VOTable.
.le
.ls name
The NAMED attribute name
.le
.ls column = 0
Found column number (1-indexed, or -1 if not found)
.le
.ls ucd = ""
Value of the UCD attribute for the found column.
.le
.ls name = ""
Value of the NAME attribute for the found column.
.le
.ls print = no
Print column field number?
.le
.ls found = no
Was column found in table?
.le

.ih
DESCRIPTION
The \fICOLBYNAMED\fR task is used to find the column in a VOTable with the
named \fINAMED\fR attribute value of a table column.  This attribute is not
generally guaranteed to be unique within a table and so the task will print
a warning if multiple values are found, but only the first value found will
be saved.  This attribute value is not generally guaranteed to be the same
across VO services (e.g. an 'RA' and 'Dec' column may have alternate NAMEs),
and so some knowledge of the table contents is assumed.

If a column with the specified attribute is found, the \fIcolumn\fR parameter
will be the one-indexed column number and the \fIfound\fR parameter will 
be set, otherwise the \fIcolumn\fR value will be '-1'.  If the column is
found, the \fIucd\fR and \fIname\fR values will be filled in with the
corresponding attributes for that column or the null string.

If the \fIprint\fR parameter is set, the column number will be printed to the
standard output.

.ih
EXAMPLES
1. Find the column in the table where the 'name' attribute is 'RA' in a
VOTable document:

.nf
  votools> colbyname vodata$usno-b.xml RA print+
  2
  votools> colbyname http://iraf.noao.edu/votest/usno-b.xml RA print+
  2
  votools> colbyname file:///<path>/usno-b.xml RA print+
  2
  votools> colbyname file:///localhost/<path>/usno-b.xml RA print+
  2
.fi

Or when a parameter is not found:

.nf
  votools> colbyname vodata$usno-b.xml FOO print+
  -1
.fi

If a matching column is found in the table, the task parameters may be 
queried for additional information:

.nf
  votools> =colbyname.column
  2
  votools> =colbyname.found
  yes
  votools> =colbyname.ucd
  POS_EQ_RA_MAIN
  votools> =colbyname.name
  RA
.fi

.ih
REVISIONS
.le
.ih
SEE ALSO
colbyucd, colbyid
.endhelp
