From dc32f2450a2fd1fc25950887bbfba15a87c2a945 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sun, 30 Oct 2016 17:45:43 +0000
Subject: [PATCH] Document new automatic file locking

We also restructure the notes and warnings accordingly, and move more
important info up. We also mention SQLite as alternative.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@340805 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/dbase/book.xml | 44 ++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 17 deletions(-)

diff --git a/reference/dbase/book.xml b/reference/dbase/book.xml
index a1867db175..20bb41a243 100644
--- a/reference/dbase/book.xml
+++ b/reference/dbase/book.xml
@@ -8,10 +8,36 @@
  <!-- {{{ preface -->
  <preface xml:id="intro.dbase">
   &reftitle.intro;
+  <note>
+   <para>
+    &pecl.moved-ver;5.3.0.
+   </para>
+  </note>
   <para>
    These functions allow you to access records stored in dBase-format
    (dbf) databases.
   </para>
+  <warning>
+   <para>
+    We recommend against using dBase files as your production
+    database. Use <link xlink:href="&url.sqlite;">SQLite</link> or choose any real SQL server instead; <link 
+    xlink:href="&url.mysql;">MySQL</link> or <link xlink:href="&url.pgsql;">Postgres</link>
+    are common choices with PHP. dBase support is here to allow you to
+    import and export data to and from your web database, because the
+    file format is commonly understood by Windows spreadsheets and
+    organizers.
+   </para>
+  </warning>
+  <caution>
+   <para>
+    As of dbase 7.0.0 the databases are automatically locked via
+    <function>flock</function>. There has been no support for locking earlier,
+    so two concurrent web server processes modifying the same dBase file would
+    have very likely ruined your database. This can happen even with dbase
+    7.0.0+ on systems which implement the locks at the process level with
+    multithreaded SAPIs such as ISAPI.
+   </para>
+  </caution>
   <para>
    dBase files are simple sequential files of fixed length records. 
    Records are appended to the end of the file and deleted records are
@@ -89,25 +115,9 @@
   </para>
   <note>
    <para>
-    &pecl.moved-ver;5.3.0.
+    There is no support for indexes or memo fields.
    </para>
   </note>
-  <warning>
-   <para>
-    There is no support for indexes or memo fields. There is no
-    support for locking, too. Two concurrent web server processes
-    modifying the same dBase file will very likely ruin your database.
-   </para>
-   <para>
-    We recommend that you do not use dBase files as your production
-    database. Choose any real SQL server instead; <link 
-    xlink:href="&url.mysql;">MySQL</link> or <link xlink:href="&url.pgsql;">Postgres</link>
-    are common choices with PHP. dBase support is here to allow you to
-    import and export data to and from your web database, because the
-    file format is commonly understood by Windows spreadsheets and
-    organizers.
-   </para>
-  </warning>
  </preface>
  <!-- }}} -->