~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

<div id="breadCrumbs"><a href="index.html">Home</a> > <a href="index-modules-A.html">Core modules</a> > <a href="index-modules-D.html">D</a> > DB_File</div>

<div id="contentBody"><div class="title_container"><div class="page_title">DB_File</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Using-DB_File-with-Berkeley-DB-version-2-or-greater">Using DB_File with Berkeley DB version 2 or greater</a><li><a href="#Interface-to-Berkeley-DB">Interface to Berkeley DB</a><li><a href="#Opening-a-Berkeley-DB-Database-File">Opening a Berkeley DB Database File</a><li><a href="#Default-Parameters">Default Parameters</a><li><a href="#In-Memory-Databases">In Memory Databases</a></ul><li><a href="#DB_HASH">DB_HASH</a><ul><li><a href="#A-Simple-Example">A Simple Example</a></ul><li><a href="#DB_BTREE">DB_BTREE</a><ul><li><a href="#Changing-the-BTREE-sort-order">Changing the BTREE sort order</a><li><a href="#Handling-Duplicate-Keys">Handling Duplicate Keys </a><li><a href="#The-get_dup()-Method">The get_dup() Method</a><li><a href="#The-find_dup()-Method">The find_dup() Method</a><li><a href="#The-del_dup()-Method">The del_dup() Method</a><li><a href="#Matching-Partial-Keys">Matching Partial Keys </a></ul><li><a href="#DB_RECNO">DB_RECNO</a><ul><li><a href="#The-'bval'-Option">The 'bval' Option</a><li><a href="#A-Simple-Example">A Simple Example</a><li><a href="#Extra-RECNO-Methods">Extra RECNO Methods</a><li><a href="#Another-Example">Another Example</a></ul><li><a href="#THE-API-INTERFACE">THE API INTERFACE</a><li><a href="#DBM-FILTERS">DBM FILTERS</a><ul><li><a href="#The-Filter">The Filter</a><li><a href="#An-Example----the-NULL-termination-problem.">An Example -- the NULL termination problem.</a><li><a href="#Another-Example----Key-is-a-C-int.">Another Example -- Key is a C int.</a></ul><li><a href="#HINTS-AND-TIPS">HINTS AND TIPS </a><ul><li><a href="#Locking%3a-The-Trouble-with-fd">Locking: The Trouble with fd</a><li><a href="#Safe-ways-to-lock-a-database">Safe ways to lock a database</a><li><a href="#Sharing-Databases-With-C-Applications">Sharing Databases With C Applications</a><li><a href="#The-untie()-Gotcha">The untie() Gotcha</a></ul><li><a href="#COMMON-QUESTIONS">COMMON QUESTIONS</a><ul><li><a href="#Why-is-there-Perl-source-in-my-database%3f">Why is there Perl source in my database?</a><li><a href="#How-do-I-store-complex-data-structures-with-DB_File%3f">How do I store complex data structures with DB_File?</a><li><a href="#What-does-%22Invalid-Argument%22-mean%3f">What does "Invalid Argument" mean?</a><li><a href="#What-does-%22Bareword-'DB_File'-not-allowed%22-mean%3f">What does "Bareword 'DB_File' not allowed" mean? </a></ul><li><a href="#REFERENCES">REFERENCES</a><li><a href="#HISTORY">HISTORY</a><li><a href="#BUGS">BUGS</a><li><a href="#AVAILABILITY">AVAILABILITY</a><li><a href="#COPYRIGHT">COPYRIGHT</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a></ul><a name="NAME"></a><h1>NAME</h1>

<div id="contentBody"><div class="title_container"><div class="page_title">DB_File</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Using-DB_File-with-Berkeley-DB-version-2-or-greater">Using DB_File with Berkeley DB version 2 or greater</a><li><a href="#Interface-to-Berkeley-DB">Interface to Berkeley DB</a><li><a href="#Opening-a-Berkeley-DB-Database-File">Opening a Berkeley DB Database File</a><li><a href="#Default-Parameters">Default Parameters</a><li><a href="#In-Memory-Databases">In Memory Databases</a></ul><li><a href="#DB_HASH">DB_HASH</a><ul><li><a href="#A-Simple-Example">A Simple Example</a></ul><li><a href="#DB_BTREE">DB_BTREE</a><ul><li><a href="#Changing-the-BTREE-sort-order">Changing the BTREE sort order</a><li><a href="#Handling-Duplicate-Keys">Handling Duplicate Keys</a><li><a href="#The-get_dup()-Method">The get_dup() Method</a><li><a href="#The-find_dup()-Method">The find_dup() Method</a><li><a href="#The-del_dup()-Method">The del_dup() Method</a><li><a href="#Matching-Partial-Keys">Matching Partial Keys</a></ul><li><a href="#DB_RECNO">DB_RECNO</a><ul><li><a href="#The-'bval'-Option">The 'bval' Option</a><li><a href="#A-Simple-Example">A Simple Example</a><li><a href="#Extra-RECNO-Methods">Extra RECNO Methods</a><li><a href="#Another-Example">Another Example</a></ul><li><a href="#THE-API-INTERFACE">THE API INTERFACE</a><li><a href="#DBM-FILTERS">DBM FILTERS</a><ul><li><a href="#The-Filter">The Filter</a><li><a href="#An-Example----the-NULL-termination-problem.">An Example -- the NULL termination problem.</a><li><a href="#Another-Example----Key-is-a-C-int.">Another Example -- Key is a C int.</a></ul><li><a href="#HINTS-AND-TIPS">HINTS AND TIPS</a><ul><li><a href="#Locking%3a-The-Trouble-with-fd">Locking: The Trouble with fd</a><li><a href="#Safe-ways-to-lock-a-database">Safe ways to lock a database</a><li><a href="#Sharing-Databases-With-C-Applications">Sharing Databases With C Applications</a><li><a href="#The-untie()-Gotcha">The untie() Gotcha</a></ul><li><a href="#COMMON-QUESTIONS">COMMON QUESTIONS</a><ul><li><a href="#Why-is-there-Perl-source-in-my-database%3f">Why is there Perl source in my database?</a><li><a href="#How-do-I-store-complex-data-structures-with-DB_File%3f">How do I store complex data structures with DB_File?</a><li><a href="#What-does-%22Invalid-Argument%22-mean%3f">What does "Invalid Argument" mean?</a><li><a href="#What-does-%22Bareword-'DB_File'-not-allowed%22-mean%3f">What does "Bareword 'DB_File' not allowed" mean?</a></ul><li><a href="#REFERENCES">REFERENCES</a><li><a href="#HISTORY">HISTORY</a><li><a href="#BUGS">BUGS</a><li><a href="#AVAILABILITY">AVAILABILITY</a><li><a href="#COPYRIGHT">COPYRIGHT</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a></ul><a name="NAME"></a><h1>NAME</h1>

DB_File - Perl5 access to Berkeley DB version 1.x

<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>

<pre class="verbatim"> [$X =] <a class="l_k" href="functions/tie.html">tie</a> %hash, 'DB_File', [$filename, $flags, $mode, $DB_HASH] ;

[$X =] <a class="l_k" href="functions/tie.html">tie</a> %hash, 'DB_File', $filename, $flags, $mode, $DB_BTREE ;

[$X =] <a class="l_k" href="functions/tie.html">tie</a> @array, 'DB_File', $filename, $flags, $mode, $DB_RECNO ;</pre>

