idl_stsdas.tex

basic median filter simulation

\newpage

\item [TABLE\_PRINT, {\it tablename $[$, columns, row1, row2$]$} : ] 
\index{TABLE\_PRINT}
\index{SDAS tables - listing}

Procedure 
that creates a tabular listing of the requested columns and
rows.  If no columns or rows are specified, then  {\em all} columns
and rows are output. The {\bf $!$textout} command can be used to
redirect the output (Section~\ref{textout}). 

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf columns}---An optional input vector of column numbers to be 
printed or a string with column names separated by commas. If not supplied or 
set to a null string, all columns are printed.

\item {\bf row1}---An optional input designating the first row to print 
(default=0).

\item {\bf row2}---An optional input designating the last row to print 
(default=last row in table).

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf table\_print}, {\it 'zcal:blem\_001','', 1, 2} & \\
GHRS$>${\bf $!$textout=}{\it 3} & ; re-direct to file\\
GHRS$>${\bf table\_print}, {\it 'zcal:blem\_001',[1, 3, 5], 1, 2} & \\
GHRS$>${\bf $!$textout=}{\it 1} & ; re-direct to screen\\
\end{tabular}\\

\noindent
produces a tabular listing for all columns and rows 1---2.  The second call 
prints a listing of columns 1, 3, and 5 (again rows 1---2) to the output file 
{\bf table\_print.prt}. {\bf Note:} if all columns are requested, the output
format may wrap-around when directing output to the screen.
%
\item [TABLE\_LIST, {\it tablename $[$, row1, row2$]$} :] 
\index{TABLE\_LIST}
\index{SDAS tables - listing}

A procedure that generates a listing or all of the columns in a FITS
table (one column per line) for the requested rows. Normally the
output goes to the terminal screen.  To redirect the output, use the
{\bf $!$textout} command (see Section~\ref{textout}). 

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf row1}---An optional input designating the first row to list 
(default row1 = 0).

\item {\bf row2}---The last row to list (default row2 = maxrow).

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf table\_list}, {\it 'zcal:blem\_001', 10, 12} & \\
GHRS$>${\bf $!$textout=}{\it 3} & ; re-direct to file\\
GHRS$>${\bf table\_list}, {\it 'zcal:blem\_001', 10, 12} & \\
GHRS$>${\bf $!$textout=}{\it 1} & ; re-direct to screen\\
\end{tabular}\\
\newpage

\noindent
lists 
the contents of rows 10---12 to the screen, then to an output file 
{\bf table\_list.prt}.

\item [TABLE\_EXT, {\it tablename, columns, V1, $\cdots$, V9} : ] 
\index{TABLE\_EXT}
\index{SDAS tables - reading}

A procedure to read values from specified columns in a table and
place them into variables (e.g., {\bf V1}, $\cdots$, {\bf V9}, etc).

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf columns}---The table columns to extract (a string with columns 
names separated by commas).

\item {\bf V1, $\cdots$, V9}---Values 1---9 for the column names 1---9.
\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf table\_ext}, {\it 'zcal:blem\_001', 'line1', line1data} & \\
\end{tabular}\\

\noindent
extract the {\it line1} column from the table and stores the values in the
vector {\bf line1data}.
%
\item [TABLE\_SORT, {\it tablename, column $[$, out\_name$]$} : ] 
\index{TABLE\_SORT}
\index{SDAS tables - sorting}

This procedure sorts a table in {\it ascending order} based upon the values in the specified
column.

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf column}---The column to sort on.

\item {\bf out\_name}---An optional output table name.  If not 
supplied, input name is used.

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf table\_sort}, {\it 'zcal:blem\_001', 'detector', 'blem\_001\_mod'} & \\
\end{tabular}\\

\noindent
sorts the {\it detector} column into ascending order and writes it to the 
new table {\it blem\_001\_mod.tab} in the user's current directory.

\item [TABLE\_CALC, {\it tablename, expression $[$, out\_name$]$} :] 
\index{TABLE\_CALC}

This procedure allows the user to construct a new column of data
as a function of values in existing table columns.

\begin{itemize}

\item{\bf tablename}---The STSDAS table name.

\item {\bf expression}---An expression for new or updated column values.
Any legal IDL expression is valid where existing column names can be used as 
variables.  User functions within the expression are allowed if the function
is in an IDL library or has been previously compiled.

\item {\bf out\_name}---An 
optional input parameter designating the output 
table name.  If not supplied, the input name is used.

\end{itemize}

\noindent
For example, in the following call, the procedure uses data tabulated in 
columns {\bf 'line1'} and {\bf 'line2'} of the existing
table {\bf 'zcal:blem\_001'} to generate an average flux and tabulate this in
column {\bf 'ave\_line'}.  The new table is written to {\bf blem\_001\_mod}:\\

\begin{tabular}{ll}
GHRS$>${\bf table\_calc}, {\it 'zcal:blem\_001', 'ave\_line$=$(line1$+$line2)/2.0'} & \\
\end{tabular}

\item [ TABLE\_APPEND, {\it list, name}: ]  This procedure is used to 
append STSDAS tables to create a single table.  {\bf Note:} all input tables 
must have the same number of columns with the same names, datatypes, and 
column order.  Header parameters are taken only from the first table in the 
list.

\begin{itemize}
\item {\bf list}---A string vector listing the STSDAS table filenames to append.
\item {\bf name}---The name of the output STSDAS table containing all appended
tables.
\end{itemize}
%
\item [TABLE\_DELETE, {\it tablename, rows $[$, OUT\_NAME$]$} : ] 
\index{SDAS tables - modifying}
\index{TABLE\_DELETE}
Procedure that deletes rows from the specified STSDAS table.

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf rows}---The row or rows to delete from the table.

