                                AVCE00 - 1.0

                  Arc/Info Vector Coverage <-> E00 Library

                 By Daniel Morissette, danmo@videotron.ca
                   --------------------------------------
  The latest version of this documentation and of the whole package can be
        obtained from http://pages.infinit.net/danmo/e00/index.html
                   --------------------------------------

Table of Contents

   * Copyright and License terms
   * What is AVCE00?
   * Supported Coverage Features
   * Using the 'avcexport' Conversion program
   * Using the 'avcimport' Conversion program
   * Building the package
   * How to use the library in your programs
   * Library functions to read binary coverages as E00
        o Example
        o AVCE00ReadPtr data type
        o AVCE00ReadOpen()
        o AVCE00ReadClose()
        o AVCE00ReadNextLine()
        o AVCE00ReadRewind()
        o AVCE00ReadSectionsList()
        o AVCE00ReadGotoSection()
   * Library functions to create a binary coverage from an E00 source
        o Example
        o AVCE00WritePtr data type
        o AVCE00WriteOpen()
        o AVCE00WriteClose()
        o AVCE00WriteNextLine()
        o AVCE00DeleteCoverage()
   * 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

      Copyright (c) 1999, Daniel Morissette

      All rights reserved. This software may be copied or
      reproduced, in all or in part, without the prior written
      consent of its author, Daniel Morissette (danmo@videotron.ca).
      However, any material copied or reproduced must bear the
      original copyright notice (above), this original paragraph,
      and the original disclaimer (below).

      The entire risk as to the results and performance of the
      software, supporting text and other information contained in
      this file (collectively called the "Software") is with the
      user. Although considerable efforts have been used in
      preparing the Software, the author does not warrant the
      accuracy or completeness of the Software. In no event will the
      author be liable for damages, including loss of profits or
      consequential damages, arising out of the use of the Software.

What is AVCE00?

AVCE00 is an ANSI C library that makes Arc/Info binary coverages appear as
ASCII E00. It can be used to read existing binary coverages or create new
ones. The library has been designed in a way that it can be easily plugged
into an existing E00 translator that you want to extend to support binary
coverages.

In read mode, AVCE00 reads an Arc/Info binary coverage and makes it appear
as an ASCII E00 files. In other words, you use the library to open a binary
coverage for reading, and you read from it one line at a time just like if
you had opened the ASCII E00 file corresponding to this coverage.

In write mode AVCE00 takes E00 lines as input and writes the result to a
binary coverage. When you use the library for writing you create a new
binary coverage and write E00 lines to it... the library takes care of
converting the E00 to binary coverage format and to create all the
necessary coverage and info files.

Note: Writing to existing coverages (i.e. update) is not supported. You can
only read existing coverages, or create new ones using the current version
of the library.

This package contains 4 major components:

For the GIS users:

   * The 'avcexport' command-line program reads a binary coverage and
     converts it to a file in E00 format.

   * The 'avcimport' command-line program takes a E00 file as input and
     creates a binary coverage from it.

For the GIS developers:

   * A simple set of C library functions that make a binary coverage appear
     as an ASCII E00 file. These functions read a binary coverage and
     return a stream of E00 lines, making the coverage appear as an E00
     file.

   * Another set of C functions that can create a binary coverage from an
     E00 input. You write E00 lines (one line at a time) using these
     functions, and the E00 input is written as a binary coverage.

And for those who are really looking for trouble: ;-)
The read and write library can also be divided into sub-components that are
not documented here but could be used as standalone components in other
translators:

   * A set of library functions that read binary coverage files directly
     into structures in memory. This part could eventually be used as a
     base for a translator that converts binary coverage files to another
     format, or even to allow random access to the files in a coverage.

   * A set of library functions that write to binary coverage files
     directly from structures in memory.

   * A set of library functions that generate E00 lines from these same
     structures in memory. These functions could be used as a base for a
     translator that generates E00 files from another format.

   * A set of library functions that parse E00 lines and generate the
     appropriate structures in memory. These functions could be used as a
     base for a translator that converts E00 files to another format.