103

106

<pre class="verbatim"> # RECNO only

104

107

$a = $X->length;

105

108

$a = $X->pop ;

106

$X->push(list);

109

$X->push(list);

107

110

$a = $X->shift;

108

$X->unshift(list);

109

@r = $X->splice(offset, <a class="l_k" href="functions/length.html">length</a>, elements);</pre>

111

$X->unshift(list);

112

@r = $X->splice(offset, <a class="l_k" href="functions/length.html">length</a>, elements);</pre>

110

113

<pre class="verbatim"> # DBM Filters

111

114

$old_filter = $db->filter_store_key ( <a class="l_k" href="functions/sub.html">sub</a> { ... } ) ;

112

115

$old_filter = $db->filter_store_value( <a class="l_k" href="functions/sub.html">sub</a> { ... } ) ;

162

165

2.x or greater, use the Perl module BerkeleyDB instead.

163

166

Note: The database file format has changed multiple times in Berkeley

164

167

DB version 2, 3 and 4. If you cannot recreate your databases, you

165

must dump any existing databases with either the <code class="inline">db_dump</code>

168

must dump any existing databases with either the <code class="inline">db_dump</code>

166

169

or the

167

170

168

171

utility that comes with Berkeley DB.

169

172

Once you have rebuilt DB_File to use Berkeley DB version 2 or greater,

170

your databases can be recreated using <code class="inline">db_load</code>

173

your databases can be recreated using <code class="inline">db_load</code>

171

174

. Refer to the Berkeley DB

172

175

documentation for further details.

173

176

Please read <a href="#COPYRIGHT">"COPYRIGHT"</a> before using version 2.x or greater of Berkeley

184

187

<a name="Opening-a-Berkeley-DB-Database-File"></a><h2>Opening a Berkeley DB Database File</h2>

185

188

Berkeley DB uses the function dbopen() to open or create a database.

186

189

Here is the C prototype for dbopen():

187

<pre class="verbatim"> <a class="l_w" href="DB.html">DB</a>*

188

dbopen (const char * file, <a class="l_k" href="functions/int.html">int</a> flags, <a class="l_k" href="functions/int.html">int</a> mode,

189

DBTYPE type, const void * openinfo)</pre>

190

The parameter <code class="inline">type</code>

190

<pre class="verbatim"> DB*

191

dbopen (const char * file, <a class="l_k" href="functions/int.html">int</a> flags, <a class="l_k" href="functions/int.html">int</a> mode,

192

DBTYPE type, const void * openinfo)</pre>

193

The parameter <code class="inline">type</code>

191

194

is an enumeration which specifies which of the 3

192

195

interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.

193

196

Depending on which of these is actually chosen, the final parameter,

196

199

This interface is handled slightly differently in DB_File. Here is

197

200

an equivalent call using DB_File:

198

201

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %array, 'DB_File', $filename, $flags, $mode, $DB_HASH ;</pre>

199

The <code class="inline">filename</code>

200

, <code class="inline">flags</code>

201

and <code class="inline">mode</code>

202

The <code class="inline">filename</code>

203

, <code class="inline">flags</code>

204

and <code class="inline">mode</code>

202

205

parameters are the direct

203

206

equivalent of their dbopen() counterparts. The final parameter $DB_HASH

204

performs the function of both the <code class="inline">type</code>

205

and <code class="inline">openinfo</code>

207

performs the function of both the <code class="inline">type</code>

208

and <code class="inline">openinfo</code>

206

209

parameters in

207

210

dbopen().

208

211

In the example above $DB_HASH is actually a pre-defined reference to a

210

213

Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO.

211

214

The keys allowed in each of these pre-defined references is limited to

212

215

the names used in the equivalent C structure. So, for example, the

213

$DB_HASH reference will only allow keys called <code class="inline">bsize</code>

214

, <code class="inline">cachesize</code>

216

$DB_HASH reference will only allow keys called <code class="inline">bsize</code>

217

, <code class="inline">cachesize</code>

215

218

216

<code class="inline">ffactor</code>

217

, <code class="inline">hash</code>

218

, <code class="inline">lorder</code>

219

and <code class="inline">nelem</code>

220

.

219

<code class="inline">ffactor</code>

220

, <code class="inline">hash</code>

221

, <code class="inline">lorder</code>

222

and <code class="inline">nelem</code>

223

.

221

224

To change one of these elements, just assign to it like this:

222

225

<pre class="verbatim"> $DB_HASH->{'cachesize'} = 10000 ;</pre>

223

226

The three predefined variables $DB_HASH, $DB_BTREE and $DB_RECNO are

226

229

type.

227

230

Here are examples of the constructors and the valid options available

228

231

for DB_HASH, DB_BTREE and DB_RECNO respectively.

229

<pre class="verbatim"> $a = new DB_File::HASHINFO ;

232

<pre class="verbatim"> $a = new DB_File::HASHINFO ;

230

233

$a->{'bsize'} ;

231

234

$a->{'cachesize'} ;

232

235

$a->{'ffactor'};

233

236

$a->{'hash'} ;

234

237

$a->{'lorder'} ;

235

238

$a->{'nelem'} ;</pre>

236

<pre class="verbatim"> $b = new DB_File::BTREEINFO ;

239

<pre class="verbatim"> $b = new DB_File::BTREEINFO ;

237

240

$b->{'flags'} ;

238

241

$b->{'cachesize'} ;

239

242

$b->{'maxkeypage'} ;

242

245

$b->{'compare'} ;

243

246

$b->{'prefix'} ;

244

247

$b->{'lorder'} ;</pre>

245

<pre class="verbatim"> $c = new DB_File::RECNOINFO ;

248

<pre class="verbatim"> $c = new DB_File::RECNOINFO ;

246

249

$c->{'bval'} ;

247

250

$c->{'cachesize'} ;

248

251

$c->{'psize'} ;

254

257

of their C counterpart. Like their C counterparts, all are set to a

255

258

default values - that means you don't have to set all of the

256

259

values when you only want to change one. Here is an example:

257

<pre class="verbatim"> $a = new DB_File::HASHINFO ;

260

<pre class="verbatim"> $a = new DB_File::HASHINFO ;

258

261

$a->{'cachesize'} = 12345 ;

259

262

<a class="l_k" href="functions/tie.html">tie</a> %y, 'DB_File', "filename", $flags, 0777, $a ;</pre>

260

263

A few of the options need extra discussion here. When used, the C

261

equivalent of the keys <code class="inline">hash</code>

262

, <code class="inline">compare</code>

263

and <code class="inline">prefix</code>

264

equivalent of the keys <code class="inline">hash</code>

265

, <code class="inline">compare</code>

266

and <code class="inline">prefix</code>

264

267

store pointers

265

268

to C functions. In DB_File these keys are used to store references

266

269

to Perl subs. Below are templates for each of the subs:

289

292

<a class="l_k" href="functions/return.html">return</a> $bytes ;

290

293

}</pre>

291

294

See <a href="#Changing-the-BTREE-sort-order">"Changing the BTREE sort order"</a> for an example of using the

292

<code class="inline">compare</code>

295

<code class="inline">compare</code>

293

296

template.

294

297

If you are using the DB_RECNO interface and you intend making use of

295

298

296

299

, you should check out <a href="#The-'bval'-Option">"The 'bval' Option"</a>.

