E00compr - Compressed E00 Read/Write Library

E00compr 1.0

Compressed E00 Read/Write Library

By Daniel Morissette, dmorissette@mapgears.com


The latest version of this documentation and of the whole package can be obtained from http://avce00.maptools.org/

Table of Contents

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:

Copyright (c) 1998-2005, Daniel Morissette
Copyright (c) 1998-1999, Frank Warmerdam

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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:

Building the package

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

Windows users:

Unix users:

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).

How to use the library in your programs


Note: If you are not planning to use the library in your programs,
then you can stop reading here...
the rest of this document won't be of any use to you!

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);
Each function is described after the example below.

Example:

E00ReadPtr data type

E00ReadOpen()

E00ReadCallbackOpen()

E00ReadClose()

E00ReadNextLine()

E00ReadRewind()

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);
Each function is described after the example below.

Example:

E00WritePtr data type

E00WriteOpen()

E00WriteCallbackOpen()

E00WriteClose()

E00WriteNextLine()

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

CPLError()

CPLGetLastErrorNo()

CPLGetLastErrorMsg()

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.

The following errors codes can be returned:

Error CodeDescription
0 Success, no error.
CPLE_OutOfMemory Memory allocation failed. This is a fatal error, it will abort the program execution. There is currently no proper way to recover from it.
CPLE_FileIO Unexpected error reading or writing to a file. This can also happen if an input file is corrupt.
CPLE_OpenFailed Failed to open the input ou output file. Check for permissions, disk space, etc.
CPLE_IllegalArg
CPLE_AssertionFailed
Illegal argument passed to one of the library's functions. This is a kind of internal error that should not happen unless the lib is modified or is not used as it is expected.
CPLE_NotSupported One of the functions encountered an unsupported/unexpected case in one of the files. This error can also be a sign that the file is corrupt.


Last Update: $Date: 2009-02-24 20:03:50 $
Daniel Morissette, dmorissette@mapgears.com