aboutsummaryrefslogtreecommitdiffstats
path: root/lib/mnesia/doc/src/mnesia.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/mnesia/doc/src/mnesia.xml')
-rw-r--r--lib/mnesia/doc/src/mnesia.xml3100
1 files changed, 3100 insertions, 0 deletions
diff --git a/lib/mnesia/doc/src/mnesia.xml b/lib/mnesia/doc/src/mnesia.xml
new file mode 100644
index 0000000000..3484cd104a
--- /dev/null
+++ b/lib/mnesia/doc/src/mnesia.xml
@@ -0,0 +1,3100 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</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>mnesia</title>
+ <prepared>Claes Wikstr&ouml;m and H&aring;kan Mattsson</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file></file>
+ </header>
+ <module>mnesia</module>
+ <modulesummary>A Distributed Telecommunications DBMS </modulesummary>
+ <description>
+ <p><c>Mnesia</c> is a distributed DataBase Management System (DBMS),
+ appropriate for telecommunications applications and other Erlang
+ applications which require continuous operation and exhibit soft
+ real-time properties.
+ </p>
+ <p>Listed below are some of the most important and attractive capabilities, Mnesia provides:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>A relational/object hybrid data model which is
+ suitable for telecommunications applications.
+ </p>
+ </item>
+ <item>
+ <p>A specifically designed DBMS query language, QLC (as an add-on library).
+ </p>
+ </item>
+ <item>
+ <p>Persistence. Tables may be coherently kept on disc as
+ well as in main memory.
+ </p>
+ </item>
+ <item>
+ <p>Replication. Tables may be replicated at several nodes.
+ </p>
+ </item>
+ <item>
+ <p>Atomic transactions. A series of table manipulation
+ operations can be grouped into a single atomic
+ transaction.
+ </p>
+ </item>
+ <item>
+ <p>Location transparency. Programs can be written without
+ knowledge of the actual location of data.
+ </p>
+ </item>
+ <item>
+ <p>Extremely fast real time data searches.
+ </p>
+ </item>
+ <item>
+ <p>Schema manipulation routines. It is possible to
+ reconfigure the DBMS at runtime without stopping the
+ system.
+ </p>
+ </item>
+ </list>
+ <p>This Reference Manual describes the Mnesia API. This includes
+ functions used to define and manipulate Mnesia tables.
+ </p>
+ <p>All functions documented in these pages can be used in any
+ combination with queries using the list comprehension notation. The
+ query notation is described in the QLC's man page.
+ </p>
+ <p>Data in Mnesia is organized as a set of tables. Each table
+ has a name which must be an atom. Each table is made up of
+ Erlang records. The user is responsible for the record
+ definitions. Each table also has a set of properties. Below
+ are some of the properties that are associated with each
+ table:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>type</c>. Each table can either have 'set',
+ 'ordered_set' or 'bag' semantics. Note: currently 'ordered_set'
+ is not supported for 'disc_only_copies'. If a table is of type
+ 'set' it means that each key leads to either one or zero
+ records. <br></br>
+If a new item is inserted with the same key as
+ an existing record, the old record is overwritten. On the
+ other hand, if a table is of type 'bag', each key can map to
+ several records. However, all records in type bag tables are
+ unique, only the keys may be duplicated.
+ </p>
+ </item>
+ <item>
+ <p><c>record_name</c>. All records stored in a table must
+ have the same name. You may say that the records must be
+ instances of the same record type.
+ </p>
+ </item>
+ <item>
+ <p><c>ram_copies</c> A table can be replicated on a number
+ of Erlang nodes. The <c>ram_copies</c> property specifies a
+ list of Erlang nodes where RAM copies are kept. These
+ copies can be dumped to disc at regular intervals. However,
+ updates to these copies are not written to disc on a
+ transaction basis.
+ </p>
+ </item>
+ <item>
+ <p><c>disc_copies</c> The <c>disc_copies</c> property
+ specifies a list of Erlang nodes where the table is kept in
+ RAM as well as on disc. All updates of the table are
+ performed on the actual table and are also logged to disc.
+ If a table is of type <c>disc_copies</c> at a certain node,
+ it means that the entire table is resident in RAM memory as
+ well as on disc. Each transaction performed on the table is
+ appended to a LOG file as well as written into the RAM
+ table.
+ </p>
+ </item>
+ <item>
+ <p><c>disc_only_copies</c> Some, or all, table replicas
+ can be kept on disc only. These replicas are considerably
+ slower than the RAM based replicas.
+ </p>
+ </item>
+ <item>
+ <p><c>index</c> This is a list of attribute names, or
+ integers, which specify the tuple positions on which
+ Mnesia shall build and maintain an extra index table.
+ </p>
+ </item>
+ <item>
+ <p><c>local_content</c> When an application requires
+ tables whose contents is local to each node,
+ <c>local_content</c> tables may be used. The name of the
+ table is known to all Mnesia nodes, but its contents is
+ unique on each node. This means that access to such a table
+ must be done locally. Set the <c>local_content</c> field to
+ <c>true</c> if you want to enable the <c>local_content</c>
+ behavior. The default is <c>false</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>snmp</c> Each (set based) Mnesia table can be
+ automatically turned into an SNMP ordered table as well.
+ This property specifies the types of the SNMP keys.
+ </p>
+ </item>
+ <item>
+ <p><c>attributes</c>. The names of the attributes for the
+ records that are inserted in the table.
+ </p>
+ </item>
+ </list>
+ <p>See <c>mnesia:create_table/2</c> about the complete set of
+ table properties and their details.
+ </p>
+ <p>This document uses a table of persons to illustrate various
+ examples. The following record definition is assumed:
+ </p>
+ <code type="none">
+-record(person, {name,
+ age = 0,
+ address = unknown,
+ salary = 0,
+ children = []}),
+ </code>
+ <p>The first attribute of the record is the primary key, or key
+ for short.
+ </p>
+ <p>The function descriptions are sorted in alphabetic order. <em>Hint:</em>
+ start to read about <c>mnesia:create_table/2</c>,
+ <c>mnesia:lock/2</c> and <c>mnesia:activity/4</c> before you continue on
+ and learn about the rest.
+ </p>
+ <p>Writing or deleting in transaction context creates a local copy
+ of each modified record during the transaction. During iteration,
+ i.e. <c>mnesia:fold[lr]/4</c> <c>mnesia:next/2</c> <c>mnesia:prev/2</c>
+ <c>mnesia:snmp_get_next_index/2</c>, mnesia will compensate for
+ every written or deleted record, which may reduce the
+ performance. If possible avoid writing or deleting records in
+ the same transaction before iterating over the table.
+ </p>
+ </description>
+ <funcs>
+ <func>
+ <name>abort(Reason) -> transaction abort </name>
+ <fsummary>Abort the current transaction.</fsummary>
+ <desc>
+ <p>Makes the transaction silently
+ return the tuple <c>{aborted, Reason}</c>.
+ The abortion of a Mnesia transaction means that
+ an exception will be thrown to an enclosing <c>catch</c>.
+ Thus, the expression <c>catch mnesia:abort(x)</c> does
+ not abort the transaction. </p>
+ </desc>
+ </func>
+ <func>
+ <name>activate_checkpoint(Args) -> {ok,Name,Nodes} | {error,Reason}</name>
+ <fsummary>Activate a checkpoint.</fsummary>
+ <desc>
+ <p>A checkpoint is a consistent view of the system.
+ A checkpoint can be activated on a set of tables.
+ This checkpoint can then be traversed and will
+ present a view of the system as it existed at the time when
+ the checkpoint was activated, even if the tables are being or have been
+ manipulated.
+ </p>
+ <p><c>Args</c> is a list of the following tuples:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>{name,Name}</c>. <c>Name</c> of checkpoint. Each
+ checkpoint must have a name which is unique to the
+ associated nodes. The name can be reused only once the
+ checkpoint has been deactivated. By default, a name
+ which is probably unique is generated.
+ </p>
+ </item>
+ <item>
+ <p><c>{max,MaxTabs}</c><c>MaxTabs</c> is a list of
+ tables that should be included in the checkpoint. The
+ default is []. For these tables, the redundancy will be
+ maximized and checkpoint information will be retained together
+ with all replicas. The checkpoint becomes more fault
+ tolerant if the tables have several replicas. When a new
+ replica is added by means of the schema manipulation
+ function <c>mnesia:add_table_copy/3</c>, a retainer will
+ also be attached automatically.
+ </p>
+ </item>
+ <item>
+ <p><c>{min,MinTabs}</c>. <c>MinTabs</c> is a list of
+ tables that should be included in the checkpoint. The
+ default is []. For these tables, the redundancy will be
+ minimized and the checkpoint information will only be retained
+ with one replica, preferably on the local node.
+ </p>
+ </item>
+ <item>
+ <p><c>{allow_remote,Bool}</c>. <c>false</c> means that
+ all retainers must be local. The checkpoint cannot be
+ activated if a table does not reside locally.
+ <c>true</c> allows retainers to be allocated on any
+ node. Default is set to <c>true</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>{ram_overrides_dump,Bool} </c> Only applicable
+ for <c>ram_copies</c>. <c>Bool</c> allows you to choose
+ to backup the table state as it is in RAM, or as it is on
+ disc. <c>true</c> means that the latest committed
+ records in RAM should be included in the checkpoint.
+ These are the records that the application accesses.
+ <c>false</c> means that the records dumped to DAT files
+ should be included in the checkpoint. These are the
+ records that will be loaded at startup. Default is
+ <c>false</c>.
+ </p>
+ </item>
+ </list>
+ <p>Returns <c>{ok,Name,Nodes}</c> or <c>{error,Reason}</c>.
+ <c>Name</c> is the (possibly generated) name of the
+ checkpoint. <c>Nodes</c> are the nodes that
+ are involved in the checkpoint. Only nodes that keep a
+ checkpoint retainer know about the checkpoint.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>activity(AccessContext, Fun [, Args]) -> ResultOfFun | exit(Reason)</name>
+ <fsummary>Execute <c>Fun</c>in <c>AccessContext</c>.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:activity(AccessContext, Fun, Args, AccessMod)</c> where <c>AccessMod</c> is the default
+ access callback module obtained by
+ <c>mnesia:system_info(access_module)</c>. <c>Args</c>
+ defaults to the empty list <c>[]</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>activity(AccessContext, Fun, Args, AccessMod) -> ResultOfFun | exit(Reason)</name>
+ <fsummary>Execute <c>Fun</c>in <c>AccessContext</c>.</fsummary>
+ <desc>
+ <p>This function executes the functional object <c>Fun</c>
+ with the arguments <c>Args</c>.
+ </p>
+ <p>The code which executes inside the activity can
+ consist of a series of table manipulation functions, which is
+ performed in a <c>AccessContext</c>. Currently, the following
+ access contexts are supported:
+ </p>
+ <taglist>
+ <tag><c>transaction</c></tag>
+ <item>
+ <p>Short for <c>{transaction, infinity}</c></p>
+ </item>
+ <tag><c>{transaction, Retries}</c></tag>
+ <item>
+ <p>Invokes <c>mnesia:transaction(Fun, Args, Retries)</c>. Note that the result from the <c>Fun</c> is
+ returned if the transaction was successful (atomic),
+ otherwise the function exits with an abort reason.
+ </p>
+ </item>
+ <tag><c>sync_transaction</c></tag>
+ <item>
+ <p>Short for <c>{sync_transaction, infinity}</c></p>
+ </item>
+ <tag><c>{sync_transaction, Retries}</c></tag>
+ <item>
+ <p>Invokes <c>mnesia:sync_transaction(Fun, Args, Retries)</c>. Note that the result from the <c>Fun</c> is
+ returned if the transaction was successful (atomic),
+ otherwise the function exits with an abort reason.
+ </p>
+ </item>
+ <tag><c>async_dirty</c></tag>
+ <item>
+ <p>Invokes <c>mnesia:async_dirty(Fun, Args)</c>.
+ </p>
+ </item>
+ <tag><c>sync_dirty</c></tag>
+ <item>
+ <p>Invokes <c>mnesia:sync_dirty(Fun, Args)</c>.
+ </p>
+ </item>
+ <tag><c>ets</c></tag>
+ <item>
+ <p>Invokes <c>mnesia:ets(Fun, Args)</c>.
+ </p>
+ </item>
+ </taglist>
+ <p>This function (<c>mnesia:activity/4</c>) differs in an
+ important aspect from the <c>mnesia:transaction</c>,
+ <c>mnesia:sync_transaction</c>,
+ <c>mnesia:async_dirty</c>, <c>mnesia:sync_dirty</c> and
+ <c>mnesia:ets</c> functions. The <c>AccessMod</c> argument
+ is the name of a callback module which implements the
+ <c>mnesia_access</c> behavior.
+ </p>
+ <p>Mnesia will forward calls to the following functions:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>mnesia:write/3 (write/1, s_write/1)</p>
+ </item>
+ <item>
+ <p>mnesia:delete/3 (delete/1, s_delete/1)</p>
+ </item>
+ <item>
+ <p>mnesia:delete_object/3 (delete_object/1, s_delete_object/1)</p>
+ </item>
+ <item>
+ <p>mnesia:read/3 (read/1, wread/1)</p>
+ </item>
+ <item>
+ <p>mnesia:match_object/3 (match_object/1)</p>
+ </item>
+ <item>
+ <p>mnesia:all_keys/1</p>
+ </item>
+ <item>
+ <p>mnesia:first/1</p>
+ </item>
+ <item>
+ <p>mnesia:last/1</p>
+ </item>
+ <item>
+ <p>mnesia:prev/2</p>
+ </item>
+ <item>
+ <p>mnesia:next/2</p>
+ </item>
+ <item>
+ <p>mnesia:index_match_object/4 (index_match_object/2)</p>
+ </item>
+ <item>
+ <p>mnesia:index_read/3</p>
+ </item>
+ <item>
+ <p>mnesia:lock/2 (read_lock_table/1, write_lock_table/1)</p>
+ </item>
+ <item>
+ <p>mnesia:table_info/2</p>
+ </item>
+ </list>
+ <p>to the corresponding:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>AccessMod:lock(ActivityId, Opaque, LockItem, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:write(ActivityId, Opaque, Tab, Rec, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:delete(ActivityId, Opaque, Tab, Key, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:delete_object(ActivityId, Opaque, Tab, RecXS, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:read(ActivityId, Opaque, Tab, Key, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:match_object(ActivityId, Opaque, Tab, Pattern, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:all_keys(ActivityId, Opaque, Tab, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:first(ActivityId, Opaque, Tab)</p>
+ </item>
+ <item>
+ <p>AccessMod:last(ActivityId, Opaque, Tab)</p>
+ </item>
+ <item>
+ <p>AccessMod:prev(ActivityId, Opaque, Tab, Key)</p>
+ </item>
+ <item>
+ <p>AccessMod:next(ActivityId, Opaque, Tab, Key)</p>
+ </item>
+ <item>
+ <p>AccessMod:index_match_object(ActivityId, Opaque, Tab, Pattern, Attr, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:index_read(ActivityId, Opaque, Tab, SecondaryKey, Attr, LockKind)</p>
+ </item>
+ <item>
+ <p>AccessMod:table_info(ActivityId, Opaque, Tab, InfoItem)</p>
+ </item>
+ </list>
+ <p>where <c>ActivityId</c> is a record which represents the
+ identity of the enclosing Mnesia activity. The first field
+ (obtained with <c>element(1, ActivityId)</c> contains an
+ atom which may be interpreted as the type of the activity:
+ <c>'ets'</c>, <c>'async_dirty'</c>, <c>'sync_dirty'</c> or
+ <c>'tid'</c>. <c>'tid'</c> means that the activity is a
+ transaction. The structure of the rest of the identity
+ record is internal to Mnesia.
+ </p>
+ <p><c>Opaque</c> is an opaque data structure which is internal
+ to Mnesia.</p>
+ </desc>
+ </func>
+ <func>
+ <name>add_table_copy(Tab, Node, Type) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Copy a table to a remote node.</fsummary>
+ <desc>
+ <p>This function makes another copy of a table at the
+ node <c>Node</c>. The <c>Type</c> argument must be
+ either of the atoms <c>ram_copies</c>, <c>disc_copies</c>,
+ or
+ <c>disc_only_copies</c>. For example, the following call
+ ensures that a disc replica of the <c>person</c> table also
+ exists at node <c>Node</c>.</p>
+ <code type="none">
+mnesia:add_table_copy(person, Node, disc_copies)
+ </code>
+ <p>This function can also be used to add a replica of the
+ table named <c>schema</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>add_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Create an index for a table. </fsummary>
+ <desc>
+ <p>Table indices can and should be used whenever the user
+ wants to frequently use some other field than the key field
+ to look up records. If this other field has an index
+ associated with it, these lookups can occur in constant time
+ and space. For example, if our application wishes to use
+ the age field of persons to efficiently find all person with
+ a specific age, it might be a good idea to have an index on
+ the age field. This can be accomplished with the following
+ call:</p>
+ <code type="none">
+mnesia:add_table_index(person, age)
+ </code>
+ <p>Indices do not come free, they occupy space which is
+ proportional to the size of the table. They also cause insertions
+ into the table to execute slightly slower. </p>
+ </desc>
+ </func>
+ <func>
+ <name>all_keys(Tab) -> KeyList | transaction abort</name>
+ <fsummary>Return all keys in a table.</fsummary>
+ <desc>
+ <p>This function returns a list of all keys in the table
+ named <c>Tab</c>. The semantics of this function is context
+ sensitive. See <c>mnesia:activity/4</c> for more information. In
+ transaction context it acquires a read lock on the entire
+ table.</p>
+ </desc>
+ </func>
+ <func>
+ <name>async_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason)</name>
+ <fsummary>Call the Fun in a context which is not protected by a transaction.</fsummary>
+ <desc>
+ <p>Call the <c>Fun</c> in a context which is not protected
+ by a transaction. The Mnesia function calls performed in the
+ <c>Fun</c> are mapped to the corresponding dirty
+ functions. This still involves logging, replication and
+ subscriptions, but there is no locking, local transaction
+ storage, or commit protocols involved. Checkpoint retainers
+ and indices are updated, but they will be updated dirty. As
+ for normal mnesia:dirty_* operations, the operations are
+ performed semi-asynchronously. See
+ <c>mnesia:activity/4</c> and the Mnesia User's Guide for
+ more details.
+ </p>
+ <p>It is possible to manipulate the Mnesia tables without
+ using transactions. This has some serious disadvantages, but
+ is considerably faster since the transaction manager is not
+ involved and no locks are set. A dirty operation does,
+ however, guarantee a certain level of consistency and it is
+ not possible for the dirty operations to return garbled
+ records. All dirty operations provide location transparency
+ to the programmer and a program does not have to be aware of
+ the whereabouts of a certain table in order to function.
+ </p>
+ <p><em>Note:</em>It is more than 10 times more efficient to read records dirty
+ than within a transaction.
+ </p>
+ <p>Depending on the application, it may be a good idea to use
+ the dirty functions for certain operations. Almost all
+ Mnesia functions which can be called within transactions
+ have a dirty equivalent which is much more
+ efficient. However, it must be noted that it is possible for
+ the database to be left in an inconsistent state if dirty
+ operations are used to update it. Dirty operations should
+ only be used for performance reasons when it is absolutely
+ necessary. </p>
+ <p><em>Note:</em> Calling (nesting) a <c>mnesia:[a]sync_dirty</c>
+ inside a transaction context will inherit the transaction semantics.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>backup(Opaque [, BackupMod]) -> ok | {error,Reason}</name>
+ <fsummary>Back up all tables in the database.</fsummary>
+ <desc>
+ <p>Activates a new checkpoint covering all Mnesia tables,
+ including the schema, with maximum degree of redundancy and
+ performs a backup using <c>backup_checkpoint/2/3</c>. The
+ default value of the backup callback module <c>BackupMod</c>
+ is obtained by <c>mnesia:system_info(backup_module)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>backup_checkpoint(Name, Opaque [, BackupMod]) -> ok | {error,Reason}</name>
+ <fsummary>Back up all tables in a checkpoint.</fsummary>
+ <desc>
+ <p>The tables are backed up to external media using the backup
+ module <c>BackupMod</c>. Tables with the local contents
+ property is being backed up as they exist on the current
+ node. <c>BackupMod</c> is the default backup callback
+ module obtained by
+ <c>mnesia:system_info(backup_module)</c>. See the User's
+ Guide about the exact callback interface (the
+ <c>mnesia_backup behavior</c>).</p>
+ </desc>
+ </func>
+ <func>
+ <name>change_config(Config, Value) -> {error, Reason} | {ok, ReturnValue}</name>
+ <fsummary>Change a configuration parameter.</fsummary>
+ <desc>
+ <p>The <c>Config</c> should be an atom of the following
+ configuration parameters: </p>
+ <taglist>
+ <tag><c>extra_db_nodes</c></tag>
+ <item>
+ <p><c>Value</c> is a list of nodes which Mnesia should try to connect to.
+ The <c>ReturnValue</c> will be those nodes in
+ <c>Value</c> that Mnesia are connected to.
+ <br></br>
+Note: This function shall only be used to connect to newly started ram nodes
+ (N.D.R.S.N.) with an empty schema. If for example it is used after the network
+ have been partitioned it may lead to inconsistent tables.
+ <br></br>
+Note: Mnesia may be connected to other nodes than those
+ returned in <c>ReturnValue</c>.</p>
+ </item>
+ <tag><c>dc_dump_limit</c></tag>
+ <item>
+ <p><c>Value</c> is a number. See description in
+ <c>Configuration Parameters</c> below.
+ The <c>ReturnValue</c> is the new value. Note this configuration parameter
+ is not persistent, it will be lost when mnesia stopped.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>change_table_access_mode(Tab, AccessMode) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Change the access mode for the table.</fsummary>
+ <desc>
+ <p>The <c>AcccessMode</c> is by default the atom
+ <c>read_write</c> but it may also be set to the atom
+ <c>read_only</c>. If the <c>AccessMode</c> is set to
+ <c>read_only</c>, it means that it is not possible to perform
+ updates to the table. At startup Mnesia always loads
+ <c>read_only</c> tables locally regardless of when and if
+ Mnesia was terminated on other nodes.</p>
+ </desc>
+ </func>
+ <func>
+ <name>change_table_copy_type(Tab, Node, To) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Change the storage type of a table.</fsummary>
+ <desc>
+ <p>For example:</p>
+ <code type="none">
+mnesia:change_table_copy_type(person, node(), disc_copies)
+ </code>
+ <p>Transforms our <c>person</c> table from a RAM table into
+ a disc based table at <c>Node</c>.
+ </p>
+ <p>This function can also be used to change the storage type of
+ the table named <c>schema</c>. The schema table can only
+ have <c>ram_copies</c> or <c>disc_copies</c> as the storage type. If the
+ storage type of the schema is <c>ram_copies</c>, no other table
+ can be disc resident on that node.</p>
+ </desc>
+ </func>
+ <func>
+ <name>change_table_load_order(Tab, LoadOrder) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Change the load order priority for the table.</fsummary>
+ <desc>
+ <p>The <c>LoadOrder</c> priority is by default <c>0</c> (zero)
+ but may be set to any integer. The tables with the highest
+ <c>LoadOrder</c> priority will be loaded first at startup.</p>
+ </desc>
+ </func>
+ <func>
+ <name>clear_table(Tab) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Deletes all entries in a table.</fsummary>
+ <desc>
+ <p>Deletes all entries in the table <c>Tab</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>create_schema(DiscNodes) -> ok | {error,Reason}</name>
+ <fsummary>Create a brand new schema on the specified nodes.</fsummary>
+ <desc>
+ <p>Creates a new database on disc. Various files are
+ created in the local Mnesia directory of each node. Note
+ that the directory must be unique for each node. Two nodes
+ may never share the same directory. If possible, use a local
+ disc device in order to improve performance.</p>
+ <p><c>mnesia:create_schema/1</c> fails if any of the
+ Erlang nodes given as <c>DiscNodes</c> are not alive, if
+ Mnesia is running on anyone of the nodes, or if anyone of
+ the nodes already has a schema. Use
+ <c>mnesia:delete_schema/1</c> to get rid of old faulty
+ schemas.
+ </p>
+ <p><em>Note:</em> Only nodes with disc should be
+ included in <c>DiscNodes</c>. Disc-less nodes, that is nodes
+ where all tables including the schema only resides in RAM,
+ may not be included.</p>
+ </desc>
+ </func>
+ <func>
+ <name>create_table(Name, TabDef) -> {atomic, ok} | {aborted, Reason}</name>
+ <fsummary>Create a Mnesia table called <c>Name</c>with properties as described by the argument <c>TabDef</c>.</fsummary>
+ <desc>
+ <p>This function creates a Mnesia table called <c>Name</c>
+ according to the
+ argument <c>TabDef</c>. This list must be a list of
+ <c>{Item, Value}</c> tuples, where the following values are
+ allowed:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>{access_mode, Atom}</c>. The access mode is by
+ default the atom <c>read_write</c> but it may also be
+ set to the atom <c>read_only</c>. If the
+ <c>AccessMode</c> is set to <c>read_only</c>, it means
+ that it is not possible to perform updates to the table.
+ </p>
+ <p>At startup Mnesia always loads <c>read_only</c> tables
+ locally regardless of when and if Mnesia was terminated
+ on other nodes. This argument returns the access mode of
+ the table. The access mode may either be read_only or
+ read_write.
+ </p>
+ </item>
+ <item>
+ <p><c>{attributes, AtomList}</c> a list of the
+ attribute names for the records that are supposed to
+ populate the table. The default value is <c>[key, val]</c>. The table must have at least one extra
+ attribute in addition to the key.
+ </p>
+ <p>When accessing single attributes in a record, it is not
+ necessary, or even recommended, to hard code any
+ attribute names as atoms. Use the construct
+ <c>record_info(fields, RecordName)</c> instead. It can be
+ used for records of type <c>RecordName</c></p>
+ </item>
+ <item>
+ <p><c>{disc_copies, Nodelist}</c>, where
+ <c>Nodelist</c> is a list of the nodes where this table
+ is supposed to have disc copies. If a table replica is
+ of type <c>disc_copies</c>, all write operations on this
+ particular replica of the table are written to disc as
+ well as to the RAM copy of the table.
+ </p>
+ <p>It is possible
+ to have a replicated table of type <c>disc_copies</c>
+ on one node, and another type on another node. The
+ default value is <c>[]</c></p>
+ </item>
+ <item>
+ <p><c>{disc_only_copies, Nodelist}</c>, where
+ <c>Nodelist</c> is a list of the nodes where this table
+ is supposed to have <c>disc_only_copies</c>. A disc only
+ table replica is kept on disc only and unlike the other
+ replica types, the contents of the replica will not
+ reside in RAM. These replicas are considerably slower
+ than replicas held in RAM.
+ </p>
+ </item>
+ <item>
+ <p><c>{index, Intlist}</c>, where
+ <c>Intlist</c> is a list of attribute names (atoms) or
+ record fields for which Mnesia shall build and maintain
+ an extra index table. The <c>qlc</c> query compiler may
+ or may not utilize any additional indices while
+ processing queries on a table.
+ </p>
+ </item>
+ <item>
+ <p><c>{load_order, Integer}</c>. The load order
+ priority is by default <c>0</c> (zero) but may be set to
+ any integer. The tables with the highest load order
+ priority will be loaded first at startup.
+ </p>
+ </item>
+ <item>
+ <p><c>{ram_copies, Nodelist}</c>, where
+ <c>Nodelist</c> is a list of the nodes where this table
+ is supposed to have RAM copies. A table replica of type
+ <c>ram_copies</c> is obviously not written to disc on a
+ per transaction basis. It is possible to dump
+ <c>ram_copies</c> replicas to disc with the function
+ <c>mnesia:dump_tables(Tabs)</c>. The default value for
+ this attribute is <c>[node()]</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>{record_name, Name}</c>, where <c>Name</c> must
+ be an atom. All records, stored in the table, must have
+ this name as the first element. It defaults to the same
+ name as the name of the table.
+ </p>
+ </item>
+ <item>
+ <p><c>{snmp, SnmpStruct}</c>. See
+ <c>mnesia:snmp_open_table/2</c> for a description of
+ <c>SnmpStruct</c>. If this attribute is present in the
+ <c>ArgList</c> to <c>mnesia:create_table/2</c>, the
+ table is immediately accessible by means of the Simple
+ Network Management Protocol (SNMP). This means that
+ applications which use SNMP to manipulate and control
+ the system can be designed easily, since Mnesia provides
+ a direct mapping between the logical tables that make up
+ an SNMP control application and the physical data which
+ makes up a Mnesia table.
+ </p>
+ </item>
+ <item>
+ <p><c>{type, Type}</c>, where <c>Type</c> must be
+ either of the atoms <c>set</c>, <c>ordered_set</c> or
+ <c>bag</c>. The default value is <c>set</c>. In a
+ <c>set</c> all records have unique keys and in a
+ <c>bag</c> several records may have the same key, but
+ the record content is unique. If a non-unique record is
+ stored the old, conflicting record(s) will simply be
+ overwritten. Note: currently 'ordered_set'
+ is not supported for 'disc_only_copies'.
+ </p>
+ </item>
+ <item>
+ <p><c>{local_content, Bool}</c>, where <c>Bool</c> must be
+ either <c>true</c> or <c>false</c>. The default value is <c>false</c>.\011 </p>
+ </item>
+ </list>
+ <p>For example, the following call creates the <c>person</c> table
+ previously defined and replicates it on 2 nodes:
+ </p>
+ <code type="none">
+mnesia:create_table(person,
+ [{ram_copies, [N1, N2]},
+ {attributes, record_info(fields,person)}]).
+ </code>
+ <p>If it was required that Mnesia build and maintain an extra index
+ table on the <c>address</c> attribute of all the <c>person</c>
+ records that are inserted in the table, the following code would be issued:
+ </p>
+ <code type="none">
+mnesia:create_table(person,
+ [{ram_copies, [N1, N2]},
+ {index, [address]},
+ {attributes, record_info(fields,person)}]).
+ </code>
+ <p>The specification of <c>index</c> and <c>attributes</c> may be
+ hard coded as <c>{index, [2]}</c> and
+ <c>{attributes, [name, age, address, salary, children]}</c>
+ respectively.
+ </p>
+ <p><c>mnesia:create_table/2</c> writes records into the
+ <c>schema</c> table. This function, as well as all other
+ schema manipulation functions, are implemented with the
+ normal transaction management system. This guarantees that
+ schema updates are performed on all nodes in an atomic
+ manner.</p>
+ </desc>
+ </func>
+ <func>
+ <name>deactivate_checkpoint(Name) -> ok | {error, Reason}</name>
+ <fsummary>Deactivate a checkpoint.</fsummary>
+ <desc>
+ <p>The checkpoint is automatically deactivated when some of
+ the tables involved have no retainer attached to them. This may
+ happen when nodes go down or when a replica is deleted.
+ Checkpoints will also be deactivated with this function.
+ <c>Name</c> is the name of an active checkpoint.</p>
+ </desc>
+ </func>
+ <func>
+ <name>del_table_copy(Tab, Node) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Delete the replica of table <c>Tab</c>at node <c>Node</c>.</fsummary>
+ <desc>
+ <p>Deletes the replica of table <c>Tab</c> at node <c>Node</c>.
+ When the last replica is deleted with this
+ function, the table disappears entirely.
+ </p>
+ <p>This function may also be used to delete a replica of
+ the table named <c>schema</c>. Then the mnesia node will be removed.
+ Note: Mnesia must be stopped on the node first.</p>
+ </desc>
+ </func>
+ <func>
+ <name>del_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Delete an index in a table. </fsummary>
+ <desc>
+ <p>This function deletes the index on attribute with name
+ <c>AttrName</c> in a table.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete({Tab, Key}) -> transaction abort | ok </name>
+ <fsummary>Delete all records in table <c>Tab</c>with the key <c>Key</c>.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:delete(Tab, Key, write)</c></p>
+ </desc>
+ </func>
+ <func>
+ <name>delete(Tab, Key, LockKind) -> transaction abort | ok </name>
+ <fsummary>Delete all records in table <c>Tab</c>with the key <c>Key</c>.</fsummary>
+ <desc>
+ <p>Deletes all records in table <c>Tab</c> with the key
+ <c>Key</c>.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type <c>LockKind</c> in the
+ record. Currently the lock types <c>write</c> and
+ <c>sticky_write</c> are supported.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_object(Record) -> transaction abort | ok </name>
+ <fsummary>Delete a record</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:delete_object(Tab, Record, write)</c> where
+ <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_object(Tab, Record, LockKind) -> transaction abort | ok </name>
+ <fsummary>Delete a record</fsummary>
+ <desc>
+ <p>If a table is of type <c>bag</c>, we may sometimes
+ want to delete only some of the records with a certain
+ key. This can be done with the <c>delete_object/3</c>
+ function. A complete record must be supplied to this
+ function.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type <c>LockKind</c> on the
+ record. Currently the lock types <c>write</c> and
+ <c>sticky_write</c> are supported.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_schema(DiscNodes) -> ok | {error,Reason}</name>
+ <fsummary>Delete the schema on the given nodes</fsummary>
+ <desc>
+ <p>Deletes a database created with
+ <c>mnesia:create_schema/1</c>.
+ <c>mnesia:delete_schema/1</c> fails if any of the Erlang
+ nodes given as <c>DiscNodes</c> is not alive, or if Mnesia
+ is running on any of the nodes.
+ </p>
+ <p>After the database has been deleted, it may still be
+ possible to start Mnesia as a disc-less node. This depends on
+ how the configuration parameter <c>schema_location</c> is set.
+ </p>
+ <warning>
+ <p>This function must be used with extreme
+ caution since it makes existing persistent data
+ obsolete. Think twice before using it. </p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>delete_table(Tab) -> {aborted, Reason} | {atomic, ok} </name>
+ <fsummary>Delete permanently all replicas of table <c>Tab</c>.</fsummary>
+ <desc>
+ <p>Permanently deletes all replicas of table <c>Tab</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_all_keys(Tab) -> KeyList | exit({aborted, Reason}).</name>
+ <fsummary>Dirty search for all record keys in table.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:all_keys/1</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_delete({Tab, Key}) -> ok | exit({aborted, Reason}) </name>
+ <fsummary>Dirty delete of a record.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_delete(Tab, Key)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_delete(Tab, Key) -> ok | exit({aborted, Reason}) </name>
+ <fsummary>Dirty delete of a record. </fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:delete/3</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_delete_object(Record) </name>
+ <fsummary>Dirty delete of a record.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_delete_object(Tab, Record)</c>
+ where <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_delete_object(Tab, Record) </name>
+ <fsummary>Dirty delete of a record. </fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:delete_object/3</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_first(Tab) -> Key | exit({aborted, Reason}) </name>
+ <fsummary>Return the key for the first record in a table.</fsummary>
+ <desc>
+ <p>Records in <c>set</c> or <c>bag</c> tables are not ordered.
+ However, there
+ is an ordering of the records which is not known
+ to the user. Accordingly, it is possible to traverse a table by means
+ of this function in conjunction with the <c>mnesia:dirty_next/2</c>
+ function.
+ </p>
+ <p>If there are no records at all in the table, this function
+ returns the atom <c>'$end_of_table'</c>. For this reason, it
+ is highly undesirable, but not disallowed, to use this atom
+ as the key for any user records.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_index_match_object(Pattern, Pos)</name>
+ <fsummary>Dirty pattern match using index.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_index_match_object(Tab, Pattern, Pos)</c> where <c>Tab</c> is <c>element(1, Pattern)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_index_match_object(Tab, Pattern, Pos)</name>
+ <fsummary>Dirty pattern match using index.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:index_match_object/4</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_index_read(Tab, SecondaryKey, Pos)</name>
+ <fsummary>Dirty read using index.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:index_read/3</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_last(Tab) -> Key | exit({aborted, Reason}) </name>
+ <fsummary>Return the key for the last record in a table.</fsummary>
+ <desc>
+ <p>This function works exactly
+ <c>mnesia:dirty_first/1</c> but returns the last object in
+ Erlang term order for the <c>ordered_set</c> table type. For
+ all other table types, <c>mnesia:dirty_first/1</c> and
+ <c>mnesia:dirty_last/1</c> are synonyms.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_match_object(Pattern) -> RecordList | exit({aborted, Reason}).</name>
+ <fsummary>Dirty pattern match pattern.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_match_object(Tab, Pattern)</c>
+ where <c>Tab</c> is <c>element(1, Pattern)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_match_object(Tab, Pattern) -> RecordList | exit({aborted, Reason}).</name>
+ <fsummary>Dirty pattern match pattern.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:match_object/3</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_next(Tab, Key) -> Key | exit({aborted, Reason}) </name>
+ <fsummary>Return the next key in a table. </fsummary>
+ <desc>
+ <p>This function makes it possible to traverse a table
+ and perform operations on all records in the table. When
+ the end of the table is reached, the special key
+ <c>'$end_of_table'</c> is returned. Otherwise, the function
+ returns a key which can be used to read the actual record.The
+ behavior is undefined if another Erlang process performs write
+ operations on the table while it is being traversed with the
+ <c>mnesia:dirty_next/2</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_prev(Tab, Key) -> Key | exit({aborted, Reason}) </name>
+ <fsummary>Return the previous key in a table. </fsummary>
+ <desc>
+ <p>This function works exactly
+ <c>mnesia:dirty_next/2</c> but returns the previous object in
+ Erlang term order for the ordered_set table type. For
+ all other table types, <c>mnesia:dirty_next/2</c> and
+ <c>mnesia:dirty_prev/2</c> are synonyms.\011 </p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_read({Tab, Key}) -> ValueList | exit({aborted, Reason}</name>
+ <fsummary>Dirty read of records.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_read(Tab, Key)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_read(Tab, Key) -> ValueList | exit({aborted, Reason}</name>
+ <fsummary>Dirty read of records.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:read/3</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_select(Tab, MatchSpec) -> ValueList | exit({aborted, Reason}</name>
+ <fsummary>Dirty match the objects in <c>Tab</c>against <c>MatchSpec</c>.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of the
+ <c>mnesia:select/2</c> function.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_slot(Tab, Slot) -> RecordList | exit({aborted, Reason})</name>
+ <fsummary>Return the list of records that are associated with Slot in a table.</fsummary>
+ <desc>
+ <p>This function can be used to traverse a table in a
+ manner similar to the <c>mnesia:dirty_next/2</c> function.
+ A table has a number of slots which range from 0 (zero) to some
+ unknown upper bound. The function
+ <c>mnesia:dirty_slot/2</c> returns the special atom
+ <c>'$end_of_table'</c> when the end of the table is reached.
+ The behavior of this function is undefined if a write
+ operation is performed on the table while it is being
+ traversed.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_update_counter({Tab, Key}, Incr) -> NewVal | exit({aborted, Reason})</name>
+ <fsummary>Dirty update of a counter record.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_update_counter(Tab, Key, Incr)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_update_counter(Tab, Key, Incr) -> NewVal | exit({aborted, Reason})</name>
+ <fsummary>Dirty update of a counter record.</fsummary>
+ <desc>
+ <p>There are no special counter records in Mnesia. However,
+ records of the form <c>{Tab, Key, Integer}</c> can be used
+ as (possibly disc resident) counters, when <c>Tab</c> is a
+ <c>set</c>. This function updates a counter with a
+ positive or negative number. However, counters can never become less
+ than zero. There are two significant differences between
+ this function and the action of first reading the record,
+ performing the arithmetics, and then writing the record:</p>
+ <list type="bulleted">
+ <item>It is much more efficient</item>
+ <item><c>mnesia:dirty_update_counter/3</c> is
+ performed as an atomic operation despite the fact that it is not
+ protected by a transaction.</item>
+ </list>
+ <p>If two processes perform <c>mnesia:dirty_update_counter/3</c>
+ simultaneously, both updates will take effect without the
+ risk of loosing one of the updates. The new value
+ <c>NewVal</c> of the counter is returned.</p>
+ <p>If <c>Key</c> don't exits, a new record is created with the value
+ <c>Incr</c> if it is larger than 0, otherwise it is set to 0.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_write(Record) -> ok | exit({aborted, Reason})</name>
+ <fsummary>Dirty write of a record.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:dirty_write(Tab, Record)</c>
+ where <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dirty_write(Tab, Record) -> ok | exit({aborted, Reason})</name>
+ <fsummary>Dirty write of a record.</fsummary>
+ <desc>
+ <p>This is the dirty equivalent of <c>mnesia:write/3</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dump_log() -> dumped</name>
+ <fsummary>Perform a user initiated dump of the local log file.</fsummary>
+ <desc>
+ <p>Performs a user initiated dump of the local log file.
+ This is usually not necessary since Mnesia, by default,
+ manages this automatically.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dump_tables(TabList) -> {atomic, ok} | {aborted, Reason}</name>
+ <fsummary>Dump all RAM tables to disc.</fsummary>
+ <desc>
+ <p>This function dumps a set of <c>ram_copies</c> tables
+ to disc. The next time the system is started, these tables
+ are initiated with the data found in the files that are the
+ result of this dump. None of the tables may have disc
+ resident replicas.</p>
+ </desc>
+ </func>
+ <func>
+ <name>dump_to_textfile(Filename) </name>
+ <fsummary>Dump local tables into a text file.</fsummary>
+ <desc>
+ <p>Dumps all local tables of a mnesia system into a text file
+ which can then be edited (by means of a normal text editor)
+ and then later be reloaded with
+ <c>mnesia:load_textfile/1</c>. Only use this function for
+ educational purposes. Use other functions to deal with real
+ backups.</p>
+ </desc>
+ </func>
+ <func>
+ <name>error_description(Error) -> String </name>
+ <fsummary>Return a string describing a particular Mnesia error.</fsummary>
+ <desc>
+ <p>All Mnesia transactions, including all the schema
+ update functions, either return the value <c>{atomic, Val}</c> or the tuple <c>{aborted, Reason}</c>. The
+ <c>Reason</c> can be either of the following atoms. The
+ <c>error_description/1</c> function returns a descriptive
+ string which describes the error.
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>nested_transaction</c>. Nested transactions are
+ not allowed in this context.
+ </p>
+ </item>
+ <item>
+ <p><c>badarg</c>. Bad or invalid argument, possibly
+ bad type.
+ </p>
+ </item>
+ <item>
+ <p><c>no_transaction</c>. Operation not allowed
+ outside transactions.
+ </p>
+ </item>
+ <item>
+ <p><c>combine_error</c>. Table options were illegally
+ combined.
+ </p>
+ </item>
+ <item>
+ <p><c>bad_index</c>. Index already exists or was out
+ of bounds.
+ </p>
+ </item>
+ <item>
+ <p><c>already_exists</c>. Schema option is already set.
+ </p>
+ </item>
+ <item>
+ <p><c>index_exists</c>. Some operations cannot be performed on
+ tabs with index.
+ </p>
+ </item>
+ <item>
+ <p><c>no_exists</c>. Tried to perform operation on
+ non-existing, or not alive, item.
+ </p>
+ </item>
+ <item>
+ <p><c>system_limit</c>. Some system_limit was exhausted.
+ </p>
+ </item>
+ <item>
+ <p><c>mnesia_down</c>. A transaction involving
+ records at some remote node which died while
+ transaction was executing. Record(s) are no longer
+ available elsewhere in the network.
+ </p>
+ </item>
+ <item>
+ <p><c>not_a_db_node</c>. A node which does not exist
+ in the schema was mentioned.
+ </p>
+ </item>
+ <item>
+ <p><c>bad_type</c>. Bad type on some arguments.
+ </p>
+ </item>
+ <item>
+ <p><c>node_not_running</c>. Node not running.
+ </p>
+ </item>
+ <item>
+ <p><c>truncated_binary_file</c>. Truncated binary in file.
+ </p>
+ </item>
+ <item>
+ <p><c>active</c>. Some delete operations require that
+ all active records are removed.
+ </p>
+ </item>
+ <item>
+ <p><c>illegal</c>. Operation not supported on record.
+ </p>
+ </item>
+ </list>
+ <p>The <c>Error</c> may be <c>Reason</c>,
+ <c>{error, Reason}</c>, or <c>{aborted, Reason}</c>. The
+ <c>Reason</c> may be an atom or a tuple with <c>Reason</c>
+ as an atom in the first field.</p>
+ </desc>
+ </func>
+ <func>
+ <name>ets(Fun, [, Args]) -> ResultOfFun | exit(Reason)</name>
+ <fsummary>Call the Fun in a raw context which is not protected by a transaction.</fsummary>
+ <desc>
+ <p>Call the <c>Fun</c> in a raw context which is not protected by
+ a transaction. The Mnesia function call is performed in the
+ <c>Fun</c> are performed directly on the local <c>ets</c> tables on
+ the assumption that the local storage type is
+ <c>ram_copies</c> and the tables are not replicated to other
+ nodes. Subscriptions are not triggered and checkpoints are
+ not updated, but it is extremely fast. This function can
+ also be applied to <c>disc_copies</c> tables if all
+ operations are read only. See <c>mnesia:activity/4</c>
+ and the Mnesia User's Guide for more details.</p>
+ <p><em>Note:</em> Calling (nesting) a <c>mnesia:ets</c>
+ inside a transaction context will inherit the transaction semantics.</p>
+ </desc>
+ </func>
+ <func>
+ <name>first(Tab) -> Key | transaction abort </name>
+ <fsummary>Return the key for the first record in a table.</fsummary>
+ <desc>
+ <p>Records in <c>set</c> or <c>bag</c> tables are not ordered.
+ However, there
+ is an ordering of the records which is not known
+ to the user. Accordingly, it is possible to traverse a table by means
+ of this function in conjunction with the <c>mnesia:next/2</c>
+ function.
+ </p>
+ <p>If there are no records at all in the table, this function
+ returns the atom <c>'$end_of_table'</c>. For this reason, it
+ is highly undesirable, but not disallowed, to use this atom
+ as the key for any user records.</p>
+ </desc>
+ </func>
+ <func>
+ <name>foldl(Function, Acc, Table) -> NewAcc | transaction abort </name>
+ <fsummary>Call Function for each record in Table </fsummary>
+ <desc>
+ <p>Iterates over the table <c>Table</c> and calls
+ <c>Function(Record, NewAcc)</c> for each <c>Record</c> in the table.
+ The term returned from <c>Function</c> will be used as the second
+ argument in the next call to the <c>Function</c>.
+ </p>
+ <p><c>foldl</c> returns the same term as the last call to
+ <c>Function</c> returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>foldr(Function, Acc, Table) -> NewAcc | transaction abort </name>
+ <fsummary>Call Function for each record in Table </fsummary>
+ <desc>
+ <p>This function works exactly as
+ <c>foldl/3</c> but iterates the table in the opposite order
+ for the <c>ordered_set</c> table type. For
+ all other table types, <c>foldr/3</c> and
+ <c>foldl/3</c> are synonyms.</p>
+ </desc>
+ </func>
+ <func>
+ <name>force_load_table(Tab) -> yes | ErrorDescription </name>
+ <fsummary>Force a table to be loaded into the system </fsummary>
+ <desc>
+ <p>The Mnesia algorithm for table load might lead to a
+ situation where a table cannot be loaded. This situation
+ occurs when a node is started and Mnesia concludes, or
+ suspects, that another copy of the table was active after
+ this local copy became inactive due to a system crash.
+ </p>
+ <p>If this situation is not acceptable, this function can be
+ used to override the strategy of the Mnesia table load
+ algorithm. This could lead to a situation where some
+ transaction effects are lost with a inconsistent database as
+ result, but for some applications high availability is more
+ important than consistent data.</p>
+ </desc>
+ </func>
+ <func>
+ <name>index_match_object(Pattern, Pos) -> transaction abort | ObjList</name>
+ <fsummary>Match records and utilizes index information.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:index_match_object(Tab, Pattern, Pos, read)</c> where <c>Tab</c> is <c>element(1, Pattern)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>index_match_object(Tab, Pattern, Pos, LockKind) -> transaction abort | ObjList</name>
+ <fsummary>Match records and utilizes index information.</fsummary>
+ <desc>
+ <p>In a manner similar to the <c>mnesia:index_read/3</c>
+ function, we can also utilize any index information when we
+ try to match records. This function takes a pattern which
+ obeys the same rules as the <c>mnesia:match_object/3</c>
+ function with the exception that this function requires the
+ following conditions:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>The table <c>Tab</c> must have an index on
+ position <c>Pos</c>.
+ </p>
+ </item>
+ <item>
+ <p>The element in position <c>Pos</c> in
+ <c>Pattern</c> must be bound. <c>Pos</c> may either be
+ an integer (#record.Field), or an attribute name.</p>
+ </item>
+ </list>
+ <p>The two index search functions described here are
+ automatically invoked when searching tables with <c>qlc</c>
+ list comprehensions and also when using the low level
+ <c>mnesia:[dirty_]match_object</c> functions.
+ </p>
+ <p></p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type <c>LockKind</c> on the
+ entire table or on a single record. Currently, the lock type
+ <c>read</c> is supported.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>index_read(Tab, SecondaryKey, Pos) -> transaction abort | RecordList </name>
+ <fsummary>Read records via index table. </fsummary>
+ <desc>
+ <p>Assume there is an index on position <c>Pos</c> for a
+ certain record type. This function can be used to read the
+ records without knowing the actual key for the record. For
+ example, with an index in position 1 of the <c>person</c>
+ table, the call <c>mnesia:index_read(person, 36, #person.age)</c> returns a list of all persons with age
+ equal to 36. <c>Pos</c> may also be an attribute name
+ (atom), but if the notation <c>mnesia:index_read(person, 36, age)</c> is used, the field position will be searched for in
+ runtime, for each call.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a read lock on the entire table.</p>
+ </desc>
+ </func>
+ <func>
+ <name>info() -> ok </name>
+ <fsummary>Print some information about the system on the tty.</fsummary>
+ <desc>
+ <p>Prints some information about the system on the tty.
+ This function may be used even if Mnesia is not started.
+ However, more information will be displayed if Mnesia is
+ started.</p>
+ </desc>
+ </func>
+ <func>
+ <name>install_fallback(Opaque) -> ok | {error,Reason}</name>
+ <fsummary>Install a backup as fallback.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:install_fallback(Opaque, Args)</c> where
+ <c>Args</c> is <c>[{scope, global}]</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>install_fallback(Opaque), BackupMod) -> ok | {error,Reason}</name>
+ <fsummary>Install a backup as fallback.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:install_fallback(Opaque, Args)</c> where
+ <c>Args</c> is <c>[{scope, global}, {module, BackupMod}]</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>install_fallback(Opaque, Args) -> ok | {error,Reason}</name>
+ <fsummary>Install a backup as fallback.</fsummary>
+ <desc>
+ <p>This function is used to install a backup as fallback. The
+ fallback will be used to restore the database at the next
+ start-up. Installation of fallbacks requires Erlang to be up
+ and running on all the involved nodes, but it does not
+ matter if Mnesia is running or not. The installation of the
+ fallback will fail if the local node is not one of the disc
+ resident nodes in the backup.
+ </p>
+ <p><c>Args</c> is a list of the following tuples:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>{module, BackupMod}</c>.
+ All accesses of the backup media is performed via a
+ callback module named <c>BackupMod</c>. The
+ <c>Opaque</c> argument is forwarded to the callback
+ module which may interpret it as it wish. The default
+ callback module is called <c>mnesia_backup</c> and it
+ interprets the <c>Opaque</c> argument as a local
+ filename. The default for this module is also
+ configurable via the <c>-mnesia mnesia_backup</c>
+ configuration parameter. </p>
+ </item>
+ <item>
+ <p><c>{scope, Scope}</c>
+ The <c>Scope</c> of a fallback may either be
+ <c>global</c> for the entire database or <c>local</c>
+ for one node. By default, the installation of a fallback
+ is a global operation which either is performed all
+ nodes with disc resident schema or none. Which nodes
+ that are disc resident or not, is determined from the
+ schema info in the backup.</p>
+ <p>If the <c>Scope</c> of the operation is <c>local</c>
+ the fallback will only be installed on the local node.</p>
+ </item>
+ <item>
+ <p><c>{mnesia_dir, AlternateDir}</c>
+ This argument is only valid if the scope of the
+ installation is <c>local</c>. Normally the installation
+ of a fallback is targeted towards the Mnesia directory
+ as configured with the <c>-mnesia dir</c> configuration
+ parameter. But by explicitly supplying an
+ <c>AlternateDir</c> the fallback will be installed there
+ regardless of the Mnesia directory configuration
+ parameter setting. After installation of a fallback on
+ an alternate Mnesia directory that directory is fully
+ prepared for usage as an active Mnesia directory.
+ </p>
+ <p>This is a somewhat dangerous feature which must be
+ used with care. By unintentional mixing of directories
+ you may easily end up with a inconsistent database, if
+ the same backup is installed on more than one directory.</p>
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>is_transaction() -> boolean </name>
+ <fsummary>Check if code is running in a transaction.</fsummary>
+ <desc>
+ <p>When this function is executed inside a transaction context
+ it returns <c>true</c>, otherwise <c>false</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>last(Tab) -> Key | transaction abort </name>
+ <fsummary>Return the key for the last record in a table.</fsummary>
+ <desc>
+ <p>This function works exactly
+ <c>mnesia:first/1</c> but returns the last object in
+ Erlang term order for the <c>ordered_set</c> table type. For
+ all other table types, <c>mnesia:first/1</c> and
+ <c>mnesia:last/1</c> are synonyms.</p>
+ </desc>
+ </func>
+ <func>
+ <name>load_textfile(Filename)</name>
+ <fsummary>Load tables from a text file.</fsummary>
+ <desc>
+ <p>Loads a series of definitions and data found in the
+ text file (generated with <c>mnesia:dump_to_textfile/1</c>)
+ into Mnesia. This function also starts Mnesia and possibly
+ creates a new schema. This function is intended for
+ educational purposes only and using other functions to deal
+ with real backups, is recommended.</p>
+ </desc>
+ </func>
+ <func>
+ <name>lock(LockItem, LockKind) -> Nodes | ok | transaction abort</name>
+ <fsummary>Explicit grab lock.</fsummary>
+ <desc>
+ <p>Write locks are normally acquired on all nodes where a
+ replica of the table resides (and is active). Read locks are
+ acquired on one node (the local node if a local
+ replica exists). Most of the context sensitive access functions
+ acquire an implicit lock if they are invoked in a
+ transaction context. The granularity of a lock may either
+ be a single record or an entire table.
+ </p>
+ <p>The normal usage is to call the function without checking
+ the return value since it exits if it fails and the
+ transaction is restarted by the transaction manager. It
+ returns all the locked nodes if a write lock is acquired, and
+ <c>ok</c> if it was a read lock.
+ </p>
+ <p>This function <c>mnesia:lock/2</c> is intended to support
+ explicit locking on tables but also intended for situations
+ when locks need to be acquired regardless of how tables are
+ replicated. Currently, two <c>LockKind</c>'s are supported:
+ </p>
+ <taglist>
+ <tag><c>write</c></tag>
+ <item>
+ <p>Write locks are exclusive, which means that if one
+ transaction manages to acquire a write lock on an item,
+ no other transaction may acquire any kind of lock on the
+ same item.
+ </p>
+ </item>
+ <tag><c>read</c></tag>
+ <item>
+ <p>Read locks may be shared, which means that if one
+ transaction manages to acquire a read lock on an item,
+ other transactions may also acquire a read lock on the
+ same item. However, if someone has a read lock no one can
+ acquire a write lock at the same item. If some one has a
+ write lock no one can acquire a read lock nor
+ a write lock at the same item.</p>
+ </item>
+ </taglist>
+ <p>Conflicting lock requests are automatically queued if there
+ is no risk of a deadlock. Otherwise the transaction must be
+ aborted and executed again. Mnesia does this automatically
+ as long as the upper limit of maximum <c>retries</c> is not
+ reached. See <c>mnesia:transaction/3</c> for the details.
+ </p>
+ <p>For the sake of completeness sticky write locks will also
+ be described here even if a sticky write lock is not
+ supported by this particular function:
+ </p>
+ <taglist>
+ <tag><c>sticky_write</c></tag>
+ <item>
+ <p>Sticky write locks are a mechanism which can be used
+ to optimize write lock acquisition. If your application
+ uses replicated tables mainly for fault tolerance (as
+ opposed to read access optimization purpose), sticky
+ locks may be the best option available.
+ </p>
+ <p>When a sticky write lock is acquired, all nodes will be
+ informed which node is locked. Subsequently,
+ sticky lock requests from the same node will be
+ performed as a local operation without any
+ communication with other nodes. The sticky lock
+ lingers on the node even after the transaction has
+ ended. See the Mnesia User's Guide for more information.</p>
+ </item>
+ </taglist>
+ <p>Currently, two kinds of <c>LockItem</c>'s are supported by
+ this function:
+ </p>
+ <taglist>
+ <tag><c>{table, Tab}</c></tag>
+ <item>
+ <p>This acquires a lock of type <c>LockKind</c> on the
+ entire table <c>Tab</c>.
+ </p>
+ </item>
+ <tag><c>{global, GlobalKey, Nodes}</c></tag>
+ <item>
+ <p>This acquires a lock of type <c>LockKind</c> on the
+ global resource <c>GlobalKey</c>. The lock is acquired
+ on all active nodes in the <c>Nodes</c> list. </p>
+ </item>
+ </taglist>
+ <p>Locks are released when the outermost transaction ends.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires locks otherwise it just ignores the
+ request.</p>
+ </desc>
+ </func>
+ <func>
+ <name>match_object(Pattern) ->transaction abort | RecList </name>
+ <fsummary>Match <c>Pattern</c>for records. </fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:match_object(Tab, Pattern, read)</c> where
+ <c>Tab</c> is <c>element(1, Pattern)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>match_object(Tab, Pattern, LockKind) ->transaction abort | RecList </name>
+ <fsummary>Match <c>Pattern</c>for records. </fsummary>
+ <desc>
+ <p>This function takes a pattern with 'don't care' variables
+ denoted as a '_' parameter. This function returns a list of
+ records which matched the pattern. Since the second element
+ of a record in a table is considered to be the key for the
+ record, the performance of this function depends on whether
+ this key is bound or not.
+ </p>
+ <p>For example, the call <c>mnesia:match_object(person, {person, '_', 36, '_', '_'}, read)</c> returns a list of all person records with an
+ age field of thirty-six (36).
+ </p>
+ <p>The function <c>mnesia:match_object/3</c>
+ automatically uses indices if these exist. However, no
+ heuristics are performed in order to select the best
+ index.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type <c>LockKind</c> on the
+ entire table or a single record. Currently, the lock type
+ <c>read</c> is supported.</p>
+ </desc>
+ </func>
+ <func>
+ <name>move_table_copy(Tab, From, To) -> {aborted, Reason} | {atomic, ok}</name>
+ <fsummary>Move the copy of table <c>Tab</c>from node<c>From</c>to node <c>To</c>.</fsummary>
+ <desc>
+ <p>Moves the copy of table <c>Tab</c> from node
+ <c>From</c> to node <c>To</c>.
+ </p>
+ <p>The storage type is preserved. For example, a RAM table
+ moved from one node remains a RAM on the new node. It is
+ still possible for other transactions to read and write in
+ the table while it is being moved.
+ </p>
+ <p>This function cannot be used on <c>local_content</c> tables.</p>
+ </desc>
+ </func>
+ <func>
+ <name>next(Tab, Key) -> Key | transaction abort </name>
+ <fsummary>Return the next key in a table. </fsummary>
+ <desc>
+ <p>This function makes it possible to traverse a table
+ and perform operations on all records in the table. When
+ the end of the table is reached, the special key
+ <c>'$end_of_table'</c> is returned. Otherwise, the function
+ returns a key which can be used to read the actual record.</p>
+ </desc>
+ </func>
+ <func>
+ <name>prev(Tab, Key) -> Key | transaction abort </name>
+ <fsummary>Return the previous key in a table. </fsummary>
+ <desc>
+ <p>This function works exactly
+ <c>mnesia:next/2</c> but returns the previous object in
+ Erlang term order for the ordered_set table type. For
+ all other table types, <c>mnesia:next/2</c> and
+ <c>mnesia:prev/2</c> are synonyms.\011 </p>
+ </desc>
+ </func>
+ <func>
+ <name>read({Tab, Key}) -> transaction abort | RecordList </name>
+ <fsummary>Read records(s) with a given key. </fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:read(Tab, Key, read)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read(Tab, Key) -> transaction abort | RecordList </name>
+ <fsummary>Read records(s) with a given key. </fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:read(Tab, Key, read)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read(Tab, Key, LockKind) -> transaction abort | RecordList </name>
+ <fsummary>Read records(s) with a given key. </fsummary>
+ <desc>
+ <p>This function reads all records from table <c>Tab</c> with
+ key <c>Key</c>. This function has the same semantics
+ regardless of the location of <c>Tab</c>. If the table is
+ of type <c>bag</c>, the <c>mnesia:read(Tab, Key)</c> can
+ return an arbitrarily long list. If the table is of type
+ <c>set</c>, the list is either of length 1, or <c>[]</c>.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type
+ <c>LockKind</c>. Currently, the lock types <c>read</c>,
+ <c>write</c> and <c>sticky_write</c> are supported.
+ </p>
+ <p>If the user wants to update the record it is more efficient to
+ use <c>write/sticky_write</c> as the LockKind.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>read_lock_table(Tab) -> ok | transaction abort</name>
+ <fsummary>Set a read lock on an entire table.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:lock({table, Tab}, read)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>report_event(Event) -> ok</name>
+ <fsummary>Report a user event to Mnesia's event handler.</fsummary>
+ <desc>
+ <p>When tracing a system of Mnesia applications it is useful
+ to be able to interleave Mnesia's own events with
+ application related events that give information about the
+ application context.
+ </p>
+ <p>Whenever the application begins a
+ new and demanding Mnesia task, or if it is entering a new
+ interesting phase in its execution, it may be a good idea to
+ use <c>mnesia:report_event/1</c>. The <c>Event</c> may be
+ any term and generates a <c>{mnesia_user, Event}</c> event
+ for any processes that subscribe to Mnesia system
+ events.</p>
+ </desc>
+ </func>
+ <func>
+ <name>restore(Opaque, Args) -> {atomic, RestoredTabs} |{aborted, Reason}</name>
+ <fsummary>Online restore of backup.</fsummary>
+ <desc>
+ <p>With this function, tables may be restored online from a
+ backup without restarting Mnesia. <c>Opaque</c> is forwarded
+ to the backup module. <c>Args</c> is a list of the following
+ tuples:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>{module,BackupMod}</c> The backup module
+ <c>BackupMod</c> will be used to access the backup
+ media. If omitted, the default backup module will be
+ used.
+ </p>
+ </item>
+ <item><c>{skip_tables, TabList}</c> Where <c>TabList</c>
+ is a list of tables which should not be read from the
+ backup.
+ </item>
+ <item><c>{clear_tables, TabList}</c> Where
+ <c>TabList</c> is a list of tables which should be
+ cleared, before the records from the backup are inserted,
+ ie. all records in the tables are deleted before the
+ tables are restored. Schema information about the tables
+ is not cleared or read from backup.
+ </item>
+ <item><c>{keep_tables, TabList}</c> Where <c>TabList</c>
+ is a list of tables which should be not be cleared, before
+ the records from the backup are inserted, i.e. the records
+ in the backup will be added to the records in the table.
+ Schema information about the tables is not cleared or read
+ from backup.
+ </item>
+ <item><c>{recreate_tables, TabList}</c> Where
+ <c>TabList</c> is a list of tables which should be
+ re-created, before the records from the backup are
+ inserted. The tables are first deleted and then created with
+ the schema information from the backup. All the nodes in the
+ backup needs to be up and running.
+ </item>
+ <item><c>{default_op, Operation}</c> Where <c>Operation</c> is
+ one of the following operations <c>skip_tables</c>,
+ <c>clear_tables</c>, <c>keep_tables</c> or
+ <c>recreate_tables</c>. The default operation specifies
+ which operation should be used on tables from the backup
+ which are not specified in any of the lists above. If
+ omitted, the operation <c>clear_tables</c> will be used.
+ </item>
+ </list>
+ <p>The affected tables are write locked during the
+ restoration, but regardless of the lock conflicts caused by
+ this, the applications can continue to do their work while
+ the restoration is being performed. The restoration is
+ performed as one single transaction.
+ </p>
+ <p>If the database is
+ huge, it may not be possible to restore it online. In such
+ cases, the old database must be restored by installing a
+ fallback and then restart.</p>
+ </desc>
+ </func>
+ <func>
+ <name>s_delete({Tab, Key}) -> ok | transaction abort </name>
+ <fsummary>Set sticky lock and delete records.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:delete(Tab, Key, sticky_write)</c></p>
+ </desc>
+ </func>
+ <func>
+ <name>s_delete_object(Record) -> ok | transaction abort </name>
+ <fsummary>Set sticky lock and delete record.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:delete_object(Tab, Record, sticky_write)</c> where <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>s_write(Record) -> ok | transaction abort </name>
+ <fsummary>Write <c>Record</c>and sets stick lock.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:write(Tab, Record, sticky_write)</c>
+ where <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>schema() -> ok </name>
+ <fsummary>Print information about all table definitions on the tty. </fsummary>
+ <desc>
+ <p>Prints information about all table definitions on the tty.</p>
+ </desc>
+ </func>
+ <func>
+ <name>schema(Tab) -> ok </name>
+ <fsummary>Print information about one table definition on the tty.</fsummary>
+ <desc>
+ <p>Prints information about one table definition on the tty.</p>
+ </desc>
+ </func>
+ <func>
+ <name>select(Tab, MatchSpec [, Lock]) -> transaction abort | [Object] </name>
+ <fsummary>Match the objects in <c>Tab</c>against <c>MatchSpec</c>.</fsummary>
+ <desc>
+ <p>Matches the objects in the table <c>Tab</c> using a
+ match_spec as described in the ERTS Users Guide. Optionally a lock
+ <c>read</c> or <c>write</c> can be given as the third
+ argument, default is <c>read</c>. The return value depends
+ on the <c>MatchSpec</c>.</p>
+ <p><em>Note:</em> for best performance <c>select</c> should
+ be used before any modifying operations are done on that table
+ in the same transaction, i.e. don't use <c>write</c> or <c>delete</c>
+ before a <c>select</c>.</p>
+ <p>In its simplest forms the match_spec's look like this:</p>
+ <list type="bulleted">
+ <item>MatchSpec = [MatchFunction]</item>
+ <item>MatchFunction = {MatchHead, [Guard], [Result]}</item>
+ <item>MatchHead = tuple() | record()</item>
+ <item>Guard = {"Guardtest name", ...}</item>
+ <item>Result = "Term construct"</item>
+ </list>
+ <p>See the ERTS Users Guide and <c>ets</c> documentation for a
+ complete description of the select.</p>
+ <p>For example to find the names of all male persons with an age over 30 in table
+ Tab do:</p>
+ <code type="none">
+\011 MatchHead = #person{name='$1', sex=male, age='$2', _='_'},
+\011 Guard = {'>', '$2', 30},
+\011 Result = '$1',
+\011 mnesia:select(Tab,[{MatchHead, [Guard], [Result]}]),
+ </code>
+ </desc>
+ </func>
+ <func>
+ <name>select(Tab, MatchSpec, NObjects, Lock) -> transaction abort | {[Object],Cont} | '$end_of_table'</name>
+ <fsummary>Match the objects in <c>Tab</c>against <c>MatchSpec</c>.</fsummary>
+ <desc>
+ <p>Matches the objects in the table <c>Tab</c> using a
+ match_spec as described in ERTS users guide, and returns
+ a chunk of terms and a continuation, the wanted number
+ of returned terms is specified by the <c>NObjects</c> argument.
+ The lock argument can be <c>read</c> or <c>write</c>.
+ The continuation should be used as argument to <c>mnesia:select/1</c>,
+ if more or all answers are needed.</p>
+ <p><em>Note:</em> for best performance <c>select</c> should
+ be used before any modifying operations are done on that
+ table in the same transaction, i.e. don't use
+ <c>mnesia:write</c> or <c>mnesia:delete</c> before a
+ <c>mnesia:select</c>. For efficiency the <c>NObjects</c> is
+ a recommendation only and the result may contain anything
+ from an empty list to all available results. </p>
+ </desc>
+ </func>
+ <func>
+ <name>select(Cont) -> transaction abort | {[Object],Cont} | '$end_of_table'</name>
+ <fsummary>Continues selecting objects. </fsummary>
+ <desc>
+ <p>Selects more objects with the match specification initiated
+ by <c>mnesia:select/4</c>.
+ </p>
+ <p><em>Note:</em> Any modifying operations, i.e. <c>mnesia:write</c>
+ or <c>mnesia:delete</c>, that are done between the <c>mnesia:select/4</c>
+ and <c>mnesia:select/1</c> calls will not be visible in the result.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_debug_level(Level) -> OldLevel</name>
+ <fsummary>Change the internal debug level of Mnesia</fsummary>
+ <desc>
+ <p>Changes the internal debug level of Mnesia. See the
+ chapter about configuration parameters for details.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_master_nodes(MasterNodes) -> ok | {error, Reason} </name>
+ <fsummary>Set the master nodes for all tables</fsummary>
+ <desc>
+ <p>For each table Mnesia will determine its replica nodes
+ (<c>TabNodes</c>) and invoke <c>mnesia:set_master_nodes(Tab, TabMasterNodes)</c> where <c>TabMasterNodes</c> is the
+ intersection of <c>MasterNodes</c> and <c>TabNodes</c>. See
+ <c>mnesia:set_master_nodes/2</c> about the semantics.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_master_nodes(Tab, MasterNodes) -> ok | {error, Reason} </name>
+ <fsummary>Set the master nodes for a table</fsummary>
+ <desc>
+ <p>If the application detects that there has been a
+ communication failure (in a potentially partitioned network) which
+ may have caused an inconsistent database, it may use the
+ function <c>mnesia:set_master_nodes(Tab, MasterNodes)</c> to
+ define from which nodes each table will be loaded.
+ At startup Mnesia's normal table load algorithm will be
+ bypassed and the table will be loaded from one of the master
+ nodes defined for the table, regardless of when and if Mnesia
+ was terminated on other nodes. The <c>MasterNodes</c> may only
+ contain nodes where the table has a replica and if the
+ <c>MasterNodes</c> list is empty, the master node recovery
+ mechanism for the particular table will be reset and the
+ normal load mechanism will be used at next restart.
+ </p>
+ <p>The master node setting is always local and it may be
+ changed regardless of whether Mnesia is started or not.
+ </p>
+ <p>The database may also become inconsistent if the
+ <c>max_wait_for_decision</c> configuration parameter is used
+ or if <c>mnesia:force_load_table/1</c> is used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>snmp_close_table(Tab) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Remove the possibility for SNMP to manipulate the table.</fsummary>
+ <desc>
+ <p>Removes the possibility for SNMP to manipulate the
+ table.</p>
+ </desc>
+ </func>
+ <func>
+ <name>snmp_get_mnesia_key(Tab, RowIndex) -> {ok, Key} | undefined</name>
+ <fsummary>Get the corresponding Mnesia key from an SNMP index.</fsummary>
+ <type>
+ <v>Tab ::= atom()</v>
+ <v>RowIndex ::= [integer()]</v>
+ <v>Key ::= key() | {key(), key(), ...}</v>
+ <v>key() ::= integer() | string() | [integer()]</v>
+ </type>
+ <desc>
+ <p>Transforms an SNMP index to the corresponding Mnesia key.
+ If the SNMP table has multiple keys, the key is a tuple of
+ the key columns.</p>
+ </desc>
+ </func>
+ <func>
+ <name>snmp_get_next_index(Tab, RowIndex) -> {ok, NextIndex} | endOfTable</name>
+ <fsummary>Get the index of the next lexicographical row.</fsummary>
+ <type>
+ <v>Tab ::= atom()</v>
+ <v>RowIndex ::= [integer()]</v>
+ <v>NextIndex ::= [integer()]</v>
+ </type>
+ <desc>
+ <p>The <c>RowIndex</c> may specify a non-existing row.
+ Specifically, it might be the empty list. Returns the index
+ of the next lexicographical row. If <c>RowIndex</c> is the
+ empty list, this function will return the index of the first row
+ in the table.</p>
+ </desc>
+ </func>
+ <func>
+ <name>snmp_get_row(Tab, RowIndex) -> {ok, Row} | undefined</name>
+ <fsummary>Retrieve a row indexed by an SNMP index.</fsummary>
+ <type>
+ <v>Tab ::= atom()</v>
+ <v>RowIndex ::= [integer()]</v>
+ <v>Row ::= record(Tab)</v>
+ </type>
+ <desc>
+ <p>Makes it possible to read a row by its SNMP index. This
+ index is specified as an SNMP OBJECT IDENTIFIER, a list of
+ integers.</p>
+ </desc>
+ </func>
+ <func>
+ <name>snmp_open_table(Tab, SnmpStruct) -> {aborted, R} | {atomic, ok}</name>
+ <fsummary>Organize a Mnesia table as an SNMP table.</fsummary>
+ <type>
+ <v>Tab ::= atom()</v>
+ <v>SnmpStruct ::= [{key, type()}]</v>
+ <v>type() ::= type_spec() | {type_spec(), type_spec(), ...}</v>
+ <v>type_spec() ::= fix_string | string | integer</v>
+ </type>
+ <desc>
+ <p>It is possible to establish a direct one to one mapping
+ between Mnesia tables and SNMP tables. Many
+ telecommunication applications are controlled and monitored
+ by the SNMP protocol. This connection between Mnesia and
+ SNMP makes it simple and convenient to achieve this.
+ </p>
+ <p>The <c>SnmpStruct</c> argument is a list of SNMP
+ information. Currently, the only information needed is
+ information about the key types in the table. It is not
+ possible to handle multiple keys in Mnesia, but many SNMP
+ tables have multiple keys. Therefore, the following
+ convention is used: if a table has multiple keys, these must
+ always be stored as a tuple of the keys. Information about
+ the key types is specified as a tuple of atoms describing
+ the types. The only significant type is
+ <c>fix_string</c>. This means that a string has fixed
+ size. For example:
+ </p>
+ <code type="none">
+mnesia:snmp_open_table(person, [{key, string}])
+ </code>
+ <p>causes the <c>person</c> table to be ordered as an SNMP
+ table.
+ </p>
+ <p>Consider the following schema for a table of company
+ employees. Each employee is identified by department number
+ and name. The other table column stores the telephone number:
+ </p>
+ <code type="none">
+mnesia:create_table(employee,
+ [{snmp, [{key, {integer, string}}]},
+ {attributes, record_info(fields, employees)}]),
+ </code>
+ <p>The corresponding SNMP table would have three columns;
+ <c>department</c>, <c>name</c> and <c>telno</c>.
+ </p>
+ <p>It is possible to have table columns that are not visible
+ through the SNMP protocol. These columns must be the last
+ columns of the table. In the previous example, the SNMP
+ table could have columns <c>department</c> and <c>name</c>
+ only. The application could then use the <c>telno</c> column
+ internally, but it would not be visible to the SNMP
+ managers.
+ </p>
+ <p>In a table monitored by SNMP, all elements must be
+ integers, strings, or lists of integers.
+ </p>
+ <p>When a table is SNMP ordered, modifications are more
+ expensive than usual, O(logN). And more memory is used.
+ </p>
+ <p><em>Note:</em>Only the lexicographical SNMP ordering is
+ implemented in Mnesia, not the actual SNMP monitoring.</p>
+ </desc>
+ </func>
+ <func>
+ <name>start() -> ok | {error, Reason} </name>
+ <fsummary>Start a local Mnesia system.</fsummary>
+ <desc>
+ <p>The start-up procedure for a set of Mnesia nodes is a
+ fairly complicated operation. A Mnesia system consists of a set
+ of nodes, with Mnesia started locally on all
+ participating nodes. Normally, each node has a directory where
+ all the Mnesia files are written. This directory will be
+ referred to as the Mnesia directory. Mnesia may also be
+ started on disc-less nodes. See <c>mnesia:create_schema/1</c>
+ and the Mnesia User's Guide for more information about disc-less
+ nodes.
+ </p>
+ <p>The set of nodes which makes up a Mnesia system is kept in
+ a schema and it is possible to add and remove Mnesia nodes
+ from the schema. The initial schema is normally created on
+ disc with the function <c>mnesia:create_schema/1</c>. On
+ disc-less nodes, a tiny default schema is generated each time
+ Mnesia is started. During the start-up procedure, Mnesia
+ will exchange schema information between the nodes in order
+ to verify that the table definitions are compatible.
+ </p>
+ <p>Each schema has a unique cookie which may be regarded as a
+ unique schema identifier. The cookie must be the same on all
+ nodes where Mnesia is supposed to run. See the Mnesia
+ User's Guide for more information about these details.
+ </p>
+ <p>The schema file, as well as all other files which Mnesia
+ needs, are kept in the Mnesia directory. The command line
+ option <c>-mnesia dir Dir</c> can be used to specify the
+ location of this directory to the Mnesia system. If no such
+ command line option is found, the name of the directory
+ defaults to <c>Mnesia.Node</c>.
+ </p>
+ <p><c>application:start(mnesia)</c> may also be used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop() -> stopped </name>
+ <fsummary>Stop Mnesia locally.</fsummary>
+ <desc>
+ <p>Stops Mnesia locally on the current node.
+ </p>
+ <p><c>application:stop(mnesia)</c> may also be used.</p>
+ </desc>
+ </func>
+ <func>
+ <name>subscribe(EventCategory)</name>
+ <fsummary>Subscribe to events of type <c>EventCategory</c>.</fsummary>
+ <desc>
+ <p>Ensures that a copy of all events of type
+ <c>EventCategory</c> are sent to the caller. The event
+ types available are described in the Mnesia User's Guide.</p>
+ </desc>
+ </func>
+ <func>
+ <name>sync_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason) </name>
+ <fsummary>Call the Fun in a context which is not protected by a transaction.</fsummary>
+ <desc>
+ <p>Call the <c>Fun</c> in a context which is not protected
+ by a transaction. The Mnesia function calls performed in the
+ <c>Fun</c> are mapped to the corresponding dirty functions.
+ It is performed in almost the same context as
+ <c>mnesia:async_dirty/1,2</c>. The difference is that the
+ operations are performed synchronously. The caller waits for
+ the updates to be performed on all active replicas before
+ the <c>Fun</c> returns. See <c>mnesia:activity/4</c> and the
+ Mnesia User's Guide for more details.</p>
+ </desc>
+ </func>
+ <func>
+ <name>sync_transaction(Fun, [[, Args], Retries]) -> {aborted, Reason} | {atomic, ResultOfFun} </name>
+ <fsummary>Synchronously execute a transaction.</fsummary>
+ <desc>
+ <p>This function waits until data have been committed and
+ logged to disk (if disk is used) on every involved node before
+ it returns, otherwise it behaves as
+ <c>mnesia:transaction/[1,2,3]</c>.</p>
+ <p>This functionality can be used to avoid that one process may overload
+ a database on another node.</p>
+ </desc>
+ </func>
+ <func>
+ <name>system_info(InfoKey) -> Info | exit({aborted, Reason})</name>
+ <fsummary>Return information about the Mnesia system</fsummary>
+ <desc>
+ <p>Returns information about the Mnesia system, such as
+ transaction statistics, db_nodes, and configuration parameters.
+ Valid keys are:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>all</c>. This argument returns a list of all
+ local system information. Each element is a
+ <c>{InfoKey, InfoVal}</c> tuples.<em>Note:</em> New <c>InfoKey</c>'s may
+ be added and old undocumented <c>InfoKey</c>'s may be removed without
+ notice.</p>
+ </item>
+ <item>
+ <p><c>access_module</c>. This argument returns the name of
+ the module which is configured to be the activity access
+ callback module.
+ </p>
+ </item>
+ <item>
+ <p><c>auto_repair</c>. This argument returns
+ <c>true</c> or <c>false</c> to indicate if Mnesia is
+ configured to invoke the auto repair facility on corrupted
+ disc files.
+ </p>
+ </item>
+ <item>
+ <p><c>backup_module</c>. This argument returns the name of
+ the module which is configured to be the backup
+ callback module.
+ </p>
+ </item>
+ <item>
+ <p><c>checkpoints</c>. This argument
+ returns a list of the names of the
+ checkpoints currently active on this node.
+ </p>
+ </item>
+ <item>
+ <p><c>event_module</c>. This argument returns the name of
+ the module which is the event handler callback module.
+ </p>
+ </item>
+ <item>
+ <p><c>db_nodes</c>. This argument returns
+ the nodes which make up the persistent database. Disc
+ less nodes will only be included in the list of nodes if
+ they explicitly has been added to the schema, e.g. with
+ <c>mnesia:add_table_copy/3</c>. The function can be
+ invoked even if Mnesia is not yet running.
+ </p>
+ </item>
+ <item>
+ <p><c>debug</c>. This argument returns the current
+ debug level of Mnesia.
+ </p>
+ </item>
+ <item>
+ <p><c>directory</c>. This argument returns the name of
+ the Mnesia directory. It can be invoked even if Mnesia is
+ not yet running.
+ </p>
+ </item>
+ <item>
+ <p><c>dump_log_load_regulation</c>. This argument
+ returns a boolean which tells whether Mnesia is
+ configured to load regulate the dumper process or not.
+ This feature is temporary and will disappear in future
+ releases.
+ </p>
+ </item>
+ <item>
+ <p><c>dump_log_time_threshold</c>. This argument
+ returns the time threshold for transaction log dumps in
+ milliseconds.
+ </p>
+ </item>
+ <item>
+ <p><c>dump_log_update_in_place</c>. This argument
+ returns a boolean which tells whether Mnesia is
+ configured to perform the updates in the dets files
+ directly or if the updates should be performed in a copy
+ of the dets files.
+ </p>
+ </item>
+ <item>
+ <p><c>dump_log_write_threshold</c>. This argument
+ returns the write threshold for transaction log dumps as
+ the number of writes to the transaction log.
+ </p>
+ </item>
+ <item>
+ <p><c>extra_db_nodes</c>. This argument returns a list
+ of extra db_nodes to be contacted at start-up.
+ </p>
+ </item>
+ <item>
+ <p><c>fallback_activated</c>. This argument returns
+ true if a fallback is activated, otherwise false.
+ </p>
+ </item>
+ <item>
+ <p><c>held_locks</c>. This argument returns a list of
+ all locks held by the local Mnesia lock manager.
+ </p>
+ </item>
+ <item>
+ <p><c>is_running</c>. This argument returns <c>yes</c>
+ or <c>no</c> to indicate if Mnesia is running. It may
+ also return <c>starting</c> or <c>stopping</c>. Can be
+ invoked even if Mnesia is not yet running.
+ </p>
+ </item>
+ <item>
+ <p><c>local_tables</c>. This argument returns a list
+ of all tables which are configured to reside locally.
+ </p>
+ </item>
+ <item>
+ <p><c>lock_queue</c>. This argument returns a list of
+ all transactions that are queued for execution by the
+ local lock manager.
+ </p>
+ </item>
+ <item>
+ <p><c>log_version</c>. This argument returns the
+ version number of the Mnesia transaction log format.
+ </p>
+ </item>
+ <item>
+ <p><c>master_node_tables</c>. This argument returns a
+ list of all tables with at least one master node.
+ </p>
+ </item>
+ <item>
+ <p><c>protocol_version</c>. This argument
+ returns the version number
+ of the Mnesia inter-process communication protocol.
+ </p>
+ </item>
+ <item>
+ <p><c>running_db_nodes</c>. This argument returns a
+ list of nodes where Mnesia currently is running. This
+ function can be invoked even if Mnesia is not yet
+ running, but it will then have slightly different
+ semantics. If Mnesia is down on the local node, the
+ function will return those other <c>db_nodes</c> and
+ <c>extra_db_nodes</c> that for the moment are up and
+ running. If Mnesia is started, the function will return
+ those nodes that Mnesia on the local node is fully
+ connected to. Only those nodes that Mnesia has exchanged
+ schema information with are included as
+ <c>running_db_nodes</c>. After the merge of schemas, the
+ local Mnesia system is fully operable and applications
+ may perform access of remote replicas. Before the schema
+ merge Mnesia will only operate locally. Sometimes there
+ may be more nodes included in the
+ <c>running_db_nodes</c> list than all <c>db_nodes</c>
+ and <c>extra_db_nodes</c> together.
+ </p>
+ </item>
+ <item>
+ <p><c>schema_location</c>. This argument returns the
+ initial schema location.
+ </p>
+ </item>
+ <item>
+ <p><c>subscribers</c>. This argument returns a list of
+ local processes currently subscribing to system events.
+ </p>
+ </item>
+ <item>
+ <p><c>tables</c>. This argument returns a list of all
+ locally known tables.
+ </p>
+ </item>
+ <item>
+ <p><c>transactions</c>. This argument returns a list
+ of all currently active local transactions.
+ </p>
+ </item>
+ <item>
+ <p><c>transaction_failures</c>. This argument returns
+ a number which indicates how many transactions have
+ failed since Mnesia was started.
+ </p>
+ </item>
+ <item>
+ <p><c>transaction_commits</c>. This argument returns a
+ number which indicates how many transactions have
+ terminated successfully since Mnesia was started.
+ </p>
+ </item>
+ <item>
+ <p><c>transaction_restarts</c>. This argument returns
+ a number which indicates how many transactions have been
+ restarted since Mnesia was started.
+ </p>
+ </item>
+ <item>
+ <p><c>transaction_log_writes</c>. This argument
+ returns a number which indicates the number of write
+ operation that have been performed to the transaction
+ log since start-up.
+ </p>
+ </item>
+ <item>
+ <p><c>use_dir</c>. This argument returns a boolean
+ which indicates whether the Mnesia directory is used or
+ not. Can be invoked even if Mnesia is not yet running.
+ </p>
+ </item>
+ <item>
+ <p><c>version</c>. This argument returns the current
+ version number of Mnesia.
+ </p>
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>table(Tab [,[Option]]) -> QueryHandle </name>
+ <fsummary>Return a QLC query handle.</fsummary>
+ <desc>
+ <p> <marker id="qlc_table"></marker>
+Returns a QLC (Query List Comprehension) query handle, see
+ <seealso marker="stdlib:qlc">qlc(3)</seealso>.The module <c>qlc</c> implements a query language, it
+ can use mnesia tables as sources of data. Calling
+ <c>mnesia:table/1,2</c> is the means to make the <c>mnesia</c>
+ table <c>Tab</c> usable to QLC.</p>
+ <p>The list of Options may contain mnesia options or QLC
+ options, the following options are recognized by Mnesia:
+ <c>{traverse, SelectMethod},{lock, Lock},{n_objects,Number}</c>, any other option is forwarded
+ to QLC. The <c>lock</c> option may be <c>read</c> or
+ <c>write</c>, default is <c>read</c>. The option
+ <c>n_objects</c> specifies (roughly) the number of objects
+ returned from mnesia to QLC. Queries to remote tables may
+ need a larger chunks to reduce network overhead, default
+ <c>100</c> objects at a time are returned. The option
+ <c>traverse</c> determines the method to traverse the whole
+ table (if needed), the default method is <c>select</c>:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>select</c>. The table is traversed by calling
+ <c>mnesia:select/4</c> and <c>mnesia:select/1</c>. The
+ match specification (the second argument of <c>select/3</c>)
+ is assembled by QLC: simple filters are
+ translated into equivalent match specifications while
+ more complicated filters have to be applied to all
+ objects returned by <c>select/3</c> given a match
+ specification that matches all objects.</p>
+ </item>
+ <item>
+ <p><c>{select, MatchSpec}</c>. As for <c>select</c>
+ the table is traversed by calling <c>mnesia:select/3</c> and
+ <c>mnesia:select/1</c>. The difference is that the match
+ specification is explicitly given. This is how to state
+ match specifications that cannot easily be expressed
+ within the syntax provided by QLC.</p>
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>table_info(Tab, InfoKey) -> Info | exit({aborted, Reason})</name>
+ <fsummary>Return local information about table.</fsummary>
+ <desc>
+ <p>The <c>table_info/2</c> function takes two arguments.
+ The first is the name of a Mnesia table, the second is one of
+ the following keys:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>all</c>. This argument returns a list of all
+ local table information. Each element is a <c>{InfoKey, ItemVal}</c> tuples. <em>Note:</em> New <c>InfoItem</c>'s may be
+ added and old undocumented <c>InfoItem</c>'s may be removed without
+ notice.</p>
+ </item>
+ <item>
+ <p><c>access_mode</c>. This argument returns the
+ access mode of the table. The access mode may either be
+ read_only or read_write.
+ </p>
+ </item>
+ <item>
+ <p><c>arity</c>. This argument returns the arity of
+ records in the table as specified in the schema.
+ </p>
+ </item>
+ <item>
+ <p><c>attributes</c>. This argument returns the table
+ attribute names which are specified in the schema.
+ </p>
+ </item>
+ <item>
+ <p><c>checkpoints</c>. This argument returns the names
+ of the currently active checkpoints which involves this
+ table on this node.
+ </p>
+ </item>
+ <item>
+ <p><c>cookie</c>. This argument returns a table cookie
+ which is a unique system generated identifier for the
+ table. The cookie is used internally to ensure that two
+ different table definitions using the same table name
+ cannot accidentally be intermixed. The cookie is
+ generated when the table is initially created.
+ </p>
+ </item>
+ <item>
+ <p><c>disc_copies</c>. This argument returns the nodes
+ where a disc_copy of the table resides according to the
+ schema.
+ </p>
+ </item>
+ <item>
+ <p><c>disc_only_copies </c>. This argument returns the
+ nodes where a disc_only_copy of the table resides
+ according to the schema.
+ </p>
+ </item>
+ <item>
+ <p><c>index</c>. This argument returns the list of
+ index position integers for the table.
+ </p>
+ </item>
+ <item>
+ <p><c>load_node</c>. This argument returns the name of
+ the node that Mnesia loaded the table from. The
+ structure of the returned value is unspecified but may
+ be useful for debugging purposes.
+ </p>
+ </item>
+ <item>
+ <p><c>load_order</c>. This argument returns the load
+ order priority of the table. It is an integer and
+ defaults to <c>0</c> (zero).
+ </p>
+ </item>
+ <item>
+ <p><c>load_reason</c>. This argument returns the
+ reason of why Mnesia decided to load the table. The
+ structure of the returned value is unspecified but may
+ be useful for debugging purposes.
+ </p>
+ </item>
+ <item>
+ <p><c>local_content</c>. This argument returns
+ <c>true</c> or <c>false</c> to indicate whether the
+ table is configured to have locally unique content on
+ each node.
+ </p>
+ </item>
+ <item>
+ <p><c>master_nodes</c>. This argument returns the
+ master nodes of a table.
+ </p>
+ </item>
+ <item>
+ <p><c>memory</c>. This argument returns the number of
+ words allocated to the table on this node.
+ </p>
+ </item>
+ <item>
+ <p><c>ram_copies</c>. This argument returns the nodes
+ where a ram_copy of the table resides according to the
+ schema.
+ </p>
+ </item>
+ <item>
+ <p><c>record_name</c>. This argument returns the
+ record name, common for all records in the table
+ </p>
+ </item>
+ <item>
+ <p><c>size</c>. This argument returns the number of
+ records inserted in the table.
+ </p>
+ </item>
+ <item>
+ <p><c>snmp</c>. This argument returns the SNMP struct.
+ <c>[]</c>meaning that the table currently has no SNMP
+ properties.
+ </p>
+ </item>
+ <item>
+ <p><c>storage_type</c>.This argument returns the local
+ storage type of the table. It can be <c>disc_copies</c>,
+ <c>ram_copies</c>, <c>disc_only_copies</c>, or the atom
+ <c>unknown</c>. <c>unknown</c> is returned for all
+ tables which only reside remotely.
+ </p>
+ </item>
+ <item>
+ <p><c>subscribers</c>. This argument returns a list
+ of local processes currently subscribing to local table
+ events which involve this table on this node.
+ </p>
+ </item>
+ <item>
+ <p><c>type</c>. This argument returns the table type,
+ which is either <c>bag</c>, <c>set</c> or <c>ordered_set</c>..
+ </p>
+ </item>
+ <item>
+ <p><c>user_properties</c>. This argument returns the
+ user associated table properties of the table. It is a
+ list of the stored property records.
+ </p>
+ </item>
+ <item>
+ <p><c>version</c>. This argument returns the current
+ version of the table definition. The table version is
+ incremented when the table definition is changed. The
+ table definition may be incremented directly when the
+ table definition has been changed in a schema
+ transaction, or when a committed table definition is
+ merged with table definitions from other nodes during
+ start-up.
+ </p>
+ </item>
+ <item>
+ <p><c>where_to_read</c>.This argument returns the node
+ where the table can be read. If the value <c>nowhere</c>
+ is returned, the table is not loaded, or it resides at a
+ remote node which is not running.
+ </p>
+ </item>
+ <item>
+ <p><c>where_to_write</c>. This argument returns a list
+ of the nodes that currently hold an active replica of
+ the table.
+ </p>
+ </item>
+ <item>
+ <p><c>wild_pattern</c>. This argument returns a
+ structure which can be given to the various match
+ functions for a certain table. A record tuple is where all
+ record fields have the value <c>'_'</c>.
+ </p>
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>transaction(Fun [[, Args], Retries]) -> {aborted, Reason} | {atomic, ResultOfFun}</name>
+ <fsummary>Execute a transaction.</fsummary>
+ <desc>
+ <p>This function executes the functional object <c>Fun</c>
+ with arguments <c>Args</c> as a transaction.
+ </p>
+ <p>The code which executes inside the transaction
+ can consist of a series of table manipulation functions.
+ If something goes wrong inside the transaction as a result of a
+ user error or a certain table not being available, the
+ entire transaction is aborted and the function
+ <c>transaction/1</c> returns the tuple
+ <c>{aborted, Reason}</c>.
+ </p>
+ <p>If all is well, <c>{atomic, ResultOfFun}</c> is returned where
+ <c>ResultOfFun</c> is the value of the last expression in
+ <c>Fun</c>.
+ </p>
+ <p>A function which adds a family to the database can be
+ written as follows if we have a structure <c>{family, Father, Mother, ChildrenList}</c>:
+ </p>
+ <code type="none">
+add_family({family, F, M, Children}) ->
+ ChildOids = lists:map(fun oid/1, Children),
+ Trans = fun() ->
+ mnesia:write(F#person{children = ChildOids},
+ mnesia:write(M#person{children = ChildOids},
+ Write = fun(Child) -> mnesia:write(Child) end,
+ lists:foreach(Write, Children)
+ end,
+ mnesia:transaction(Trans).
+
+oid(Rec) -> {element(1, Rec), element(2, Rec)}.
+ </code>
+ <p>This code adds a set of people to the database. Running this code
+ within one transaction will ensure that either the whole
+ family is added to the database, or the whole transaction
+ aborts. For example, if the last child is badly formatted,
+ or the executing process terminates due to an
+ <c>'EXIT'</c> signal while executing the family code, the
+ transaction aborts. Accordingly, the situation where half a
+ family is added can never occur.
+ </p>
+ <p>It is also useful to update the database within a transaction
+ if several processes concurrently update the same records.
+ For example, the function <c>raise(Name, Amount)</c>, which
+ adds <c>Amount</c> to the salary field of a person, should
+ be implemented as follows:
+ </p>
+ <code type="none">
+raise(Name, Amount) ->
+ mnesia:transaction(fun() ->
+ case mnesia:wread({person, Name}) of
+ [P] ->
+ Salary = Amount + P#person.salary,
+ P2 = P#person{salary = Salary},
+ mnesia:write(P2);
+ _ ->
+ mnesia:abort("No such person")
+ end
+ end).
+ </code>
+ <p>When this function executes within a transaction,
+ several processes running on different nodes can concurrently
+ execute the <c>raise/2</c> function without interfering
+ with each other.
+ </p>
+ <p>Since Mnesia detects deadlocks, a transaction can be
+ restarted any number of times. This function will attempt a restart as specified in
+ <c>Retries</c>. <c>Retries</c> must
+ be an integer greater than 0 or the atom <c>infinity</c>. Default is
+ <c>infinity</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>transform_table(Tab, Fun, NewAttributeList, NewRecordName) -> {aborted, R} | {atomic, ok} </name>
+ <fsummary>Change format on all records in table. <c>Tab</c></fsummary>
+ <desc>
+ <p>This function applies the argument <c>Fun</c> to all
+ records in the table. <c>Fun</c> is a function which takes a
+ record of the old type and returns a transformed record of the
+ new type. The <c>Fun</c> argument can also be the atom
+ <c>ignore</c>, it indicates that only the meta data about the table will
+ be updated. Usage of <c>ignore</c> is not recommended but included
+ as a possibility for the user do to his own transform.
+ <c>NewAttributeList</c> and <c>NewRecordName</c>
+ specifies the attributes and the new record type of converted
+ table. Table name will always remain unchanged, if the
+ record_name is changed only the mnesia functions which
+ uses table identifiers will work, e.g. <c>mnesia:write/3</c>
+ will work but <c>mnesia:write/1</c> will not.</p>
+ </desc>
+ </func>
+ <func>
+ <name>transform_table(Tab, Fun, NewAttributeList) -> {aborted, R} | {atomic, ok} </name>
+ <fsummary>Change format on all records in table. <c>Tab</c></fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:transform_table(Tab, Fun, NewAttributeList, RecName)</c>
+ where <c>RecName</c> is <c>mnesia:table_info(Tab, record_name)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>traverse_backup(Source, [SourceMod,] Target, [TargetMod,] Fun, Acc) -> {ok, LastAcc} | {error, Reason}</name>
+ <fsummary>Traversal of a backup.</fsummary>
+ <desc>
+ <p>With this function it is possible to iterate over a backup,
+ either for the purpose of transforming it into a new backup,
+ or just reading it. The arguments are explained briefly
+ below. See the Mnesia User's Guide for additional
+ details.
+ </p>
+ <list type="bulleted">
+ <item><c>SourceMod</c> and <c>TargetMod</c> are the names of
+ the modules which actually access the backup
+ media.
+ </item>
+ <item><c>Source</c> and <c>Target</c> are opaque data used
+ exclusively by the modules <c>SourceMod</c> and
+ <c>TargetMod</c> for the purpose of initializing the
+ backup media.
+ </item>
+ <item><c>Acc</c> is an initial accumulator value.
+ </item>
+ <item><c>Fun(BackupItems, Acc)</c> is applied to each item in
+ the backup. The Fun must return a tuple
+ <c>{BackupItems,NewAcc}</c>, where <c>BackupItems</c> is
+ a list of valid backup items, and <c>NewAcc</c> is a new
+ accumulator value. The returned backup items are written
+ in the target backup.
+ </item>
+ <item><c>LastAcc</c> is the last accumulator value. This is
+ the last <c>NewAcc</c> value that was returned by <c>Fun</c>.
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>uninstall_fallback() -> ok | {error,Reason}</name>
+ <fsummary>Uninstall a fallback.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:uninstall_fallback([{scope, global}])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>uninstall_fallback(Args) -> ok | {error,Reason}</name>
+ <fsummary>Uninstall a fallback.</fsummary>
+ <desc>
+ <p>This function is used to de-install a fallback before it
+ has been used to restore the database. This is normally a
+ distributed operation that is either performed on all
+ nodes with disc resident schema or none. Uninstallation of
+ fallbacks requires Erlang to be up and running on all
+ involved nodes, but it does not matter if Mnesia is running
+ or not. Which nodes that are considered as disc-resident
+ nodes is determined from the schema info in the local
+ fallback.
+ </p>
+ <p><c>Args</c> is a list of the following tuples:
+ </p>
+ <list type="bulleted">
+ <item>
+ <p><c>{module, BackupMod}</c>.
+ See <c>mnesia:install_fallback/2</c> about the
+ semantics.</p>
+ </item>
+ <item>
+ <p><c>{scope, Scope}</c>
+ See <c>mnesia:install_fallback/2</c> about the
+ semantics.</p>
+ </item>
+ <item>
+ <p><c>{mnesia_dir, AlternateDir}</c>
+ See <c>mnesia:install_fallback/2</c> about the
+ semantics.</p>
+ </item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>unsubscribe(EventCategory)</name>
+ <fsummary>Subscribe to events of type <c>EventCategory</c>.</fsummary>
+ <desc>
+ <p>Stops sending events of type
+ <c>EventCategory</c> to the caller.</p>
+ </desc>
+ </func>
+ <func>
+ <name>wait_for_tables(TabList,Timeout) -> ok | {timeout, BadTabList} | {error, Reason} </name>
+ <fsummary>Wait for tables to be accessible.</fsummary>
+ <desc>
+ <p>Some applications need to wait for certain tables to
+ be accessible in order to do useful work.
+ <c>mnesia:wait_for_tables/2</c> hangs until all tables in the
+ <c>TabList</c> are accessible, or until <c>timeout</c> is
+ reached.</p>
+ </desc>
+ </func>
+ <func>
+ <name>wread({Tab, Key}) -> transaction abort | RecordList </name>
+ <fsummary>Read records with given key.</fsummary>
+ <desc>
+ <p>Invoke <c>mnesia:read(Tab, Key, write)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write(Record) -> transaction abort | ok </name>
+ <fsummary>Writes a record into the database.</fsummary>
+ <desc>
+ <p>Invoke <c>mnesia:write(Tab, Record, write)</c> where
+ <c>Tab</c> is <c>element(1, Record)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write(Tab, Record, LockKind) -> transaction abort | ok </name>
+ <fsummary>Write an record into the database.</fsummary>
+ <desc>
+ <p>Writes the record <c>Record</c> to the table <c>Tab</c>.
+ </p>
+ <p>The function returns <c>ok</c>, or aborts if an error
+ occurs. For example, the transaction aborts if no
+ <c>person</c> table exists.
+ </p>
+ <p>The semantics of this function is context sensitive. See
+ <c>mnesia:activity/4</c> for more information. In transaction
+ context it acquires a lock of type <c>LockKind</c>. The
+ following lock types are supported: <c>write</c> and
+ <c>sticky_write</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_lock_table(Tab) -> ok | transaction abort</name>
+ <fsummary>Set write lock on an entire table.</fsummary>
+ <desc>
+ <p>Invokes <c>mnesia:lock({table, Tab}, write)</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>Configuration Parameters</title>
+ <p>Mnesia reads the following application configuration
+ parameters:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>-mnesia access_module Module</c>. The
+ name of the Mnesia activity access callback module. The default is
+ <c>mnesia</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia auto_repair true | false</c>. This flag controls
+ whether Mnesia will try to automatically repair
+ files that have not been properly closed. The default is
+ <c>true</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia backup_module Module</c>. The
+ name of the Mnesia backup callback module. The default is
+ <c>mnesia_backup</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia debug Level</c>
+ Controls the debug level of Mnesia.
+ Possible values are:</p>
+ <taglist>
+ <tag><c>none</c></tag>
+ <item>
+ <p>No trace outputs at all. This is the default setting.
+ </p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Activates tracing of important debug events. These
+ debug events generate <c>{mnesia_info, Format, Args}</c>
+ system events. Processes may subscribe to these events with
+ <c>mnesia:subscribe/1</c>. The events are always sent to Mnesia's
+ event handler.
+ </p>
+ </item>
+ <tag><c>debug</c></tag>
+ <item>
+ <p>Activates all events at the verbose level plus full
+ trace of all debug events. These debug events generate
+ <c>{mnesia_info, Format, Args}</c> system events. Processes may
+ subscribe to these events with <c>mnesia:subscribe/1</c>. The
+ events are always sent to the Mnesia event handler. On this
+ debug level, the Mnesia event handler starts subscribing to
+ updates in the schema table.
+ </p>
+ </item>
+ <tag><c>trace</c></tag>
+ <item>
+ <p>Activates all events at the level debug. On this
+ debug level, the Mnesia event handler starts subscribing to
+ updates on all Mnesia tables. This level is only intended
+ for debugging small toy systems since many large
+ events may be generated.
+ </p>
+ </item>
+ <tag><c>false</c></tag>
+ <item>
+ <p>An alias for none.
+ </p>
+ </item>
+ <tag><c>true</c></tag>
+ <item>
+ <p>An alias for debug.
+ </p>
+ </item>
+ </taglist>
+ </item>
+ <item>
+ <p><c>-mnesia core_dir Directory</c>. The name of the
+ directory where Mnesia core files is stored or
+ false. Setting it implies that also ram only nodes, will
+ generate a core file if a crash occurs. </p>
+ </item>
+ <item>
+ <p><c>-mnesia dc_dump_limit Number</c>.
+ Controls how often <c>disc_copies</c> tables are dumped from memory.
+ Tables are dumped when
+ <c>filesize(Log) > (filesize(Tab)/Dc_dump_limit)</c>.
+ Lower values reduces cpu overhead but increases disk space and
+ startup times. The default is 4.</p>
+ </item>
+ <item>
+ <p><c>-mnesia dir Directory</c>. The name of the directory
+ where all Mnesia data is stored. The name of the directory must
+ be unique for the current node. Two nodes may, under no
+ circumstances, share the same Mnesia directory. The results are
+ totally unpredictable.</p>
+ </item>
+ <item>
+ <p><c>-mnesia dump_log_load_regulation true | false</c>.
+ Controls if the log dumps should be performed as fast as
+ possible or if the dumper should do its own load
+ regulation. This feature is temporary and will disappear in a
+ future release. The default is <c>false</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia dump_log_update_in_place true | false</c>.
+ Controls if log dumps are performed on a copy of
+ the original data file, or if the log dump is
+ performed on the original data file. The default is <c>true</c></p>
+ </item>
+ <item>
+ <p><c>-mnesia dump_log_write_threshold Max</c>, where
+ <c>Max</c> is an integer which specifies the maximum number of writes
+ allowed to the transaction log before a new dump of the log
+ is performed. It defaults to 100 log writes.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia dump_log_time_threshold Max</c>,
+ where <c>Max</c> is an integer which
+ specifies the dump log interval in milliseconds. It defaults
+ to 3 minutes. If a dump has not been performed within
+ <c>dump_log_time_threshold</c> milliseconds, then a new dump is
+ performed regardless of how many writes have been
+ performed.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia event_module Module</c>. The
+ name of the Mnesia event handler callback module. The default is
+ <c>mnesia_event</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia extra_db_nodes Nodes</c> specifies a list of
+ nodes, in addition to the ones found in the schema, with which
+ Mnesia should also establish contact. The default value
+ is the empty list <c>[]</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia fallback_error_function {UserModule, UserFunc}</c>
+ specifies a user supplied callback function
+ which will be called if a fallback is installed and mnesia
+ goes down on another node. Mnesia will call the function
+ with one argument the name of the dying node, e.g.
+ <c>UserModule:UserFunc(DyingNode)</c>.
+ Mnesia should be restarted or else
+ the database could be inconsistent.
+ The default behaviour is to terminate mnesia.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia max_wait_for_decision Timeout</c>. Specifies
+ how long Mnesia will wait for other nodes to share their
+ knowledge regarding the outcome of an unclear transaction. By
+ default the <c>Timeout</c> is set to the atom
+ <c>infinity</c>, which implies that if Mnesia upon startup
+ encounters a "heavyweight transaction" whose outcome is
+ unclear, the local Mnesia will wait until Mnesia is started
+ on some (in worst cases all) of the other nodes that were
+ involved in the interrupted transaction. This is a very rare
+ situation, but when/if it happens, Mnesia does not guess if
+ the transaction on the other nodes was committed or aborted.
+ Mnesia will wait until it knows the outcome and then act
+ accordingly.
+ </p>
+ <p>If <c>Timeout</c> is set to an integer value in
+ milliseconds, Mnesia will force "heavyweight transactions"
+ to be finished, even if the outcome of the transaction for
+ the moment is unclear. After <c>Timeout</c> milliseconds,
+ Mnesia will commit/abort the transaction and continue with
+ the startup. This may lead to a situation where the
+ transaction is committed on some nodes and aborted on other
+ nodes. If the transaction was a schema transaction, the
+ inconsistency may be fatal.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia no_table_loaders NUMBER</c> specifies the number of
+ parallel table loaders during start. More loaders can be good if the
+ network latency is high or if many tables contains few records.
+ The default value is <c>2</c>.
+ </p>
+ </item>
+ <item>
+ <p><c>-mnesia schema_location Loc</c> controls where
+ Mnesia will look for its schema. The parameter
+ <c>Loc</c> may be one of the following atoms: </p>
+ <taglist>
+ <tag><c>disc</c></tag>
+ <item>
+ <p>Mandatory disc. The schema is assumed to be located
+ in the Mnesia directory. If the schema cannot be found,
+ Mnesia refuses to start. This is the old behavior.
+ </p>
+ </item>
+ <tag><c>ram</c></tag>
+ <item>
+ <p>Mandatory RAM. The schema resides in RAM
+ only. At start-up, a tiny new schema is generated. This
+ default schema just contains the definition of the schema
+ table and only resides on the local node. Since no other
+ nodes are found in the default schema, the configuration
+ parameter <c>extra_db_nodes</c> must be used in
+ order to let the
+ node share its table definitions with other nodes. (The
+ <c>extra_db_nodes</c> parameter may also be used on disc based nodes.)
+ </p>
+ </item>
+ <tag><c>opt_disc</c></tag>
+ <item>
+ <p>Optional disc. The schema may reside either on disc
+ or in RAM. If the schema is found on disc, Mnesia starts as a
+ disc based node and the storage type of the schema table is
+ <c>disc_copies</c>. If no schema is found on disc, Mnesia starts
+ as a disc-less node and the storage type of the schema table is
+ <c>ram_copies</c>. The default value for the application parameter
+ is <c>opt_disc</c>.
+ </p>
+ </item>
+ </taglist>
+ </item>
+ </list>
+ <p>First the SASL application parameters are checked, then
+ the command line flags are checked, and finally, the default
+ value is chosen.
+ </p>
+ </section>
+
+ <section>
+ <title>See Also</title>
+ <p>mnesia_registry(3), mnesia_session(3), qlc(3),
+ dets(3), ets(3), disk_log(3), application(3)
+ </p>
+ </section>
+
+</erlref>
+