File: avce00.html

package info (click to toggle)
avce00 2.0.0-10
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 948 kB
sloc: ansic: 9,851; makefile: 3
file content (1066 lines) | stat: -rw-r--r-- 37,530 bytes
parent folder | download | duplicates (7)
<HTML>
<HEADER>
<TITLE>AVCE00 - Arc/Info Vector Coverage &lt;-&gt; E00 Library</TITLE>
</HEADER>
<BODY>
<CENTER>
 <H1>AVCE00 - 2.0.0</H1>
 <P>
 <H2>Arc/Info Vector Coverage &lt;-&gt; E00 Library</H2>
 <P>
 By Daniel Morissette, 
  <A HREF="mailto:dmorissette@mapgears.com">dmorissette@mapgears.com</A>
</CENTER>
 <HR WIDTH=50%>
<CENTER>
<I>The latest version of this documentation and of the whole package can be obtained from <A HREF="http://avce00.maptools.org/">http://avce00.maptools.org/</A></I>
</CENTER>
 <HR WIDTH=50%>

<P>

<H2>Table of Contents</H2>
<P>
<UL>
  <LI><A HREF="#license">Copyright and License terms</a>
  <LI><A HREF="#whatis">What is AVCE00?</a>
  <LI><A HREF="#supported">Supported Coverage Features</a>
  <LI><A HREF="#avcexport">Using the 'avcexport' Conversion program</a>
  <LI><A HREF="#avcimport">Using the 'avcimport' Conversion program</a>
  <LI><A HREF="#build">Building the package</a>
  <LI><A HREF="#howto-lib">How to use the library in your programs</a>
  <LI><A HREF="#libread">Library functions to read binary coverages as E00</a>
  <UL>
    <LI><A HREF="#readexample">Example</a>
    <LI><A HREF="#readptr">AVCE00ReadPtr data type</a>
    <LI><A HREF="#readopen">AVCE00ReadOpen()</a>
    <LI><A HREF="#readclose">AVCE00ReadClose()</a>
    <LI><A HREF="#readnextline">AVCE00ReadNextLine()</a>
    <LI><A HREF="#readrewind">AVCE00ReadRewind()</a>
    <LI><A HREF="#readsectionslist">AVCE00ReadSectionsList()</a>
    <LI><A HREF="#readgotosection">AVCE00ReadGotoSection()</a>
  </UL>
  <LI><A HREF="#libwrite">Library functions to create a binary coverage from 
         an E00 source</a>
  <UL>
    <LI><A HREF="#writeexample">Example</a>
    <LI><A HREF="#writeptr">AVCE00WritePtr data type</a>
    <LI><A HREF="#writeopen">AVCE00WriteOpen()</a>
    <LI><A HREF="#writeclose">AVCE00WriteClose()</a>
    <LI><A HREF="#writenextline">AVCE00WriteNextLine()</a>
    <LI><A HREF="#deletecover">AVCE00DeleteCoverage()</a>
  </UL>
  <LI><A HREF="#errors">Trapping errors reported by the library</a>
  <UL>
    <LI><A HREF="#errsethandler">CPLSetErrorHandler()</a>
    <LI><A HREF="#cplerror">CPLError()</a>
    <LI><A HREF="#errlastno">CPLGetLastErrorNo()</a>
    <LI><A HREF="#errlastmsg">CPLGetLastErrorMsg()</a>
    <LI><A HREF="#errno-read">Errors generated by the library and their
         meaning</a>
  </UL>
</UL>

<P>
<H2><A NAME="license">Copyright and License terms</A></H2>
<P>
<CENTER><TABLE WIDTH=90% BORDER=1 CELLPADDING=15><TR><TD>
<P>
 Copyright (c) 1999-2005, Daniel Morissette
<P>
 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:
<P>
 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
<P> 
 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.
</TD></TR></TABLE></CENTER>

<P>
<H2><A NAME="whatis">What is AVCE00?</A></H2>
<P>
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.
<P>
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. 
<P>
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. 
<P>
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.
<P>
This package contains 4 major components:
<P>
<B>For the GIS users:</B>
  <P>
<UL>
  <LI>The 'avcexport' command-line program reads a binary coverage and 
      converts it to a file in E00 format.
  <P>
  <LI>The 'avcimport' command-line program takes a E00 file as input 
      and creates a binary coverage from it.
</UL>
  <P>
<B>For the GIS developers:</B>
  <P>
<UL>
  <LI>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.
  <P>
  <LI>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.
