.help colbyid Mar12 votools
.ih
NAME
colbyid -- Identify VOTable column by ID attribute
.ih
USAGE
colbyid input id
.ih
PARAMETERS
.ls input
The input VOTable.
.le
.ls id
The ID 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 \fICOLBYID\fR task is used to find the column in a VOTable with the
named \fIID\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 IDs),
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 'id' attribute is 'RA' in a
VOTable document:

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

Or when a parameter is not found:

.nf
  votools> colbyid 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> =colbyid.column
  2
  votools> =colbyid.found
  yes
  votools> =colbyid.ucd
  POS_EQ_RA_MAIN
  votools> =colbyid.name
  RA
.fi

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