E00compr 1.0

Table of Contents

• Copyright and License terms
• What is E00compr?
• Building the package
• Using the 'e00conv' Conversion program
• How to use the library in your programs
• Library functions to Read compressed E00 files
  • Example
  • E00ReadPtr data type
  • E00ReadOpen()
  • E00ReadCallbackOpen()
  • E00ReadClose()
  • E00ReadNextLine()
  • E00ReadRewind()
• Library functions to Write compressed E00 files
  • Example
  • E00WritePtr data type
  • E00WriteOpen()
  • E00WriteCallbackOpen()
  • E00WriteClose()
  • E00WriteNextLine()
• Trapping errors reported by the library
  • CPLSetErrorHandler()
  • CPLError()
  • CPLGetLastErrorNo()
  • CPLGetLastErrorMsg()
  • Errors generated by the library and their meaning

Copyright and License terms

The most part of the E00COMPR library is Copyright (c) 1998-2005, Daniel Morissette (dmorissette@mapgears.com)
it also contains portions (CPL lib) that are Copyright (c) 1998-1999, Frank Warmerdam (warmerdam@pobox.com)

The AVCE00 library and the supporting CPL code are freely available under the following Open Source license terms:

What is E00compr?

E00compr is an ANSI C library that reads and writes Arc/Info compressed E00 files. Both "PARTIAL" and "FULL" compression levels are supported.

This package can be divided in three parts:

• The 'e00conv' command-line program. This program takes a E00 file as input (compressed or not) and copies it to a new file with the requested compression level (NONE, PARTIAL or FULL).

• A set of library functions to read compressed E00 files. These functions read a E00 file (compressed or not) and return a stream of uncompressed lines, making the E00 file appear as if it was not compressed.

• A set of library functions to write compressed E00 files. These functions take one line after another from what should be a uncompressed E00 file, and write them to a file with the requested compression level, either NONE, PARTIAL or FULL.

Building the package

The library has already been succesfully built on Windows (with MSVC++ 4 and 5), and on Linux (with gcc).

Windows users:

A MSVC++ 4 makefile (e00compr.mak) to build the 'e00conv.exe' command-line program is included with the distribution. You should have no problem opening this file with MSVC++ and building the package directly.

MSVC++ 5 will ask you if you want to convert the makefile to the new project format. Answer "Yes" and you should be just fine.

If you are using another development environment, then you will likley need to build your own project. Include the following files in your project:

e00compr.h
e00read.c
e00write.c


cpl_port.h
cpl_conv.h
cpl_error.h
cpl_vsi.h
cpl_conv.c
cpl_error.c
cpl_vsisimple.c

Unix users:

A Makefile is included with the distribution. Its default target will build the 'e00conv' executable using gcc. Take a look at the definitions at the top of the Makefile to see if you need to modify it to build in your own environment.

In most cases, building the package should be as simple as extracting the distribution files to a empty directory, and then going to this directory and typing make.

If you encounter problems with the Makefile, then make sure that it contains Unix line breaks. The line breaks are sometimes altered when the distribution is copied between PCs and Unix systems, and Make doesn't seem to like Makefiles that contain DOS CR-LF line breaks.

Using the 'e00conv' Conversion Program

'e00conv' is a command-line executable that takes a E00 file as input (compressed or not) and copies it to a new file with the requested compression level (NONE, PARTIAL or FULL).

e00conv <input_file> <output_file> [NONE|PARTIAL|FULL]
• input_file is the name of the E00 file to read from.

• output_file is the name of the file to create. If the file already exists then it is overwritten.

• The last argument is optional and specifies the compression level to use when creating the output file (one of NONE, PARTIAL or FULL). The default is NONE (uncompressed).

How to use the library in your programs

To use the library in your programs, include the file "e00compr.h", and link with the "e00compr.a" library produced by the Unix Makefile.

If you are working in a Windows development environment (i.e. with projects, no Makefiles!) then add all the C files from the distribution to your project, except "e00conv.c".