</UL>
<P>
<B>And for those who are really looking for trouble:</B> <CODE>;-)</CODE> <BR>
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:
<UL>
  <LI>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.
  <P>
  <LI>A set of library functions that write to binary coverage files directly
      from structures in memory. 
  <P>
  <LI>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.
  <P>
  <LI>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.
</UL>

<P>
<H2><A NAME="supported">Supported Coverage Features</A></H2>
<P>
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.
<P>
The following Arc/Info features are expected to be properly converted from
binary to E00 format, for both single and double precision coverages:
<P>
<UL>
  <LI> ARC (arc.adf) - Arcs
  <LI> CNT (cnt.adf) - Polygon Centroids
  <LI> LAB (lab.adf) - Polygon Labels
  <LI> PAL (pal.adf) - Polygon Arc Lists
  <LI> TOL (tol.adf, par.adf) - Coverage Tolerances
  <LI> TXT/TX6/TX7 (txt.adf, *.txt) - Annotations
  <LI> PRJ (prj.adf) - Projection
  <LI> RXP/RPL (*.rxp, *.pal) - Files specific to region coverages
  <LI> INFO Tables (info directory) - Attribute tables of any type 
       (.AAT, .PAT, .NAT, .TIC, .BND, .TAT, .SEC, .RAT, etc... as well as
        internal tables)
</UL>
<P>
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!

<P>
<H2><A NAME="avcexport">Using the 'avcexport' Conversion Program</A></H2>
<P>
'avcexport' is a command-line executable that takes an Arc/Info binary
coverage as input and converts it to E00.
<P>
<UL>
<B><CODE>avcexport &lt;input_cover&gt; &lt;output_file&gt; </CODE></B>
<P>
  <UL>
    <LI><B><CODE>input_cover</CODE></B> is the path to the Arc/Info
        coverage to read from.
    <P>
    <LI><B><CODE>output_file</CODE></B> is the name of the E00 file to create.
        If the file already exists then it is overwritten.  <BR>
	Passing "-" as output_file will send the output to standard output
	(stdout).
  </UL>
</UL>

<P>
<H2><A NAME="avcimport">Using the 'avcimport' Conversion Program</A></H2>
<P>
'avcimport' is a command-line executable that takes an Arc/Info E00 file 
as input and converts it to a binary coverage.
<P>
<UL>
<B><CODE>avcimport &lt;input_file&gt; &lt;output_cover&gt; </CODE></B>
<P>
  <UL>
    <LI><B><CODE>input_file</CODE></B> is the name of the E00 file to read 
        from. <BR>
	Passing "-" as input_file will take the input from standard input
	(stdin).
    <P>
    <LI><B><CODE>output_cover</CODE></B> 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.
  </UL>
</UL>

<P>
<H2><A NAME="build">Building the package</A></H2>
<P>
The library has already been succesfully built on Windows (with MSVC++),
and on Linux (with gcc).
<P>
<B>Windows users:</B>
<P>
<UL>
  <P>
  Note: Precompiled executables for WIN32 are available on the library's
  web page at <A HREF="http://avce00.maptools.org/">http://avce00.maptools.org/</A>.  So if all you need is the AVCIMPORT and AVCEXPORT 
  programs then you should get them from there.
  <P>
  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.  
  <P>
  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:  
  <CODE>nmake /f makefile.vc</CODE>
  <P>
  Another option is to build a project in your development environment.
  Include the following files in your project for the library:
  <P>
  <UL>
    avc.h<BR>
    cpl_error.h<BR>
    cpl_conv.h<BR>
    cpl_port.h<BR>
    cpl_string.h<BR>
    cpl_vsi.h<BR>
    <BR>
    avc_e00read.c<BR>
    avc_bin.c<BR>
    avc_rawbin.c<BR>
    avc_e00gen.c<BR>
    avc_e00write.c<BR>
    avc_binwr.c<BR>
    avc_e00parse.c<BR>
    avc_misc.c<BR>
    cpl_error.c<BR>
    cpl_conv.c<BR>
    cpl_string.c<BR>
    cpl_vsisimple.c<BR>
    cpl_dir.c<BR>
  </UL>
  <P>
  And the main() function for the AVCEXPORT and AVCIMPORT programs are
  located in the files:
  <UL>
    avcexport.c<BR>
    avcimport.c<BR>
  </UL>

</UL>
<P>
<B>Unix users:</B>
<P>
<UL>
  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.
  <P>
  An important flag to set in the Makefile is the <B>byte ordering flag</B>.
  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.
  <P>
  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 <CODE>make</CODE>.
  <P>
  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.
