1XBase::Index(3) User Contributed Perl Documentation XBase::Index(3)
2
6 XBase::Index - base class for the index files for dbf
7
9 use XBase;
10 my $table = new XBase "data.dbf";
11 my $cur = $table->prepare_select_with_index("id.ndx",
12 "ID", "NAME);
13 $cur->find_eq(1097);
14 while (my @data = $cur->fetch()) {
16 last if $data[0] != 1097;
17 print "@data\n";
18 }
19 This is a snippet of code to print ID and NAME fields from dbf data.dbf
21 where ID equals 1097. Provided you have index on ID in file id.ndx. You
22 can use the same code for ntx and idx index files. For the cdx and
23 mdx, the prepare_select call would be
24 prepare_select_with_index(['rooms.cdx', 'ROOMNAME'])
26 so instead of plain filename you specify an arrayref with filename and
28 an index tag in that file. The reason is that cdx and mdx can contain
29 multiple indexes in one file and you have to distinguish, which you
30 want to use.
31
33 The module XBase::Index is a collection of packages to provide index
34 support for XBase-like dbf database files.
35 An index file is generaly a file that holds values of certain database
37 field or expression in sorted order, together with the record number
38 that the record occupies in the dbf file. So when you search for a
39 record with some value, you first search in this sorted list and once
40 you have the record number in the dbf, you directly fetch the record
41 from dbf.
42 What indexes do
44 To make the searching in this ordered list fast, it's generally orga‐
46 nized as a tree -- it starts with a root page with records that point
47 to pages at lower level, etc., until leaf pages where the pointer is no
48 longer a pointer to the index but to the dbf. When you search for a
49 record in the index file, you fetch the root page and scan it (lineary)
50 until you find key value that is equal or grater than that you are
51 looking for. That way you've avoided reading all pages describing the
52 values that are lower. Here you descend one level, fetch the page and
53 again search the list of keys in that page. And you repeat this process
54 until you get to the leaf (lowest) level and here you finaly find a
55 pointer to the dbf. XBase::Index does this for you.
56 Some of the formats also support multiple indexes in one file -- usu‐
58 ally there is one top level index that for different field values
59 points to different root pages in the index file (so called tags).
60 XBase::Index supports (or aims to support) the following index formats:
62 ndx, ntx, mdx, cdx and idx. They differ in a way they store the keys
63 and pointers but the idea is always the same: make a tree of pages,
64 where the page contains keys and pointer either to pages at lower lev‐
65 els, or to dbf (or both). XBase::Index only supports read only access
66 to the index fields at the moment (and if you need writing them as
67 well, follow reading because we need to have the reading support stable
68 before I get to work on updating the indexes).
69 Testing your index file (and XBase::Index)
71 You can test your index using the indexdump script in the main direc‐
73 tory of the DBD::XBase distribution (I mean test XBase::Index on cor‐
74 rect index data, not testing corrupted index file, of course ;-) Just
75 run
76 ./indexdump ~/path/index.ndx
78 ./indexdump ~/path/index.cdx tag_name
79 or
81 perl -Ilib ./indexdump ~/path/index.cdx tag_name
83 if you haven't installed this version of XBase.pm/DBD::XBase yet. You
85 should get the content of the index file. On each row, there is the key
86 value and a record number of the record in the dbf file. Let me know if
87 you get results different from those you expect. I'd probably ask you
88 to send me the index file (and possibly the dbf file as well), so that
89 I can debug the problem.
90 The index file is (as already noted) a complement to a dbf file. Index
92 file without a dbf doesn't make much sense because the only thing that
93 you can get from it is the record number in the dbf file, not the
94 actual data. But it makes sense to test -- dump the content of the
95 index to see if the sequence is OK.
96 The index formats usually distinguish between numeric and character
98 data. Some of the file formats include the information about the type
99 in the index file, other depend on the dbf file. Since with indexdump
100 we only look at the index file, you may need to specify the -type
101 option to indexdump if it complains that it doesn't know the data type
102 of the values (this is the case with cdx at least). The possible values
103 are num, char and date and the call would be like
104 ./indexdump -type=num ~/path/index.cdx tag_name
106 (this -type option may not work with all index formats at the moment --
108 will be fixed and patches always welcome).
109 You can use "-ddebug" option to indexdump to see how pages are fetched
111 and decoded, or run debugger to see the calls and parsing.
112 Using the index files to speed up searches in dbf
114 The syntax for using the index files to access data in the dbf file is
116 generally
117 my $table = new XBase "tablename";
119 # or any other arguments to get the XBase object
120 # see XBase(3)
121 my $cur = $table->prepare_select_with_index("indexfile",
122 "list", "of", "fields", "to", "return");
123 or
125 my $cur = $table->prepare_select_with_index(
127 [ "indexfile_with_tags", "tag_name" ],
128 "list", "of", "fields", "to", "return");
129 where we specify the tag in the index file (this is necessary with cdx
131 and mdx). After we have the cursor, we can search to given record and
132 start fetching the data:
133 $cur->find_eq('jezek');
135 while (my @data = $cur->fetch) { # do something
136 Supported index formats
138 The following table summarizes which formats are supproted by
140 XBase::Index. If the field says something else that Yes, I welcome
141 testers and offers of example index files.
142 Reading of index files -- types supported by XBase::Index
144 type string numeric date
146 ----------------------------------------------------------
147 ndx Yes Yes Yes (you need to
148 convert to Julian)
149 ntx Yes Yes Untested
151 idx Untested Untested Untested
153 (but should be pretty usable)
154 mdx Untested Untested Untested
156 cdx Yes Yes Untested
158 Writing of index files -- not supported untill the reading
160 is stable enough.
161 So if you have access to an index file that is untested or unsupported
163 and you care about support of these formats, contact me. If you are
164 able to actually generate those files on request, the better because I
165 may need specific file size or type to check something. If the file
166 format you work with is supported, I still appreciate a report that it
167 really works for you.
168 Please note that there is very little documentation about the file for‐
170 mats and the work on XBase::Index is heavilly based on making assump‐
171 tion based on real life data. Also, the documentation is often wrong or
172 only describing some format variations but not the others. I person‐
173 ally do not need the index support but am more than happy to make it a
174 reality for you. So I need your help -- contact me if it doesn't work
175 for you and offer me your files for testing. Mentioning word XBase
176 somewhere in the Subject line will get you (hopefully ;-) fast
177 response. Mentioning work Help or similar stupidity will probably make
178 my filters to consider your email as spam. Help yourself by making my
179 life easier in helping you.
180 Programmer's notes
182 Programmers might find the following information usefull when trying to
184 debug XBase::Index from their files:
185 The XBase::Index module contains the basic XBase::Index package and
187 also packages XBase::ndx, XBase::ntx, XBase::idx, XBase::mdx and
188 XBase::cdx, and for each of these also a package
189 XBase::index_type::Page. Reading the file goes like this: you create as
190 object calling either new XBase::Index or new XBase::ndx (or whatever
191 the index type is). This can also be done behind the scenes, for exam‐
192 ple XBase::prepare_select_with_index calls new XBase::Index. The index
193 file is opened using the XBase::Base::new/open and then the
194 XBase::index_type::read_header is called. This function fills the basic
195 data fields of the object from the header of the file. The new method
196 returns the object corresponding to the index type.
197 Then you probably want to do $index->prepare_select or $index->pre‐
199 pare_select_eq, that would possition you just before record equal or
200 greater than the parameter (record in the index file, that is). Then
201 you do a series of fetch'es that return next pair of (key,
202 pointer_to_dbf). Behind the scenes, prepare_select_eq or fetch call
203 XBase::Index::get_record which in turn calls
204 XBase::index_type::Page::new. From the index file perspective, the
205 atomic item in the file is one index page (or block, or whatever you
206 call it). The XBase::index_type::Page::new reads the block of data from
207 the file and parses the information in the page -- pages have more or
208 less complex structures. Page::new fills the structure, so that the
209 fetch calls can easily check what values are in the page.
210 For some examples, please see eg/use_index in the distribution direc‐
212 tory.
213
215 0.220
216
218 (c) 1998--2002 Jan Pazdziora, adelton@fi.muni.cz
219
221 XBase(3), XBase::FAQ(3)
222perl v5.8.8 2003-11-21 XBase::Index(3)