idl_stsdas.tex

basic median filter simulation

\item	{\bf tab}---table array returned by TAB\_READ
\item	{\bf columns}---(optional) vector of numbers a string with
column names, separated by commas, of the columns to be printed. If
not supplied, or provided as a null string, all columns are printed. 
\item	{\bf row1}---first row to print  (default = 0).
\item	{\bf row2}---last row to print (default = last row in table).
\end{itemize} 
%
\index{TAB\_SIZE}
\item [TAB\_SIZE, {\it tcb, NROWS, NCOLS, MAXROWS, MAXCOLS, ROWLEN, 
MAX\_RL} : ] This procedure returns those factors which define the 
structure of the STSDAS table.

\begin{itemize}

\item {\bf tcb}---The Table Control Block.

\item {\bf NROWS}---The number of rows in the table.

\item {\bf NCOLS}---The number of columns in the table.

\item {\bf MAXROWS}---The 
number of allocated rows.

\item {\bf MAXCOLS}---The number of allocated columns.

\item {\bf ROWLEN}---The byte-length of a row.

\item {\bf MAX\_RL}---The allocated row length.

\end{itemize}

\noindent
For example:\\

\begin{small}
\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf tab\_size}, {\it tcb, NROWS, NCOLS, MAXROWS, MAXCOLS,} & \\
\hspace{1.1in}{\it ROWLEN, MAX\_RL} & \\
\end{tabular}\\
\end{small}

\noindent
returns the values for the requested table parameters.
%
\item {\bf RESULT=TAB\_VAL(}{\it tcb, tab, column $[$, rows$]$}){\bf :} 
Function used to extract values from a STSDAS table.
 
\index{TAB\_VAL}
\index{SDAS tables - extracting values}

\begin{itemize}

\item {\bf tcb}---The Table Control Block.

\item {\bf tab}---The Data Table Array (TAB).

\item {\bf column}---A scalar column name or number.  These names and numbers 
can be listed with the high-level routine {\bf TABLE\_HELP}.

\item {\bf rows}---An optional input to which is assigned the row number or
numbers to extract data values from.  If not supplied, all rows are returned.

\item {\bf RESULT}---Contains the values for the specified column and row(s). 

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf table\_help}, {\it tcb, header} & ; list table info\\
GHRS$>${\bf result=tab\_val(}{\it tcb, tab, 1, 1}{\bf )} & \\
GHRS$>${\bf print}, {\it result} & ; result$=$1 \\
\end{tabular}\\

\noindent
Here, the table file is first read to determine the names and
numbering of the columns.  The table is then read and the value
associated with column 1, row 1 is assigned to {\bf result}.
%
\newpage
\item [TAB\_SORT, {\it column, TCB, TAB}:]
\index{TAB\_SORT}
\index{SDAS table - modifying}
Procedure 
for sorting a column of an STSDAS table in ascending 
order.

\begin{itemize}
\item	{\bf column} - column name or number to sort.
\item	{\bf tcb} - table control block.
\item	{\bf tab} - output table array.
\end{itemize}
%
\item [TAB\_PUT, {\it column, values, tcb, tab $[$, row$]$} :] 
\index{SDAS tables - adding data}
\index{TAB\_PUT}

Used to add data to a new or existing table. 

\begin{itemize}

\item {\bf column}---The column name or number. {\bf Note:} If adding a new 
column, a column name must be specified.

\item {\bf values}---The data values to add to the table.

\item {\bf tcb}---The Table Control Block.

\item {\bf tab}---The Data Table Array.

\item {\bf row}---An optional input starting row to insert values.   If not 
specified then {\bf row=}{\it 0} is assumed.

\end{itemize}

\noindent
Examples:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf table\_help}, {\it tcb, header} & ; list table info\\
GHRS$>${\bf values=}{\it lonarr(165)} & ; create column vector\\
GHRS$>${\bf values(}{\it $*$}{\bf )=}{\it 10} & ; a row of 10's\\
GHRS$>${\bf tab\_put}, {\it 1, values, tcb, tab} & \\
\end{tabular}\\