297

300

<a name="Default-Parameters"></a><h2>Default Parameters</h2>

298

301

It is possible to omit some or all of the final 4 parameters in the

300

303

common file format used, the call:

301

304

302

305

is equivalent to:

303

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %A, "DB_File", "filename", O_CREAT|O_RDWR, 0666, $DB_HASH ;</pre>

306

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %A, "DB_File", "filename", O_CREAT|O_RDWR, 0666, $DB_HASH ;</pre>

304

307

It is also possible to omit the filename parameter as well, so the

305

308

call:

306

309

307

310

is equivalent to:

308

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %A, "DB_File", <a class="l_k" href="functions/undef.html">undef</a>, O_CREAT|O_RDWR, 0666, $DB_HASH ;</pre>

311

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %A, "DB_File", <a class="l_k" href="functions/undef.html">undef</a>, O_CREAT|O_RDWR, 0666, $DB_HASH ;</pre>

309

312

See <a href="#In-Memory-Databases">"In Memory Databases"</a> for a discussion on the use of <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code>

310

313

in place of a filename.

311

314

<a name="In-Memory-Databases"></a><h2>In Memory Databases</h2>

320

323

This example shows how to create a database, add key/value pairs to the

321

324

database, delete keys/value pairs and finally how to enumerate the

322

325

contents of the database.

323

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

324

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

325

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

326

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

327

<a class="l_k" href="functions/use.html">use</a> strict ;

328

<a class="l_k" href="functions/use.html">use</a> DB_File ;

326

329

327

330

<pre class="verbatim"> <a class="l_k" href="functions/unlink.html">unlink</a> "fruit" ;

328

<a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0666, $DB_HASH

331

<a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0666, $DB_HASH

329

332

or <a class="l_k" href="functions/die.html">die</a> "Cannot open file 'fruit': $!\n";</pre>

330

333

<pre class="verbatim"> # Add a few key/value pairs to the file

331

334

$h{"apple"} = "red" ;

341

344

{ <a class="l_k" href="functions/print.html">print</a> "$k -> $v\n" }</pre>

342

345

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

343

346

here is the output:

344

<pre class="verbatim"> Banana Exists</pre>

345

<pre class="verbatim"> orange -> orange

346

tomato -> red

347

banana -> yellow</pre>

347

<pre class="verbatim"> Banana Exists</pre>

348

<pre class="verbatim"> orange -> orange

349

tomato -> red

350

banana -> yellow</pre>

348

351

Note that the like ordinary associative arrays, the order of the keys

349

352

retrieved is in an apparently random order.

350

353

<a name="DB_BTREE"></a><h1>DB_BTREE</h1>

356

359

This script shows how to override the default sorting algorithm that

357

360

BTREE uses. Instead of using the normal lexical ordering, a case

358

361

insensitive compare function will be used.

359

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

360

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

361

362

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

363

<a class="l_k" href="functions/use.html">use</a> strict ;

364

362

365

363

366

<pre class="verbatim"><a name="Compare"></a> sub Compare

364

367

{

368

371

<pre class="verbatim"> # specify the Perl sub that will do the comparison

369

372

$DB_BTREE->{'compare'} = \&Compare ;</pre>

370

373

<pre class="verbatim"> <a class="l_k" href="functions/unlink.html">unlink</a> "tree" ;

371

<a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", "tree", O_RDWR|O_CREAT, 0666, $DB_BTREE

374

<a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", "tree", O_RDWR|O_CREAT, 0666, $DB_BTREE

372

375

or <a class="l_k" href="functions/die.html">die</a> "Cannot open file 'tree': $!\n" ;</pre>

373

376

<pre class="verbatim"> # Add a key/value pair to the file

374

377

$h{'Wall'} = 'Larry' ;

384

387

{ <a class="l_k" href="functions/print.html">print</a> "$_\n" }</pre>

385

388

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

386

389

Here is the output from the code above.

387

<pre class="verbatim"> mouse

388

Smith

389

Wall</pre>

390

<pre class="verbatim"> mouse

391

Smith

392

Wall</pre>

390

393

There are a few point to bear in mind if you want to change the

391

394

ordering in a BTREE database:

392

395

<ol>

424

427

compared as equal).

425

428

</li>

426

429

</ol>

427

<a name="Handling-Duplicate-Keys"></a><h2>Handling Duplicate Keys </h2>

430

<a name="Handling-Duplicate-Keys"></a><h2>Handling Duplicate Keys</h2>

428

431

The BTREE file type optionally allows a single key to be associated

429

432

with an arbitrary number of values. This option is enabled by setting

430

433

the flags element of <code class="inline">$DB_BTREE</code>

432

435

There are some difficulties in using the tied hash interface if you

433

436

want to manipulate a BTREE database with duplicate keys. Consider this

434

437

code:

435

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

436

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

437

438

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

439

<a class="l_k" href="functions/use.html">use</a> strict ;

440

438

441

439

442

<pre class="verbatim"> $filename = "tree" ;

440

443

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

441

444

<pre class="verbatim"> # Enable duplicate records

442

$DB_BTREE->{'flags'} = R_DUP ;</pre>

443

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

445

$DB_BTREE->{'flags'} = R_DUP ;</pre>

446

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

444

447

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

445

448

<pre class="verbatim"> # Add some key/value pairs to the file

446

449

$h{'Wall'} = 'Larry' ;

454

457

{ <a class="l_k" href="functions/print.html">print</a> "$_ -> $h{$_}\n" }</pre>

455

458

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

456

459

Here is the output:

457

<pre class="verbatim"> Smith -> John

458

Wall -> Larry

459

Wall -> Larry

460

Wall -> Larry

461

mouse -> mickey</pre>

462

As you can see 3 records have been successfully created with key <code class="inline">Wall</code>

460

<pre class="verbatim"> Smith -> John

461

Wall -> Larry

462

Wall -> Larry

463

Wall -> Larry

464

mouse -> mickey</pre>

465

As you can see 3 records have been successfully created with key <code class="inline">Wall</code>

463

466

464

467

- the only thing is, when they are retrieved from the database they

465

seem to have the same value, namely <code class="inline">Larry</code>

468

seem to have the same value, namely <code class="inline">Larry</code>

466

469

. The problem is caused

467

470

by the way that the associative array interface works. Basically, when

468

471

the associative array interface is used to fetch the value associated

471

474

associative array interface can be used to write values with duplicate

472

475

keys, but it cannot be used to read them back from the database.

473

476

The way to get around this problem is to use the Berkeley DB API method

474

called <code class="inline">seq</code>

477

called <code class="inline">seq</code>

475

478

. This method allows sequential access to key/value

476

pairs. See <a href="#THE-API-INTERFACE">"THE API INTERFACE"</a> for details of both the <code class="inline">seq</code>

479

pairs. See <a href="#THE-API-INTERFACE">"THE API INTERFACE"</a> for details of both the <code class="inline">seq</code>

477

480

method

478

481

and the API in general.

479

Here is the script above rewritten using the <code class="inline">seq</code>

482

Here is the script above rewritten using the <code class="inline">seq</code>

480

483

API method.

481

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

482

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

483

484

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

485

<a class="l_k" href="functions/use.html">use</a> strict ;

486

484

487

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($filename, $x, %h, $status, $key, $value) ;</pre>

485

488

<pre class="verbatim"> $filename = "tree" ;

