/usr/share/doc/shapelib/dbf_api.html is in shapelib 1.2.10-7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 | <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(). Note that fields
can only be added to xBase files with no records, though this is limitation
of this API, not of the file format.<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>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>
|