1XBase(3)              User Contributed Perl Documentation             XBase(3)
2
3
4

NAME

6       XBase - Perl module for reading and writing the dbf files
7

SYNOPSIS

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

DESCRIPTION

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
26       The following methods are supported by XBase module:
27
28   General methods
29       new Creates the XBase object, loads the info about the table form the
30           dbf file. The first parameter should be the name of existing dbf
31           file (table, in fact) to read. A suffix .dbf will be appended if
32           needed.  This method creates and initializes new object, will also
33           check for memo file, if needed.
34
35           The parameters can also be specified in the form of hash: value of
36           name is then the name of the table, other flags supported are:
37
38           memofile specifies non standard name for the associated memo file.
39           By default it's the name of the dbf file, with extension dbt or
40           fpt.
41
42           ignorememo ignore memo file at all. This is usefull if you've lost
43           the dbt file and you do not need it. Default is false.
44
45           memosep separator of memo records in the dBase III dbt files. The
46           standard says it should be "\x1a\x1a". There are however
47           implamentations that only put in one "\x1a". XBase.pm tries to
48           guess which is valid for your dbt but if it fails, you can tell it
49           yourself.
50
51           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
55               my $table = new XBase "table.dbf" or die XBase->errstr;
56
57               my $table = new XBase "name" => "table.dbf",
58                                                   "ignorememo" => 1;
59
60           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
65       close
66           Closes the object/file, no arguments.
67
68       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
71           contains some memo fields. Parameters to create are passed as hash.
72
73           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
78           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
85               my $newtable = $table->create("name" => "copy.dbf");
86
87               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
93           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
101           The new file mustn't exist yet -- XBase will not allow you to
102           overwrite existing table. Use drop (or unlink) to delete it first.
103
104       drop
105           This method closes the table and deletes it on disk (including
106           associated memo file, if there is any).
107
108       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
112       last_field
113           Returns number of the last field in the file, number of fields
114           minus 1.
115
116       field_names, field_types, field_lengths, field_decimals
117           Return list of field names and so on for the dbf file.
118
119       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
123   Reading the data one by one
124       When dealing with the records one by one, reading or writing (the
125       following six methods), you have to specify the number of the record in
126       the file as the first argument. The range is "0 ..
127       $table->last_record".
128
129       get_record
130           Returns a list of data (field values) from the specified record
131           (line of the table). The first parameter in the call is the number
132           of the record. If you do not specify any other parameters, all
133           fields are returned in the same order as they appear in the file.
134           You can also put list of field names after the record number and
135           then only those will be returned. The first value of the returned
136           list is always the 1/0 "_DELETED" value saying whether the record
137           is deleted or not, so on success, get_record never returns empty
138           list.
139
140       get_record_nf
141           Instead if the names of the fields, you can pass list of numbers of
142           the fields to read.
143
144       get_record_as_hash
145           Returns hash (in list context) or reference to hash (in scalar
146           context) containing field values indexed by field names. The name
147           of the deleted flag is "_DELETED". The only parameter in the call
148           is the record number. The field names are returned as uppercase.
149
150   Writing the data
151       All three writing methods always undelete the record. On success they
152       return true -- the record number actually written.
153
154       set_record
155           As parameters, takes the number of the record and the list of
156           values of the fields. It writes the record to the file. Unspecified
157           fields (if you pass less than you should) are set to undef/empty.
158
159       set_record_hash
160           Takes number of the record and hash as parameters, sets the fields,
161           unspecified are undefed/emptied.
162
163       update_record_hash
164           Like set_record_hash but fields that do not have value specified in
165           the hash retain their value.
166
167       To explicitely delete/undelete a record, use methods delete_record or
168       undelete_record with record number as a parameter.
169
170       Assorted examples of reading and writing:
171
172           my @data = $table->get_record(3, "jezek", "krtek");
173           my $hashref = $table->get_record_as_hash(38);
174           $table->set_record_hash(8, "jezek" => "jezecek",
175                                               "krtek" => 5);
176           $table->undelete_record(4);
177
178       This is a code to update field MSG in record where ID is 123.
179
180           use XBase;
181           my $table = new XBase "test.dbf" or die XBase->errstr;
182           for (0 .. $table->last_record) {
183               my ($deleted, $id) = $table->get_record($_, "ID")
184               die $table->errstr unless defined $deleted;
185               next if $deleted;
186               $table->update_record_hash($_, "MSG" => "New message")
187                                                       if $id == 123;
188           }
189
190   Sequentially reading the file
191       If you plan to sequentially walk through the file, you can create a
192       cursor first and then repeatedly call fetch to get next record.
193
194       prepare_select
195           As parameters, pass list of field names to return, if no
196           parameters, the following fetch will return all fields.
197
198       prepare_select_with_index
199           The first parameter is the file name of the index file, the rest is
200           as above. For index types that can hold more index structures in on
201           file, use arrayref instead of the file name and in that array
202           include file name and the tag name, and optionaly the index type.
203           The fetch will then return records in the ascending order,
204           according to the index.
205
206       Prepare will return object cursor, the following method are methods of
207       the cursor, not of the table.
208
209       fetch
210           Returns the fields of the next available undeleted record. The list
211           thus doesn't contain the "_DELETED" flag since you are guaranteed
212           that the record is not deleted.
213
214       fetch_hashref
215           Returns a hash reference of fields for the next non deleted record.
216
217       last_fetched
218           Returns the number of the record last fetched.
219
220       find_eq
221           This only works with cursor created via prepare_select_with_index.
222           Will roll to the first record what is equal to specified argument,
223           or to the first greater if there is none equal. The following
224           fetches then continue normally.
225
226       Examples of using cursors:
227
228           my $table = new XBase "names.dbf" or die XBase->errstr;
229           my $cursor = $table->prepare_select("ID", "NAME", "STREET");
230           while (my @data = $cursor->fetch) {
231               ### do something here, like print "@data\n";
232           }
233
234           my $table = new XBase "employ.dbf";
235           my $cur = $table->prepare_select_with_index("empid.ndx");
236           ## my $cur = $table->prepare_select_with_index(
237                       ["empid.cdx", "ADDRES", "char"], "id", "address");
238           $cur->find_eq(1097);
239           while (my $hashref = $cur->fetch_hashref
240                               and $hashref->{"ID"} == 1097) {
241               ### do something here with $hashref
242           }
243
244       The second example shows that after you have done find_eq, the fetches
245       continue untill the end of the index, so you have to check whether you
246       are still on records with given value. And if there is no record with
247       value 1097 in the indexed field, you will just get the next record in
248       the order.
249
250       The updating example can be rewritten to:
251
252           use XBase;
253           my $table = new XBase "test.dbf" or die XBase->errstr;
254           my $cursor = $table->prepare_select("ID")
255           while (my ($id) = $cursor->fetch) {
256               $table->update_record_hash($cursor->last_fetched,
257                               "MSG" => "New message") if $id == 123
258           }
259
260   Dumping the content of the file
261       A method get_all_records returns reference to an array containing array
262       of values for each undeleted record at once. As parameters, pass list
263       of fields to return for each record.
264
265       To print the content of the file in a readable form, use method
266       dump_records. It prints all not deleted records from the file. By
267       default, all fields are printed, separated by colons, one record on a
268       row. The method can have parameters in a form of a hash with the
269       following keys:
270
271       rs  Record separator, string, newline by default.
272
273       fs  Field separator, string, one colon by default.
274
275       fields
276           Reference to a list of names of the fields to print. By default
277           it's undef, meaning all fields.
278
279       undef
280           What to print for undefined (NULL) values, empty string by default.
281
282       Example of use is
283
284           use XBase;
285           my $table = new XBase "table" or die XBase->errstr;
286           $table->dump_records("fs" => " | ", "rs" => " <-+\n",
287                               "fields" => [ "id", "msg" ]);'
288
289       Also note that there is a script dbfdump.pl(1) that does the printing.
290
291   Errors and debugging
292       If the method fails (returns false or null list), the error message can
293       be retrieved via errstr method. If the new or create method fails, you
294       have no object so you get the error message using class syntax
295       "XBase->errstr()".
296
297       The method header_info returns (not prints) string with information
298       about the file and about the fields.
299
300       Module XBase::Base(3) defines some basic functions that are inherited
301       by both XBase and XBase::Memo(3) module.
302