486

489

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

487

490

<pre class="verbatim"> # Enable duplicate records

488

$DB_BTREE->{'flags'} = R_DUP ;</pre>

489

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

491

$DB_BTREE->{'flags'} = R_DUP ;</pre>

492

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

490

493

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

491

494

<pre class="verbatim"> # Add some key/value pairs to the file

492

495

$h{'Wall'} = 'Larry' ;

497

500

<pre class="verbatim"> # iterate through the btree using seq

498

501

# and print each key/value pair.

499

502

$key = $value = 0 ;

500

for ($status = $x->seq($key, $value, R_FIRST) ;

503

for ($status = $x->seq($key, $value, R_FIRST) ;

501

504

$status == 0 ;

502

$status = $x->seq($key, $value, R_NEXT) )

505

$status = $x->seq($key, $value, R_NEXT) )

503

506

{ <a class="l_k" href="functions/print.html">print</a> "$key -> $value\n" }</pre>

504

507

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $x ;

505

508

<a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

506

509

that prints:

507

<pre class="verbatim"> Smith -> John

508

Wall -> Brick

509

Wall -> Brick

510

Wall -> Larry

511

mouse -> mickey</pre>

510

<pre class="verbatim"> Smith -> John

511

Wall -> Brick

512

Wall -> Brick

513

Wall -> Larry

514

mouse -> mickey</pre>

512

515

This time we have got all the key/value pairs, including the multiple

513

values associated with the key <code class="inline">Wall</code>

516

values associated with the key <code class="inline">Wall</code>

514

517

.

515

518

To make life easier when dealing with duplicate keys, DB_File comes with

516

519

a few utility methods.

517

520

<a name="The-get_dup()-Method"></a><h2>The get_dup() Method</h2>

518

The <code class="inline">get_dup</code>

521

The <code class="inline">get_dup</code>

519

522

method assists in

520

523

reading duplicate values from BTREE databases. The method can take the

521

524

following forms:

533

536

associative array correspond to the values that matched in the BTREE

534

537

and the values of the array are a count of the number of times that

535

538

particular value occurred in the BTREE.

536

So assuming the database created above, we can use <code class="inline">get_dup</code>

539

So assuming the database created above, we can use <code class="inline">get_dup</code>

537

540

538

541

this:

539

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

540

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

541

542

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

543

<a class="l_k" href="functions/use.html">use</a> strict ;

544

542

545

543

546

<pre class="verbatim"> $filename = "tree" ;</pre>

544

547

<pre class="verbatim"> # Enable duplicate records

545

$DB_BTREE->{'flags'} = R_DUP ;</pre>

546

548

$DB_BTREE->{'flags'} = R_DUP ;</pre>

549

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

547

550

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

548

551

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $cnt = $x->get_dup("Wall") ;

549

552

<a class="l_k" href="functions/print.html">print</a> "Wall occurred $cnt times\n" ;</pre>

568

571

pair exists, the cursor is left pointing to the pair and the method

569

572

returns 0. Otherwise the method returns a non-zero value.

570

573

Assuming the database from the previous example:

571

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

572

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

573

574

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

575

<a class="l_k" href="functions/use.html">use</a> strict ;

576

574

577

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($filename, $x, %h, $found) ;</pre>

575

578

<pre class="verbatim"> $filename = "tree" ;</pre>

576

579

<pre class="verbatim"> # Enable duplicate records

577

$DB_BTREE->{'flags'} = R_DUP ;</pre>

578

580

$DB_BTREE->{'flags'} = R_DUP ;</pre>

581

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

579

582

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

580

583

<pre class="verbatim"> $found = ( $x->find_dup("Wall", "Larry") == 0 ? "" : "not") ;

581

584

<a class="l_k" href="functions/print.html">print</a> "Larry Wall is $found there\n" ;</pre>

584

587

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $x ;

585

588

<a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

586

589

prints this

587

<pre class="verbatim"> Larry Wall is there

588

Harry Wall is not there</pre>

590

<pre class="verbatim"> Larry Wall is there

591

Harry Wall is not there</pre>

589

592

<a name="The-del_dup()-Method"></a><h2>The del_dup() Method</h2>

590

593

<pre class="verbatim"> $status = $X->del_dup($key, $value) ;</pre>

591

594

This method deletes a specific key/value pair. It returns

592

595

0 if they exist and have been deleted successfully.

593

596

Otherwise the method returns a non-zero value.

594

Again assuming the existence of the <code class="inline">tree</code>

597

Again assuming the existence of the <code class="inline">tree</code>

595

598

database

596

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

597

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

598

599

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

600

<a class="l_k" href="functions/use.html">use</a> strict ;

601

599

602

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($filename, $x, %h, $found) ;</pre>

600

603

<pre class="verbatim"> $filename = "tree" ;</pre>

601

604

<pre class="verbatim"> # Enable duplicate records

602

$DB_BTREE->{'flags'} = R_DUP ;</pre>

603

605

$DB_BTREE->{'flags'} = R_DUP ;</pre>

606

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

604

607

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

605

608

<pre class="verbatim"> $x->del_dup("Wall", "Larry") ;</pre>

606

609

608

611

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $x ;

609

612

<a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

610

613

prints this

611

<pre class="verbatim"> Larry Wall is not there</pre>

612

<a name="Matching-Partial-Keys"></a><h2>Matching Partial Keys </h2>

614

<pre class="verbatim"> Larry Wall is not there</pre>

615

<a name="Matching-Partial-Keys"></a><h2>Matching Partial Keys</h2>

613

616

The BTREE interface has a feature which allows partial keys to be

614

matched. This functionality is only available when the <code class="inline">seq</code>

617

matched. This functionality is only available when the <code class="inline">seq</code>

615

618

method

616

619

is used along with the R_CURSOR flag.

617

<pre class="verbatim"> $x->seq($key, $value, R_CURSOR) ;</pre>

620

<pre class="verbatim"> $x->seq($key, $value, R_CURSOR) ;</pre>

618

621

Here is the relevant quote from the dbopen man page where it defines

619

622

the use of the R_CURSOR flag with seq:

620

<pre class="verbatim"> Note, for the DB_BTREE access method, the returned key is not

621

necessarily an exact match for the specified key. The returned key

622

is the smallest key greater than or equal to the specified key,

623

permitting partial key matches and range searches.</pre>

624

In the example script below, the <code class="inline">match</code>

623

<pre class="verbatim"> Note, for the DB_BTREE access method, the returned key is not

624

necessarily an exact match for the specified key. The returned key

625

is the smallest key greater than or equal to the specified key,

626

permitting partial key matches and range searches.</pre>

627

In the example script below, the <code class="inline">match</code>

625

628

sub uses this feature to find

626

629

and print the first matching key/value pair given a partial key.

627

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

628

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

629

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

630

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="Fcntl.html">Fcntl</a> ;</pre>

630

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

631

<a class="l_k" href="functions/use.html">use</a> strict ;

632

<a class="l_k" href="functions/use.html">use</a> DB_File ;

633

<a class="l_k" href="functions/use.html">use</a> Fcntl ;</pre>

631

634

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($filename, $x, %h, $st, $key, $value) ;</pre>

632

635

<pre class="verbatim"><a name="match"></a> sub match

633

636