\noindent
This example reads an existing table, gets column information (specifically the
column numbers, the data types of the columns, and how many elements are in 
a given column).  It then overwrites the {\bf values} vector into all rows of
column 1 ({\it 'detector'}).\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf table\_help}, {\it tcb, header} & ; list table info\\
GHRS$>${\bf tab\_put}, {\it 'comment', 'this is great', tcb, tab, 3} & \\
GHRS$>${\bf tab\_write}, {\it 'blem\_001\_mod', tcb, tab, header} & ; write changes\\
\end{tabular}\\

\noindent
This example writes a single comment starting in row 3 of the {\it comments}
 column.  It only overwrites to the length of the string assigned to 
{\bf values} (i.e., if {\bf comment} is already populated, it may not be 
completely overwritten).  {\bf Note:} the number of elements in the 
{\bf values} vector dictates how many rows are written to. The modified
table is then written to the user's current directory.
%
\item [TAB\_COL, {\it TCB, column, offset, width, type, column\_name, 
units, format} :]
\index{TAB\_COL}
\index{SDAS table - modifying}

This 
very low level ({\it i.e.} basic) procedure extracts column
information from the table control block. 

\begin{itemize}
\item	{\bf tcb}-- table control block.
\item	{\bf column}-- column name (string) or column number
\item	{\bf offset}-- output column offset in bytes
\item	{\bf width}-- output column width in bytes
\item	{\bf type}-- column data type:
\begin{itemize}
\item		1 - boolean
\item		2 - character string
\item		4 - integer*4
\item		6 - real*4
\item		7 - real*8
\end{itemize}
\item	{\bf column\_name}--column name
\item	{\bf units}-- units of the column entries
\item	{\bf format}-- format code
\end{itemize}
%
\item [TAB\_MODCOL, {\it tcb, column $[$, units, format, newname$]$} : ]  
\index{TAB\_MODCOL}
A procedure used to change the specification for a table column.

\begin{itemize}

\item {\bf tcb}---The Table Control Block.

\item {\bf column}---The column name or number to be modified.

\item {\bf units}---An optional input string giving physical units for the 
column (i.e., 'CM/SEC').  If not supplied or set to the null string ('') 
the units are not changed.  {\bf Note:} case sensitivity on unit name.

\item {\bf format}---An optional input print format (either FORTRAN or SPP 
format). An SPP format should be preceeded by a '%'.  If not supplied or set 
to a null string (''), the print format for the column is not changed.

\item {\bf newname}---The new name for the column.  If not supplied
or set to a null string (''), the name is not changed. {\bf Note:}
case sensitivity on column name.

\end{itemize}

\noindent
For example:\\

\begin{tabular}{ll}
GHRS$>${\bf tab\_read}, {\it 'zcal:blem\_001', tcb, tab, header} & \\
GHRS$>${\bf tab\_modcol}, {\it tcb, 'line1', 'Angstroms', 'f10.3', 'wave'} & \\
GHRS$>${\bf tab\_write}, {\it 'blem\_001\_mod', tcb, tab, header} & \\
\end{tabular}\\

\noindent
This example 
reads an existing table and changes the column labelled 
{\it 'line1'} from having no defined units, to units of {\it 'Angstroms'}; 
from a format of {\it f16.8} to {\it f10.3}; and from a column name of {\it LINE1} 
to {\it wave}.  The table is then written to the user's current directory 
under {\it blem\_001\_mod.tab}.  {\bf Note:} the formatting is only for 
display purposes and does not reflect a change in precision of the value.
%
\item [	TAB\_EXPAND,{\it tcb,tab,maxcol,maxrow,rowlen}:]
\index{TAB\_EXPAND}
\index{SDAS table - modifying}

A procedure to expand the size of an STSDAS table file.

\begin{itemize}
\item	{\bf tcb} -- table control block returned by routine TAB\_READ
\item	{\bf tab} -- output table array
\item	{\bf maxcol} -- (optional) new maximum number of columns.
\item	{\bf maxrow} -- new maximum number of rows.
\item	{\bf rowlen} -- new maximum row length in 2 byte units.
 \end{itemize}

	If {\it maxcol}, {\it maxrow}, or {\it rowlen} are given 
	values {\it less} than the previous maximum values, the previous
	values are used.  All values are defaulted to zero
	if not supplied.
%
\item [TAB\_ADDCOL, {\it col\_name, data\_temp, TCB, TAB} : ] This procedure adds a new
column to an existing STSDAS table.  {\bf Note:} this procedure does not 
populate the column with data values.

\begin{itemize}
\item {\bf col\_name}---The name of the column.
\item {\bf data\_temp}---Sample data of type to be written to the column.  
{\bf Note:} this parameter is only used as a template to determine data type.
\item {\bf TCB}---Table Control Block.
\item {\bf TAB}---The Data Table array.
\end{itemize}
%
\item [NULLS=TAB\_NULL({\it values}) :]
\index{TAB\_NULL}
\index{SDAS table - modifying}
A function that finds null values in any column or row.  The 
vector {\it values} must already have been created using {\bf 
TAB\_EXT} or {\bf TAB\_VAL} (see above).  It returns a set of index 
values for the nulls in the vector by applying a logical T/F test to 
each value in the extracted list.  So, for instance:\\

\begin{tabular}{ll}
GHRS$>${\bf i=where(not TAB\_NULL(}{\it value}{\bf ))} & \\
GHRS$>${\bf value=value(}{\it i}{\bf )} & \\
\end{tabular}\\

\noindent
removes all of the nulls from the vector {\it values}.
\newpage
\item [TAB\_NULLROW,{\it tcb,tab,row1,row2}:]
\index{TAB\_NULLROW}
\index{SDAS table - modifying}
Procedure for 
inserting null row(s) into an STSDAS table.

\begin{itemize} 
\item	{\bf tcb}---table control block
\item	{\bf tab}---output table array
\item	{\bf row1}---(optional) first row number to insert nulls (default=0)
\item	{\bf row2}---(optional) last row number to insert nulls (default = last row)
\end{itemize}
%
\item [TAB\_DEL, {\it TCB, TAB, rows} :]
\index{TAB\_DEL}
\index{SDAS table - modifying}
Procedure for deleting specific row(s) from an STSDAS table.  

\begin{itemize}
\item	{\bf tcb}---table control block
\item	{\bf tab}---table array
\item	{\bf rows}---(Optional) A scalar vector giving the list of
rows to delete from the table.  {\bf Note:} If {\it rows} is not
supplied, all rows are deleted. 
\end{itemize}
%
\item [TAB\_WRITE, {\it tablename, tcb, tab $[$, header$]$} :] Procedure 
used to save a modified STSDAS table.
\index{TAB\_WRITE}
\index{SDAS table - modifying}

\begin{itemize}
\item {\bf tablename}---The table name (default extension = .tab).

\item {\bf tcb}---The Table Control Block.

\item {\bf tab}---The Data Table Array.

\item {\bf header}---An optional input header vector.
\end{itemize}

\noindent
For example:\\

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

\noindent
writes the table to a new name into the user's default directory.
%
\item [TAB\_TO\_DB, {\it tablename, dbname, new}:]
\index{TAB\_TO\_DB}
\index{SDAS table - adding to Database}
\index{Databases -- adding an SDAS table to existing}

Procedure for adding the contents of an STSDAS table to an existing or
new database file. 

\begin{itemize}
\item	{\bf tablename}---table name
\item	{\bf dbname}---database name
\item	{\bf new}---(optional) integer that flags one of the following states 
for the target database (default = 0):
\begin{itemize}
\item  0 -add 
to existing database 
\item  1 -create new database
\item 2 -create new database and allow user to edit the {\bf .DBD} file (for 
example, to add spares)
\end{itemize}
\end{itemize}
 
In order to execute TAB\_TO\_DB, {\bf !priv} must be set to 2 or 
higher.  If you are creating a new database, TAB\_TO\_DB places it in 
your current default directory.  The default directory must be 
included the logical definition {\bf zdbase}.  {\bf Note:}  
TAB\_TO\_DB will update the item ENTRY in any database.

\item [TAB\_FORTOSPP, {\it format, SPPFORMAT} :] Procedure to convert a 
Fortran-format to an SPP-format specfication.
\begin{itemize}
\item {\bf format}---Fortran-format specifi