By Daniel Morissette, dmorissette@mapgears.com
|
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. |
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:
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!
'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.
'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.
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.
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:
And the main() function for the AVCEXPORT and AVCIMPORT programs are located in the files:
Unix users:
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.
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.
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.
/**********************************************************************
* 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 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.
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().
void AVCE00ReadClose(AVCE00ReadPtr hInfo);
Closes the coverage and releases any memory associated with the
AVCE00ReadPtr handle.
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.
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.
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"
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);
}
}
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.
/**********************************************************************
* 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 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.
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 passAVC_SINGLE_PRECorAVC_DOUBLE_PRECto 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().
void AVCE00WriteClose(AVCE00writePtr hInfo);
Closes the coverage and releases any memory associated with the
AVCE00writePtr handle.
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.
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.
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).
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 );
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.
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() .
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() .
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. |