Syntax: TABLE [subtable] ['format'] file
or      TABLE subtable
or      READ TABLE { WORD [WORD ...] }
or      READ TABLE 'format' { WORD [WORD ...] }
or      READ TABLE 'byname' { WORD [WORD ...] }
or      READ TABLE 'bycolumn' { WORD id [WORD id ...] }
or      LIST TABLE
or      WRITE TABLE [+] file { vector_list }
or      WRITE TABLE [+] file < vector_list >
or      TABLE DELETE

   SM is able to read a wide range of table formats, using tricks similar
to those used for the IMAGE command. The variable table_type is used to
specify which you want (and may be set in your .sm file). Common values
are "bintable" and "ctable".

   TABLE [...] file is the equivalent of the DATA command, and sets
file "file" to be the source of data read with the READ TABLE command;
if the file can't be opened for read, you will be warned. If the
subtable argument is provided, it specifies which table in a TABLE
file is to be read; this is only currently supported for FITS tables
($table_type is "bintable" or a type derived therefrom; for such tables
you probably want to use a subtable of 1). The format, if provided,
specifies the types of the columns in the table; some tables may
provide this either in the table header (e.g. FITS binary tables) or
in the filecap file, as the FM quantity. Allowable format strings are
specified at the end of this file. This format applies to READ TABLE
commands for this table, unless specifically overridden.

   The range of lines specified by LINES is reset; the LINES command may
be used to select portions of TABLEs to read.

If you don't specify the filename, and if SM knows how to skip tables,
it will skip over  HDUs that it has already read, provided that the SM variable
save_read_ptr is set (which it is by default).

   The READ TABLE command is used to read data from a table. If you specify
a format string and a list of names, a vector will be read from each column
specified in the format and assigned to the corresponding vector (for
example, READ TABLE 'x16if2' { i x y } will skip 16 bytes at the start of
the row, then read an integer into i, and two columns of floats into x and y).
Format strings are described at the end of the file.

   If you specify the format as 'byname', the names of the vectors
will be taken to be the names of columns in the file, and the
corresponding columns will be read. If the column name, say "RDL",
specifies an array, the vector will be filled from column RDL[0]; as
an alternative to this you can specify the name as (e.g.) "RDL[2]" in
which case vector "RDL2" will be created from column RDL[2]. You can
also say "RDL[0-2]" to read vectors RDL0, RDL1, and RDL2. Byname
access is only currently supported for FITS binary tables. For these
tables, you can list the columns with "LIST TABLE".

   If you specify the format as 'bycolumn', the list is expected to be a
list of pairs of values (similar to the regular READ { x 1 y 2 ... } command).
The first element of each pair is the name of a vector, the second may be
either a number or a column name (if supported). The number gives the
desired column with respect to the current format string. For example,
	TABLE 'd*' file
	READ TABLE 'bycolumn' { x 1 y 2 }
will read x and y from the first two columns of the file, whereas
	TABLE 'x8d*' file
	READ TABLE 'bycolumn' { x 1 y 2 }
will read x and y from the second and third columns of the file, assuming
that a double is eight bytes wide.

   Instead of a number, you may be able to specify a column name, for
example
	READ TABLE 'bycolumn' { x_u rowc[0] x_g rowc[2] }
but this depends on your chosen table_type having support for byname access.
In general you will not be able to mix name- and column- orientated access
(for example, we do not support column orientated access to FITS binary
tables unless you provide a format).

   TABLE's formats are strings (i.e. they must be enclosed with '').
consisting of a set of types followed by optional repeat counts, for
example 'x12f5d*' would specify a table, each of whose rows had 12
unwanted bytes, 5 floats, and the rest integers.  Format letters are:
	a		A 1-byte ascii string
	c		A 1-byte char
	d		An 8-byte double
	f		A 4-byte float
	i		A 4-byte int
	l		A long int (may be 8-bytes on some machines)
	s		A 2-byte int
	x		1 byte to skip (a space may be used instead of an x)
and each may be followed by a repeat count (default: 1), or a *, meaning
to repeat as many times as fits into a row. In all cases except 'a', the
repeat count refers to how many columns there are (so d4 means 4 doubles);
for a it refers to the length of the string (so a4 is one 4-byte string).

    Header keywords may be available with the DEFINE name IMAGE command;
all current header keywords may be forgotten with TABLE DELETE (note
that this doesn't do anything to any vectors that may have been read
from the table).

You may write a limited number of types of table using WRITE TABLE.
Currently only FITS binary tables are supported (adding C tables would
be easy; just ask).  All the vectors listed in the vector_list are
written to the table; if you ask to append (with +) another HDU is
created.  When the table's written all current image variables are
written to the header; in general this may include keywords that
described the data in a table that you read earlier. If this is a
problem, you can explicitly save the ones that you want as variables
(or a string-valued vector); use TABLE DELETE to remove all image
variables; and reinstate your chosen ones with IMAGE DEFINE.