DATA TYPES

304       The character fields are returned "as is". No charset or other
305       translation is done. The numbers are converted to Perl numbers. The
306       date fields are returned as 8 character string of the 'YYYYMMDD' form
307       and when inserting the date, you again have to provide it in this form.
308       No checking for the validity of the date is done. The datetime field is
309       returned in the number of (possibly negative) seconds since 1970/1/1,
310       possibly with decimal part (since it allows precision up to 1/1000 s).
311       To get the fields, use the gmtime (or similar) Perl function.
312
313       If there is a memo field in the dbf file, the module tries to open file
314       with the same name but extension dbt, fpt or smt. It uses module
315       XBase::Memo(3) for this. It reads and writes this memo field
316       transparently (you do not know about it) and returns the data as single
317       scalar.
318

INDEX, LOCKS

320       New: A support for ndx, ntx, mdx, idx and cdx index formats is
321       available with alpha status for testing. Some of the formats are
322       already rather stable (ndx). Please read the XBase::Index(3) man page
323       and the eg/use_index file in the distribution for examples and ideas.
324       Send me examples of your data files and suggestions for interface if
325       you need indexes.
326
327       General locking methods are locksh, lockex and unlock for shared lock,
328       exclusive lock and unlock. They call flock but you can redefine then in
329       XBase::Base package.
330

INFORMATION SOURCE

332       This module is built using information from and article XBase File
333       Format Description by Erik Bachmann, URL
334
335               http://www.clicketyclick.dk/databases/xbase/format/
336
337       Thanks a lot.
338

VERSION

340       1.08
341

AVAILABLE FROM

343       http://www.adelton.com/perl/DBD-XBase/
344

AUTHOR

346       (c) 1997--2017 Jan Pazdziora.
347
348       All rights reserved. This package is free software; you can
349       redistribute it and/or modify it under the same terms as Perl itself.
350
351       Contact the author at jpx dash perl at adelton dot com.
352

THANKS

354       Many people have provided information, test files, test results and
355       patches. This project would not be so great without them. See the
356       Changes file for (I hope) complete list. Thank you all, guys!
357
358       Special thanks go to Erik Bachmann for his great page about the file
359       structures; to Frans van Loon, William McKee, Randy Kobes and Dan
360       Albertsson for longtime cooperation and many emails we've exchanged
361       when fixing and polishing the modules' behaviour; and to Dan Albertsson
362       for providing support for the project.
363

SEE ALSO

365       perl(1); XBase::FAQ(3); DBD::XBase(3) and DBI(3) for DBI interface;
366       dbfdump.pl(1)
367
368
369
370perl v5.36.0                      2023-01-20                          XBase(3)
Impressum