</UL>

<P>
<H2><A NAME="howto-lib">How to use the library in your programs</A></H2>
<P>
<HR WIDTH=50%>
<CENTER>
  Note: If you are not planning to use the library in your programs, <BR>
  then you can stop reading here... <BR>
  the rest of this document won't be of any use to you!
</CENTER>
<HR WIDTH=50%>
<P>
To use the library in your programs, include the file "avc.h", and link
with the "avc.a" library produced by the Unix Makefile.
<P>
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 <A HREF="#build">building the library for Windows</A>
above for the list of files to include.


<P>
<H2><A NAME="libread">Library functions to read a coverage as if it was an E00 file</A></H2>
<P>
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.  
<P>
All you need is to declare a <B><CODE>AVCE00ReadPtr</CODE></B> variable which 
will serve as a handle on the input file for all the other functions.
<P>
You use the following functions to read a coverage as a ASCII E00 file:
<PRE>
    AVCE00ReadPtr  AVCE00ReadOpen(const char *pszCoveragePath);
    void           AVCE00ReadClose(AVCE00ReadPtr hInfo);

    const char    *AVCE00ReadNextLine(AVCE00ReadPtr hInfo);
    void           AVCE00ReadRewind(AVCE00ReadPtr hInfo);
</PRE>
<P>
You can also optionally use the 2 following functions to go directly
to the files that are of interest for you in the coverage:
<PRE>
    AVCE00Section  *AVCE00ReadSectionsList(AVCE00ReadPtr hInfo, 
                                           int *numSect);
    int             AVCE00ReadGotoSection(AVCE00ReadPtr hInfo, 
                                          AVCE00Section *psSect,
                                          GBool bContinue);
</PRE>

<P>
Each function is described after the example below.
<P>
<H3><A NAME="readexample">Example:</A></H3>
<UL>
This short <B>example</B> uses the library to read the coverage in
"data/cover1/" and convert it to E00 on stdout.
<P>
<PRE>
/**********************************************************************
 * This example program illustrates the use of the AVCE00ReadOpen()
 * and associated AVC -&gt; E00 read functions.
 **********************************************************************/

#include &lt;stdio.h&gt;

#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;
}
  </PRE>
</UL>

<P>
<H3><A NAME="readptr">AVCE00ReadPtr data type</A></H3>
<P>
<UL>
    A variable of type <CODE>AVCE00ReadPtr</CODE> serves as a handle on the
    current input file.
    <P>
    The handle is allocated by <CODE>AVCE00ReadOpen()</CODE>, and you must
    call <CODE>AVCE00ReadClose()</CODE> to properly release the memory 
    associated with it.
</UL>
<P>
<H3><A NAME="readopen">AVCE00ReadOpen()</A></H3>
<P>
<UL>
    <PRE>AVCE00ReadPtr  AVCE00ReadOpen(const char *pszCoverPath);</PRE>
    <P>
    Open a Arc/Info coverage to read it as if it was an E00 file.
    <P>
    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.
    <P>
    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.
   <P>
    The following are all valid values for pszCoverPath:
<PRE>
                /home/data/country
                /home/data/country/
                /home/data/country/arc.adf
                /home/data/info
                /home/data/info/arc.dir
</PRE>
    (Of course you should replace the '/' with '\\' on DOS systems!)
    <P>
    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.
    <P>
    The handle will eventually have to be released with AVCE00ReadClose().
</UL>
<P>
<H3><A NAME="readclose">AVCE00ReadClose()</A></H3>
<P>
<UL>
    <PRE>void           AVCE00ReadClose(AVCE00ReadPtr hInfo);</PRE>
    <P>
    Closes the coverage and releases any memory associated with the
    <CODE>AVCE00ReadPtr</CODE> handle.
</UL>
<P>
<H3><A NAME="readnextline">AVCE00ReadNextLine()</A></H3>
<P>
<UL>
    <PRE>const char    *AVCE00ReadNextLine(AVCE00ReadPtr hInfo);</PRE>
    <P>
    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.
    <P>
    Call <CODE>CPLGetLastErrorNo()</CODE> after calling
    <CODE>AVCE00ReadNextLine()</CODE> to make sure that the line was 
    generated succesfully.
    <P>
    Note that <CODE>AVCE00ReadNextLine()</CODE> 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.
