diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/apprec_auto.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/apprec_auto.html')
| -rw-r--r-- | docs/programmer_reference/apprec_auto.html | 280 |
1 files changed, 181 insertions, 99 deletions
diff --git a/docs/programmer_reference/apprec_auto.html b/docs/programmer_reference/apprec_auto.html index 3f7d009e..12aa26eb 100644 --- a/docs/programmer_reference/apprec_auto.html +++ b/docs/programmer_reference/apprec_auto.html @@ -14,17 +14,17 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Automatically generated functions</th> + <th colspan="3" align="center">Automatically generated + functions</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="apprec_def.html">Prev</a> </td> - <th width="60%" align="center">Chapter 14. - Application Specific Logging and Recovery - </th> + <th width="60%" align="center">Chapter 14. Application Specific Logging and + Recovery </th> <td width="20%" align="right"> <a accesskey="n" href="apprec_config.html">Next</a></td> </tr> </table> @@ -34,41 +34,54 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="apprec_auto"></a>Automatically generated functions</h2> + <h2 class="title" style="clear: both"><a id="apprec_auto"></a>Automatically generated + functions</h2> </div> </div> </div> - <p>The XXX.src file is processed using the gen_rec.awk script included in -the dist directory of the Berkeley DB distribution. This is an awk script -that is executed from with the following command line:</p> + <p> + The XXX.src file is processed using the gen_rec.awk script + included in the dist directory of the Berkeley DB + distribution. This is an awk script that is executed from with + the following command line: + </p> <pre class="programlisting">awk -f gen_rec.awk \ - -v source_file=<span class="emphasis"><em>C_FILE</em></span> \ - -v header_file=<span class="emphasis"><em>H_FILE</em></span> \ - -v print_file=<span class="emphasis"><em>P_FILE</em></span> \ - -v template_file=<span class="emphasis"><em>TMP_FILE</em></span> < XXX.src</pre> - <p>where <span class="emphasis"><em>C_FILE</em></span> is the name of the file into which to place the -automatically generated C code, <span class="emphasis"><em>H_FILE</em></span> is the name of the -file into which to place the automatically generated data structures -and declarations, <span class="emphasis"><em>P_FILE</em></span> is the name of the file into which to -place the automatically generated C code that prints log records, -and <span class="emphasis"><em>TMP_FILE</em></span> is the name of the file into -which to place a template for the recovery routines.</p> - <p>Because the gen_rec.awk script uses sources files located relative to -the Berkeley DB dist directory, it must be run from the dist directory. For -example, in building the Berkeley DB logging and recovery routines for -ex_apprec, the following script is used to rebuild the automatically -generated files:</p> - <pre class="programlisting">E=../examples_c/ex_apprec -<p></p> + -v source_file=<span class="emphasis"><em>C_FILE</em></span> \ + -v header_file=<span class="emphasis"><em>H_FILE</em></span> \ + -v print_file=<span class="emphasis"><em>P_FILE</em></span> \ + -v template_file=<span class="emphasis"><em>TMP_FILE</em></span> < XXX.src</pre> + <p> + where <span class="emphasis"><em>C_FILE</em></span> is the name of the file + into which to place the automatically generated C code, + <span class="emphasis"><em>H_FILE</em></span> is the name of the file into + which to place the automatically generated data structures and + declarations, <span class="emphasis"><em>P_FILE</em></span> is the name of the + file into which to place the automatically generated C code + that prints log records, and <span class="emphasis"><em>TMP_FILE</em></span> is + the name of the file into which to place a template for the + recovery routines. + </p> + <p> + Because the gen_rec.awk script uses sources files located + relative to the Berkeley DB dist directory, it must be run + from the dist directory. For example, in building the Berkeley + DB logging and recovery routines for ex_apprec, the following + script is used to rebuild the automatically generated + files: + </p> + <pre class="programlisting">E=../examples/c/ex_apprec + cd ../../dist awk -f gen_rec.awk \ -v source_file=$E/ex_apprec_auto.c \ -v header_file=$E/ex_apprec_auto.h \ -v print_file=$E/ex_apprec_autop.c \ -v template_file=$E/ex_apprec_template < $E/ex_apprec.src</pre> - <p>For each log record description found in the XXX.src file, the following -structure declarations and #defines will be created in the file -<span class="emphasis"><em>header_file</em></span>:</p> + <p> + For each log record description found in the XXX.src file, + the following structure declarations and #defines will be + created in the file <span class="emphasis"><em>header_file</em></span>: + </p> <pre class="programlisting">#define DB_PREFIX_RECORD_TYPE /* Integer ID number */ typedef struct _PREFIX_RECORD_TYPE_args { @@ -94,26 +107,36 @@ typedef struct _PREFIX_RECORD_TYPE_args { * the entries in the record statement. */ };</pre> - <p>Thus, the auto-generated ex_apprec_mkdir_args structure looks as follows:</p> + <p> + Thus, the auto-generated ex_apprec_mkdir_args structure + looks as follows: + </p> <pre class="programlisting">typedef struct _ex_apprec_mkdir_args { - u_int32_t type; - DB_TXN *txnid; - DB_LSN prev_lsn; - DBT dirname; + u_int32_t type; + DB_TXN *txnid; + DB_LSN prev_lsn; + DBT dirname; } ex_apprec_mkdir_args;</pre> - <p>The template_file will contain a template for a recovery function. The -recovery function is called on each record read from the log during -system recovery, transaction abort, or the application of log records -on a replication client, and is expected to redo or undo the operations -described by that record. The details of the recovery function will be -specific to the record being logged and need to be written manually, but -the template provides a good starting point. (See ex_apprec_template -and ex_apprec_rec.c for an example of both the template produced and the -resulting recovery function.)</p> - <p>The template file should be copied to a source file in the application -(but not the automatically generated source_file, as that will get -overwritten each time gen_rec.awk is run) and fully developed there. -The recovery function takes the following parameters:</p> + <p> + The template_file will contain a template for a recovery + function. The recovery function is called on each record read + from the log during system recovery, transaction abort, or the + application of log records on a replication client, and is + expected to redo or undo the operations described by that + record. The details of the recovery function will be specific + to the record being logged and need to be written manually, + but the template provides a good starting point. (See + ex_apprec_template and ex_apprec_rec.c for an example of both + the template produced and the resulting recovery + function.) + </p> + <p> + The template file should be copied to a source file in the + application (but not the automatically generated source_file, + as that will get overwritten each time gen_rec.awk is run) and + fully developed there. The recovery function takes the + following parameters: + </p> <div class="blockquote"> <blockquote class="blockquote"> <div class="variablelist"> @@ -121,38 +144,56 @@ The recovery function takes the following parameters:</p> <dt> <span class="term">dbenv</span> </dt> - <dd>The environment in which recovery is running.</dd> + <dd> + The environment in which recovery is + running. + </dd> <dt> <span class="term">rec</span> </dt> - <dd>The record being recovered.</dd> + <dd> + The record being recovered. + </dd> <dt> <span class="term">lsn</span> </dt> - <dd>The log sequence number of the record being recovered. The -prev_lsn field, automatically included in every auto-generated log -record, should be returned through this argument. The prev_lsn field -is used to chain log records together to allow transaction aborts; -because the recovery function is the only place that a log record gets -parsed, the responsibility for returning this value lies with the -recovery function writer.</dd> + <dd> + The log sequence number of the record being + recovered. The prev_lsn field, automatically + included in every auto-generated log record, + should be returned through this argument. The + prev_lsn field is used to chain log records + together to allow transaction aborts; because the + recovery function is the only place that a log + record gets parsed, the responsibility for + returning this value lies with the recovery + function writer. + </dd> <dt> <span class="term">op</span> </dt> - <dd>A parameter of type db_recops, which indicates what operation is being -run (<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a>, <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a>, <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a>, -<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_FORWARD_ROLL" class="olink">DB_TXN_FORWARD_ROLL</a> or <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_PRINT" class="olink">DB_TXN_PRINT</a>). -</dd> + <dd> + A parameter of type db_recops, which + indicates what operation is being run + (<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a>, <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a>, + <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a>, <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_FORWARD_ROLL" class="olink">DB_TXN_FORWARD_ROLL</a> or + <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_PRINT" class="olink">DB_TXN_PRINT</a>). + </dd> </dl> </div> </blockquote> </div> - <p>In addition to the header_file and template_file, a source_file is -created, containing a log, read, recovery, and print function for each -record type.</p> - <p>The log function marshalls the parameters into a buffer, and calls -<a href="../api_reference/C/logput.html" class="olink">DB_ENV->log_put()</a> on that buffer returning 0 on success and non-zero on -failure. The log function takes the following parameters:</p> + <p> + In addition to the header_file and template_file, a + source_file is created, containing a log, read, recovery, and + print function for each record type. + </p> + <p> + The log function marshalls the parameters into a buffer, and + calls <a href="../api_reference/C/logput.html" class="olink">DB_ENV->log_put()</a> on that buffer returning 0 on success and + non-zero on failure. The log function takes the following + parameters: + </p> <div class="blockquote"> <blockquote class="blockquote"> <div class="variablelist"> @@ -160,36 +201,52 @@ failure. The log function takes the following parameters:</p> <dt> <span class="term">dbenv</span> </dt> - <dd>The environment in which recovery is running.</dd> + <dd>The environment in which recovery is + running.</dd> <dt> <span class="term">txnid</span> </dt> - <dd>The transaction identifier for the transaction handle returned by -<a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>.</dd> + <dd> + The transaction identifier for the + transaction handle returned by + <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>. + </dd> <dt> <span class="term">lsnp</span> </dt> - <dd>A pointer to storage for a log sequence number into which the log -sequence number of the new log record will be returned.</dd> + <dd> + A pointer to storage for a log sequence + number into which the log sequence number of the + new log record will be returned. + </dd> <dt> <span class="term">syncflag</span> </dt> - <dd>A flag indicating whether the record must be written synchronously. -Valid values are 0 and <a href="../api_reference/C/logput.html#put_DB_FLUSH" class="olink">DB_FLUSH</a>.</dd> + <dd> + A flag indicating whether the record must be + written synchronously. Valid values are 0 and + <a href="../api_reference/C/logput.html#put_DB_FLUSH" class="olink">DB_FLUSH</a>. + </dd> <dt> <span class="term">args</span> </dt> - <dd>The remaining parameters to the log message are the fields described -in the XXX.src file, in order.</dd> + <dd> + The remaining parameters to the log message + are the fields described in the XXX.src file, in + order. + </dd> </dl> </div> </blockquote> </div> - <p>The read function takes a buffer and unmarshalls its contents into a -structure of the appropriate type. It returns 0 on success and non-zero -on error. After the fields of the structure have been used, the pointer -returned from the read function should be freed. The read function -takes the following parameters:</p> + <p> + The read function takes a buffer and unmarshalls its + contents into a structure of the appropriate type. It returns + 0 on success and non-zero on error. After the fields of the + structure have been used, the pointer returned from the read + function should be freed. The read function takes the + following parameters: + </p> <div class="blockquote"> <blockquote class="blockquote"> <div class="variablelist"> @@ -197,25 +254,36 @@ takes the following parameters:</p> <dt> <span class="term">dbenv</span> </dt> - <dd>The environment in which recovery is running.</dd> + <dd> + The environment in which recovery is + running. + </dd> <dt> <span class="term">recbuf</span> </dt> - <dd>A buffer.</dd> + <dd> + A buffer. + </dd> <dt> <span class="term">argp</span> </dt> - <dd>A pointer to a structure of the appropriate type.</dd> + <dd> + A pointer to a structure of the appropriate + type. + </dd> </dl> </div> </blockquote> </div> - <p>The print function displays the contents of the record. The print -function takes the same parameters as the recovery function described -previously. Although some of the parameters are unused by the print -function, taking the same parameters allows a single dispatch loop to -dispatch to a variety of functions. The print function takes the -following parameters:</p> + <p> + The print function displays the contents of the record. The + print function takes the same parameters as the recovery + function described previously. Although some of the parameters + are unused by the print function, taking the same parameters + allows a single dispatch loop to dispatch to a variety of + functions. The print function takes the following + parameters: + </p> <div class="blockquote"> <blockquote class="blockquote"> <div class="variablelist"> @@ -223,27 +291,40 @@ following parameters:</p> <dt> <span class="term">dbenv</span> </dt> - <dd>The environment in which recovery is running.</dd> + <dd> + The environment in which recovery is + running. + </dd> <dt> <span class="term">rec</span> </dt> - <dd>The record being recovered.</dd> + <dd> + The record being recovered. + </dd> <dt> <span class="term">lsn</span> </dt> - <dd>The log sequence number of the record being recovered.</dd> + <dd> + The log sequence number of the record being + recovered. + </dd> <dt> <span class="term">op</span> </dt> - <dd>Unused.</dd> + <dd> + Unused. + </dd> </dl> </div> </blockquote> </div> - <p>Finally, the source file will contain a function (named XXX_init_print, -where XXX is replaced by the prefix) which should be added to the -initialization part of the standalone <a href="../api_reference/C/db_printlog.html" class="olink">db_printlog</a> utility code -so that utility can be used to display application-specific log records.</p> + <p> + Finally, the source file will contain a function (named + XXX_init_print, where XXX is replaced by the prefix) which + should be added to the initialization part of the standalone + <a href="../api_reference/C/db_printlog.html" class="olink">db_printlog</a> utility code so that utility can be used to display + application-specific log records. + </p> </div> <div class="navfooter"> <hr /> @@ -256,7 +337,8 @@ so that utility can be used to display application-specific log records.</p> <td width="40%" align="right"> <a accesskey="n" href="apprec_config.html">Next</a></td> </tr> <tr> - <td width="40%" align="left" valign="top">Defining application-specific log records </td> + <td width="40%" align="left" valign="top">Defining application-specific log + records </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |