The R13B03 release.OTP_R13B03

1 files changed, 265 insertions, 0 deletions

diff --git a/lib/mnesia/doc/src/Mnesia_chap1.xml b/lib/mnesia/doc/src/Mnesia_chap1.xml
new file mode 100644
index 0000000000..9af81c85cb
--- /dev/null
+++ b/lib/mnesia/doc/src/Mnesia_chap1.xml
@@ -0,0 +1,265 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Introduction</title>
+    <prepared>Claes Wikstr&ouml;m, Hans Nilsson and H&aring;kan Mattsson</prepared>
+    <responsible>Bjarne D&auml;cker</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked>Bjarne D&auml;cker</checked>
+    <date></date>
+    <rev>C</rev>
+    <file>Mnesia_chap1.xml</file>
+  </header>
+  <p>This book describes the Mnesia DataBase Management
+    System (DBMS). <em>Mnesia</em> is a distributed Database Management
+    System, appropriate for telecommunications applications and other
+    Erlang applications which require continuous operation and soft
+    real-time properties. It is one section of the Open Telecom Platform
+    (OTP), which is a control system platform for building
+    telecommunications applications.</p>
+
+  <section>
+    <title>About Mnesia</title>
+    <p>The management of data in telecommunications system has many
+      aspects whereof some, but not all, are addressed by traditional
+      commercial DBMSs (Data Base Management Systems). In particular the
+      very high level of fault tolerance which is required in many nonstop
+      systems,  combined with requirements on the DBMS to run in the same
+      address space as the application, have led us to implement a brand new
+      DBMS. called Mnesia. Mnesia is implemented in, and very tightly
+      connected to, the programming language Erlang and it provides the
+      functionality that is necessary for the implementation of fault 
+      tolerant telecommunications systems. Mnesia is a multiuser Distributed
+      DBMS specially made for industrial telecommunications applications
+      written in the symbolic programming language Erlang, which is also 
+      the intended target language. Mnesia tries to address all of the data
+      management issues required for typical telecommunications systems and
+      it has a number of features that are not normally found in traditional
+      databases.      <br></br>
+
+      In telecommunications applications there are different needs 
+      from the features provided by traditional DBMSs. The applications now
+      implemented in the Erlang language need a mixture of a broad range
+      of features, which generally are not satisfied by traditional DBMSs.
+      Mnesia is designed with requirements like the following in mind:</p>
+    <list type="ordered">
+      <item>Fast real-time key/value lookup</item>
+      <item>Complicated non real-time queries mainly for
+       operation and maintenance</item>
+      <item>Distributed data due to distributed 
+       applications</item>
+      <item>High fault tolerance</item>
+      <item>Dynamic re-configuration</item>
+      <item>Complex objects</item>
+    </list>
+    <p>What
+      sets Mnesia apart from most other DBMSs is that it is designed with
+      the typical data management problems of telecommunications applications
+      in mind. Hence Mnesia combines many concepts found in traditional
+      databases, such as transactions and queries with concepts found in data
+      management systems for telecommunications applications, such as very
+      fast real-time operations, configurable degree of fault tolerance (by
+      means of replication) and the ability to reconfigure the system without
+      stopping or suspending it. Mnesia is also interesting due to its tight
+      coupling to the programming language Erlang, thus almost turning Erlang
+      into a database programming language. This has many benefits, the
+      foremost is that
+      the impedance mismatch between data format used by the
+      DBMS and data format used by the programming language, which is used
+      to manipulate the data, completely disappears.      <br></br>
+</p>
+  </section>
+
+  <section>
+    <title>The Mnesia DataBase Management System (DBMS)</title>
+    <p></p>
+
+    <section>
+      <title>Features</title>
+      <p>Mnesia contains the following features which combine to produce a fault-tolerant,
+        distributed database management system written in Erlang:
+        </p>
+      <list type="bulleted">
+        <item>Database schema can be dynamically reconfigured at runtime.
+        </item>
+        <item>Tables can be declared to have properties such as location, 
+         replication, and persistence.
+        </item>
+        <item>Tables can be moved or replicated to several nodes to improve 
+         fault tolerance. The rest of the system can still access the tables 
+         to read, write, and delete records.
+        </item>
+        <item>Table locations are transparent to the programmer. 
+         Programs address table names and the system itself keeps track of 
+         table locations.
+        </item>
+        <item>Database transactions can be distributed, and a large number of 
+         functions can be called within one transaction.
+        </item>
+        <item>Several transactions can run concurrently, and their execution is 
+         fully synchronized by the database management system. 
+         Mnesia ensures that no two processes manipulate data simultaneously.
+        </item>
+        <item>Transactions can be assigned the property of being executed on 
+         all nodes in the system, or on none. Transactions can also be bypassed 
+         in favor of running so called "dirty operations", which reduce 
+         overheads and run very fast.
+        </item>
+      </list>
+      <p>Details of these features are described in the following sections.</p>
+    </section>
+    <p></p>
+
+    <section>
+      <title>Add-on Applications</title>
+      <p>QLC and Mnesia Session can be used in conjunction with Mnesia to produce 
+        specialized functions which enhance the  operational ability of Mnesia.  
+        Both Mnesia Session and QLC have their own documentation as part
+        of the OTP documentation set.  Below are the main features of Mnesia Session
+        and QLC when used in conjunction with Mnesia:</p>
+      <list type="bulleted">
+        <item><em>QLC</em> has the ability to optimize the query
+         compiler for the Mnesia Database Management System, essentially making
+         the DBMS more efficient.</item>
+        <item><em>QLC</em>, can be used as a database programming
+         language for Mnesia. It includes a notation called "list
+         comprehensions" and can be used to make complex database
+         queries over a set of tables.</item>
+        <item><em>Mnesia Session</em> is an interface for the Mnesia Database 
+         Management System</item>
+        <item><em>Mnesia Session</em> enables access to the
+         Mnesia DBMS from foreign programming languages (i.e. other
+         languages than Erlang).</item>
+      </list>
+      <p></p>
+
+      <section>
+        <title>When to Use Mnesia</title>
+        <p>Use Mnesia with the following types of applications:
+          </p>
+        <list type="bulleted">
+          <item>Applications that need to replicate data.
+          </item>
+          <item>Applications that perform complicated searches on data.
+          </item>
+          <item>Applications that need to use atomic transactions to 
+           update several records simultaneously.
+          </item>
+          <item>Applications that  use soft real-time characteristics.
+          </item>
+        </list>
+        <p>On the other hand, Mnesia may not be appropriate with the 
+          following types of applications:
+          </p>
+        <list type="bulleted">
+          <item>Programs that process plain text or binary data files
+          </item>
+          <item>Applications that merely need a look-up dictionary
+           which can be stored to disc can utilize the standard
+           library module <c>dets</c>, which is a disc based version
+           of the module <c>ets</c>. 
+          </item>
+          <item>Applications which need disc logging facilities can
+           utilize the module <c>disc_log</c> by preference.
+          </item>
+          <item>Not suitable for hard real time systems.
+          </item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>Scope and Purpose</title>
+      <p>This manual is included in the OTP document set. It describes
+        how to build Mnesia database applications, and how to integrate
+        and utilize the Mnesia database management system with
+        OTP. Programming constructs are described, and numerous
+        programming examples are included to illustrate the use of
+        Mnesia.
+        </p>
+    </section>
+
+    <section>
+      <title>Prerequisites</title>
+      <p>Readers of this manual are assumed to be familiar with system
+        development principles and database management systems. Readers
+        are also assumed to be familiar with the Erlang programming
+        language.</p>
+    </section>
+
+    <section>
+      <title>About This Book</title>
+      <p>This book contains the following chapters:
+        </p>
+      <list type="bulleted">
+        <item>Chapter 2, "Getting Started with Mnesia", introduces
+         Mnesia with an example database. Examples are shown of how to
+         start an Erlang session, specify a Mnesia database directory,
+         initialize a database schema, start Mnesia, and create
+         tables. Initial prototyping of record definitions is also
+         discussed.
+        </item>
+        <item>Chapter 3, "Building a Mnesia Database", more formally
+         describes the steps introduced in Chapter 2, namely the Mnesia
+         functions which define a database schema, start Mnesia, and
+         create the required tables.
+        </item>
+        <item>Chapter 4, "Transactions and other access contexts",
+         describes the transactions properties which make Mnesia into a
+         fault tolerant, real-time distributed database management
+         system. This chapter also describes the concept of locking in
+         order to ensure consistency in tables, and so called "dirty
+         operations", or short cuts which bypass the transaction system
+         to improve speed and reduce overheads.
+        </item>
+        <item>Chapter 5, "Miscellaneous Mnesia Features", describes
+         features which enable the construction of more complex
+         database applications. These features includes indexing,
+         checkpoints, distribution and fault tolerance, disc-less
+         nodes, replication manipulation, local content tables, concurrency,
+         and object based programming in Mnesia.
+        </item>
+        <item>Chapter 6, "Mnesia System Information", describes the
+         files contained in the Mnesia database directory, database
+         configuration data, core and table dumps, as well as the
+         important subject of backup, fall-back, and disaster recovery
+         principles.
+        </item>
+        <item>Chapter 7, "Combining Mnesia with SNMP", is a short
+         chapter which outlines  Mnesia  integrated with SNMP.
+        </item>
+        <item>Appendix A, "Mnesia Errors Messages", lists Mnesia error
+         messages and their meanings.
+        </item>
+        <item>Appendix B, "The Backup Call Back Interface", is a
+         program listing of the default implementation of this facility.
+        </item>
+        <item>Appendix C, "The Activity Access Call Back Interface",
+         is a program outlining of one possible implementations of this facility.
+        </item>
+      </list>
+    </section>
+  </section>
+</chapter>
+