Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5001.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/XBase::Index.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XBase::Index 3"
.TH XBase::Index 3 "2003-11-21" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
XBase::Index \- base class for the index files for dbf
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&        use XBase;
\&        my $table = new XBase "data.dbf";
\&        my $cur = $table->prepare_select_with_index("id.ndx",
\&                "ID", "NAME);
\&        $cur->find_eq(1097);
.Ve
.PP
.Vb 4
\&        while (my @data = $cur->fetch()) {
\&                last if $data[0] != 1097;
\&                print "@data\en";
\&        }
.Ve
.PP
This is a snippet of code to print \s-1ID\s0 and \s-1NAME\s0 fields from dbf
data.dbf where \s-1ID\s0 equals 1097. Provided you have index on \s-1ID\s0 in
file id.ndx. You can use the same code for ntx and idx index files.
For the cdx and mdx, the prepare_select call would be
.PP
.Vb 1
\&        prepare_select_with_index(['rooms.cdx', 'ROOMNAME'])
.Ve
.PP
so instead of plain filename you specify an arrayref with filename and
an index tag in that file. The reason is that cdx and mdx can contain
multiple indexes in one file and you have to distinguish, which you
want to use.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module XBase::Index is a collection of packages to provide index
support for XBase-like dbf database files.
.PP
An index file is generaly a file that holds values of certain database
field or expression in sorted order, together with the record number
that the record occupies in the dbf file. So when you search for
a record with some value, you first search in this sorted list and
once you have the record number in the dbf, you directly fetch the
record from dbf.
.Sh "What indexes do"
.IX Subsection "What indexes do"
To make the searching in this ordered list fast, it's generally organized
as a tree \*(-- it starts with a root page with records that point to
pages at lower level, etc., until leaf pages where the pointer is no
longer a pointer to the index but to the dbf. When you search for a
record in the index file, you fetch the root page and scan it
(lineary) until you find key value that is equal or grater than that you
are looking for. That way you've avoided reading all pages describing
the values that are lower. Here you descend one level, fetch the page
and again search the list of keys in that page. And you repeat this
process until you get to the leaf (lowest) level and here you finaly
find a pointer to the dbf. XBase::Index does this for you.
.PP
Some of the formats also support multiple indexes in one file \*(--
usually there is one top level index that for different field values
points to different root pages in the index file (so called tags).
.PP
XBase::Index supports (or aims to support) the following index
formats: ndx, ntx, mdx, cdx and idx. They differ in a way they store
the keys and pointers but the idea is always the same: make a tree of
pages, where the page contains keys and pointer either to pages at
lower levels, or to dbf (or both). XBase::Index only supports
read only access to the index fields at the moment (and if you need
writing them as well, follow reading because we need to have the
reading support stable before I get to work on updating the indexes).
.Sh "Testing your index file (and XBase::Index)"
.IX Subsection "Testing your index file (and XBase::Index)"
You can test your index using the indexdump script in the main
directory of the DBD::XBase distribution (I mean test XBase::Index
on correct index data, not testing corrupted index file, of course ;\-)
Just run
.PP
.Vb 2
\&        ./indexdump ~/path/index.ndx
\&        ./indexdump ~/path/index.cdx tag_name
.Ve
.PP
or
.PP
.Vb 1
\&        perl -Ilib ./indexdump ~/path/index.cdx tag_name
.Ve
.PP
if you haven't installed this version of XBase.pm/DBD::XBase yet. You
should get the content of the index file. On each row, there is
the key value and a record number of the record in the dbf file. Let
me know if you get results different from those you expect. I'd
probably ask you to send me the index file (and possibly the dbf file
as well), so that I can debug the problem.
.PP
The index file is (as already noted) a complement to a dbf file. Index
file without a dbf doesn't make much sense because the only thing that
you can get from it is the record number in the dbf file, not the
actual data. But it makes sense to test \*(-- dump the content of the
index to see if the sequence is \s-1OK\s0.
.PP
The index formats usually distinguish between numeric and character
data. Some of the file formats include the information about the type
in the index file, other depend on the dbf file. Since with indexdump
we only look at the index file, you may need to specify the \-type
option to indexdump if it complains that it doesn't know the data
type of the values (this is the case with cdx at least). The possible
values are num, char and date and the call would be like
.PP
.Vb 1
\&        ./indexdump -type=num ~/path/index.cdx tag_name
.Ve
.PP
(this \-type option may not work with all index formats at the moment
\&\*(-- will be fixed and patches always welcome).
.PP
You can use \f(CW\*(C`\-ddebug\*(C'\fR option to indexdump to see how pages are
fetched and decoded, or run debugger to see the calls and parsing.
.Sh "Using the index files to speed up searches in dbf"
.IX Subsection "Using the index files to speed up searches in dbf"
The syntax for using the index files to access data in the dbf file is
generally
.PP
.Vb 5
\&        my $table = new XBase "tablename";
\&                # or any other arguments to get the XBase object
\&                # see XBase(3)
\&        my $cur = $table->prepare_select_with_index("indexfile",
\&                "list", "of", "fields", "to", "return");
.Ve
.PP
or
.PP
.Vb 3
\&        my $cur = $table->prepare_select_with_index(
\&                [ "indexfile_with_tags", "tag_name" ],
\&                "list", "of", "fields", "to", "return");
.Ve
.PP
where we specify the tag in the index file (this is necessary with cdx
and mdx). After we have the cursor, we can search to given record and
start fetching the data:
.PP
.Vb 2
\&        $cur->find_eq('jezek');
\&        while (my @data = $cur->fetch) { # do something
.Ve
.Sh "Supported index formats"
.IX Subsection "Supported index formats"
The following table summarizes which formats are supproted by
XBase::Index. If the field says something else that Yes, I welcome
testers and offers of example index files.
.PP
.Vb 1
\&  Reading of index files -- types supported by XBase::Index
.Ve
.PP
.Vb 4
\&  type  string          numeric         date
\&  ----------------------------------------------------------
\&  ndx   Yes             Yes             Yes (you need to
\&                                        convert to Julian)
.Ve
.PP
.Vb 1
\&  ntx   Yes             Yes             Untested
.Ve
.PP
.Vb 2
\&  idx   Untested        Untested        Untested
\&        (but should be pretty usable)
.Ve
.PP
.Vb 1
\&  mdx   Untested        Untested        Untested
.Ve
.PP
.Vb 1
\&  cdx   Yes             Yes             Untested
.Ve
.PP
.Vb 2
\&  Writing of index files -- not supported untill the reading
\&  is stable enough.
.Ve
.PP
So if you have access to an index file that is untested or unsupported
and you care about support of these formats, contact me. If you are
able to actually generate those files on request, the better because I
may need specific file size or type to check something. If the file
format you work with is supported, I still appreciate a report that it
really works for you.
.PP
\&\fBPlease note\fR that there is very little documentation about the file
formats and the work on XBase::Index is heavilly based on making
assumption based on real life data. Also, the documentation is often
wrong or only describing some format variations but not the others.
I personally do not need the index support but am more than happy to
make it a reality for you. So I need your help \*(-- contact me if it
doesn't work for you and offer me your files for testing. Mentioning
word XBase somewhere in the Subject line will get you (hopefully ;\-)
fast response. Mentioning work Help or similar stupidity will probably
make my filters to consider your email as spam. Help yourself by
making my life easier in helping you.
.Sh "Programmer's notes"
.IX Subsection "Programmer's notes"
Programmers might find the following information usefull when trying
to debug XBase::Index from their files:
.PP
The XBase::Index module contains the basic XBase::Index package and
also packages XBase::ndx, XBase::ntx, XBase::idx, XBase::mdx and
XBase::cdx, and for each of these also a package
XBase::index_type::Page. Reading the file goes like this: you create
as object calling either new XBase::Index or new XBase::ndx (or
whatever the index type is). This can also be done behind the scenes,
for example XBase::prepare_select_with_index calls new XBase::Index.
The index file is opened using the XBase::Base::new/open and then the
XBase::index_type::read_header is called. This function fills the
basic data fields of the object from the header of the file. The new
method returns the object corresponding to the index type.
.PP
Then you probably want to do \f(CW$index\fR\->prepare_select or
\&\f(CW$index\fR\->prepare_select_eq, that would possition you just before record
equal or greater than the parameter (record in the index file, that
is). Then you do a series of fetch'es that return next pair of (key,
pointer_to_dbf). Behind the scenes, prepare_select_eq or fetch call
XBase::Index::get_record which in turn calls
XBase::index_type::Page::new. From the index file perspective, the
atomic item in the file is one index page (or block, or whatever
you call it). The XBase::index_type::Page::new reads the block of data
from the file and parses the information in the page \*(-- pages have
more or less complex structures. Page::new fills the structure, so
that the fetch calls can easily check what values are in the page.
.PP
For some examples, please see eg/use_index in the distribution
directory.
.SH "VERSION"
.IX Header "VERSION"
0.220
.SH "AUTHOR"
.IX Header "AUTHOR"
(c) 1998\-\-2002 Jan Pazdziora, adelton@fi.muni.cz
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIXBase\fR\|(3), \fIXBase::FAQ\fR\|(3)
Creat By MiNi SheLL
Email: devilkiller@gmail.com