</UL>
<P>
<H3><A NAME="readrewind">AVCE00ReadRewind()</A></H3>
<P>
<UL>
    <PRE>int            AVCE00ReadRewind(AVCE00ReadPtr hInfo);</PRE>
    <P>
    Rewinds the <CODE>AVCE00ReadPtr</CODE> just like the stdio 
    <CODE>rewind()</CODE> 
    function would do if you were reading an ASCII E00 file.
    Useful when you have to do multiple read passes on the same coverage.
    <P>
    Returns 0 on success, or -1 on error.
</UL>

<P>
<H3><A NAME="readsectionslist">AVCE00ReadSectionsList()</A></H3>
<P>
<UL>
<PRE>
AVCE00Section  *AVCE00ReadSectionsList(AVCE00ReadPtr hInfo, 
                                       int *numSect);
</PRE>
    <P>
    Returns an array of <CODE>AVCE00Section</CODE> structures that describe
    the squeleton of the whole coverage, with each E00 section corresponding
    to one file from the coverage.  The value of <CODE>*numSect</CODE>
    will be set to the number of items in the array.
    <P>
    The AVCE00Section structure is defined in "avc.h" as:
<PRE>
    typedef struct AVCE00Section_t 
    {
        AVCFileType eType;     /* File Type          */
        char        *pszName;  /* File or Table Name */
    }AVCE00Section;
</PRE>
    And <CODE>AVCFileType</CODE> defines the type of the file associated
    with a given E00 section:
<PRE>
    typedef enum
    {
        AVCFileUnknown = 0,
        AVCFileARC,
        AVCFilePAL,
        AVCFileCNT,
        AVCFileLAB,
        AVCFilePRJ,
        AVCFileTOL,
        AVCFileLOG,
        AVCFileTABLE
    }AVCFileType;
</PRE>
    <P>
    You can scan the returned array and use 
    <CODE>AVCE00ReadGotoSection()</CODE> to move the read pointer directly
    to the beginning of a given section of the file.
    <P>
    Sections of type <CODE>AVCFileUnknown</CODE> 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.
    <P>
    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.
    <P>
    Example: The array of sections returned for a coverage with valid
    polygon topology could take the following form:
<PRE>
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"
</PRE>
<P>
</UL>

<P>
<H3><A NAME="readgotosection">AVCE00ReadGotoSection()</A></H3>
<P>
<UL>
<PRE>
int             AVCE00ReadGotoSection(AVCE00ReadPtr hInfo, 
                                      AVCE00Section *psSect,
                                      GBool bContinue);
</PRE>
    <P>
    Moves the read pointer to the beginning of the E00 section (coverage file)
    described in the <CODE>psSect</CODE> structure.
    Call <CODE>AVCE00ReadListSections()</CODE>
    to get the list of sections for the current coverage.
    <P>
    If <CODE>bContinue=TRUE</CODE>, then reading will automatically 
    continue with the next sections 
    of the file once the requested section is finished.  Otherwise, if
    <CODE>bContinue=FALSE</CODE> then reading will stop at the end of 
    this section
    (i.e. <CODE>AVCE00ReadNextLine()</CODE> will return NULL when it 
    reaches the end of this section)
    <P>
    Sections of type <CODE>AVCFileUnknown</CODE> returned by 
    <CODE>AVCE00ReadListSections()</CODE>
    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.
    <P> 
    This function returns 0 on success or -1 on error.
    <P>
    Example: The following function would look for a .AAT table in
    a coverage and convert it to E00.
<PRE>
/**********************************************************************
 *                          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&lt;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);
    }
}

</PRE>
    <P>
</UL>


<P>
<H2><A NAME="libwrite">Library functions to create a coverage from an E00 source</A></H2>
<P>
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.  
<P>
All you need is to declare a <B><CODE>AVCE00WritePtr</CODE></B> variable which 
will serve as a handle on the input file for all the other functions.
<P>
You use the following functions to create a coverage from an E00 input:
<PRE>
    AVCE00WritePtr  AVCE00WriteOpen(const char *pszCoverPath,
                                    AVCCoverType eNewCoverType,  
				    int nPrecision);
    void            AVCE00WriteClose(AVCE00WritePtr psInfo);
    int             AVCE00WriteNextLine(AVCE00WritePtr psInfo, 
                                        const char *pszLine);
</PRE>
<P>
To overwrite an existing coverage, it should first be properly destroyed using
AVCE00DeleteCoverage():
<PRE>
    int             AVCE00DeleteCoverage(const char *pszCoverPath);
</PRE>

<P>
Each function is described after the example below.
<P>
<H3><A NAME="writeexample">Example:</A></H3>
<UL>
This short <B>example</B> uses the library to create a coverage in
"data/cover2/" from the contents of the ASCII E00 file "data/test2.e00".
<P>
<PRE>
/**********************************************************************
 * This example program illustrates the use of the AVCE00WriteOpen()
 * and the functions to use to write a binary coverage from E00 input.
 **********************************************************************/