\item {\bf out\_name}---An optional output table name. If not supplied, the 
input name is used.

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf table\_delete}, {\it 'zcal:blem\_001', [10, 12], 'blem\_001\_mod'} & \\
\end{tabular}\\

\noindent
deletes rows 10 and 12 from the existing table and writes the modified table to 
the user's current directory.
\end{description}
\newpage

\subsubsection{\bf The Low-Level TAB Routines}
\label{sdas table low}
\index{SDAS tables - low level routines}

The routines 
described in this section are summarized below:\\

\begin{description}

\item [TAB\_CREATE :] A procedure that creates {\bf tcb} and {\bf tab} 
structures to pass to other routines.
\item [TAB\_READ :] A procedure used to read STSDAS tables into IDL variables.
\item [TAB\_PRINT :] A procedure that prints the columns of a table.
\item [TAB\_SIZE :] A procedure which returns the number of rows and columns 
in a table.
\item [TAB\_VAL :] A function used t extract data from an STSDAS table.
\item [TAB\_SORT :] A procedure used to sort an STSDAS table by a specified 
columns.
\item [TAB\_PUT :] A procedure used to add data to existing columns in a 
table.
\item [TAB\_COL :] A procedure used to extract column information from 
table control block (TCB).
\item [TAB\_MODCOL  :] A procedure used to change the name of a 
column in an STSDAS table.
\item [TAB\_EXPAND :] A procedure used to exapnd the number of 
columns in an STSDAS table.
\item [TAB\_ADDCOL :] A procedure used to add a new column to an STSDAS table.
\item [TAB\_NULL :] A function used to locate null values within a vector of 
values from an STSDAS table.
\item [TAB\_NULLROW :] A procedure that adds a null row or rows to a table.
\item [TAB\_DEL :] A procedure used to delete a row or rows from an 
STSDAS table.
\item [TAB\_WRITE :] A procedure used to save a modified table.
\item [TAB\_TO\_DB :] A procedure used to write the contents of an STSDAS 
table to an existing or new database.
\item [TAB\_FORTOSPP :] A  procedure to convert a fortran format to an spp 
format specfication.
\newpage
\item [TAB\_SPPTOFOR :] A 
procedure used for converting an SPP format 
specification to a normal Fortran format specification.
\item [TAB\_HCONVERT :] A procedure used to perform byte-swapping when 
converting STSDAS tables from VMS to UNIX. 
\item [TAB\_CONVERT :] A procedure used to convert STSDAS tables from VMS to 
UNIX (or DOS).
\end{description}

These are all called by the TABLE routines.  When working with the low-level
routines, the first step is to read the contents of an STSDAS table into the
IDL variables {\bf TCB} and {\bf TAB} using {\bf TAB\_READ} or {\bf
TAB\_CREATE}.  When the table  modifications have been completed,
the revised STSDAS table is saved to file using {\bf TAB\_WRITE}.\\ 

\begin{description}

\item [TAB\_CREATE, {\it TCB, TAB $[$, maxcol, maxrows, row\_len,
tb\_type$]$} :] 
\index{TAB\_CREATE}
\index{SDAS tables - creating}

Procedure that creates a {\it template} Table Control Block {\bf TCB} and Table Data Array
{\bf TAB} required by other low-level routines.  {\bf Note:} you do not need to
specify the table size, since all of the table routines will automatically 
expand the table dimensions when required.  This routine is required for 
{\it new} STSDAS tables.  If working with an existing table, proceed to the 
routine {\bf TAB\_READ}.

\begin{itemize}

\item {\bf TCB}---The {\it template} Table Control Block array.

\item {\bf TAB}---The {\it template} Data Table array.

\item {\bf maxcol}---An optional input parameter which designates the maximum 
allocated number of table columns ({\bf maxcol=}{\it 10} Default).

\item {\bf maxrows}---An optional input and designates the maximum allocated 
number of table rows ({\bf maxrows=}{\it 100} Default).

\item {\bf row\_len}---An optional input and designates the table row length 
in 2-byte units {\bf row\_len=maxcol$*$2}

\item {\bf tb\_type}---An optional input and designates the table order 
type; either\\
{\bf tb\_type=}{\it 'row'} or {\it 'column'} ordered ('column' Default).

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_create}, {\it TCB, TAB} & ; create template arrays\\
\end{tabular}\\

\noindent
will create template arrays for use with other low-level routines listed
below.

\item [TAB\_READ, {\it tablename, TCB, TAB $[$, HEADER$]$} :] 

\index{TAB\_READ}
\index{sdas tables - reading}

The main 
procedure used to read the contents of the specified table file into 
IDL variables. {\bf Note:} if you are working with an existing table, this 
would be the first call to make.  Otherwise, you need to first create a 
table using {\bf TAB\_CREATE}.

\begin{itemize}

\item {\bf tablename}---The STSDAS table name.

\item {\bf TCB}---Table control block.

\item {\bf TAB}---The data table array.

\item {\bf header}---An optional output header vector in a form usable 
by {\bf SXPAR}, {\bf SXADDHIST}, {\bf SXADDPAR} 
(i.e., the header is re-formatted to look like a normal FITS header).

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
\end{tabular}\\

\noindent
reads one of the GHRS calibration table files.
%
\item [TAB\_PRINT, {\it TCB, TAB, columns, row1, row2} :]
\index{TAB\_PRINT}
\index{SDAS table - printing}
 
Procedure for printing all or select columns of an STSDAS table.  The
text is printed as directed by the value of {\bf !textout}.  You must 
use TAB\_READ before using this procedure.
 
\begin{itemize}
\item	{\bf tcb}---table control block returned by TAB\_READ