Supported Coverage Features

Since the coverage file's format is not documented by ESRI, this library is
based on the analysis of binary dumps of the files... this implies that
support for some features may be incomplete (or even inaccurate!) in some
cases. Of course, it is expected that the lib. will evolve as we (the whole
GIS community) learn more about the format.

The following Arc/Info features are expected to be properly converted from
binary to E00 format, for both single and double precision coverages:

   * ARC (arc.adf) - Arcs
   * CNT (cnt.adf) - Polygon Centroids
   * LAB (lab.adf) - Polygon Labels
   * PAL (pal.adf) - Polygon Arc Lists
   * TOL (tol.adf, par.adf) - Coverage Tolerances
   * TXT/TX6/TX7 (txt.adf, *.txt) - Annotations
   * PRJ (prj.adf) - Projection
   * RXP/RPL (*.rxp, *.pal) - Files specific to region coverages
   * INFO Tables (info directory) - Attribute tables of any type (.AAT,
     .PAT, .NAT, .TIC, .BND, .TAT, .SEC, .RAT, etc... as well as internal
     tables)

If you use the library and encounter unsupported features, then please
report the problem and I'll try to add support for that new case... this
will just make the whole library better!

Using the 'avcexport' Conversion Program

'avcexport' is a command-line executable that takes an Arc/Info binary
coverage as input and converts it to E00.

     avcexport <input_cover> <output_file>

        o input_cover is the path to the Arc/Info coverage to read from.

        o output_file is the name of the E00 file to create. If the file
          already exists then it is overwritten.
          Passing "-" as output_file will send the output to standard
          output (stdout).

Using the 'avcimport' Conversion Program

'avcimport' is a command-line executable that takes an Arc/Info E00 file as
input and converts it to a binary coverage.

     avcimport <input_file> <output_cover>

        o input_file is the name of the E00 file to read from.
          Passing "-" as input_file will take the input from standard input
          (stdin).

        o output_cover is the path to the Arc/Info coverage to create. The
          program cannot write to (or overwrite) an existing coverage, so
          you have to make sure that the coverage name does not already
          exist.

Building the package

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

Windows users:

     Note: Precompiled executables for WIN32 are available on the library's
     web page at http://pages.infinit.net/danmo/e00/. So if all you need is
     the AVCIMPORT and AVCEXPORT programs then you should get them from
     there.

     For the developers using MSVC++, a NMAKE makefile (makefile.vc) to
     build the library and the 'avcexport.exe' and 'avcimport.exe'
     command-line programs is included with the distribution.

     To build the package using the makefile and NMAKE: open a DOS prompt
     window, run the VCVARS32.BAT script to initialize the VC++ environment
     variables, and start the build with the command: nmake /f makefile.vc

     Another option is to build a project in your development environment.
     Include the following files in your project for the library:

          avc.h
          cpl_error.h
          cpl_conv.h
          cpl_port.h
          cpl_string.h
          cpl_vsi.h

          avc_e00read.c
          avc_bin.c
          avc_rawbin.c
          avc_e00gen.c
          avc_e00write.c
          avc_binwr.c
          avc_e00parse.c
          avc_misc.c
          cpl_error.c
          cpl_conv.c
          cpl_string.c
          cpl_vsisimple.c
          cpl_dir.c

     And the main() function for the AVCEXPORT and AVCIMPORT programs are
     located in the files:
          avcexport.c
          avcimport.c

Unix users:

     A GNUmakefile is included with the distribution. Its default target
     will build the 'e00export' and 'e00import' executables 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.

     An important flag to set in the Makefile is the byte ordering flag.
     The Makefile's default behavior is to build for systems with LSB first
     (Intel ordering). If you are building the library on a platform with
     MSB first (on a SUN for instance) then you will need to define the
     CPL_MSB flag in the Makefile.

     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.

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 "avc.h", and link
with the "avc.a" library produced by the Unix Makefile.