Library functions to Read compressed E00 files

All the read functions are defined inside "e00read.c". Information about the file currently being read is stored inside an internal structure. You do not need to understand the contents of this structure to use the library.

All you need is to declare a E00ReadPtr variable which will serve as a handle on the input file for all the other functions.

You use the following functions to read a E00 file:

    E00ReadPtr  E00ReadOpen(const char *pszFname);
    void        E00ReadClose(E00ReadPtr hInfo);

    const char *E00ReadNextLine(E00ReadPtr hInfo);
    void        E00ReadRewind(E00ReadPtr hInfo);

Example:

This short example uses the library to read a E00 compressed file ("test.e00") and prints the uncompressed result to stdout.

/**********************************************************************
 *                          ex_read.c
 *
 * This example program illustrates the use of the E00ReadOpen()
 * and associated compressed E00 read functions.
 **********************************************************************/

#include <stdio.h>

#include "e00compr.h"

int main(int argc, char *argv[])
{
    E00ReadPtr  hReadPtr;
    const char  *pszLine;

    /* Open input */
    hReadPtr = E00ReadOpen("test.e00");

    if (hReadPtr)
    {
        /* Read lines from input until we reach EOF */
        while((pszLine = E00ReadNextLine(hReadPtr)) != NULL)
        {
            if (CPLGetLastErrorNo() == 0)
                printf("%s\n", pszLine);
            else
            {
                /* An error happened while reading the last line... */
                break;
            }
        }

        /* Close input file */
        E00ReadClose(hReadPtr);
    }
    else
    {
        /* ERROR ... failed to open input file */
    }

    return 0;
}
  

E00ReadPtr data type

A variable of type E00ReadPtr serves as a handle on the current input file.

The handle is allocated by E00ReadOpen(), and you must call E00ReadClose() to properly release the memory associated with it.

E00ReadOpen()

E00ReadPtr E00ReadOpen(const char *pszFname);

Opens a E00 input file and returns a E00ReadPtr handle.

The input file can be in compressed or uncompressed format. E00ReadClose() will eventually have to be called to release the returned handle.

Returns NULL if the file could not be opened or if it does not appear to be a valid E00 file.

E00ReadCallbackOpen()

E00ReadPtr  E00ReadCallbackOpen(void *pRefData,
                                const char * (*pfnReadNextLine)(void *),
                                void (*pfnReadRewind)(void *));

This is an alternative to E00ReadOpen() for cases where you have to do all the file management yourself. You open/close the file yourself and provide 2 callback functions: to read from the file and rewind the file pointer.

pRefData is your own handle on the physical file and can be whatever you want... it is not used by the library, it will be passed directly to your 2 callback functions when they are called.

The callback functions must have the following C prototype:

    const char *myReadNextLine(void *pRefData);
    void        myReadRewind(void *pRefData);
    

myReadNextLine() should return a reference to its own internal buffer, or NULL if an error happens or when EOF is reached.

E00ReadCallbackOpen() returns a E00ReadPtr handle or NULL if the file does not appear to be a valid E00 file.

For an example of the use of this method, see the file ex_readcb.c included in the library distribution.

E00ReadClose()

void E00ReadClose(E00ReadPtr hInfo);

Closes the physical file and releases any memory associated with a E00ReadPtr handle.

E00ReadNextLine()

const char *E00ReadNextLine(E00ReadPtr hInfo);

Returns the next line of input from the E00 file in uncompressed form or NULL if we reached EOF or if an error happened. The returned line is a null-terminated string, and it does not include a newline character. Call CPLGetLastErrorNo() after calling E00ReadNextLine() to make sure that the whole line was read succesfully.

Note that E00ReadNextLine() returns a reference to an internal buffer whose contents will be valid only until the next call to this function. The caller should not attempt to free() the returned pointer.

E00ReadRewind()

void E00ReadRewind(E00ReadPtr hInfo);