{

634

637

<a class="l_k" href="functions/my.html">my</a> $key = <a class="l_k" href="functions/shift.html">shift</a> ;

635

638

<a class="l_k" href="functions/my.html">my</a> $value = 0;

636

639

<a class="l_k" href="functions/my.html">my</a> $orig_key = $key ;

637

$x->seq($key, $value, R_CURSOR) ;

640

$x->seq($key, $value, R_CURSOR) ;

638

641

<a class="l_k" href="functions/print.html">print</a> "$orig_key\t-> $key\t-> $value\n" ;

639

642

}</pre>

640

643

<pre class="verbatim"> $filename = "tree" ;

641

644

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

642

645

<pre class="verbatim"> $x = <a class="l_k" href="functions/tie.html">tie</a> %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE

643

646

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n";</pre>

644

647

<pre class="verbatim"> # Add some key/value pairs to the file

645

648

$h{'mouse'} = 'mickey' ;

648

651

$h{'Smith'} = 'John' ;</pre>

649

652

<pre class="verbatim"> $key = $value = 0 ;

650

653

<a class="l_k" href="functions/print.html">print</a> "IN ORDER\n" ;

651

for ($st = $x->seq($key, $value, R_FIRST) ;

654

for ($st = $x->seq($key, $value, R_FIRST) ;

652

655

$st == 0 ;

653

$st = $x->seq($key, $value, R_NEXT) )</pre>

656

$st = $x->seq($key, $value, R_NEXT) )</pre>

654

657

<pre class="verbatim"> { <a class="l_k" href="functions/print.html">print</a> "$key -> $value\n" }</pre>

655

658

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "\nPARTIAL MATCH\n" ;</pre>

656

<pre class="verbatim"> match "Wa" ;

657

match "A" ;

658

match "a" ;</pre>

659

<pre class="verbatim"> match "Wa" ;

660

match "A" ;

661

match "a" ;</pre>

659

662

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $x ;

660

663

<a class="l_k" href="functions/untie.html">untie</a> %h ;</pre>

661

664

Here is the output:

662

<pre class="verbatim"> IN ORDER

663

Smith -> John

664

Wall -> Larry

665

Walls -> Brick

666

mouse -> mickey</pre>

667

<pre class="verbatim"> PARTIAL MATCH

668

Wa -> Wall -> Larry

669

A -> Smith -> John

670

a -> mouse -> mickey</pre>

665

<pre class="verbatim"> IN ORDER

666

Smith -> John

667

Wall -> Larry

668

Walls -> Brick

669

mouse -> mickey</pre>

670

<pre class="verbatim"> PARTIAL MATCH

671

Wa -> Wall -> Larry

672

A -> Smith -> John

673

a -> mouse -> mickey</pre>

671

674

<a name="DB_RECNO"></a><h1>DB_RECNO</h1>

672

675

DB_RECNO provides an interface to flat text files. Both variable and

673

676

fixed length records are supported.

705

708

Here is a simple example that uses RECNO (if you are using a version

706

709

of Perl earlier than 5.004_57 this example won't work -- see

707

710

<a href="#Extra-RECNO-Methods">"Extra RECNO Methods"</a> for a workaround).

708

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

709

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

710

711

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

712

<a class="l_k" href="functions/use.html">use</a> strict ;

713

711

714

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $filename = "text" ;

712

715

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

713

716

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> @h ;

714

<a class="l_k" href="functions/tie.html">tie</a> @h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_RECNO

717

<a class="l_k" href="functions/tie.html">tie</a> @h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_RECNO

715

718

or <a class="l_k" href="functions/die.html">die</a> "Cannot open file 'text': $!\n" ;</pre>

716

719

<pre class="verbatim"> # Add a few key/value pairs to the file

717

720

$h[0] = "orange" ;

749

752

Here are the methods:

750

753

<ul>

751

754

<li><a name="*%24X-%3epush(list)-%3b*"></a>$X->push(list) ;

752

Pushes the elements of <code class="inline">list</code>

755

Pushes the elements of <code class="inline">list</code>

753

756

to the end of the array.

754

757

</li>

755

758

<li><a name="*%24value-%3d-%24X-%3epop-%3b*"></a>$value = $X->pop ;

759

762

Removes and returns the first element of the array.

760

763

</li>

761

764

<li><a name="*%24X-%3eunshift(list)-%3b*"></a>$X->unshift(list) ;

762

Pushes the elements of <code class="inline">list</code>

765

Pushes the elements of <code class="inline">list</code>

763

766

to the start of the array.

764

767

</li>

765

768

<li><a name="*%24X-%3elength*"></a>$X->length

773

776

Here is a more complete example that makes use of some of the methods

774

777

described above. It also makes use of the API interface directly (see

775

778

<a href="#THE-API-INTERFACE">"THE API INTERFACE"</a>).

776

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

777

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

779

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

780

<a class="l_k" href="functions/use.html">use</a> strict ;

778

781

<a class="l_k" href="functions/my.html">my</a> (@h, $H, $file, $i) ;

779

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

780

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="Fcntl.html">Fcntl</a> ;</pre>

782

<a class="l_k" href="functions/use.html">use</a> DB_File ;

783

<a class="l_k" href="functions/use.html">use</a> Fcntl ;</pre>

781

784

782

785

<pre class="verbatim"> <a class="l_k" href="functions/unlink.html">unlink</a> $file ;</pre>

783

<pre class="verbatim"> $H = <a class="l_k" href="functions/tie.html">tie</a> @h, "DB_File", $file, O_RDWR|O_CREAT, 0666, $DB_RECNO

786

<pre class="verbatim"> $H = <a class="l_k" href="functions/tie.html">tie</a> @h, "DB_File", $file, O_RDWR|O_CREAT, 0666, $DB_RECNO

784

787

or <a class="l_k" href="functions/die.html">die</a> "Cannot open file $file: $!\n" ;</pre>

785

788

<pre class="verbatim"> # first create a text file to play with

786

789

$h[0] = "zero" ;

792

795

#

793

796

# The length method is needed here because evaluating a tied

794

797

# array in a scalar context does not return the number of

795

# elements in the array. </pre>

798

# elements in the array.</pre>

796

799

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "\nORIGINAL\n" ;

797

800

foreach $i (0 .. $H->length - 1) {

798

801

<a class="l_k" href="functions/print.html">print</a> "$i: $h[$i]\n" ;

807

810

<a class="l_k" href="functions/print.html">print</a> "The first record was [$a]\n" ;</pre>

808

811

<pre class="verbatim"> # Use the API to add a new record after record 2.

809

812

$i = 2 ;

810

$H->put($i, "Newbie", R_IAFTER) ;</pre>

813

$H->put($i, "Newbie", R_IAFTER) ;</pre>

811

814

<pre class="verbatim"> # and a new record before record 1.

812

815

$i = 1 ;

813

$H->put($i, "New One", R_IBEFORE) ;</pre>

816

$H->put($i, "New One", R_IBEFORE) ;</pre>

814

817

<pre class="verbatim"> # delete record 3

815

818

$H->del(3) ;</pre>

816

819

<pre class="verbatim"> # now print the records in reverse order

820

823

<pre class="verbatim"> # same again, but use the API functions instead

821

824

<a class="l_k" href="functions/print.html">print</a> "\nREVERSE again\n" ;

822

825

<a class="l_k" href="functions/my.html">my</a> ($s, $k, $v) = (0, 0, 0) ;

823

for ($s = $H->seq($k, $v, R_LAST) ;

826

for ($s = $H->seq($k, $v, R_LAST) ;

824

827

$s == 0 ;

825

$s = $H->seq($k, $v, R_PREV))

828

$s = $H->seq($k, $v, R_PREV))

826

829

{ <a class="l_k" href="functions/print.html">print</a> "$k: $v\n" }</pre>

827

830

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $H ;

828

831

<a class="l_k" href="functions/untie.html">untie</a> @h ;</pre>

832

835

1: one

833

836

2: two

834

837

3: three

835

4: four</pre><pre class="verbatim"> The <a class="l_k" href="functions/last.html">last</a> record was [four]

836

The first record was [zero]</pre>

838

4: four</pre><pre class="verbatim"> The <a class="l_k" href="functions/last.html">last</a> record was [four]

839

The first record was [zero]</pre>

837

840

<pre class="verbatim"> REVERSE

838

841

5: last

839

842

4: three

853

856

like this:

854

857

<pre class="verbatim"> foreach $i (@h)</pre>

855

858

it is necessary to use either this:

856

<pre class="verbatim"> foreach $i (0 .. $H->length - 1) </pre>

859

857

860

or this:

858

<pre class="verbatim"> for ($a = $H->get($k, $v, R_FIRST) ;

861

<pre class="verbatim"> for ($a = $H->get($k, $v, R_FIRST) ;

859

862

$a == 0 ;

860

$a = $H->get($k, $v, R_NEXT) )</pre>

863

$a = $H->get($k, $v, R_NEXT) )</pre>

861

864

</li>

862

865

<li>

863

Notice that both times the <code class="inline">put</code>

866

Notice that both times the <code class="inline">put</code>

864

867

method was used the record index was

865

868

specified using a variable, <code class="inline">$i</code>

866

869

, rather than the literal value

867

itself. This is because <code class="inline">put</code>

870

itself. This is because <code class="inline">put</code>

868

871

will return the record number of the

869

872

inserted line via that parameter.

870

873

</li>

877

880

<pre class="verbatim"> $db = <a class="l_k" href="functions/tie.html">tie</a> %hash, "DB_File", "filename" ;</pre>

878

881

Once you have done that, you can access the Berkeley DB API functions

879

882

as DB_File methods directly like this:

880

<pre class="verbatim"> $db->put($key, $value, R_NOOVERWRITE) ;</pre>

883

<pre class="verbatim"> $db->put($key, $value, R_NOOVERWRITE) ;</pre>

881

884

Important: If you have saved a copy of the object returned from

882

885

<code class="inline"><a class="l_k" href="functions/tie.html">tie</a></code>, the underlying database file will not be closed until both

883

886

the tied variable is untied and all copies of the saved object are

884

destroyed.

885

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

887

destroyed.

888

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> DB_File ;

886

889

$db = <a class="l_k" href="functions/tie.html">tie</a> %hash, "DB_File", "filename"

887

890

or <a class="l_k" href="functions/die.html">die</a> "Cannot tie filename: $!" ;

888

891

...

915

918

the cursor, you should always assume that the cursor has been changed

916

919

any time the tied hash/array interface is used. As an example, this

917

920

code will probably not do what you expect:

918

<pre class="verbatim"> $X = <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE

921

<pre class="verbatim"> $X = <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE

919

922

or <a class="l_k" href="functions/die.html">die</a> "Cannot tie $filename: $!" ;</pre>

920

923

<pre class="verbatim"> # Get the first key/value pair and set the cursor

921

$X->seq($key, $value, R_FIRST) ;</pre>

924

$X->seq($key, $value, R_FIRST) ;</pre>

922

925

<pre class="verbatim"> # this line will modify the cursor

923

$count = <a class="l_k" href="functions/scalar.html">scalar</a> <a class="l_k" href="functions/keys.html">keys</a> %x ; </pre>

926

$count = <a class="l_k" href="functions/scalar.html">scalar</a> <a class="l_k" href="functions/keys.html">keys</a> %x ;</pre>

924

927

<pre class="verbatim"> # Get the second key/value pair.

925

928

# oops, it didn't, it got the last key/value pair!

926

$X->seq($key, $value, R_NEXT) ;</pre>

929

$X->seq($key, $value, R_NEXT) ;</pre>

927

930

The code above can be rearranged to get around the problem, like this:

928

931

<pre class="verbatim"> $X = <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE

929

932

or <a class="l_k" href="functions/die.html">die</a> "Cannot tie $filename: $!" ;</pre>

930

933

<pre class="verbatim"> # this line will modify the cursor

931

$count = <a class="l_k" href="functions/scalar.html">scalar</a> <a class="l_k" href="functions/keys.html">keys</a> %x ; </pre>

934

$count = <a class="l_k" href="functions/scalar.html">scalar</a> <a class="l_k" href="functions/keys.html">keys</a> %x ;</pre>

932

935

<pre class="verbatim"> # Get the first key/value pair and set the cursor

933

936

$X->seq($key, $value, R_FIRST) ;</pre>

934

937

<pre class="verbatim"> # Get the second key/value pair.

935

938

# worked this time.

936

$X->seq($key, $value, R_NEXT) ;</pre>

939

$X->seq($key, $value, R_NEXT) ;</pre>

937

940

</li>

938

941

</ul>

939

942

All the constants defined in <a href="http://search.cpan.org/perldoc/dbopen">dbopen</a> for use in the flags parameters

968

971

<li><a name="*%24status-%3d-%24X-%3efd-%3b*"></a>$status = $X->fd ;

969

972

Returns the file descriptor for the underlying database.

970

973

See <a href="#Locking%3a-The-Trouble-with-fd">"Locking: The Trouble with fd"</a> for an explanation for why you should

971

not use <code class="inline">fd</code>

974

not use <code class="inline">fd</code>

972

975

to lock your database.

973

976

</li>

974

977

<li><a name="*%24status-%3d-%24X-%3eseq(%24key%2c-%24value%2c-%24flags)-%3b*"></a>$status = $X->seq($key, $value, $flags) ;

1039

1042

the database and have them removed when you read from the database. As I'm

1040

1043

sure you have already guessed, this is a problem that DBM Filters can

1041

1044

fix very easily.

1042

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

1043

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

1044

1045

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

1046

<a class="l_k" href="functions/use.html">use</a> strict ;

1047

1045

1048

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> %hash ;

1046

1049

<a class="l_k" href="functions/my.html">my</a> $filename = "filt" ;

1047

1050

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

1048

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $db = <a class="l_k" href="functions/tie.html">tie</a> %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH

1051

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $db = <a class="l_k" href="functions/tie.html">tie</a> %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH

1049

1052

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n" ;</pre>

1050

1053

<pre class="verbatim"> # Install DBM Filters

1051

1054

$db->filter_fetch_key ( <a class="l_k" href="functions/sub.html">sub</a> { s/\0$// } ) ;

1070

1073

as a C int, you will have to use <code class="inline"><a class="l_k" href="functions/pack.html">pack</a></code> when writing, and <code class="inline"><a class="l_k" href="functions/unpack.html">unpack</a></code>

1071

1074

when reading.

1072

1075

Here is a DBM Filter that does it:

1073

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

1074

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

1075

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

1076

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

1077

<a class="l_k" href="functions/use.html">use</a> strict ;

1078

<a class="l_k" href="functions/use.html">use</a> DB_File ;

1076

1079

<a class="l_k" href="functions/my.html">my</a> %hash ;

1077

1080

<a class="l_k" href="functions/my.html">my</a> $filename = "filt" ;

1078

1081

<a class="l_k" href="functions/unlink.html">unlink</a> $filename ;</pre>

1079

1082

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $db = <a class="l_k" href="functions/tie.html">tie</a> %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH

1080

1083

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $filename: $!\n" ;</pre>

1081

1084

<pre class="verbatim"> $db->filter_fetch_key ( <a class="l_k" href="functions/sub.html">sub</a> { $_ = <a class="l_k" href="functions/unpack.html">unpack</a>("i", $_) } ) ;

1082

1085

$db->filter_store_key ( <a class="l_k" href="functions/sub.html">sub</a> { $_ = <a class="l_k" href="functions/pack.html">pack</a> ("i", $_) } ) ;

1087

1090

This time only two filters have been used -- we only need to manipulate

1088

1091

the contents of the key, so it wasn't necessary to install any value

1089

1092

filters.

1090

<a name="HINTS-AND-TIPS"></a><h1>HINTS AND TIPS </h1>

1093

<a name="HINTS-AND-TIPS"></a><h1>HINTS AND TIPS</h1>

1091

1094

<a name="Locking%3a-The-Trouble-with-fd"></a><h2>Locking: The Trouble with fd</h2>

1092

1095

Until version 1.72 of this module, the recommended technique for locking

1093

1096

DB_File databases was to flock the filehandle returned from the "fd"

1094

1097

function. Unfortunately this technique has been shown to be fundamentally

1095

1098

flawed (Kudos to David Harris for tracking this down). Use it at your own

1096

1099

peril!

1097

The locking technique went like this.

1098

<pre class="verbatim"> $db = <a class="l_k" href="functions/tie.html">tie</a>(%db, 'DB_File', 'foo.db', O_CREAT|O_RDWR, 0644)

1100

The locking technique went like this.

1101

<pre class="verbatim"> $db = <a class="l_k" href="functions/tie.html">tie</a>(%db, 'DB_File', 'foo.db', O_CREAT|O_RDWR, 0644)

1099

1102

|| <a class="l_k" href="functions/die.html">die</a> "dbcreat foo.db $!";

1100

1103

$fd = $db->fd;

1101

<a class="l_k" href="functions/open.html">open</a>(DB_FH, "+<&=$fd") || <a class="l_k" href="functions/die.html">die</a> "dup $!";

1102

<a class="l_k" href="functions/flock.html">flock</a> (DB_FH, LOCK_EX) || <a class="l_k" href="functions/die.html">die</a> "flock: $!";

1104

<a class="l_k" href="functions/open.html">open</a>(DB_FH, "+<&=$fd") || <a class="l_k" href="functions/die.html">die</a> "dup $!";

1105

<a class="l_k" href="functions/flock.html">flock</a> (DB_FH, LOCK_EX) || <a class="l_k" href="functions/die.html">die</a> "flock: $!";

1103

1106

...

1104

1107

$db{"Tom"} = "Jerry" ;

1105

1108

...

1106

<a class="l_k" href="functions/flock.html">flock</a>(DB_FH, LOCK_UN);

1109

<a class="l_k" href="functions/flock.html">flock</a>(DB_FH, LOCK_UN);

1107

1110

<a class="l_k" href="functions/undef.html">undef</a> $db;

1108

1111

<a class="l_k" href="functions/untie.html">untie</a> %db;

1109

<a class="l_k" href="functions/close.html">close</a>(DB_FH);</pre>

1112

<a class="l_k" href="functions/close.html">close</a>(DB_FH);</pre>

1110

1113

In simple terms, this is what happens:

1111

1114

<ol>

1112

1115

<li>

1165

1168

system. However, updates are still serial. Use for databases where reads

1166

1169

may be lengthy and consistency problems may occur.

1167

1170

</li>

1168

<li><a name="*Tie%3a%3aDB_LockFile*"></a>Tie::DB_LockFile

1171

<li><a name="*Tie%3a%3aDB_LockFile*"></a>Tie::DB_LockFile

1169

1172

A DB_File wrapper that has the ability to lock and unlock the database

1170

1173

while it is being used. Avoids the tie-before-flock problem by simply

1171

1174

re-tie-ing the database when you get or drop a lock. Because of the

1174

1177

updates and/or reads if the application follows the hints in the POD

1175

1178

documentation.

1176

1179

</li>

1177

<li><a name="*DB_File%3a%3aLock*"></a>DB_File::Lock

1180

<li><a name="*DB_File%3a%3aLock*"></a>DB_File::Lock

1178

1181

An extremely lightweight DB_File wrapper that simply flocks a lockfile

1179

1182

before tie-ing the database and drops the lock after the untie. Allows

1180

1183

one to use the same lockfile for multiple databases to avoid deadlock

1199

1202

Here is a snippet of code that is loosely based on Tom Christiansen's

1200

1203

ggh script (available from your nearest CPAN archive in

1201

1204

authors/id/TOMC/scripts/nshist.gz).

1202

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

1203

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

1204

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

1205

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="Fcntl.html">Fcntl</a> ;</pre>

1205

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

1206

<a class="l_k" href="functions/use.html">use</a> strict ;

1207

<a class="l_k" href="functions/use.html">use</a> DB_File ;

1208

<a class="l_k" href="functions/use.html">use</a> Fcntl ;</pre>

1206

1209

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($dotdir, $HISTORY, %hist_db, $href, $binary_time, $date) ;

1207

$dotdir = $ENV{HOME} || $ENV{LOGNAME};</pre>

1210

$dotdir = $ENV{HOME} || $ENV{LOGNAME};</pre>

1208

1211

<pre class="verbatim"> $HISTORY = "$dotdir/.netscape/history.db";</pre>

1209

1212

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %hist_db, 'DB_File', $HISTORY

1210

1213

or <a class="l_k" href="functions/die.html">die</a> "Cannot open $HISTORY: $!\n" ;;</pre>

1226

1229

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %hist_db ;</pre>

1227

1230

<a name="The-untie()-Gotcha"></a><h2>The untie() Gotcha</h2>

1228

1231

If you make use of the Berkeley DB API, it is very strongly

1229

recommended that you read <a href="perltie.html#The-untie-Gotcha">"The untie Gotcha" in perltie</a>.

1232

recommended that you read <a href="perltie.html#The-untie-Gotcha">"The untie Gotcha" in perltie</a>.

1230

1233

Even if you don't currently make use of the API interface, it is still

1231

1234

worth reading it.

1232

1235

Here is an example which illustrates the problem from a DB_File

1233

1236

perspective:

1234

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

1235

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="Fcntl.html">Fcntl</a> ;</pre>

1237

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> DB_File ;

1238

<a class="l_k" href="functions/use.html">use</a> Fcntl ;</pre>

1236

1239

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> %x ;

1237

1240

1238

1241

<pre class="verbatim"> $X = <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', 'tst.fil' , O_RDWR|O_TRUNC

1239

1242

or <a class="l_k" href="functions/die.html">die</a> "Cannot tie first time: $!" ;</pre>

1240

1243

1241

1244

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %x ;</pre>

1242

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT

1245

1243

1246

or <a class="l_k" href="functions/die.html">die</a> "Cannot tie second time: $!" ;</pre>

1244

1247

<pre class="verbatim"> <a class="l_k" href="functions/untie.html">untie</a> %x ;</pre>

1245

1248

When run, the script will produce this error message:

1271

1274

$x{123} = 456 ;</pre>

1272

1275

<pre class="verbatim"> <a class="l_k" href="functions/undef.html">undef</a> $X ;

1273

1276

<a class="l_k" href="functions/untie.html">untie</a> %x ;</pre>

1274

1277

<pre class="verbatim"> $X = <a class="l_k" href="functions/tie.html">tie</a> %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT

1275

1278

...</pre>

1276

1279

<a name="COMMON-QUESTIONS"></a><h1>COMMON QUESTIONS</h1>

1277

1280

<a name="Why-is-there-Perl-source-in-my-database%3f"></a><h2>Why is there Perl source in my database?</h2>

1299

1302

Here are a couple of possibilities:

1300

1303

<ol>

1301

1304

<li>

1302

Attempting to reopen a database without closing it.

1305

Attempting to reopen a database without closing it.

1303

1306

</li>

1304

1307

<li>

1305

1308

Using the O_WRONLY flag.

1306

1309

</li>

1307

1310

</ol>

1308

<a name="What-does-%22Bareword-'DB_File'-not-allowed%22-mean%3f"></a><h2>What does "Bareword 'DB_File' not allowed" mean? </h2>

1311

<a name="What-does-%22Bareword-'DB_File'-not-allowed%22-mean%3f"></a><h2>What does "Bareword 'DB_File' not allowed" mean?</h2>

1309

1312

You will encounter this particular error message when you have the

1310

<code class="inline"><a class="l_w" href="strict.html">strict</a> 'subs'</code>

1313

<code class="inline">strict 'subs'</code>

1311

1314

pragma (or the full strict pragma) in your script.

1312

1315

Consider this script:

1313

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> ;

1314

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a> ;

1315

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="DB_File.html">DB_File</a> ;

1316

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings ;

1317

<a class="l_k" href="functions/use.html">use</a> strict ;

1318

<a class="l_k" href="functions/use.html">use</a> DB_File ;

1316

1319

<a class="l_k" href="functions/my.html">my</a> %x ;

1317

<a class="l_k" href="functions/tie.html">tie</a> %x, <a class="l_w" href="DB_File.html">DB_File</a>, "filename" ;</pre>

1320

<a class="l_k" href="functions/tie.html">tie</a> %x, DB_File, "filename" ;</pre>

1318

1321

Running it produces the error in question:

1319

<pre class="verbatim"> Bareword "DB_File" not allowed while "strict subs" in use </pre>To get around the error, place the word <code class="inline"><a class="l_w" href="DB_File.html">DB_File</a></code> in either single or

1322

<pre class="verbatim"> Bareword "DB_File" not allowed while "strict subs" in use</pre>To get around the error, place the word <code class="inline">DB_File</code>

1323

in either single or

1320

1324

double quotes, like this:

1321

1325

<pre class="verbatim"> <a class="l_k" href="functions/tie.html">tie</a> %x, "DB_File", "filename" ;</pre>

1322

1326

Although it might seem like a real pain, it is really worth the effort

1323

of having a <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="strict.html">strict</a></code>

1327

of having a <code class="inline"><a class="l_k" href="functions/use.html">use</a> strict</code>

1324

1328

in all your scripts.

1325

1329

<a name="REFERENCES"></a><h1>REFERENCES</h1>

1326

1330

Articles that are either about DB_File or make use of it.

1348

1352

This version of DB_File will work with either version 1.x, 2.x or

1349

1353

3.x of Berkeley DB, but is limited to the functionality provided by

1350

1354

version 1.

1351

The official web site for Berkeley DB is <a href="http://www.sleepycat.com">http://www.sleepycat.com</a>.

1355

The official web site for Berkeley DB is <a href="http://www.oracle.com/technology/products/berkeley-db/db/index.html">http://www.oracle.com/technology/products/berkeley-db/db/index.html</a>.

1352

1356

All versions of Berkeley DB are available there.

1353

1357

Alternatively, Berkeley DB version 1 is available at your nearest CPAN

1354

1358

archive in src/misc/db.1.85.tar.gz.

1356

1360

<a href="http://reality.sgi.com/ariel">http://reality.sgi.com/ariel</a>. It has the patches necessary to

1357

1361

compile properly on IRIX 5.3.

1358

1362

<a name="COPYRIGHT"></a><h1>COPYRIGHT</h1>

1359

1363

1360

1364

is free software; you can redistribute it and/or modify it under the

1361

1365

same terms as Perl itself.

1362

1366

Although DB_File is covered by the Perl license, the library it

1363

1367

makes use of, namely Berkeley DB, is not. Berkeley DB has its own

1364

1368

1365

1369

Here are are few words taken from the Berkeley DB FAQ (at

1366

<a href="http://www.sleepycat.com">http://www.sleepycat.com</a>) regarding the license:

1367

<pre class="verbatim"> Do I have to license DB to use it in Perl scripts? </pre><pre class="verbatim"> No. The Berkeley <a class="l_w" href="DB.html">DB</a> license requires that software that uses

1368

Berkeley <a class="l_w" href="DB.html">DB</a> be freely redistributable. In the case of Perl, that

1369

software is Perl, and not your scripts. Any Perl scripts that you

1370

<a class="l_k" href="functions/write.html">write</a> are your property, including scripts that make <a class="l_k" href="functions/use.html">use</a> of

1371

Berkeley <a class="l_w" href="DB.html">DB</a>. Neither the Perl license nor the Berkeley <a class="l_w" href="DB.html">DB</a> license

1372

place any restriction on what you may <a class="l_k" href="functions/do.html">do</a> with them.</pre>

1370

<a href="http://www.oracle.com/technology/products/berkeley-db/db/index.html">http://www.oracle.com/technology/products/berkeley-db/db/index.html</a>) regarding the license:

1371

<pre class="verbatim"> Do I have to license DB to use it in Perl scripts?</pre><pre class="verbatim"> No. The Berkeley DB license requires that software that uses

1372

Berkeley DB be freely redistributable. In the case of Perl, that

1373

software is Perl, and not your scripts. Any Perl scripts that you

1374

<a class="l_k" href="functions/write.html">write</a> are your property, including scripts that make <a class="l_k" href="functions/use.html">use</a> of

1375

Berkeley DB. Neither the Perl license nor the Berkeley DB license

1376

place any restriction on what you may <a class="l_k" href="functions/do.html">do</a> with them.</pre>

1373

1377

If you are in any doubt about the license situation, contact either the

1374

1378

Berkeley DB authors or the author of DB_File. See <a href="#AUTHOR">"AUTHOR"</a> for details.

1375

1379

1377

1381

<a href="perldbmfilter.html">perldbmfilter</a>

1378

1382

<a name="AUTHOR"></a><h1>AUTHOR</h1>

1379

1383

The DB_File interface was written by Paul Marquess

1380

<pmqs@cpan.org>.

1381

Questions about the DB system itself may be addressed to

1382

<db@sleepycat.com>.

1384

<pmqs@cpan.org>.

1383

1385

</div>

1384

1386

1385

1387

</div>

1397

1399

1398

1400

</form>

1399

1401

1402

1400

1403

<h2>Labels:</h2>

1401

1404

1402

1405

Older »