If you are working in a Windows development environment (i.e. with
projects, no Makefiles!) then include the C files from the library in your
project. See the section about building the library for Windows above for
the list of files to include.

Library functions to read a coverage as if it was an E00 file

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 AVCE00ReadPtr variable which will serve as a
handle on the input file for all the other functions.

You use the following functions to read a coverage as a ASCII E00 file:

    AVCE00ReadPtr  AVCE00ReadOpen(const char *pszCoveragePath);
    void           AVCE00ReadClose(AVCE00ReadPtr hInfo);

    const char    *AVCE00ReadNextLine(AVCE00ReadPtr hInfo);
    void           AVCE00ReadRewind(AVCE00ReadPtr hInfo);

You can also optionally use the 2 following functions to go directly to the
files that are of interest for you in the coverage:

    AVCE00Section  *AVCE00ReadSectionsList(AVCE00ReadPtr hInfo,
                                           int *numSect);
    int             AVCE00ReadGotoSection(AVCE00ReadPtr hInfo,
                                          AVCE00Section *psSect,
                                          GBool bContinue);

Each function is described after the example below.

Example:

     This short example uses the library to read the coverage in
     "data/cover1/" and convert it to E00 on stdout.

     /**********************************************************************
      * This example program illustrates the use of the AVCE00ReadOpen()
      * and associated AVC -> E00 read functions.
      **********************************************************************/

     #include <stdio.h>

     #include "avc.h"

     int main(int argc, char *argv[])
     {
         AVCE00ReadPtr hReadInfo;
         const char    *pszLine;

         /* Open input */
         hReadInfo = AVCE00ReadOpen("data/cover1/");

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

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

         return 0;
     }


AVCE00ReadPtr data type

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

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

AVCE00ReadOpen()

     AVCE00ReadPtr  AVCE00ReadOpen(const char *pszCoverPath);

     Open a Arc/Info coverage to read it as if it was an E00 file.

     You can either pass the name of the coverage directory, or the path to
     one of the files in the coverage directory. The name of the coverage
     MUST be included in pszCoverPath... this means that passing "." is
     invalid.

     The following are all valid values for pszCoverPath:

                     /home/data/country
                     /home/data/country/
                     /home/data/country/arc.adf

     (Of course you should replace the '/' with '\\' on DOS systems!)

     Returns a new AVCE00ReadPtr handle or NULL if the coverage could not
     be opened or if it does not appear to be a valid Arc/Info coverage.

     The handle will eventually have to be released with AVCE00ReadClose().

AVCE00ReadClose()

     void           AVCE00ReadClose(AVCE00ReadPtr hInfo);

     Closes the coverage and releases any memory associated with the
     AVCE00ReadPtr handle.

AVCE00ReadNextLine()

     const char    *AVCE00ReadNextLine(AVCE00ReadPtr hInfo);

     Returns the next line of the E00 representation of the coverage or
     NULL when there are no more lines to generate, 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 AVCE00ReadNextLine() to make
     sure that the line was generated succesfully.

     Note that AVCE00ReadNextLine() 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.

AVCE00ReadRewind()

     int            AVCE00ReadRewind(AVCE00ReadPtr hInfo);

     Rewinds the AVCE00ReadPtr just like the stdio rewind() function would
     do if you were reading an ASCII E00 file. Useful when you have to do
     multiple read passes on the same coverage.

     Returns 0 on success, or -1 on error.

