units string may contain any information that will fit; calling it "units" is just a suggestion. A table may also contain header parameters in a format similar to FITS header keywords.
The data types supported for tables are double precision real, single precision real, integer, boolean, and text strings. Values are stored in the table file in the host machine's binary format. Elements that have not been assigned values or that have been set to "undefined" are flagged as such in the table.
The object library specified to xc as -ltbtables contains all the spp-callable table I/O routines. The include file
A table with more than one column is a 2-D array of values. A 2-D array can be stored in the file in row or column ordered format. That is, as you step from word to word in the file, you could be stepping along a row or down a column. Both options are supported for STSDAS tables. Simple text files in row and column format can also be accessed as tables by the STSDAS table I/O routines.
The file name for a binary table must include an extension, with
The table interface includes routines for accessing table files, columns, header parameters, table parameters, and table data. The name of each routine begins with "tb", the next letter indicates what type of object is involved (row, column, parameter, etc.), and the last three letters specify what is to be done (e.g., open, close, get, put). For example, tbtopn opens a table. The third letter ("t") implies that the routine applies to a table as a whole, and "opn" means "open". Similarly, tbtclo closes a table. For some routines the last letter indicates the data type of the input or output buffer. For example, tbegtr operates on a table element ("e") to get ("gt") an element, and the output buffer is of type real ("r"). The corresponding "put" routine is tbeptr. Table E.1 is a list of third letters and what they refer to:
xc -p stsdas test.x -ltbtables.
Generated with CERN WebMaker
tbset.h defines parameters for getting such information as the number of rows or columns in a table. Some items may also be set. The maximum lengths of column names and similar values are also specified in that file. Further details are given below. The tbpset routine is used to set parameter values, and the integer function tbpsta returns values.tab as the default. A text table, on the other hand, need not have an extension. STDIN and STDOUT may be used for input and output text tables.
Table E.1: Table I/O Procedure Naming Conventions.
Table E.2: Procedures to Open and Close Tables.
Example E.1 reads all values from one table column and prints the values that are defined. If this were in a file called test.x, it could be compiled and linked by typing*2:
task test
include <tbset.h> # defines TBL_NROWS, SZ_COLNAME, etc
procedure test()
pointer tp # pointer to table descriptor
pointer cp # pointer to column descriptor
char intable[SZ_FNAME] # table name
char colname[SZ_COLNAME] # column name
real value # a single value from a table element
int nrows # number of rows in table
int row # loop index for row number
pointer tbtopn()
int tbpsta()
begin
call clgstr ("intable", intable, SZ_FNAME)
call clgstr ("colname", colname, SZ_FNAME)
tp = tbtopn (intable, READ_ONLY, NULL) # open the table
call tbcfnd (tp, colname, cp, 1) # find the column in the table
if (cp == NULL) {
call tbtclo (tp)
call error (1, "column not found")
}
nrows = tbpsta (tp, TBL_NROWS)
do row = 1, nrows {
call tbegtr (tp, cp, row, value) # get value in current row
if (!IS_INDEF(value)) { # is the value defined?
call printf ("%14.6g\n")
call pargr (value)
}
}
call tbtclo (tp) # close the table
end
Table E.3: Procedures Dealing with Columns.
Table E.4: Table File Operations.