.help tchsize Oct95 tables
.nj
.ih
NAME
tchsize -- Change the size of tables.
.ih
USAGE
tchsize intable outtable maxpar maxcols rowlen allrows
.ih
DESCRIPTION
This task changes the allocated sizes of various portions of a table
or a list of tables.
In some cases it is difficult to effectively use this task,
so caution is advised.

NOTE:  This task should not be used on FITS tables.
If any input table is of type FITS,
a message will be printed, and that file will be skipped.

Four integer parameters specify table sizes.
Passing a value of -1 to any parameter means that the current value
should not be changed.  A value (such as zero) that is smaller than
the minimum allowed value for that parameter results in the truncation
of unused space; for example, if three header parameters have already
been written to a table then setting 'maxpar=0' gives you a table with
space for only three header parameters.

The input may be a general filename
template, including wildcard characters or the name of a list file (preceded
by an "@" sign) containing table names.  The output may be null, a directory
specification, or a list of table names.  If the output is a list of tables
then there must be the same number of names in the input and output lists,
and the names are taken in pairs, one from input and one from output.
A null string for the output is equivalent to specifying the same names
for the input and output tables.

NOTE: Be careful when using a wildcard for the extension.
If you have the files 'table.tab' and 'table.lis' in the current directory,
for example, then "tchsize tab* test/" would crash when trying to open
'table.lis' as a table.
.ih
PARAMETERS
.ls intable [file name template]
A list of one or more tables whose sizes are to be changed.
.le
.ls outtable = "" [file name template]
Either a null string, a directory name, or a list of output table names.
.le
.ls maxpar = -1 [integer]
The number of records to allocate for header (i.e., user) parameters.

Use 'maxpar=-1' if no change is to be made; set 'maxpar=0' to 
truncate unused space.
.le
.ls maxcols = -1 [integer]
The amount of space to allocate for column descriptors.  There must be
at least one for each column that is defined or is to be defined.
For a column-ordered table 'maxcols' actually determines the maximum
number of columns that may be defined (without having to rewrite the
table).  For a row-ordered table, however, you must also specify an
appropriate value for 'rowlen'; you may want to use the 'tinfo' task
to get the
current row length before using this task.

Set 'maxcols=-1' if no change is to be made; set 'maxcols=0' 
to truncate unused space.
.le
.ls rowlen = -1 [integer]
The row length; this is only relevant for a row-ordered table.
The unit of length is the amount of memory used to store 
a real number; so a double-precision column
takes two units, and a character*24 column takes six units (assuming
that a real
is four bytes).
The number of columns that may be defined is limited both by the
space allocated for column descriptors and by the row length.

Set 'rowlen=-1' if no change is to be made; set 'rowlen=0' 
to truncate unused space.
.le
.ls allrows = -1 [integer]
The number of rows to allocate; this is only relevant for a column-ordered
table.

Set 'allrows=-1' if no change is to be made; set 'allrows=0' to truncate
unused space.
.le
.ls (verbose = yes) [boolean]
Display the names of the input and output tables for each table that is
processed?
.le
.ih
EXAMPLES
1. Truncate (in-place) all unused space in a single table:

.nf
	tt> tchsize table "" 0 0 0 0
		or
	tt> tchsize table table 0 0 0 0
.fi

2. Set the allocated space for user (header) parameters to 27 records
without changing any other size parameter.  The result is to be put
in a new file called 'table2.tab', leaving the input table unchanged.

	tt> tchsize table table2 27 -1 -1 -1

3. Truncate unused space in three different tables, with the truncated tables
named 'a.tab', 'b.tab', and 'c.tab':

.nf
	tt> tchsize table1,table2,tab67 a,b,c 0 0 0 0
		or
	tt> tchsize tab*.tab a,b,c 0 0 0 0
.fi
In the latter case the extension is given explicitly in case there
are other files beginning with 'tab' that are not tables; there must
be exactly three tables beginning with tab because the output list
has three names.

4. Increase the space available for allocating new columns:

Suppose the following information about the table has been obtained
by using the 'tinfo' task:

.nf
  tinfo.ncols   = 7
  tinfo.maxcols = 8
  tinfo.rowlen  = 12
  tinfo.rowused = 10
  tinfo.tbltype = "row"
.fi

Suppose we want to add 10 more columns:  five single-precision columns,
two double-precision, and three character*12.  If the table were
column-ordered we would only have to increase 'maxcols' to at least 17
('ncols'+10).  Since the table is row-ordered we still must have 'maxcols=17',
but we also have to increase the row length to allow room for the
additional columns.  The extra row length needed is 5 + 2*2 + 3*3 = 18,
so we must set the new row length to at least 'tinfo.rowused' + 18 = 28.
So we have

.nf
	tt> tchsize table "" -1 17 28 -1
.fi

if the space for header parameters does not need to be changed, and
the allocated number of rows is irrelevant for a row-ordered table.

.ih
BUGS
.ih
REFERENCES
This task was written by Phil Hodge.
.ih
SEE ALSO
tinfo
.endhelp