Rewinds the E00ReadPtr just like the stdio rewind() function would do.

Useful when you have to do multiple read passes on the same input file.

Library functions to Write compressed E00 files

The write functions are defined inside "e00write.c". The information about the file currently being written is stored inside an internal structure. As for the read library, you do not need to understand the contents of this structure to use the library.

Your program has to declare a E00WritePtr variable which will serve as a handle on the output file for all the other functions.

You use the following functions to write a E00 file:

    E00WritePtr E00WriteOpen(const char *pszFname, int nComprLevel);
    void        E00WriteClose(E00WritePtr hInfo);

    int		E00WriteNextLine(E00WritePtr hInfo, const char *pszLine);

Example:

This example is a simpler version of the "e00conv.c" program that is included with this distribution. It uses the read library to read a E00 file ("test1.e00") and uses the write library to copy its contents one line at a time to a new E00 file ("test2.e00") with FULL compression:

/**********************************************************************
 *                          ex_write.c
 *
 * This example program illustrates the use of the E00WriteOpen()
 * and associated compressed E00 write functions.
 **********************************************************************/
#include <stdio.h>

#include "e00compr.h"

int main(int argc, char *argv[])
{
    E00ReadPtr  hReadPtr;
    E00WritePtr hWritePtr;
    const char  *pszLine;
    int         nStatus = 0;

    /* Open input file */
    hReadPtr = E00ReadOpen("test1.e00");

    if (hReadPtr)
    {
        /* Open output file */
        hWritePtr = E00WriteOpen("test2.e00", E00_COMPR_FULL);

        if (hWritePtr)
        {
            /* Read lines from input until we reach EOF */
            while((pszLine = E00ReadNextLine(hReadPtr)) != NULL)
            {
                if ((nStatus = CPLGetLastErrorNo()) == 0)
                    nStatus = E00WriteNextLine(hWritePtr, pszLine);

                if (nStatus != 0)
                {
                    /* An error happened while converting the last 
                     * line... abort*/
                    break;
                }
            }
            /* Close output file. */
            E00WriteClose(hWritePtr);
        }
        else
        {
            /* ERROR ... failed to open output file */
            nStatus = CPLGetLastErrorNo();
        }

        /* Close input file. */
        E00ReadClose(hReadPtr);
    }
    else
    {
        /* ERROR ... failed to open input file */
        nStatus = CPLGetLastErrorNo();
    }

    return nStatus;
}

E00WritePtr data type

A variable of type E00WritePtr serves as a handle on the current input file.

The handle is allocated by E00WriteOpen(), and you must call E00WriteClose() to properly release the memory associated with it.

E00WriteOpen()

E00WritePtr E00WriteOpen(const char *pszFname, int nComprLevel);

Creates a new E00 file for output with the specified compression level, and returns a E00WritePtr handle for it. If the file already exists, then it is overwritten.

nComprLevel is one of Arc/Info's 3 levels of compression:

• E00_COMPR_NONE - creates an uncompressed file.
• E00_COMPR_PARTIAL - creates a file with PARTIAL compression.
• E00_COMPR_FULL - creates a file with FULL compression.

Returns NULL if the file could not be opened.

E00WriteCallbackOpen()

E00WritePtr E00WriteCallbackOpen(void *pRefData,
                                 int (*pfnWriteNextLine)(void *, const char *),
                                 int nComprLevel);

This is an alternative to E00WriteOpen() for cases where you have to do all the file management yourself. You open/close the file yourself and provide a callback function to write one line at a time to the file.

pRefData is your own handle on the physical file and can be whatever you want... it is not used by the library, it will be passed directly to your callback function when it is called.

The callback function must have the following C prototype:

    int    myWriteNextLine(void *pRefData, const char *pszLine);

myWriteNextLine() should return a positive value on success (the number of chars written, like printf() does) or -1 if an error happened.