AVCE00ReadSectionsList()

     AVCE00Section  *AVCE00ReadSectionsList(AVCE00ReadPtr hInfo,
                                            int *numSect);

     Returns an array of AVCE00Section structures that describe the
     squeleton of the whole coverage, with each E00 section corresponding
     to one file from the coverage. The value of *numSect will be set to
     the number of items in the array.

     The AVCE00Section structure is defined in "avc.h" as:

         typedef struct AVCE00Section_t
         {
             AVCFileType eType;     /* File Type          */
             char        *pszName;  /* File or Table Name */
         }AVCE00Section;

     And AVCFileType defines the type of the file associated with a given
     E00 section:

         typedef enum
         {
             AVCFileUnknown = 0,
             AVCFileARC,
             AVCFilePAL,
             AVCFileCNT,
             AVCFileLAB,
             AVCFilePRJ,
             AVCFileTOL,
             AVCFileLOG,
             AVCFileTABLE
         }AVCFileType;

     You can scan the returned array and use AVCE00ReadGotoSection() to
     move the read pointer directly to the beginning of a given section of
     the file.

     Sections of type AVCFileUnknown correspond to lines in the E00 output
     that are not directly linked to any file, like the "EXP 0" line, the
     "IFO X", "SIN X", etc.

     THE RETURNED ARRAY IS AN INTERNAL STRUCTURE AND SHOULD NOT BE MODIFIED
     OR FREED BY THE CALLER... its contents will be valid for as long as
     the coverage will remain open.

     Example: The array of sections returned for a coverage with valid
     polygon topology could take the following form:

     numSections = 17
     Sect[0]:  eType = AVCFileUnknown  pszName = "EXP  0"
     Sect[1]:  eType = AVCFileARC      pszName = "arc.adf"
     Sect[2]:  eType = AVCFilePAL      pszName = "pal.adf"
     Sect[3]:  eType = AVCFileCNT      pszName = "cnt.adf"
     Sect[4]:  eType = AVCFileLAB      pszName = "lab.adf"
     Sect[5]:  eType = AVCFileTOL      pszName = "tol.adf"
     Sect[6]:  eType = AVCFileUnknown  pszName = "SIN  2"
     Sect[7]:  eType = AVCFileUnknown  pszName = "EOX"
     Sect[8]:  eType = AVCFilePRJ      pszName = "prj.adf"
     Sect[9]:  eType = AVCFileUnknown  pszName = "IFO  2"
     Sect[10]: eType = AVCFileTABLE    pszName = "TEST.AAT                        "
     Sect[11]: eType = AVCFileTABLE    pszName = "TEST.PAT                        "
     Sect[12]: eType = AVCFileTABLE    pszName = "TEST.NAT                        "
     Sect[13]: eType = AVCFileTABLE    pszName = "TEST.BND                        "
     Sect[14]: eType = AVCFileTABLE    pszName = "TEST.TIC                        "
     Sect[15]: eType = AVCFileUnknown  pszName = "EOI"
     Sect[16]: eType = AVCFileUnknown  pszName = "EOS"

