    Title: A TUTORIAL INTRODUCTION TO THE C LANGUAGE RECIO LIBRARY
Copyright: (C) 1994 William Pierpoint
  Version: 1.10
     Date: March 28, 1994



1.0 STDIO AND RECIO

The program many people learned when first introduced to the C programming 
language was the "hello, world" program published in Kernighan and Richie's 
"The C Programming Language."  And the first line of that first program,

#include <stdio.h>

tells the compiler that the functions and macros provided by the standard 
input/output library are needed for the program.  The "hello, world" program 
uses the powerful printf statement for output.  Unfortunately printf's 
counterpart for input, scanf, looks deceptively like printf, but has many 
ways to trap to unwary programmer.  These include failure to provide the 
address of an variable, size of argument mismatched with the specification 
in the format statement, and number of arguments mismatched with the 
specification in the format statement.

Suppose you use a library that defines a boolean type as an unsigned 
character.  You develop an output module that writes variables of type 
boolean to a file,

    /* output */
    boolean state=0;
    ...
    fprintf(fp, "%6d", state);

where fp is a pointer to FILE.  Once you get the output module working, you 
decide to develop the input module to read back into the program the data 
you wrote to disk.

    /* input */
    boolean state;
    ...
    fscanf(fp, "%d", &state);
    
So, is this ok?  On one compiler this worked consistently without problems, 
but on another compiler, it overwrote the value in another variable.  Why?  
Because fscanf expects the address of an integer, not an unsigned char.  
One compiler overwrote the adjoining memory address and the other compiler 
apparently did not.  And since compilers don't do type checking on functions 
with variable number of arguments, you don't get any errors or warnings.  That 
is what is so infuriating about this type of error.  You see that another 
variable has the wrong value, you check all the code that uses the other 
variable, and you can't find anything wrong with it.  In the midst of 
development, it is hard to imagine that the problem is caused by code that 
has nothing to do with the variable containing the bad value.

The recio (record input/output) library takes a different approach to input.  
To input the boolean variable using the recio library, just write

    /* input */
    boolean state;
    ...
    state = rgeti(rp);

where rp is a pointer to REC (more about this later).  The rgeti function 
gets an integer from the input and the compiler converts it to a boolean 
when it makes the assignment.  No need to worry about crazy pointers here!

Since virtually every program has to do input or output, the stdio library 
is familiar to every C programmer.  Many functions in the recio library 
are analogous to the stdio library.  This makes the learning curve easier.

        Analogous stdio/recio components

	stdio		recio
	---------	---------
	FILE		REC
	FOPEN_MAX	ROPEN_MAX

	stdin		recin

	fopen		ropen
	fclose		rclose
	fgets		rgetrec
	fscanf		rgeti, rgetd, rgets, ...
	clearerr	rclearerr
	feof		reof
	ferror		rerror

At this time recio only includes functions for input.  So why then does it 
stand for record input/output?  Why isn't it called just reci?  Output might 
be added in a later version, and if so, we don't want to have to go through 
our code and change every reci to recio.  


2.0 EXAMPLES

2.1 Line Input

One of the first things you can do with the recio library to is to substitute 
rgetrec() for fgets() to get a line of text (record) from a file (or standard 
input).  The advantage of rgetrec() is that you don't have to go to the 
trouble to allocate space for a string buffer, or worry about the size of the 
string buffer.  The recio library handles that for you automatically.  The 
rgetrec function is like fgets() in that it gets a string from a stream, but 
it is like gets() in that it trims off the trailing newline character.

The echo program demonstrates the use of the rgetrec function.

/* echo.c - echo input to output */

#include <stdio.h>
#include <stdlib.h>

#include "recio.h"

main()
{
    /* while input continues to be available */
    while (rgetrec(recin)) {

        /* echo record buffer to output */
        puts(rrecs(recin));
    }

    /* if exited loop before end-of-file */
    if (!reof(recin)) {
        exit (EXIT_FAILURE);
    }
    return (EXIT_SUCCESS);
}

The echo program reads standard input using recin, the recio equivalent to 
stdin.  

The rgetrec function returns a pointer to the record buffer, but the echo 
program did not use a variable to hold a pointer to the string (although
it could have).  Instead, the record buffer was accessed through the rrecs 
macro, which provides a pointer to the record buffer.

Since rgetrec returns NULL on either error or end-of-file, your program 
needs to find out which condition occurred.  The echo program just exits 
with a failure status if an error occurred before the end of the file was 
reached.


2.2 Line, Word, and Character Counting

The power of the recio library comes from its facilities to break records 
into fields and from the many functions that operate on fields.  Because 
the default field delimiter is the space character (which breaks on any 
whitespace), the default behavior is equivalent to subdividing a line of 
text into words.  

The wc program counts lines, words, and characters for files specified 
on the command line.

/* wc.c - count lines, words, characters */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "recio.h"

#define SIZE_T_MAX (~(size_t)0)