The value passed by the library in pszLine is not terminated by a '\n' character... it is assumed that your myWriteNextLine() implementation will take care of terminating the line with a '\n' if necessary.

nComprLevel is one of Arc/Info's 3 levels of compression:
• E00_COMPR_NONE - creates an uncompressed file.
• E00_COMPR_PARTIAL - creates a file with PARTIAL compression.
• E00_COMPR_FULL - creates a file with FULL compression.

E00WriteCallbackOpen() returns a new E00ReadWritePtr handle and E00WriteClose() will eventually have to be called to release the resources used by the new handle.

For an example of the use of this method, see the file ex_writecb.c included in the library distribution.

E00WriteClose()

void E00WriteClose(E00WritePtr hInfo);

Closes the physical file and release any memory associated with a E00WritePtr handle.

E00WriteNextLine()

int E00WriteNextLine(E00WritePtr hInfo, const char *pszLine);

Takes the next line of what should be headed to a uncompressed E00 file, converts it to the requested compression level, and writes the (compressed) result to the output file.

pszLine should be a null-terminated string with a maximum of 80 characters (E00 lines cannot be longer than 80 characters). Do NOT include a '\n' at the end of the line, it will be added automatically by the function if it is needed.

Returns 0 if the line was processed succesfully, or an error number (see error codes below) if an error happened.

Note that this function does not do any syntax check on the input you provide. It assumes that what you pass to it is a valid stream of E00 lines as they would appear in an uncompressed E00 file.

Trapping errors reported by the library

When errors happen, the library's default behavior is to report an error message on stderr, and to fail nicely, usually by simulating a EOF situation. Errors are reported through the function CPLError() defined in "cpl_error.c".

While this is sufficient for the purposes of the 'e00conv' command-line program, you may want to trap and handle errors yourself if you use the library in a bigger application (a GUI application for instance).

CPLSetErrorHandler()

void  CPLSetErrorHandler(void (*pfnErrorHandler)(CPLErr, int, const char *));

You can use CPLSetErrorHandler() to override the default error handler function. Your new error handler should be a C function with the following prototype:

void MyErrorHandler(CPLErr eErrClass, int err_no, const char *msg);

And you register it with the following call at the beginning of your program:

CPLSetErrorHandler( MyErrorHandler );

CPLError()

void CPLError(CPLErr eErrClass, int err_no, const char *fmt, ...);

The library reports errors through this function. It's default behavior is to display the error messages to stderr, but it can be overridden using CPLSetErrorHandler().

You can call CPLGetLastErrorNo() or CPLGetLastErrorMsg() to get the last error number and string.

eErrClass defines the severity of the error:

    typedef enum
    {
        CE_None = 0,
        CE_Log = 1,
        CE_Warning = 2,
        CE_Failure = 3,
        CE_Fatal = 4
    } CPLErr;

Error class CE_Fatal will abort the execution of the program, it is mainly used for out of memory errors, or unrecoverable situations of that kind. All the other error classes return control to the calling function.

CPLGetLastErrorNo()

int         CPLGetLastErrorNo();

Returns the number of the last error that was produced. Returns 0 if the last library function that was called completed without any error. See the list of possible error numbers below.

Note: This function works even if you redefined your own error handler using CPLSetErrorHandler() .

CPLGetLastErrorMsg()

const char *CPLGetLastErrorMsg();

Returns a reference to a static buffer containing the last error message that was produced. The caller should not attempt to free this buffer. Returns an empty string ("") if the last library function that was called completed without any error.

Note: This function works even if you redefined your own error handler using CPLSetErrorHandler() .

Errors generated by the library and their meaning:

The values for the error codes returned by the library are defined in the file cpl_error.h.

#define CPLE_OutOfMemory		2
#define CPLE_FileIO			3
#define CPLE_OpenFailed			4
#define CPLE_IllegalArg			5
#define CPLE_NotSupported		6
#define CPLE_AssertionFailed		7

The following errors codes can be returned: