mingw/html/ext/ODBM_File/ODBM_File.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>ODBM_File - Tied access to odbm files</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;ODBM_File - Tied access to odbm files</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#diagnostics">DIAGNOSTICS</a></li>
  26         <ul>
  27
  28                 <li><a href="#odbm_store_returned_1__errno_22__key_____at____"><code>odbm store returned -1, errno 22, key &quot;...&quot; at ...</code></a></li>
  29         </ul>
  30
  31         <li><a href="#bugs_and_warnings">BUGS AND WARNINGS</a></li>
  32 </ul>
  33 <!-- INDEX END -->
  34
  35 <hr />
  36 <p>
  37 </p>
  38 <h1><a name="name">NAME</a></h1>
  39 <p>ODBM_File - Tied access to odbm files</p>
  40 <p>
  41 </p>
  42 <hr />
  43 <h1><a name="synopsis">SYNOPSIS</a></h1>
  44 <pre>
  45  use Fcntl;   # For O_RDWR, O_CREAT, etc.
  46  use ODBM_File;</pre>
  47 <pre>
  48   # Now read and change the hash
  49   $h{newkey} = newvalue;
  50   print $h{oldkey};
  51   ...</pre>
  52 <pre>
  53   untie %h;</pre>
  54 <p>
  55 </p>
  56 <hr />
  57 <h1><a name="description">DESCRIPTION</a></h1>
  58 <p><code>ODBM_File</code> establishes a connection between a Perl hash variable and
  59 a file in ODBM_File format;.  You can manipulate the data in the file
  60 just as if it were in a Perl hash, but when your program exits, the
  61 data will remain in the file, to be used the next time your program
  62 runs.</p>
  63 <p>Use <code>ODBM_File</code> with the Perl built-in <code>tie</code> function to establish
  64 the connection between the variable and the file.  The arguments to
  65 <code>tie</code> should be:</p>
  66 <ol>
  67 <li>
  68 <p>The hash variable you want to tie.</p>
  69 </li>
  70 <li>
  71 <p>The string <code>&quot;ODBM_File&quot;</code>.  (Ths tells Perl to use the <code>ODBM_File</code>
  72 package to perform the functions of the hash.)</p>
  73 </li>
  74 <li>
  75 <p>The name of the file you want to tie to the hash.</p>
  76 </li>
  77 <li>
  78 <p>Flags.  Use one of:</p>
  79 <dl>
  80 <dt><strong><a name="item_o_rdonly"><code>O_RDONLY</code></a></strong>
  81
  82 <dd>
  83 <p>Read-only access to the data in the file.</p>
  84 </dd>
  85 </li>
  86 <dt><strong><a name="item_o_wronly"><code>O_WRONLY</code></a></strong>
  87
  88 <dd>
  89 <p>Write-only access to the data in the file.</p>
  90 </dd>
  91 </li>
  92 <dt><strong><a name="item_o_rdwr"><code>O_RDWR</code></a></strong>
  93
  94 <dd>
  95 <p>Both read and write access.</p>
  96 </dd>
  97 </li>
  98 </dl>
  99 <p>If you want to create the file if it does not exist, add <code>O_CREAT</code> to
 100 any of these, as in the example.  If you omit <code>O_CREAT</code> and the file
 101 does not already exist, the <code>tie</code> call will fail.</p>
 102 <li>
 103 <p>The default permissions to use if a new file is created.  The actual
 104 permissions will be modified by the user's umask, so you should
 105 probably use 0666 here. (See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_umask">umask in the perlfunc manpage</a>.)</p>
 106 </li>
 107 </ol>
 108 <p>
 109 </p>
 110 <hr />
 111 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 112 <p>On failure, the <code>tie</code> call returns an undefined value and probably
 113 sets <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>$!</code></a> to contain the reason the file could not be tied.</p>
 114 <p>
 115 </p>
 116 <h2><a name="odbm_store_returned_1__errno_22__key_____at____"><code>odbm store returned -1, errno 22, key &quot;...&quot; at ...</code></a></h2>
 117 <p>This warning is emitted when you try to store a key or a value that
 118 is too long.  It means that the change was not recorded in the
 119 database.  See BUGS AND WARNINGS below.</p>
 120 <p>
 121 </p>
 122 <hr />
 123 <h1><a name="bugs_and_warnings">BUGS AND WARNINGS</a></h1>
 124 <p>There are a number of limits on the size of the data that you can
 125 store in the ODBM file.  The most important is that the length of a
 126 key, plus the length of its associated value, may not exceed 1008
 127 bytes.</p>
 128 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#tie">tie in the perlfunc manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perldbmfilter.html">the perldbmfilter manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Fcntl.html">the Fcntl manpage</a></p>
 129 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 130 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 131 <big><strong><span class="block">&nbsp;ODBM_File - Tied access to odbm files</span></strong></big>
 132 </td></tr>
 133 </table>
 134
 135 </body>
 136
 137 </html>