1=head1 NAME
2
3perldbmfilter - Perl DBM Filters
4
5=head1 SYNOPSIS
6
7    $db = tie %hash, 'DBM', ...
8
9    $old_filter = $db->filter_store_key  ( sub { ... } );
10    $old_filter = $db->filter_store_value( sub { ... } );
11    $old_filter = $db->filter_fetch_key  ( sub { ... } );
12    $old_filter = $db->filter_fetch_value( sub { ... } );
13
14=head1 DESCRIPTION
15
16The four C<filter_*> methods shown above are available in all the DBM
17modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
18ODBM_File and SDBM_File.
19
20Each of the methods work identically, and are used to install (or
21uninstall) a single DBM Filter. The only difference between them is the
22place that the filter is installed.
23
24To summarise:
25
26=over 5
27
28=item B<filter_store_key>
29
30If a filter has been installed with this method, it will be invoked
31every time you write a key to a DBM database.
32
33=item B<filter_store_value>
34
35If a filter has been installed with this method, it will be invoked
36every time you write a value to a DBM database.
37
38
39=item B<filter_fetch_key>
40
41If a filter has been installed with this method, it will be invoked
42every time you read a key from a DBM database.
43
44=item B<filter_fetch_value>
45
46If a filter has been installed with this method, it will be invoked
47every time you read a value from a DBM database.
48
49=back
50
51You can use any combination of the methods from none to all four.
52
53All filter methods return the existing filter, if present, or C<undef>
54in not.
55
56To delete a filter pass C<undef> to it.
57
58=head2 The Filter
59
60When each filter is called by Perl, a local copy of C<$_> will contain
61the key or value to be filtered. Filtering is achieved by modifying
62the contents of C<$_>. The return code from the filter is ignored.
63
64=head2 An Example -- the NULL termination problem.
65
66DBM Filters are useful for a class of problems where you I<always>
67want to make the same transformation to all keys, all values or both.
68
69For example, consider the following scenario. You have a DBM database
70that you need to share with a third-party C application. The C application
71assumes that I<all> keys and values are NULL terminated. Unfortunately
72when Perl writes to DBM databases it doesn't use NULL termination, so
73your Perl application will have to manage NULL termination itself. When
74you write to the database you will have to use something like this:
75
76    $hash{"$key\0"} = "$value\0";
77
78Similarly the NULL needs to be taken into account when you are considering
79the length of existing keys/values.
80
81It would be much better if you could ignore the NULL terminations issue
82in the main application code and have a mechanism that automatically
83added the terminating NULL to all keys and values whenever you write to
84the database and have them removed when you read from the database. As I'm
85sure you have already guessed, this is a problem that DBM Filters can
86fix very easily.
87
88    use strict;
89    use warnings;
90    use SDBM_File;
91    use Fcntl;
92
93    my %hash;
94    my $filename = "filt";
95    unlink $filename;
96
97    my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
98      or die "Cannot open $filename: $!\n";
99
100    # Install DBM Filters
101    $db->filter_fetch_key  ( sub { s/\0$//    } );
102    $db->filter_store_key  ( sub { $_ .= "\0" } );
103    $db->filter_fetch_value(
104        sub { no warnings 'uninitialized'; s/\0$// } );
105    $db->filter_store_value( sub { $_ .= "\0" } );
106
107    $hash{"abc"} = "def";
108    my $a = $hash{"ABC"};
109    # ...
110    undef $db;
111    untie %hash;
112
113The code above uses SDBM_File, but it will work with any of the DBM
114modules.
115
116Hopefully the contents of each of the filters should be
117self-explanatory. Both "fetch" filters remove the terminating NULL,
118and both "store" filters add a terminating NULL.
119
120
121=head2 Another Example -- Key is a C int.
122
123Here is another real-life example. By default, whenever Perl writes to
124a DBM database it always writes the key and value as strings. So when
125you use this:
126
127    $hash{12345} = "something";
128
129the key 12345 will get stored in the DBM database as the 5 byte string
130"12345". If you actually want the key to be stored in the DBM database
131as a C int, you will have to use C<pack> when writing, and C<unpack>
132when reading.
133
134Here is a DBM Filter that does it:
135
136    use strict;
137    use warnings;
138    use DB_File;
139    my %hash;
140    my $filename = "filt";
141    unlink $filename;
142
143
144    my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
145      or die "Cannot open $filename: $!\n";
146
147    $db->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
148    $db->filter_store_key  ( sub { $_ = pack ("i", $_) } );
149    $hash{123} = "def";
150    # ...
151    undef $db;
152    untie %hash;
153
154The code above uses DB_File, but again it will work with any of the
155DBM modules.
156
157This time only two filters have been used -- we only need to manipulate
158the contents of the key, so it wasn't necessary to install any value
159filters.
160
161=head1 SEE ALSO
162
163L<DB_File>, L<GDBM_File>, L<NDBM_File>, L<ODBM_File> and L<SDBM_File>.
164
165=head1 AUTHOR
166
167Paul Marquess
168
169