#include &lt;stdio.h&gt;

#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;
}

</PRE>
</UL>

<P>
<H3><A NAME="writeptr">AVCE00WritePtr data type</A></H3>
<P>
<UL>
    A variable of type <CODE>AVCE00WritePtr</CODE> serves as a handle on the
    current output coverage.
    <P>
    The handle is allocated by <CODE>AVCE00WriteOpen()</CODE>, and you must
    call <CODE>AVCE00writeClose()</CODE> to properly release the memory 
    associated with it.
</UL>
<P>
<H3><A NAME="writeopen">AVCE00WriteOpen()</A></H3>
<P>
<UL>
    <PRE>AVCE00WritePtr  AVCE00WriteOpen(const char *pszCoverPath, AVCCoverType eNewCoverType, int nPrecision);</PRE>
    <P>
   Open (create) an Arc/Info coverage, ready to receive a stream
   of ASCII E00 lines and convert that to the binary coverage format.
  <P>
   Directly overwriting or updating existing coverages is not supported
   (and may quite well never be!)... you can only create new coverages.
   However, <A HREF="#deletecover">AVCE00DeleteCoverage()</A> can be used
   to cleanly destroy an existing coverage, allowing you to eventually 
   overwrite it.
  <P>
   <BLOCKQUOTE>
   <B>IMPORTANT NOTE:</B> 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.
   </BLOCKQUOTE>
  <P>
   <CODE>pszCoverPath</CODE> 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.  
   <P> 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.
  <P>
   <CODE>eNewCoverType</CODE> is the type of coverage to create.  
    Either <CODE>AVCCoverV7</CODE> to create an Arc/Info V7 (Unix) coverage
    or <CODE>AVCCoverPC</CODE> to create a PC Arc/Info coverage.
  <P>
  <B><CODE>nPrecision</CODE> SHOULD ALWAYS BE <CODE>AVC_DEFAULT_PREC</CODE></B>
              to automagically detect the source coverage's precision and 
	      use that same precision for the new coverage.  
  <P>
  <BLOCKQUOTE>
  <B>IMPORTANT NOTE</B>: 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.<BR>
             Given the way the lib is built, it should be possible to
             also pass  <CODE>AVC_SINGLE_PREC</CODE> or
	     <CODE>AVC_DOUBLE_PREC</CODE> 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!
   </BLOCKQUOTE>
  <P>
   Returns a new AVCE00WritePtr handle or NULL if the coverage could 
   not be created or if a coverage with that name already exists.
  <P>
   The handle will eventually have to be released with AVCE00ReadClose().
</UL>
<P>
<H3><A NAME="writeclose">AVCE00WriteClose()</A></H3>
<P>
<UL>
    <PRE>void  AVCE00WriteClose(AVCE00writePtr hInfo);</PRE>
    <P>
    Closes the coverage and releases any memory associated with the
    <CODE>AVCE00writePtr</CODE> handle.
</UL>
<P>
<H3><A NAME="writenextline">AVCE00WriteNextLine()</A></H3>
<P>
<UL>
    <PRE>int   AVCE00WriteNextLine(AVCE00WritePtr psInfo,  const char *pszLine);</PRE>
    <P>
    Take the next line of E00 input for this coverage, parse it and 
    write the result to the coverage.
    <P>
    <CODE>pszLine</CODE> should be a null-terminated string and should not
    be terminated by a newline character.
    <P>
   <B>Important Note:</B> 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.
   <P>
    Returns 0 on success or -1 on error.   If an error happens, then
    <CODE>CPLGetLastErrorNo()</CODE> can be used to find out what went
    wrong.
</UL>
<P>
<H3><A NAME="deletecover">AVCE00DeleteCoverage()</A></H3>
<P>
<UL>
    <PRE>int   AVCE00DeleteCoverage(const char *pszCoverPath);</PRE>
    <P>
    Delete a coverage directory, its contents, and the associated info
    tables.
    <P> 
   Note:<BR>
   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.
   <P>
    Returns 0 on success or -1 on error.   If an error happens, then
    <CODE>CPLGetLastErrorNo()</CODE> can be used to find out what went
    wrong.
</UL>
<P>

