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
        o Example
        o E00ReadPtr data type
        o E00ReadOpen()
        o E00ReadCallbackOpen()
        o E00ReadClose()
        o E00ReadNextLine()
        o E00ReadRewind()
   * Library functions to Write compressed E00 files
        o Example
        o E00WritePtr data type
        o E00WriteOpen()
        o E00WriteCallbackOpen()
        o E00WriteClose()
        o E00WriteNextLine()
   * Trapping errors reported by the library
        o CPLSetErrorHandler()
        o CPLError()
        o CPLGetLastErrorNo()
        o CPLGetLastErrorMsg()
        o 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
   Portions 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]

        o input_file is the name of the E00 file to read from.

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

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

        o E00_COMPR_NONE - creates an uncompressed file.
        o E00_COMPR_PARTIAL - creates a file with PARTIAL compression.
        o 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:

        o E00_COMPR_NONE - creates an uncompressed file.
        o E00_COMPR_PARTIAL - creates a file with PARTIAL compression.
        o 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      Illegal argument passed to one of the
    CPLE_AssertionFailed 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