Monster Media 1994 #1/monster.zip/monster/PROG_C/RECIO110.ZIP/TUTOR.TXT

Text File | 1994-03-28 | 12KB | 310 lines

    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.