main(int argc, char *argv[])
{
    int  nf;    /* number of files */
    REC *rp;    /* pointer to open record stream */
    long nc,    /* number of characters */
         nw,    /* number of words */
         nl;    /* number of lines */
    
    /* loop through all files */
    for (nf=1; nf < argc; nf++) {
    
        /* open record stream */
        rp = ropen(argv[nf], "r");
        if (!rp) {
            if (errno == ENOENT) {
                printf("ERROR: Could not open %s\n", argv[nf]);
                continue;
            } else {
                printf("FATAL ERROR: %s\n", strerror(errno));
                exit (EXIT_FAILURE);
            }
        }
 
        /* initialize */
        nc = nw = 0;
        rsetfldch(rp, ' ');
        rsettxtch(rp, ' ');

        /* loop through all lines (records) */
        while (rgetrec(rp)) {
        
            /* count number of characters in line w/o '\n' */
            nc += strlen(rrecs(rp));
        
            /* count actual number of words (fields) */
            nw += rskipnfld(rp, SIZE_T_MAX);
        }

        /* if exited loop on error rather than end-of-file */
        if (rerror(rp)) {
            printf("FATAL ERROR: %s\n", strerror(rerror(recin)));
            exit (EXIT_FAILURE);
        }

        /* get number of lines (records) */
        nl = rrecno(rp);

        /* adjust nc for operating system line termination character(s) */
#ifdef __MSDOS__
        nc += nl + nl;  /* carriage return and linefeed for each line */
#else
        nc += nl;       /* newline for each line */
#endif

        /* output results */
        printf("%s: %ld %ld %ld\n", rnames(rp), nl, nw, nc);
        
        /* close record stream */
        rclose(rp);
    }
    return (EXIT_SUCCESS);
}

If ropen() fails, the wc program goes to the trouble to check errno for 
ENOENT rather than just assuming that the failure was caused by a missing 
file.  

The wc program also sets the field and text delimiters even though it is 
unneccessary here since they are the same as the default values.  If you 
wanted to read a comma-delimited file, you could set the the delimiters to,

    rsetfldch(rp, ',');
    rsettxtch(rp, '"');

which allows you to also read text fields containing commas by delimiting 
the text with quotes, such as "Hello, World."

Fields are counted using the rskipnfld function.  The program asks the 
function to skip more fields than could possibly exist in the record and 
the function returns with the number of fields actually skipped.  The 
rskipnfld function can be handy to have around.  You might have a data file 
with dozens of fields in a record but your program only needs a couple of 
them.  You can use rskipnfld() to skip over the fields you don't need to read.

The recio library gives you more control over your input data than stdio.  
If the last field is missing from a data file, fscanf() starts reading the 
next line.  In a file with a complex structure, it can be difficult to tell 
where you are.  Sometimes every record in a file has a different format.  
The recio library has functions you can use to always find out where you are.  
You only move from record to record when you use the rgetrec function.

Note that the wc program assumes that each line ends with a line terminator.  
That assumption may not be correct as the last line could end with the 
file terminator, in which case the character count is off by one or two.


2.3 Field Functions

For most programs you will want to use those recio functions that read data 
from the fields of a record.  Functions are available to read integer, 
unsigned integer, long, unsigned long, double, float, character, and string 
fields.  Functions are divided into two groups: those that read character 
delimited fields (such as comma-delimited) and those that read column 
delimited fields (such as an integer between columns 0 and 9).  Each group 
is further divided into two subgroups: one for numeric data in base 10 and 
the other for numeric data in any base from 2 to 36.  See the text files 
USAGE.TXT and SPEC.TXT for more information.

If you explore the source code for the recio library, you will find that the 
field functions can easily be extended for other data types.  For example 
you could define, in one line of code, a function that would get a boolean 
variable and that function would generate an ERANGE error if the value was 
anything other than 0 or 1.  See the file DESIGN.TXT for more information.  
Of course if you are not concerned with validation, you can always use 
rgeti().


2.4 Error Handling

Rather than checking errno and rerror() for errors after each call to a recio 
function, or checking the return value from those functions that return an 
error value, you can register a callback error function using the rseterrfn 
function.  The error function gives you one convenient place to handle all 
recio errors.  As you write your error function, you will find that the recio 
library provides many useful functions for determining and reporting the 
location and type of error.

One important kind of error is the data error.  Data errors occur when data 
values are too large or too small, when fields contain illegal characters, or 
when data is missing.  Your error function can correct data errors either 
through algorithms you supply or by asking the user for a replacement value.  

For an example of a callback error function, see the TEST.C source code.  
A skeleton code structure for a callback error function is given in the 
file DESIGN.TXT.


3.0 WHAT NOW?

That's it for this brief introduction.  Next, if you haven't already done 
so, spend a few minutes running TEST.EXE, inputting various data values 
(both valid and invalid) to see what happens, and perusing the TEST.C source 
code.  Then to study the recio functions in more detail, move on to the 
remaining documentation.
