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.

• topen() opens the file and returns the number of columns as defined by the header record.

• tclose() closes the file.

• tinfo() returns the name of a column by index (char *NULL if the index is invalid).

• tcol() returns the index of a column by name (-1 if the name isn't found).

• tseek() jumps to the beginning of the specified row and returns 0 for OK and a value less than 0 for an error (see below).
  CAUTION: This only works for files where the header line and all records have the same number of bytes.

• tread() reads the next row and returns 0 for OK and a value less than 0 for an error (see below).

• tval() returns the value of a particular column in the current record (char *NULL if the column is invalid).

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.

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