AVCE00 - Arc/Info Vector Coverage <-> E00 Library

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

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:

For the GIS developers:

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:

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:

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.

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.

Building the package

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

Windows users:

Unix users:

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:

AVCE00ReadPtr data type

AVCE00ReadOpen()

AVCE00ReadClose()

AVCE00ReadNextLine()

AVCE00ReadRewind()

AVCE00ReadSectionsList()

AVCE00ReadGotoSection()

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:

AVCE00WritePtr data type

AVCE00WriteOpen()

AVCE00WriteClose()

AVCE00WriteNextLine()

AVCE00DeleteCoverage()

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

CPLError()

CPLGetLastErrorNo()

CPLGetLastErrorMsg()

Errors generated by the library and their meaning:

The values for the error codes returned by the library are defined in the file cpl_error.h.

The following errors codes can be returned:

Error CodeDescription
0 Success, no error.
CPLE_OutOfMemory Memory allocation failed. This is a fatal error, it will abort the program execution. There is currently no proper way to recover from it.
CPLE_FileIO Unexpected error reading 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 $
Daniel Morissette, dmorissette@mapgears.com