1XBase(3) User Contributed Perl Documentation XBase(3)
2
6 XBase - Perl module for reading and writing the dbf files
7
9 use XBase;
10 my $table = new XBase "dbase.dbf" or die XBase->errstr;
11 for (0 .. $table->last_record) {
12 my ($deleted, $id, $msg)
13 = $table->get_record($_, "ID", "MSG");
14 print "$id:\t$msg\n" unless $deleted;
15 }
16
18 This module can read and write XBase database files, known as dbf in
19 dBase and FoxPro world. It also reads memo fields from the dbt and fpt
20 files, if needed. An alpha code of reading index support for ndx, ntx,
21 mdx, idx and cdx is available for testing -- see the DBD::Index(3) man
22 page. Module XBase provides simple native interface to XBase files.
23 For DBI compliant database access, see the DBD::XBase and DBI modules
24 and their man pages.
25 The following methods are supported by XBase module:
27 General methods
29 new Creates the XBase object, loads the info about the table form the
31 dbf file. The first parameter should be the name of existing dbf
32 file (table, in fact) to read. A suffix .dbf will be appended if
33 needed. This method creates and initializes new object, will also
34 check for memo file, if needed.
35 The parameters can also be specified in the form of hash: value of
37 name is then the name of the table, other flags supported are:
38 memofile specifies non standard name for the associated memo file.
40 By default it's the name of the dbf file, with extension dbt or
41 fpt.
42 ignorememo ignore memo file at all. This is usefull if you've lost
44 the dbt file and you do not need it. Default is false.
45 memosep separator of memo records in the dBase III dbt files. The
47 standard says it should be "\x1a\x1a". There are however implamen‐
48 tations that only put in one "\x1a". XBase.pm tries to guess which
49 is valid for your dbt but if it fails, you can tell it yourself.
50 nolongchars prevents XBase to treat the decimal value of character
52 fields as high byte of the length -- there are some broken products
53 around producing character fields with decimal values set.
54 my $table = new XBase "table.dbf" or die XBase->errstr;
56 my $table = new XBase "name" => "table.dbf",
58 "ignorememo" => 1;
59 recompute_lastrecno forces XBase.pm to disbelieve the information
61 about the number of records in the header of the dbf file and
62 recompute the number of records. Use this only if you know that
63 some other software of yours produces incorrect headers.
64 close
66 Closes the object/file, no arguments.
67 create
69 Creates new database file on disk and initializes it with 0
70 records. A dbt (memo) file will be also created if the table con‐
71 tains some memo fields. Parameters to create are passed as hash.
72 You can call this method as method of another XBase object and then
74 you only need to pass name value of the hash; the structure
75 (fields) of the new file will be the same as of the original
76 object.
77 If you call create using class name (XBase), you have to (besides
79 name) also specify another four values, each being a reference to
80 list: field_names, field_types, field_lengths and field_decimals.
81 The field types are specified by one letter strings (C, N, L, D,
82 ...). If you set some value as undefined, create will make it into
83 some reasonable default.
84 my $newtable = $table->create("name" => "copy.dbf");
86 my $newtable = XBase->create("name" => "copy.dbf",
88 "field_names" => [ "ID", "MSG" ],
89 "field_types" => [ "N", "C" ],
90 "field_lengths" => [ 6, 40 ],
91 "field_decimals" => [ 0, undef ]);
92 Other attributes are memofile for non standard memo file location,
94 codepage to set the codepage flag in the dbf header (it does not
95 affect how XBase.pm reads or writes the data though, just to make
96 FoxPro happy), and version to force different version of the dbt
97 (dbt) file. The default is the version of the object from which you
98 create the new one, or 3 if you call this as class method
99 (XBase->create).
100 The new file mustn't exist yet -- XBase will not allow you to over‐
102 write existing table. Use drop (or unlink) to delete it first.
103 drop
105 This method closes the table and deletes it on disk (including
106 associated memo file, if there is any).
107 last_record
109 Returns number of the last record in the file. The lines deleted
110 but present in the file are included in this number.
111 last_field
113 Returns number of the last field in the file, number of fields
114 minus 1.
115 field_names, field_types, field_lengths, field_decimals
117 Return list of field names and so on for the dbf file.
118 field_type, field_length, field_decimal
120 For a field name, returns the appropriate value. Returns undef if
121 the field doesn't exist in the table.
122 Reading the data one by one
124 When dealing with the records one by one, reading or writing (the fol‐
126 lowing six methods), you have to specify the number of the record in
127 the file as the first argument. The range is "0 .. $ta‐
128 ble->last_record".
129 get_record
131 Returns a list of data (field values) from the specified record
132 (line of the table). The first parameter in the call is the number
133 of the record. If you do not specify any other parameters, all
134 fields are returned in the same order as they appear in the file.
135 You can also put list of field names after the record number and
136 then only those will be returned. The first value of the returned
137 list is always the 1/0 "_DELETED" value saying whether the record
138 is deleted or not, so on success, get_record never returns empty
139 list.
140 get_record_nf
142 Instead if the names of the fields, you can pass list of numbers of
143 the fields to read.
144 get_record_as_hash
146 Returns hash (in list context) or reference to hash (in scalar con‐
147 text) containing field values indexed by field names. The name of
148 the deleted flag is "_DELETED". The only parameter in the call is
149 the record number. The field names are returned as uppercase.
150 Writing the data
152 All three writing methods always undelete the record. On success they
154 return true -- the record number actually written.
155 set_record
157 As parameters, takes the number of the record and the list of val‐
158 ues of the fields. It writes the record to the file. Unspecified
159 fields (if you pass less than you should) are set to undef/empty.
160 set_record_hash
162 Takes number of the record and hash as parameters, sets the fields,
163 unspecified are undefed/emptied.
164 update_record_hash
166 Like set_record_hash but fields that do not have value specified in
167 the hash retain their value.
168 To explicitely delete/undelete a record, use methods delete_record or
170 undelete_record with record number as a parameter.
171 Assorted examples of reading and writing:
173 my @data = $table->get_record(3, "jezek", "krtek");
175 my $hashref = $table->get_record_as_hash(38);
176 $table->set_record_hash(8, "jezek" => "jezecek",
177 "krtek" => 5);
178 $table->undelete_record(4);
179 This is a code to update field MSG in record where ID is 123.
181 use XBase;
183 my $table = new XBase "test.dbf" or die XBase->errstr;
184 for (0 .. $table->last_record) {
185 my ($deleted, $id) = $table->get_record($_, "ID")
186 die $table->errstr unless defined $deleted;
187 next if $deleted;
188 $table->update_record_hash($_, "MSG" => "New message")
189 if $id == 123;
190 }
191 Sequentially reading the file
193 If you plan to sequentially walk through the file, you can create a
195 cursor first and then repeatedly call fetch to get next record.
196 prepare_select
198 As parameters, pass list of field names to return, if no parame‐
199 ters, the following fetch will return all fields.
200 prepare_select_with_index
202 The first parameter is the file name of the index file, the rest is
203 as above. For index types that can hold more index structures in on
204 file, use arrayref instead of the file name and in that array
205 include file name and the tag name, and optionaly the index type.
206 The fetch will then return records in the ascending order, accord‐
207 ing to the index.
208 Prepare will return object cursor, the following method are methods of
210 the cursor, not of the table.
211 fetch
213 Returns the fields of the next available undeleted record. The list
214 thus doesn't contain the "_DELETED" flag since you are guaranteed
215 that the record is not deleted.
216 fetch_hashref
218 Returns a hash reference of fields for the next non deleted record.
219 last_fetched
221 Returns the number of the record last fetched.
222 find_eq
224 This only works with cursor created via prepare_select_with_index.
225 Will roll to the first record what is equal to specified argument,
226 or to the first greater if there is none equal. The following
227 fetches then continue normally.
228 Examples of using cursors:
230 my $table = new XBase "names.dbf" or die XBase->errstr;
232 my $cursor = $table->prepare_select("ID", "NAME", "STREET");
233 while (my @data = $cursor->fetch) {
234 ### do something here, like print "@data\n";
235 }
236 my $table = new XBase "employ.dbf";
238 my $cur = $table->prepare_select_with_index("empid.ndx");
239 ## my $cur = $table->prepare_select_with_index(
240 ["empid.cdx", "ADDRES", "char"], "id", "address");
241 $cur->find_eq(1097);
242 while (my $hashref = $cur->fetch_hashref
243 and $hashref->{"ID"} == 1097) {
244 ### do something here with $hashref
245 }
246 The second example shows that after you have done find_eq, the fetches
248 continue untill the end of the index, so you have to check whether you
249 are still on records with given value. And if there is no record with
250 value 1097 in the indexed field, you will just get the next record in
251 the order.
252 The updating example can be rewritten to:
254 use XBase;
256 my $table = new XBase "test.dbf" or die XBase->errstr;
257 my $cursor = $table->prepare_select("ID")
258 while (my ($id) = $cursor->fetch) {
259 $table->update_record_hash($cursor->last_fetched,
260 "MSG" => "New message") if $id == 123
261 }
262 Dumping the content of the file
264 A method get_all_records returns reference to an array containing array
266 of values for each undeleted record at once. As parameters, pass list
267 of fields to return for each record.
268 To print the content of the file in a readable form, use method
270 dump_records. It prints all not deleted records from the file. By
271 default, all fields are printed, separated by colons, one record on a
272 row. The method can have parameters in a form of a hash with the fol‐
273 lowing keys:
274 rs Record separator, string, newline by default.
276 fs Field separator, string, one colon by default.
278 fields
280 Reference to a list of names of the fields to print. By default
281 it's undef, meaning all fields.
282 undef
284 What to print for undefined (NULL) values, empty string by default.
285 Example of use is
287 use XBase;
289 my $table = new XBase "table" or die XBase->errstr;
290 $table->dump_records("fs" => " ⎪ ", "rs" => " <-+\n",
291 "fields" => [ "id", "msg" ]);'
292 Also note that there is a script dbfdump.pl(1) that does the printing.
294 Errors and debugging
296 If the method fails (returns false or null list), the error message can
298 be retrieved via errstr method. If the new or create method fails, you
299 have no object so you get the error message using class syntax
300 "XBase->errstr()".
301 The method header_info returns (not prints) string with information
303 about the file and about the fields.
304 Module XBase::Base(3) defines some basic functions that are inherited
306 by both XBase and XBase::Memo(3) module.
307
309 The character fields are returned "as is". No charset or other transla‐
310 tion is done. The numbers are converted to Perl numbers. The date
311 fields are returned as 8 character string of the 'YYYYMMDD' form and
312 when inserting the date, you again have to provide it in this form. No
313 checking for the validity of the date is done. The datetime field is
314 returned in the number of (possibly negative) seconds since 1970/1/1,
315 possibly with decimal part (since it allows precision up to 1/1000 s).
316 To get the fields, use the gmtime (or similar) Perl function.
317 If there is a memo field in the dbf file, the module tries to open file
319 with the same name but extension dbt, fpt or smt. It uses module
320 XBase::Memo(3) for this. It reads and writes this memo field transpar‐
321 ently (you do not know about it) and returns the data as single scalar.
322
324 New: A support for ndx, ntx, mdx, idx and cdx index formats is avail‐
325 able with alpha status for testing. Some of the formats are already
326 rather stable (ndx). Please read the XBase::Index(3) man page and the
327 eg/use_index file in the distribution for examples and ideas. Send me
328 examples of your data files and suggestions for interface if you need
329 indexes.
330 General locking methods are locksh, lockex and unlock for shared lock,
332 exclusive lock and unlock. They call flock but you can redefine then in
333 XBase::Base package.
334
336 This module is built using information from and article XBase File For‐
337 mat Description by Erik Bachmann, URL
338 http://www.e-bachmann.dk/docs/xbase.htm
340 Thanks a lot.
342
344 0.241
345
347 (c) 1997--2003 Jan Pazdziora, adelton@fi.muni.cz,
348 http://www.fi.muni.cz/~adelton/ at Faculty of Informatics, Masaryk Uni‐
349 versity in Brno, Czech Republic
350 All rights reserved. This package is free software; you can redis‐
352 tribute it and/or modify it under the same terms as Perl itself.
353
355 Many people have provided information, test files, test results and
356 patches. This project would not be so great without them. See the
357 Changes file for (I hope) complete list. Thank you all, guys!
358 Special thanks go to Erik Bachmann for his great page about the file
360 structures; to Frans van Loon, William McKee, Randy Kobes and Dan
361 Albertsson for longtime cooperation and many emails we've exchanged
362 when fixing and polishing the modules' behaviour; and to Dan Albertsson
363 for providing support for the project.
364
366 perl(1); XBase::FAQ(3); DBD::XBase(3) and DBI(3) for DBI interface;
367 dbfdump.pl(1)
368perl v5.8.8 2003-11-21 XBase(3)