You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
434 lines
15 KiB
434 lines
15 KiB
<html> |
|
<head> |
|
<title>Attribute (.DBF) API</title> |
|
</head> |
|
<body> |
|
<h1>Attribute (.DBF) API</h1> |
|
|
|
The Attribute (DBF) API uses DBFHandle to represent a handle for access |
|
to one .dbf file. The contents of the DBFHandle are visible (see shapefil.h) |
|
but should be ignored by the application. It is intended that all information |
|
be accessed by API functions. Note that there should be exactly one record |
|
in the .dbf file for each shape in the .shp/.shx files. This constraint |
|
must be maintained by the application.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFOpen()</h2> |
|
|
|
<pre> |
|
DBFHandle DBFOpen( const char * pszDBFFile, const char * pszAccess ); |
|
|
|
pszDBFFile: The name of the xBase (.dbf) file to access. |
|
|
|
pszAccess: The fopen() style access string. At this time only |
|
"rb" (read-only binary) and "rb+" (read/write binary) |
|
should be used. |
|
</pre> |
|
|
|
The DBFOpen() function should be used to establish access to an existing |
|
xBase format table file. The returned DBFHandle is passed to other |
|
access functions, and DBFClose() should be invoked to recover resources, and |
|
flush changes to disk when complete. The DBFCreate() function should |
|
called to create new xBase files. As a convenience, DBFOpen() can be |
|
called with the name of a .shp or .shx file, and it will figure out the |
|
name of the related .dbf file.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFCreate()</h2> |
|
|
|
<pre> |
|
DBFHandle DBFCreate( const char * pszDBFFile ); |
|
|
|
pszDBFFile: The name of the xBase (.dbf) file to create. |
|
</pre> |
|
|
|
The DBFCreate() function creates a new xBase format file with the given |
|
name, and returns an access handle that can be used with other DBF functions. |
|
The newly created file will have no fields, and no records. Fields should |
|
be added with DBFAddField() before any records add written. |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFGetFieldCount()</h2> |
|
|
|
<pre> |
|
int DBFGetFieldCount( DBFHandle hDBF ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned |
|
by DBFOpen(), or DBFCreate(). |
|
</pre> |
|
|
|
The DBFGetFieldCount() function returns the number of fields currently |
|
defined for the indicated xBase file. |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFGetRecordCount()</h2> |
|
|
|
<pre> |
|
int DBFGetRecordCount( DBFHandle hDBF ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
</pre> |
|
|
|
The DBFGetRecordCount() function returns the number of records that |
|
exist on the xBase file currently. Note that with shape files one xBase |
|
record exists for each shape in the .shp/.shx files.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFGetFieldIndex()</h2> |
|
|
|
<pre> |
|
int DBFGetFieldIndex( DBFHandle hDBF, const char *pszFieldName ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
pszFieldName: Name of the field to search for. |
|
</pre> |
|
|
|
Returns the index of the field matching this name, or -1 on failure. The |
|
comparison is case insensitive. However, lengths must match exactly.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFGetFieldInfo()</h2> |
|
|
|
<pre> |
|
DBFFieldType DBFGetFieldInfo( DBFHandle hDBF, int iField, char * pszFieldName, |
|
int * pnWidth, int * pnDecimals ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iField: The field to be queried. This should be a number between |
|
0 and n-1, where n is the number fields on the file, as |
|
returned by DBFGetFieldCount(). |
|
|
|
pszFieldName: If this pointer is not NULL the name of the requested field |
|
will be written to this location. The pszFieldName buffer |
|
should be at least 12 character is size in order to hold |
|
the longest possible field name of 11 characters plus a |
|
terminating zero character. |
|
|
|
pnWidth: If this pointer is not NULL, the width of the requested field |
|
will be returned in the int pointed to by pnWidth. This is |
|
the width in characters. |
|
|
|
pnDecimals: If this pointer is not NULL, the number of decimal places |
|
precision defined for the field will be returned. This is |
|
zero for integer fields, or non-numeric fields. |
|
</pre> |
|
|
|
The DBFGetFieldInfo() returns the type of the requested field, which is |
|
one of the DBFFieldType enumerated values. As well, the field name, and |
|
field width information can optionally be returned. The field type returned |
|
does not correspond one to one with the xBase field types. For instance |
|
the xBase field type for Date will just be returned as being FTInteger. <p> |
|
|
|
<pre> |
|
typedef enum { |
|
FTString, /* fixed length string field */ |
|
FTInteger, /* numeric field with no decimals */ |
|
FTDouble, /* numeric field with decimals */ |
|
FTLogical, /* logical field. */ |
|
FTInvalid /* not a recognised field type */ |
|
} DBFFieldType; |
|
</pre> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFAddField()</h2> |
|
|
|
<pre> |
|
int DBFAddField( DBFHandle hDBF, const char * pszFieldName, |
|
DBFFieldType eType, int nWidth, int nDecimals ); |
|
|
|
hDBF: The access handle for the file to be updated, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
pszFieldName: The name of the new field. At most 11 character will be used. |
|
In order to use the xBase file in some packages it may be |
|
necessary to avoid some special characters in the field names |
|
such as spaces, or arithmetic operators. |
|
|
|
eType: One of FTString, FTInteger or FTDouble in order to establish |
|
the type of the new field. Note that some valid xBase field |
|
types cannot be created such as date fields. |
|
|
|
nWidth: The width of the field to be created. For FTString fields this |
|
establishes the maximum length of string that can be stored. |
|
For FTInteger this establishes the number of digits of the |
|
largest number that can |
|
be represented. For FTDouble fields this in combination |
|
with the nDecimals value establish the size, and precision |
|
of the created field. |
|
|
|
nDecimals: The number of decimal places to reserve for FTDouble fields. |
|
For all other field types this should be zero. For instance |
|
with nWidth=7, and nDecimals=3 numbers would be formatted |
|
similarly to `123.456'. |
|
</pre> |
|
|
|
The DBFAddField() function is used to add new fields to an existing xBase |
|
file opened with DBFOpen(), or created with DBFCreate().<p> |
|
|
|
The DBFAddField() return value is the field number of the new field, or |
|
-1 if the addition of the field failed.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFReadIntegerAttribute()</h2> |
|
|
|
<pre> |
|
int DBFReadIntegerAttribute( DBFHandle hDBF, int iShape, int iField ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) from which the field value |
|
should be read. |
|
|
|
iField: The field within the selected record that should be read. |
|
</pre> |
|
|
|
The DBFReadIntegerAttribute() will read the value of one field and return |
|
it as an integer. This can be used even with FTString fields, though the |
|
returned value will be zero if not interpretable as a number.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFReadDoubleAttribute()</h2> |
|
|
|
<pre> |
|
double DBFReadDoubleAttribute( DBFHandle hDBF, int iShape, int iField ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) from which the field value |
|
should be read. |
|
|
|
iField: The field within the selected record that should be read. |
|
</pre> |
|
|
|
The DBFReadDoubleAttribute() will read the value of one field and return |
|
it as a double. This can be used even with FTString fields, though the |
|
returned value will be zero if not interpretable as a number.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFReadStringAttribute()</h2> |
|
|
|
<pre> |
|
const char *DBFReadStringAttribute( DBFHandle hDBF, int iShape, int iField ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) from which the field value |
|
should be read. |
|
|
|
iField: The field within the selected record that should be read. |
|
</pre> |
|
|
|
The DBFReadStringAttribute() will read the value of one field and return |
|
it as a string. This function may be used on any field type (including |
|
FTInteger and FTDouble) and will return the string representation stored |
|
in the .dbf file. The returned pointer is to an internal buffer |
|
which is only valid untill the next DBF function call. It's contents may |
|
be copied with normal string functions such as strcpy(), or strdup(). If |
|
the TRIM_DBF_WHITESPACE macro is defined in shapefil.h (it is by default) |
|
then all leading and trailing space (ASCII 32) characters will be stripped |
|
before the string is returned.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFIsAttributeNULL()</h2> |
|
|
|
<pre> |
|
int DBFIsAttributeNULL( DBFHandle hDBF, int iShape, int iField ); |
|
|
|
hDBF: The access handle for the file to be queried, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) from which the field value |
|
should be read. |
|
|
|
iField: The field within the selected record that should be read. |
|
</pre> |
|
|
|
This function will return TRUE if the indicated field is NULL valued |
|
otherwise FALSE. Note that NULL fields are represented in the .dbf file |
|
as having all spaces in the field. Reading NULL fields will result in |
|
a value of 0.0 or an empty string with the other DBFRead*Attribute() |
|
functions.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFWriteIntegerAttribute</h2> |
|
|
|
<pre> |
|
int DBFWriteIntegerAttribute( DBFHandle hDBF, int iShape, int iField, |
|
int nFieldValue ); |
|
|
|
hDBF: The access handle for the file to be written, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) to which the field value |
|
should be written. |
|
|
|
iField: The field within the selected record that should be written. |
|
|
|
nFieldValue: The integer value that should be written. |
|
</pre> |
|
|
|
The DBFWriteIntegerAttribute() function is used to write a value to a numeric |
|
field (FTInteger, or FTDouble). If the write succeeds the value TRUE will |
|
be returned, otherwise FALSE will be returned. If the value is too large to |
|
fit in the field, it will be truncated and FALSE returned.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFWriteDoubleAttribute()</h2> |
|
|
|
<pre> |
|
int DBFWriteDoubleAttribute( DBFHandle hDBF, int iShape, int iField, |
|
double dFieldValue ); |
|
|
|
hDBF: The access handle for the file to be written, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) to which the field value |
|
should be written. |
|
|
|
iField: The field within the selected record that should be written. |
|
|
|
dFieldValue: The floating point value that should be written. |
|
</pre> |
|
|
|
The DBFWriteDoubleAttribute() function is used to write a value to a numeric |
|
field (FTInteger, or FTDouble). If the write succeeds the value TRUE will |
|
be returned, otherwise FALSE will be returned. If the value is too large to |
|
fit in the field, it will be truncated and FALSE returned.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFWriteStringAttribute()</h2> |
|
|
|
<pre> |
|
int DBFWriteStringAttribute( DBFHandle hDBF, int iShape, int iField, |
|
const char * pszFieldValue ); |
|
|
|
hDBF: The access handle for the file to be written, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) to which the field value |
|
should be written. |
|
|
|
iField: The field within the selected record that should be written. |
|
|
|
pszFieldValue: The string to be written to the field. |
|
</pre> |
|
|
|
The DBFWriteStringAttribute() function is used to write a value to a string |
|
field (FString). If the write succeeds the value TRUE willbe returned, |
|
otherwise FALSE will be returned. If the value is too large to |
|
fit in the field, it will be truncated and FALSE returned.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFWriteNULLAttribute()</h2> |
|
|
|
<pre> |
|
int DBFWriteNULLAttribute( DBFHandle hDBF, int iShape, int iField ); |
|
|
|
hDBF: The access handle for the file to be written, as returned by |
|
DBFOpen(), or DBFCreate(). |
|
|
|
iShape: The record number (shape number) to which the field value |
|
should be written. |
|
|
|
iField: The field within the selected record that should be written. |
|
</pre> |
|
|
|
The DBFWriteNULLAttribute() function is used to clear the indicated field |
|
to a NULL value. In the .dbf file this is represented by setting the entire |
|
field to spaces. If the write succeeds the value TRUE willbe returned, |
|
otherwise FALSE will be returned.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFClose()</h2> |
|
|
|
<pre> |
|
void DBFClose( DBFHandle hDBF ); |
|
|
|
hDBF: The access handle for the file to be closed. |
|
</pre> |
|
|
|
The DBFClose() function will close the indicated xBase file (opened with |
|
DBFOpen(), or DBFCreate()), flushing out all information to the file on |
|
disk, and recovering any resources associated with having the file open. |
|
The file handle (hDBF) should not be used again with the DBF API after |
|
calling DBFClose().<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFIsRecordDeleted()</h2> |
|
|
|
<pre> |
|
int DBFIsRecordDeleted( DBFHandle hDBF, int iShape ); |
|
|
|
hDBF: The access handle for the file to be checked. |
|
iShape: The record index to check. |
|
</pre> |
|
|
|
Returns TRUE (non-zero) if the record is marked for deletion, otherwise |
|
it returns FALSE.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFMarkRecordDeleted()</h2> |
|
|
|
<pre> |
|
int DBFMarkRecordDeleted( DBFHandle hDBF, int iShape, int bIsDeleted ); |
|
|
|
hDBF: The access handle for the file. |
|
iShape: The record index to update. |
|
bIsDeleted: TRUE to mark record deleted, or FALSE to undelete it. |
|
</pre> |
|
|
|
Returns TRUE on success, or FALSE on error.<p> |
|
|
|
<!--------------------------------------------------------------------------> |
|
|
|
<h2>DBFGetNativeFieldType()</h2> |
|
|
|
<pre> |
|
char DBFGetNativeFieldType( DBFHandle hDBF, int iField ); |
|
|
|
hDBF: The access handle for the file. |
|
iField: The field index to query. |
|
|
|
</pre> |
|
|
|
This function returns the DBF type code of the indicated field. It will |
|
be one of:<p> |
|
|
|
<ul> |
|
<li> 'C' (String) |
|
<li> 'D' (Date) |
|
<li> 'F' (Float) |
|
<li> 'N' (Numeric, with or without decimal) |
|
<li> 'L' (Logical) |
|
<li> 'M' (Memo: 10 digits .DBT block ptr) |
|
<li> ' ' (field out of range) |
|
</ul> |
|
|
|
</body> |
|
</html>
|
|
|