# 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
- 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:

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:

- 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

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:

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

Each function is described after the example below.

### 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:

Error Code | Description
--- | ---
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 $