AVCE00ReadGotoSection()

     int             AVCE00ReadGotoSection(AVCE00ReadPtr hInfo,
                                           AVCE00Section *psSect,
                                           GBool bContinue);

     Moves the read pointer to the beginning of the E00 section (coverage
     file) described in the psSect structure. Call AVCE00ReadListSections()
     to get the list of sections for the current coverage.

     If bContinue=TRUE, then reading will automatically continue with the
     next sections of the file once the requested section is finished.
     Otherwise, if bContinue=FALSE then reading will stop at the end of
     this section (i.e. AVCE00ReadNextLine() will return NULL when it
     reaches the end of this section)

     Sections of type AVCFileUnknown returned by AVCE00ReadListSections()
     correspond to lines in the E00 output that are not directly linked to
     any coverage file, like the "EXP 0" line, the "IFO X", "SIN X", etc.
     You can jump to these sections or any other one without problems.

     This function returns 0 on success or -1 on error.

     Example: The following function would look for a .AAT table in a
     coverage and convert it to E00.

     /**********************************************************************
      *                          ConvertAATonly()
      *
      * Look for a .AAT table in the coverage, and if we find one then
      * convert it to E00 on stdout.
      **********************************************************************/
     static void ConvertAATOnly(const char *pszFname)
     {
         AVCE00ReadPtr   hReadInfo;
         AVCE00Section  *pasSect;
         const char     *pszLine;
         int             i, numSect;
         GBool           bFound;

         hReadInfo = AVCE00ReadOpen(pszFname);

         if (hReadInfo)
         {
             /* Fetch the list of E00 sections for the coverage, and
              * try to find a .AAT table in it.
              */
             pasSect = AVCE00ReadSectionsList(hReadInfo, &numSect);
             bFound = FALSE;
             for(i=0; i<numSect; i++)
             {
                 if (pasSect[i].eType == AVCFileTABLE &&
                     strstr(pasSect[i].pszName, ".AAT") != NULL)
                 {
                     /* Found it!  Move the read pointer to the beginning
                      * of the .AAT table, and tell the lib to stop reading
                      * at the end of table (3rd argument=FALSE)
                      */
                     bFound = TRUE;
                     AVCE00ReadGotoSection(hReadInfo, &(pasSect[i]), FALSE);
                     break;
                 }
             }

             if (bFound)
             {
                 /* Convert the .AAT table to E00.  AVCE00ReadNextLine()
                  * will return NULL at the end of the table.
                  */
                 while ((pszLine = AVCE00ReadNextLine(hReadInfo)) != NULL)
                 {
                     printf("%s\n", pszLine);
                 }
             }
             else
             {
                 printf("No .AAT table found in this coverage!\n");
             }

             AVCE00ReadClose(hReadInfo);
         }
     }

Library functions to create a coverage from an E00 source

Information about the coverage currently being written 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 AVCE00WritePtr variable which will serve as a
handle on the input file for all the other functions.

You use the following functions to create a coverage from an E00 input:

    AVCE00WritePtr  AVCE00WriteOpen(const char *pszCoverPath,
                                    AVCCoverType eNewCoverType,
                                    int nPrecision);
    void            AVCE00WriteClose(AVCE00WritePtr psInfo);
    int             AVCE00WriteNextLine(AVCE00WritePtr psInfo,
                                        const char *pszLine);

To overwrite an existing coverage, it should first be properly destroyed
using AVCE00DeleteCoverage():

    int             AVCE00DeleteCoverage(const char *pszCoverPath);

Each function is described after the example below.

Example:

     This short example uses the library to create a coverage in
     "data/cover2/" from the contents of the ASCII E00 file
     "data/test2.e00".

     /**********************************************************************
      * This example program illustrates the use of the AVCE00WriteOpen()
      * and the functions to use to write a binary coverage from E00 input.
      **********************************************************************/

     #include <stdio.h>

     #include "avc.h"

     int main()
     {
         FILE           *fpIn;
         AVCE00WritePtr hWritePtr;
         const char     *pszLine;
         int            nStatus = 0;

         /* Open input file */
         fpIn = fopen("data/test2.e00", "rt");

         if (fpIn)
         {
             /* Open output file */
             hWritePtr = AVCE00WriteOpen("data/cover2", AVCCoverV7,
                                         AVC_DEFAULT_PREC);

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

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

             /* Close input file. */
             fclose(fpIn);
         }
         else
         {
             /* ERROR ... failed to open input file */
             nStatus = -1;
         }

         return nStatus;
     }

AVCE00WritePtr data type

     A variable of type AVCE00WritePtr serves as a handle on the current
     output coverage.

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

