1 /**************************************************************************** 2 * libdbf.h 3 **************************************************************************** 4 * Library to read information from dBASE files 5 * Author: Bjoern Berg, clergyman@gmx.de 6 * (C) Copyright 2004, Bj�rn Berg 7 * 8 **************************************************************************** 9 * Permission to use, copy, modify and distribute this software and its 10 * documentation for any purpose is hereby granted without fee, provided that 11 * the above copyright notice appear in all copies and that both that copyright 12 * notice and this permission notice appear in supporting documentation. The 13 * author makes no representations about the suitability of this software for 14 * any purpose. It is provided "as is" without express or implied warranty. 15 * 16 ***************************************************************************** 17 * $Id: libdbf.h,v 1.6 2006/04/14 12:25:30 rollinhand Exp $ 18 ****************************************************************************/ 19 20 #ifndef __LIBDBF_H__ 21 #define __LIBDBF_H__ 22 23 #include <sys/types.h> 24 25 /*! \file libdbf.h 26 \brief provides access to libdbf. 27 28 If you want to use functions of libdbf in your own programme, you have to add 29 libdbf.h to your source files. libdbf.h describes all necessary accessible functions 30 that libdbf provides. 31 */ 32 /*! \mainpage libdbf Documentation 33 \section intro Introduction 34 <p>libdbf is the backend library for dbf to convert dBASE/FoxPro files to any 35 format you want to. libdbf provides generic interfaces to access information 36 in a dBASE file very easily without knowing much about the structure of the 37 file.</p> 38 <p>The commands and functions of libdbf orientate much on PHP's functions to access 39 MySQL or Oracle databases. So, first steps should be very easy.</p> 40 41 \section data Data Structures 42 <p>The Link "Data Structures" gives a brief overview of the used classes and 43 structures in libdbf.</p> 44 45 \section file File List 46 <p>This section is less important</p> 47 48 \section fields Data Fields 49 <p>This section describes the used variables used in libdbf.</p> 50 51 \section globals Globals 52 <p>This is the most important section. Behind this section you find all accessible 53 functions and defines you can use in your own programme.</p> 54 55 \section license License 56 <p>Permission to use, copy, modify and distribute this software and its 57 documentation for any purpose is hereby granted without fee, provided that 58 the above copyright notice appear in all copies and that both that copyright 59 notice and this permission notice appear in supporting documentation. The 60 author makes no representations about the suitability of this software for 61 any purpose. It is provided "as is" without express or implied warranty.</p> 62 */ 63 64 /*! \def FoxBase Code for FoxBase */ 65 #define FoxBase 0x02 66 /*! \def FoxBasePlus Code for FoxBasePlus, same as for dBase III */ 67 #define FoxBasePlus 0x03 68 /*! \def dBase3 Code for dBase III */ 69 #define dBase3 0x03 70 /*! \def dBase3WM Code for dBase III with memo fields */ 71 #define dBase3WM 0x83 72 /*! \def dBase4 Code for dBase IV */ 73 #define dBase4 0x04 74 /*! \def dBase4WM Code for dBase IV with memo fields */ 75 #define dBase4WM 0x8B 76 /*! \def dBase4SQL Code for dBase IV with SQL table */ 77 #define dBase4SQL 0x8E 78 /*! \def dBase5 Code for dBase 5.0 */ 79 #define dBase5 0x05 80 /*! \def FoxPro2WM Code for FoxPro 2.0 (or earlier) with memo fields */ 81 #define FoxPro2WM 0xF5 82 /*! \def VisualFoxPro Code for Visual FoxPro without memo fields */ 83 #define VisualFoxPro 0x30 84 85 /*! \brief Object handle for dBASE file 86 87 A pointer of type P_DBF is used by all functions except for \ref dbf_Open 88 which returns it if the dBASE file could be successfully opened. 89 */ 90 typedef struct _P_DBF P_DBF; 91 92 /*! \brief Structure to store specification for one field 93 94 A pointer of type DB_FIELD is passed to \ref dbf_Create and 95 \ref dbf_CreateFH. 96 */ 97 typedef struct _DB_FIELD DB_FIELD; 98 #define SIZE_OF_DB_FIELD 32 99 100 /* 101 * FUNCTIONS 102 */ 103 104 /*! \fn dbf_GetVersion(P_DBF *p_dbf) 105 \brief return the version of dbf file as a human readable string 106 \param *p_dbf the object handle of the opened file 107 */ 108 const char *dbf_GetStringVersion(P_DBF *p_dbf); 109 110 /*! \fn dbf_GetVersion(P_DBF *p_dbf) 111 \brief return the version of dbf file 112 \param *p_dbf the object handle of the opened file 113 114 \return version or -1 on error 115 */ 116 int dbf_GetVersion(P_DBF *p_dbf); 117 118 /*! \fn P_DBF *dbf_Open (const char *file) 119 \brief dbf_Open opens a dBASE \a file and returns the object handle 120 \param file the filename of the dBASE file 121 122 Opens a dBASE file and returns the object handle. 123 Additional information from the dBASE header are read and stored 124 internally. 125 \return NULL in case of an error. 126 */ 127 P_DBF *dbf_Open (const char *file); 128 129 /*! \fn P_DBF *dbf_CreateFH (int fh, DB_FIELD *fields, int numfields) 130 \brief dbf_Create opens a new dBASE \a file and returns the object handle 131 \param fh file handle of already open file 132 \param fields record of field specification 133 \param numfields number of fields 134 135 Creates a dBASE file and returns the object handle. 136 \return NULL in case of an error. 137 */ 138 P_DBF *dbf_CreateFH (int fh, DB_FIELD *fields, int numfields); 139 140 /*! \fn P_DBF *dbf_Create (const char *file, DB_FIELD *fields, int numfields) 141 \brief dbf_Create opens a new dBASE \a file and returns the object handle 142 \param file the filename of the dBASE file 143 \param fields record of field specification 144 \param numfields number of fields 145 146 Creates a dBASE file and returns the object handle. 147 \return NULL in case of an error. 148 */ 149 P_DBF *dbf_Create (const char *file, DB_FIELD *fields, int numfields); 150 151 /*! \fn int dbf_Close (P_DBF *p_dbf) 152 \brief dbf_Close closes a dBASE file. 153 \param *p_dbf the object handle of the opened file 154 155 Closes a dBASE file and frees all memory. 156 \return 0 if closing was successful and -1 if not. 157 */ 158 int dbf_Close (P_DBF *p_dbf); 159 160 // Functions to info about rows and columns 161 /*! \fn int dbf_NumRows (P_DBF *p_dbf) 162 \brief dbf_NumRows returns the number of datasets/rows 163 \param *p_dbf the object handle of the opened file 164 165 Returns the number of datasets/rows. 166 \return Number of rows or -1 in case of an error. 167 */ 168 int dbf_NumRows (P_DBF *p_dbf); 169 170 /*! \fn int dbf_NumCols (P_DBF *p_dbf) 171 \brief dbf_NumCols returns the number of attributes/columns 172 \param *p_dbf the object handle of the opened file 173 174 Returns the number of fields/columns. 175 \return Number of columns or -1 in case of an error. 176 */ 177 int dbf_NumCols (P_DBF *p_dbf); 178 179 /*! \fn const char *dbf_ColumnName(P_DBF *p_dbf, int column) 180 \brief dbf_ColumnName returns the name of a selected \a column 181 \param *p_dbf the object handle of the opened file 182 \param column the number of the column 183 184 Returns the name of a selected column. 185 The first column has number 0. The maximum number of columns can 186 be determined with \ref dbf_NumCols. 187 \return Name of column or -1 on error 188 */ 189 const char *dbf_ColumnName(P_DBF *p_dbf, int column); 190 191 /*! \fn int dbf_ColumnSize(P_DBF *p_dbf, int column); 192 \brief dbf_ColumnSize returns the field length of a column 193 \param *p_dbf the object handle of the opened file 194 \param column the number of the column 195 196 Returns the field length of a column. 197 The first column has number 0. The maximum number of columns can 198 be determined with \ref dbf_NumCols. 199 \return field length of column or -1 on error 200 */ 201 int dbf_ColumnSize(P_DBF *p_dbf, int column); 202 203 /*! \fn const char dbf_ColumnType(P_DBF *p_dbf, int column) 204 \brief dbf_ColumnType returns the type of a field resp. column 205 \param *p_dbf the object handle of the opened file 206 \param column the number of the column 207 208 Returns the type of a column. Type can be any 209 of 'N' (number), 'C' (string), 'D' (data), 'M' (memo), 'L' (boolean) 210 for dBASE III files. 211 The first column has number 0. The maximum number of columns can 212 be determined with \ref dbf_NumCols. 213 \return field type of column or -1 on error 214 */ 215 const char dbf_ColumnType(P_DBF *p_dbf, int column); 216 217 /*! \fn int dbf_ColumnDecimals(P_DBF *p_dbf, int column) 218 \brief 219 \param *p_dbf the object handle of the opened file 220 \param column the number of the column 221 222 Returns the number of digits right to the 223 decimal point. 224 The first column has number 0. The maximum number of columns can 225 be determined with \ref dbf_NumCols. 226 \return Number of decimals of column or -1 on error 227 */ 228 int dbf_ColumnDecimals(P_DBF *p_dbf, int column); 229 230 /*! \fn u_int32_t dbf_ColumnAddress(P_DBF *p_dbf, int column) 231 \brief dbf_ColumnAddress returns the address of a column 232 \param *p_dbf the object handle of the opened file 233 \param column the number of the column 234 235 The first column has number 0. The maximum number of columns can 236 be determined with \ref dbf_NumCols. 237 \return Address of column or -1 on error 238 */ 239 u_int32_t dbf_ColumnAddress(P_DBF *p_dbf, int column); 240 241 /*! \fn const char *dbf_GetDate(P_DBF *p_dbf) 242 \brief dbf_GetDate returns a formatted date string 243 \param *p_dbf the object handle of the opened file 244 245 Returns a formatted date string of the type 246 yyyy-mm-dd. The date indicates the time the file was last 247 modified. 248 249 \return formatted date or -1 on error 250 */ 251 const char *dbf_GetDate(P_DBF *p_dbf); 252 253 /*! \fn int dbf_SetField(DB_FIELD *field, int type, const char *name, int len, int dec) 254 \brief dbf_SetField fills a field structure 255 \param *field pointer to field which shall be set 256 \param type type of field 257 \param name name of field 258 \param len length of field 259 \param dec number of decimals 260 261 Sets the field structure with the given values. 262 263 \return 0 264 */ 265 int dbf_SetField(DB_FIELD *field, int type, const char *name, int len, int dec); 266 267 /*! \fn int dbf_RecordLength(P_DBF *p_dbf) 268 \brief dbf_RecordLength returns length of a dataset 269 \param *p_dbf the object handle of the opened file 270 271 Returns the length of a dataset. Do not confuse this 272 with \ref dbf_HeaderSize. 273 274 \return record length or -1 on error 275 */ 276 int dbf_RecordLength(P_DBF *p_dbf); 277 278 /*! \fn int dbf_HeaderSize(P_DBF *p_dbf) 279 \brief dbf_HeaderSize returns length of the header 280 \param *p_dbf the object handle of the opened file 281 282 Returns the length of the header. 283 284 \return header length or -1 on error 285 */ 286 int dbf_HeaderSize(P_DBF *p_dbf); 287 288 /*! \fn int dbf_SetRecordOffset(P_DBF *p_dbf, int offset) 289 \brief dbf_SetRecordOffset set the internal record counter 290 \param *p_dbf the object handle of the opened file 291 \param offset the new record number of the next record read 292 293 Sets the internal record counter. The counter is an index counting 294 through the records within a dBASE file. The first record has 295 number 1. A negative offset will be counted from the end of the file. 296 The last record has index -1. 297 \ref dbf_ReadRecord uses the counter when reading the 298 next record. Setting a value outside the range -numrecord to numrecords 299 or 0 will cause an error. 300 301 \return the new internal record counter or -1 in case of an error 302 */ 303 int dbf_SetRecordOffset(P_DBF *p_dbf, int offset); 304 305 /*! \fn int dbf_ReadRecord(P_DBF *p_dbf, char *record, int len) 306 \brief dbf_ReadRecord reads the current record 307 \param *p_dbf the object handle of the opened file 308 \param *record a memory block large enough to contain a record 309 \param len the length of the record block 310 311 Returns a record as it stored in the dBASE file. The memory must 312 be large enough and allocated by the calling application. 313 314 \return 0 if successful, -1 on error 315 */ 316 int dbf_ReadRecord(P_DBF *p_dbf, char *record, int len); 317 318 /*! \fn int dbf_WriteRecord(P_DBF *p_dbf, char *record, int len) 319 \brief dbf_WriteRecord writes a record 320 \param *p_dbf the object handle of the opened file 321 \param *record record data suitable for writing into the dBASE file 322 \param len the length of the record block 323 324 Writes a record into a dBASE file and returns the number of 325 records. The record data must contain all field data but not 326 the leading byte which indicates whether the record is deleted. 327 Hence, len must be \ref dbf_RecordLength() - 1. 328 329 \return number of records written, -1 on error 330 */ 331 int dbf_WriteRecord(P_DBF *p_dbf, char *record, int len); 332 333 /*! \fn int dbf_IsMemo(P_DBF *p_dbf) 334 \brief dbf_IsMemo tells if dbf provides also a memo file 335 \param *p_dbf the object handle of the opened file 336 337 dbf_IsMemo indicates if dbf provides also a memo file 338 339 \return 0 no memo, 1 memo, -1 on error 340 */ 341 int dbf_IsMemo(P_DBF *p_dbf); 342 343 #endif /* __LIBDBF_H__ */ 344