<P>
<H2><A NAME="errors">Trapping errors reported by the library</A></H2>
<P>
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 <CODE>CPLError()</CODE> defined in
"cpl_error.c".
<P>
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).
<P>
<H3><A NAME="errsethandler">CPLSetErrorHandler()</A></H3>
<P>
<UL>
<PRE>
void  CPLSetErrorHandler(void (*pfnErrorHandler)(CPLErr, int, const char *));
</PRE>
    <P>
    You can use <CODE>CPLSetErrorHandler()</CODE> to override the default error
    handler function.  Your new error handler should be a C function with the
    following prototype:
    <P>
    <UL>
<PRE>void MyErrorHandler(CPLErr eErrClass, int err_no, const char *msg);</PRE>
    </UL>
    <P>
    And you register it with the following call at the beginning of your
    program:
    <P>
    <UL><PRE>CPLSetErrorHandler( MyErrorHandler );</PRE>
    </UL>
</UL>

<P>
<H3><A NAME="cplerror">CPLError()</A></H3>
<P>
<UL>
    <PRE>void CPLError(CPLErr eErrClass, int err_no, const char *fmt, ...);</PRE>
    <P>
    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
    <CODE>CPLSetErrorHandler()</CODE>.  
    <P>
    You can call <CODE>CPLGetLastErrorNo()</CODE> or 
    <CODE>CPLGetLastErrorMsg()</CODE> to get the last error number and string.
    <P>
    <CODE>eErrClass</CODE> defines the severity of the error:
<PRE>
    typedef enum
    {
        CE_None = 0,
        CE_Log = 1,
        CE_Warning = 2,
        CE_Failure = 3,
        CE_Fatal = 4
    } CPLErr;
</PRE>
    <P>
    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.
    <P>
</UL>

<P>
<H3><A NAME="errlastno">CPLGetLastErrorNo()</A></H3>
<P>
<UL>
    <PRE>int         CPLGetLastErrorNo();</PRE>
    <P>
    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.
    <P>
    Note: This function works even if you redefined your own error handler 
    using <CODE>CPLSetErrorHandler()</CODE> .
</UL>
<P>
<H3><A NAME="errlastmsg">CPLGetLastErrorMsg()</A></H3>
<P>
<UL>
    <PRE>const char *CPLGetLastErrorMsg();</PRE>
    <P>
    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.
    <P>
    Note: This function works even if you redefined your own error handler 
    using <CODE>CPLSetErrorHandler()</CODE> .
</UL>

<P>
<H3><A NAME="errno">Errors generated by the library and their meaning:</A></H3>
<P>
The values for the error codes returned by the library are defined in
the file cpl_error.h.  
<P>
<UL><PRE>
#define CPLE_OutOfMemory		2
#define CPLE_FileIO			3
#define CPLE_OpenFailed			4
#define CPLE_IllegalArg			5
#define CPLE_NotSupported		6
</PRE></UL>
<P>
The following errors codes can be returned:
<P>
<CENTER>
<TABLE BORDER=1 WIDTH=90%>
<TR><TH>Error Code</TH><TH>Description</TH></TR>
<TR>
  <TD VALIGN=TOP>0</TD>
  <TD>Success, no error.</TD>
</TR>
<TR>
  <TD VALIGN=TOP>CPLE_OutOfMemory</TD>
  <TD> Memory allocation failed.  This is a fatal
      error, it will abort the program execution.  There is currently no 
      proper way to recover from it.
  </TD>
</TR>
<TR>
  <TD VALIGN=TOP>CPLE_FileIO</TD>
  <TD>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.
  </TD>
</TR>
<TR>
  <TD VALIGN=TOP>CPLE_OpenFailed</TD>
  <TD>Failed to open the coverage, or failed to open
      one of the files that was expected to be present in the coverage.
  </TD>
</TR>
<TR>
  <TD VALIGN=TOP>CPLE_IllegalArg</TD>
  <TD>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.
  </TD>
</TR>
<TR>
  <TD VALIGN=TOP>CPLE_NotSupported</TD>
  <TD>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.
  </TD>
</TR>
</TABLE>
</CENTER>

<P>
<HR>
Last Update: $Date: 2006/08/17 20:09:45 $
<ADDRESS>Daniel Morissette, 
<A HREF="mailto:dmorissette@mapgears.com">dmorissette@mapgears.com</A></ADDRESS>

<!-- $Id: avce00.html,v 1.17 2006/08/17 20:09:45 dmorissette Exp $ -->

</BODY>
</HTML>