AT_FREE(3)



NAME

     at_read,  at_write,  at_create,  at_define_table,   at_free,
     at_check_n_grow,  at_put_info,  at_put_name,  at_put_string,
     at_put_time,       at_put_value,       at_rec_setkey_double,
     at_rec_setkey_int,   at_rec_setkey_str,  at_rec_setkey_time,
     at_rec_setkey_time_interval,   at_rec_setkey_uint,   at_col,
     at_cols,  at_rows, at_get_ascii, at_get_name, at_get_string,
     at_get_time,       at_get_value,       at_rec_getkey_double,
     at_rec_getkey_int,   at_rec_getkey_str,   AT_rec_getkey_str,
     at_rec_getkey_time,             at_rec_getkey_time_interval,
     at_rec_getkey_uint, at_error_msg, at_in_bounds, at_copy_row,
     at_remove_row, at_remove_rows

     -a set of functions to create and manipulate tabular data


SYNOPSIS

     #include <soi_at.h>

     read and write tables
     AT *at_read(char *pathname);
     int at_write(AT *at, char *pathname);

     create table
     AT *at_create(char *header_info);
     AT *at_define_table(int cols, int rows);
     void at_free(AT *at);
     int at_check_n_grow(AT *at, int col, int row);

     insert info
     int at_put_info(AT *at, char *header_info);
     int at_put_name(AT *at, int col, char *name);
     int at_put_string(AT *at, int col, int row, char *text);
     int at_put_time  (AT *at, int col, int row, double value);
     int at_put_value(AT *at, int col, int row, double value);
     int at_rec_setkey_double(AT *at, int rec, char *key, double dval);
     int at_rec_setkey_int(AT *at, int rec, char *key, int ival);
     int at_rec_setkey_str(AT *at, int rec, char *key, char *val);
     int at_rec_setkey_time(AT *at, int rec, char *key, TIME tval);
     int at_rec_setkey_time_interval(AT *at, int rec, char *key, TIME tival);
     int at_rec_setkey_uint(AT *at, int rec, char *key, unsigned int ival);

     retrieve info
     int at_col(AT *at, char *data_name);
     int at_cols(AT *at);
     int at_rows(AT *at);
     char *at_get_ascii(AT *at, int col, int row);
     char *at_get_name(AT *at, int col);
     char *at_get_string(AT *at, int col, int row);
     double at_get_time (AT *at, int col, int row);
     double at_get_value(AT *at, int col, int row);
     double at_rec_getkey_double(AT *at, int rec, char *key);
     int at_rec_getkey_int(AT *at, int rec, char *key);
     char *at_rec_getkey_str(AT *at, int rec, char *key);
     char *AT_rec_getkey_str(AT *at, int rec, char *key);
     TIME at_rec_getkey_time(AT *at, int rec, char *key);
     TIME at_rec_getkey_time_interval(AT *at, int rec, char *key);
     unsigned int at_rec_getkey_uint(AT *at, int rec, char *key);
     char *at_error_msg(AT *at);
     int at_in_bounds(AT *at, int col, int row);

     manipulate tables
     int at_copy_row (AT *at, int new, int old);
     int at_remove_row (AT *at, int row);
     int at_remove_rows (AT *at, int row0, int row1);




DESCRIPTION

     This library provides support for simple "spreadsheet-style"
     tables of values.  The terminology used is:
           row          A row in the table
           col          A column in the table
           header       an initial line with names

     File format is RDB format with all data kept in  strings  in
     the  file  and in the structure.  functions are provided for
     conversions to/from numbers and times

     at_read reads an RDB formatted file and returns a pointer to
     a table data structure containing the column headings, rows,
     and columns of the file.  It uncompresses files  using  zcat
     if  necessary.  It returns NULL on error and sets soi_errno.
     Note that the return from reading a 0  length  file  is  not
     treated as an error but rather returns a pointer to a struc-
     ture with no rows and columns.

     at_write writes an RDB formatted file containing the  column
     headings, rows, and columns of the table data structure.

     at_create creates a table with column headings but no  rows.
     The  info  argument  to at_create is a string containing the
     tab-separated column headings.

     at_free frees free all memory associated with a  table  data
     structure.   It  does not (and cannot) set the pointer argu-
     ment itself to NULL.

     at_col returns the column index of the table column with the
     given heading.  On error, it returns AT_BAD_COL_COUNT.

     at_cols returns the number of columns in the table.

     at_rows returns the number of rows in the table.

     at_put* functions insert info  into  a  table.   at_put_info
     adds  string  of  one  or  more  lines.  Other put functions
     insert cells into the table based on column and row indices,
     performing data conversions as necessary.

     at_rec_setkey* functions insert cells into the  table  based
     on column name and row index and perform data conversions..

     at_get* and at_at_rec_getkey* retrieve  information  from  a
     table data structure.

     at_copy_row() copies the contents of row old  to  new;  both
     original  and  target  records  must  be within the existing
     table range.

     at_remove_row() removes the requested row from the table.

     at_remove_rows() removes rows row0  through  row1  inclusive
     from  the  table.  The  entire range of deleted rows must be
     within the table; otherwise nothing is removed.



EXAMPLES

     The function to read an existing table is:

     AT *at; at = at_read("filename");

     The function to save a table to a file is:

     AT *at; at_write(at, "filename");

     To make a table from scratch, a line of names must  be  pro-
     vided.  they should be delimited by tabs.  The name line can
     be ingested with "at_put_info"  A  line  of  "---"  per  col
     should  follow  with at_put_info.  Then the data can be ing-
     ested a line at a time with "at_put_info"

     Alternatively,  set   the   table   rows   and   cols   with
     "at_define_table" then stick in the names and values at will
     with    at_put_name    and    at_put_value,     at_put_time,
     at_put_string calls.




FILES

     ~soi/CM/include/soi_key.h



SEE ALSO

     ~soi/CM/src/modules/*.c                 ~soi/CM/src/pipe/*.c
     /soidata/info/mdi_rec/lev*/*/*.record.rdb*


DIAGNOSTICS

     soi_errno is set on error.



BUGS

     The structure of the AT is too tightly bound to the RDB file
     format;  more  general representations of ASCII tabular data
     should be supported.



HISTORY

     2001.07.06      SOI Version 4.8