SPP Reference Manual


STSDAS tables
*1 are binary files that contain data in row and column format. Each column has a name, data type, print format, and unit. All the values in a given column are of the same data type, but different columns may have different data types. The column name should be unique within a table. The print format may be used to display the values but does not affect the way the values are stored in the table. The 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 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.

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 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.

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:

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:

xc -p stsdas test.x -ltbtables.

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() 
        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 

Table E.3: Procedures Dealing with Columns.

Table E.4: Table File Operations.

Table E.1: - Table I/O Procedure Naming Conventions.
Table E.2: - Procedures to Open and Close Tables.
Table E.3: - Procedures Dealing with Columns.
Table E.4: - Table File Operations.
Reading and Writing Data
Header Parameters
The tbset.h Include File
Print Formats
Table Utilities

Generated with CERN WebMaker