Mini Table-Handling Library

Table of Contents

General Description

We often wish to open a single ASCII table file and walk through it sequentially, examining a few fields in each record. This library was designed with that in mind and to be as small and efficient as possible.

For documentation on table formatting, see the related tbl Library documentation.


Library Routines

The calls in the mtbl library are as follows:

      int   ncol   = topen   ( char *file );
		     tclose  ( );
      char *name   = tinfo   ( int   column );
      int   column = tcol    ( char *colname );
      int   status = tseek   ( int   row );
      int   status = tread   ( );
      char *value  = tval    ( int   column );

These names conflict with a UNIX standard FORTRAN tape reading library, so use a little care if you want to use them from that language.


tread() populates the tbl_rec structure from mtbl.h:

      #define TBL_MAXSTR  4096
      #define TBL_MAXCOL   128

      #define TBL_OK      0
      #define TBL_NOFILE -2
      #define TBL_COLUMN -3
      #define TBL_RDERR  -4

      struct
      {
	 char  name[TBL_MAXSTR];
	 char *dptr;
	 int   endcol;
	 int   colwd;
      }
	 tbl_rec[TBL_MAXCOL];

      char    dval[TBL_MAXSTR];

      int     ncol;

      char    tbl_rec_string[TBL_MAXSTR];
      char    tbl_hdr_string[TBL_MAXSTR];

This file only needs to be included explicity if you plan to examine the structure manually.

tbl_rec is mainly a set of pointers into dval, a copy of tbl_rec_string (the line from the file) with nulls inserted at the end of each column.

The programmer is at liberty to use this structure directly instead of the library routine tval(), which just looks up the string in a column.


Usage Example

The following is the code for a program using the mtbl library routines to examine a couple of columns in a table file.

test1.c

      #include <stdio.h>

      main()
      {
	 int    i, ncol, icol, jcol;
	 char  *value;

	 ncol = topen("test.tbl");
	 icol = tcol("fnu_25");
	 jcol = tcol("fnu_60");

	 while(tread() >= 0)
	    printf("%s %s\n",  tval(icol), tval(jcol));

	 tclose();
      }


Author: John Good
Address: jcg@ipac.caltech.edu
Last update: 01-Mar-97