# AVCE00 - 2.0.0

## Arc/Info Vector Coverage <-> E00 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 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
  - Example
  - AVCE00ReadPtr data type
  - AVCE00ReadOpen()
  - AVCE00ReadClose()
  - AVCE00ReadNextLine()
  - AVCE00ReadRewind()
  - AVCE00ReadSectionsList()
  - AVCE00ReadGotoSection()
- Library functions to create a binary coverage from an E00 source
  - Example
  - AVCE00WritePtr data type
  - AVCE00WriteOpen()
  - AVCE00WriteClose()
  - AVCE00WriteNextLine()
  - AVCE00DeleteCoverage()
- Trapping errors reported by the library
  - CPLSetErrorHandler()
  - CPLError()
  - CPLGetLastErrorNo()
  - CPLGetLastErrorMsg()
  - Errors generated by the library and their meaning

## Copyright and License terms

Copyright (c) 1999-2005, Daniel Morissette 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 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>`

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

- `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>`

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

- `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://avce00.maptools.org/. 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.

Since version 1.4.0 it is also possible to pass the path to the info directory to AVCE00ReadOpen(). In this case, a E00 stream with all the info tables (and no coverage data) will be returned.

The following are all valid values for pszCoverPath:

                    /home/data/country
                    /home/data/country/
                    /home/data/country/arc.adf
                    /home/data/info
                    /home/data/info/arc.dir

(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: $Date: 2006/08/17 20:09:45 $