AVCE00WriteOpen()

     AVCE00WritePtr  AVCE00WriteOpen(const char *pszCoverPath, AVCCoverType eNewCoverType, int nPrecision);

     Open (create) an Arc/Info coverage, ready to receive a stream of ASCII
     E00 lines and convert that to the binary coverage format.

     Directly overwriting or updating existing coverages is not supported
     (and may quite well never be!)... you can only create new coverages.
     However, AVCE00DeleteCoverage() can be used to cleanly destroy an
     existing coverage, allowing you to eventually overwrite it.

          IMPORTANT NOTE: The E00 source lines are assumed to be
          valid... the library performs no validation on the
          consistency of what it is given as input (i.e. topology,
          polygons consistency, etc.). So the coverage that will be
          created will be only as good as the E00 input that was used
          to generate it.

     pszCoverPath MUST be the name of the coverage directory, including the
     path to it. (Contrary to AVCE00ReadOpen(), you cannot pass the name of
     one of the files in the coverage directory). The name of the coverage
     MUST be included in pszCoverPath... this means that passing "." is
     invalid.

     Also note that to be valid, a coverage name cannot be longer than 13
     characters and can contain only alphanumerical characters and '_'
     (underscore). Spaces and '.' (dots) should be specially avoided inside
     coverage names.

     eNewCoverType is the type of coverage to create. Either AVCCoverV7 to
     create an Arc/Info V7 (Unix) coverage or AVCCoverPC to create a PC
     Arc/Info coverage.

     nPrecision SHOULD ALWAYS BE AVC_DEFAULT_PREC to automagically detect
     the source coverage's precision and use that same precision for the
     new coverage.

          IMPORTANT NOTE: The nPrecision parameter is there only to
          allow future enhancements of the library. It should
          eventually be possible to create coverages with a precision
          different from the one of the source E00.
          Given the way the lib is built, it should be possible to
          also pass AVC_SINGLE_PREC or AVC_DOUBLE_PREC to explicitly
          request the creation of a coverage with that precision, but
          the library does not (not yet!) properly convert the TABLE
          attributes' precision, and the resulting coverage may be
          invalid in some cases. This improvement is on the ToDo list!

     Returns a new AVCE00WritePtr handle or NULL if the coverage could not
     be created or if a coverage with that name already exists.

     The handle will eventually have to be released with AVCE00ReadClose().

AVCE00WriteClose()

     void  AVCE00WriteClose(AVCE00writePtr hInfo);

     Closes the coverage and releases any memory associated with the
     AVCE00writePtr handle.

AVCE00WriteNextLine()

     int   AVCE00WriteNextLine(AVCE00WritePtr psInfo,  const char *pszLine);

     Take the next line of E00 input for this coverage, parse it and write
     the result to the coverage.

     pszLine should be a null-terminated string and should not be
     terminated by a newline character.

     Important Note: The E00 source lines are assumed to be valid... the
     library performs no validation on the consistency of what it is given
     as input (i.e. topology, polygons consistency, etc.). So the coverage
     that will be created will be only as good as the E00 input that was
     used to generate it.

     Returns 0 on success or -1 on error. If an error happens, then
     CPLGetLastErrorNo() can be used to find out what went wrong.

AVCE00DeleteCoverage()

     int   AVCE00DeleteCoverage(const char *pszCoverPath);

     Delete a coverage directory, its contents, and the associated info
     tables.

     Note:
     When deleting tables, only the ../info/arc????.nit and arc????.dat
     will be deleted; the entries in the arc.dir will not be updated. This
     is apparently what Arc/Info's KILL command does.

     Returns 0 on success or -1 on error. If an error happens, then
     CPLGetLastErrorNo() can be used to find out what went wrong.

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 'avcexport' and
'avcimport' command-line programs, 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

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 to a file. This is more
                      likely to happen if one of the files is corrupt
                      which could result in an attempt to read past
                      EOF.
    CPLE_OpenFailed   Failed to open the coverage, or failed to open
                      one of the files that was expected to be present
                      in the coverage.
    CPLE_IllegalArg   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
                      coverage files. This error can also be a sign
                      that the file is corrupt.

  ------------------------------------------------------------------------
Last Update: December 4, 1999
Daniel Morissette, danmo@videotron.ca
