1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB_ENV->set_event_notify()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="env.html" title="Chapter��5.�� The DB_ENV Handle" /> 11 <link rel="prev" href="envset_encrypt.html" title="DB_ENV->set_encrypt()" /> 12 <link rel="next" href="envset_errcall.html" title="DB_ENV->set_errcall()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_ENV->set_event_notify()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envset_encrypt.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��5.�� 23 The DB_ENV Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="envset_errcall.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="envevent_notify"></a>DB_ENV->set_event_notify()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->set_event_notify(DB_ENV *dbenv, 42 void (*db_event_fcn)(DB_ENV *dbenv, u_int32_t event, 43 void *event_info)); </pre> 44 <p> 45 The <code class="methodname">DB_ENV->set_event_notify()</code> method configures a callback function 46 which is called to notify the process of specific Berkeley DB events. 47 </p> 48 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 49 <h3 class="title">Note</h3> 50 <p> 51 Berkeley DB is not re-entrant. Callback functions should not attempt to make library calls (for 52 example, to release locks or close open handles). Re-entering Berkeley DB is not guaranteed to work 53 correctly, and the results are undefined. 54 </p> 55 </div> 56 <p> 57 The <code class="methodname">DB_ENV->set_event_notify()</code> method configures operations performed 58 using the specified <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> handle, not all 59 operations performed on the underlying database environment. 60 </p> 61 <p> 62 The <code class="methodname">DB_ENV->set_event_notify()</code> method may be called at any time 63 during the life of the application. 64 </p> 65 <p> 66 The <code class="methodname">DB_ENV->set_event_notify()</code> <span> 67 <span> 68 method returns a non-zero error value on failure and 0 on success. 69 </span> 70 71 </span> 72 </p> 73 <div class="sect2" lang="en" xml:lang="en"> 74 <div class="titlepage"> 75 <div> 76 <div> 77 <h3 class="title"><a id="id1667925"></a>Parameters</h3> 78 </div> 79 </div> 80 </div> 81 <div class="sect3" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h4 class="title"><a id="id1667873"></a>db_event_fcn</h4> 86 </div> 87 </div> 88 </div> 89 <p> 90 The <span class="bold"><strong>db_event_fcn</strong></span> parameter is the 91 application's event notification function. The function takes three 92 parameters: 93 </p> 94 <div class="itemizedlist"> 95 <ul type="disc"> 96 <li> 97 <p> 98 <code class="literal">dbenv</code> 99 </p> 100 <p> 101 The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing 102 database environment handle. 103 </p> 104 </li> 105 <li> 106 <p> 107 <code class="literal">event</code> 108 </p> 109 <p> 110 The <span class="bold"><strong>event</strong></span> parameter is one of the 111 following values: 112 </p> 113 <div class="itemizedlist"> 114 <ul type="circle"> 115 <li> 116 <p><a id="event_notify_DB_EVENT_PANIC"></a> 117 <code class="literal">DB_EVENT_PANIC</code> 118 </p> 119 <p> 120 Errors can occur in the Berkeley DB library where the only solution is 121 to shut down the application and run recovery (for example, if 122 Berkeley DB is unable to allocate heap memory). In such cases, the 123 Berkeley DB methods will return 124 <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_RUNRECOVERY" class="olink">DB_RUNRECOVERY</a>. 125 It is often easier to simply exit the application when such errors 126 occur rather than gracefully return up the stack. 127 </p> 128 <p> 129 When <span class="bold"><strong>event</strong></span> is set to DB_EVENT_PANIC, 130 the database environment has failed. All threads of control in the 131 database environment should exit the environment, and recovery should 132 be run. 133 </p> 134 </li> 135 <li> 136 <p><a id="event_notify_DB_EVENT_REG_ALIVE"></a> 137 <code class="literal">DB_EVENT_REG_ALIVE</code> 138 </p> 139 <p> 140 Recovery is needed in an environment where the 141 <a class="link" href="envopen.html#envopen_DB_REGISTER">DB_REGISTER</a> 142 flag was specified on the 143 <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> method and there is 144 a process attached to the environment. The callback function is triggered 145 once for each process attached. 146 </p> 147 <p> 148 The <span class="bold"><strong>event_info</strong></span> parameter points to a pid_t value 149 containing the process identifier (pid) of the process the Berkeley DB library 150 detects is attached to the environment. 151 </p> 152 </li> 153 <li> 154 <p><a id="event_notify_DB_EVENT_REG_PANIC"></a> 155 <code class="literal">DB_EVENT_REG_PANIC</code> 156 </p> 157 <p> 158 Recovery is needed in an environment where the 159 <a class="link" href="envopen.html#envopen_DB_REGISTER">DB_REGISTER</a> 160 flag was specified 161 on the <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> method. All threads 162 of control in the database environment should exit the environment. 163 </p> 164 <p> 165 This event is different than the <code class="literal">DB_EVENT_PANIC</code> event 166 because it can only be triggered when <code class="literal">DB_REGISTER</code> was 167 specified. It can be used to distinguish between the case when a process 168 dies in the environment and recovery is initiated versus the case when an 169 error happened (for example, if Berkeley DB is unable to allocate heap 170 memory) 171 </p> 172 </li> 173 <li> 174 <p><a id="event_notify_DB_EVENT_REP_CLIENT"></a> 175 <code class="literal">DB_EVENT_REP_CLIENT</code> 176 </p> 177 <p> 178 The local site is now a replication client. 179 </p> 180 </li> 181 <li> 182 <p><a id="event_notify_DB_EVENT_REP_ELECTED"></a> 183 <code class="literal">DB_EVENT_REP_ELECTED</code> 184 </p> 185 <p> 186 The local replication site has just won an election. An application 187 using the Base replication API should arrange for a call to the 188 <a class="xref" href="repstart.html" title="DB_ENV->rep_start()">DB_ENV->rep_start()</a> method 189 after receiving this event, to reconfigure the local environment as a 190 replication master. 191 </p> 192 <p> 193 Replication Manager applications may safely ignore this event. The 194 Replication Manager calls <a class="xref" href="repstart.html" title="DB_ENV->rep_start()">DB_ENV->rep_start()</a> 195 automatically on behalf of the application when appropriate (resulting 196 in firing of the DB_EVENT_REP_MASTER event). 197 </p> 198 </li> 199 <li> 200 <p><a id="event_notify_DB_EVENT_REP_MASTER"></a> 201 <code class="literal">DB_EVENT_REP_MASTER</code> 202 </p> 203 <p> 204 The local site is now the master site of its replication group. It is 205 the application's responsibility to begin acting as the master 206 environment. 207 </p> 208 </li> 209 <li> 210 <p><a id="event_notify_DB_EVENT_REP_NEWMASTER"></a> 211 <code class="literal">DB_EVENT_REP_NEWMASTER</code> 212 </p> 213 <p> 214 The replication group of which this site is a member has just 215 established a new master; the local site is not the new master. The 216 <span class="bold"><strong>event_info</strong></span> parameter points to an 217 integer containing the environment ID of the new master. 218 </p> 219 </li> 220 <li> 221 <p><a id="event_notify_DB_EVENT_REP_PERM_FAILED"></a> 222 <code class="literal">DB_EVENT_REP_PERM_FAILED</code> 223 </p> 224 <p> 225 The replication manager did not receive enough acknowledgements (based 226 on the acknowledgement policy configured with 227 <a class="xref" href="repmgrset_ack_policy.html" title="DB_ENV->repmgr_set_ack_policy()">DB_ENV->repmgr_set_ack_policy()</a> ) 228 to ensure a transaction's durability within the replication group. 229 The transaction will be flushed to the master's local disk storage for 230 durability. 231 </p> 232 <p> 233 The DB_EVENT_REP_PERM_FAILED event is provided only to applications 234 configured for the replication manager. 235 </p> 236 </li> 237 <li> 238 <p><a id="event_notify_DB_EVENT_REP_STARTUPDONE"></a> 239 <code class="literal">DB_EVENT_REP_STARTUPDONE</code> 240 </p> 241 <p> 242 The client has completed startup synchronization and is now processing 243 live log records received from the master. 244 </p> 245 </li> 246 <li> 247 <p><a id="event_notify_DB_EVENT_WRITE_FAILED"></a> 248 <code class="literal">DB_EVENT_WRITE_FAILED</code> 249 </p> 250 <p> 251 A Berkeley DB write to stable storage failed. 252 </p> 253 </li> 254 </ul> 255 </div> 256 </li> 257 <li> 258 <p> 259 <code class="literal">event_info</code> 260 </p> 261 <p> 262 The <span class="bold"><strong>event_info</strong></span> parameter may 263 reference memory which contains additional information describing an 264 event. By default, <span class="bold"><strong>event_info</strong></span> is 265 NULL; specific events may pass non-NULL values, in which case the 266 event will also describe the memory's structure. 267 </p> 268 </li> 269 </ul> 270 </div> 271 </div> 272 </div> 273 <div class="sect2" lang="en" xml:lang="en"> 274 <div class="titlepage"> 275 <div> 276 <div> 277 <h3 class="title"><a id="id1668209"></a>Class</h3> 278 </div> 279 </div> 280 </div> 281 <p> 282 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 283 </p> 284 </div> 285 <div class="sect2" lang="en" xml:lang="en"> 286 <div class="titlepage"> 287 <div> 288 <div> 289 <h3 class="title"><a id="id1668229"></a>See Also</h3> 290 </div> 291 </div> 292 </div> 293 <p> 294 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 295 </p> 296 </div> 297 </div> 298 <div class="navfooter"> 299 <hr /> 300 <table width="100%" summary="Navigation footer"> 301 <tr> 302 <td width="40%" align="left"><a accesskey="p" href="envset_encrypt.html">Prev</a>��</td> 303 <td width="20%" align="center"> 304 <a accesskey="u" href="env.html">Up</a> 305 </td> 306 <td width="40%" align="right">��<a accesskey="n" href="envset_errcall.html">Next</a></td> 307 </tr> 308 <tr> 309 <td width="40%" align="left" valign="top">DB_ENV->set_encrypt()��</td> 310 <td width="20%" align="center"> 311 <a accesskey="h" href="index.html">Home</a> 312 </td> 313 <td width="40%" align="right" valign="top">��DB_ENV->set_errcall()</td> 314 </tr> 315 </table> 316 </div> 317 </body> 318</html> 319