diff --git a/doc/man/tarantool.pod b/doc/man/tarantool.pod
index e267fb3a9def5bead725449f90b27d5bcc89e51b..030c78df83a20e3d0d6e11683e11e7208c66b67a 100644
--- a/doc/man/tarantool.pod
+++ b/doc/man/tarantool.pod
@@ -76,3 +76,124 @@ Display version information and exit.
=back
+=head1 DESCRIPTION
+
+Statements in alphabetical order
+
+Although an initial statement may be entered on the tarantool command line, generally they are entered following the prompt in interactive mode while tarantool is running. (A prompt will be the name of the host and a greater-than sign, for example localhost>). The end-of-statement marker is a newline (line feed).
+
+=over
+
+=item CALL
+
+Syntax: CALL procedure-identifier (). Effect: The client tells the server to execute the procedure identified by procedure-identifier. Example: CALL proc50(). Notes: The client sends to the server's read/write data port.
+
+=item DELETE
+
+Syntax: DELETE FROM tuple-set-name WHERE field-name = literal. Effect: Client tells server to delete the tuple identified by the WHERE clause. Example: DELETE FROM t0 WHERE k0='a'. Notes: field-name must identify the primary key. The client sends to the server's read/write data port after converting from SQL to binary protocol.
+
+=item EXIT
+
+Syntax: E[XIT]. Effect: The tarantool program stops. Example: EXIT. Notes: The QUIT statement does the same thing. The client sends nothing to the server.
+
+=item HELP
+
+Syntax: H[ELP]. Effect: Client displays a message including a list of possible statements. Example: HELP. Notes: The client sends nothing to the server.
+
+=item INSERT
+
+Syntax: INSERT [INTO] tuple-set-identifier VALUES (literal [,literal...]). Effect: The client tells the server to add the tuple consisting of the literal values. Example: INSERT INTO t0 VALUES ('a',0). Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
+
+=item LOADFILE
+
+Syntax: LOADFILE string-literal. Effect: The client loads instructions from the file identified by string-literal. Example: LOADFILE '/home/tarantool_user/file5.txt'.
+
+=item LUA
+
+Syntax: LUA token [token...]. Effect: The client tells the server to execute the tokens as Lua statements. Example: LUA "hello".." world". Notes: The client sends to the server's administrative port.
+
+=item PING
+
+Syntax: PING. Effect: The client sends a ping to the server. Example: PING. Notes: The client sends to the server's read/write data port.
+
+=item QUIT
+
+Syntax: Q[UIT]. Effect: The client stops. This statement is handled entirely by the client. Example: QUIT. Notes: The EXIT statement does the same thing. The client sends nothing to the server.
+
+=item RELOAD
+
+Syntax: RELOAD CONFIGURATION. Effect: The client tells the server to re-read the configuration file. Example: RELOAD CONFIGURATION. Notes: The client sends to the server's administrative port.
+
+=item REPLACE
+
+Syntax; REPLACE [INTO] tuple-set-identifier VALUES (literal [,literal...]). Effect: The client tells the server to add the tuple consisting of the literal values. Example: REPLACE INTO t0 VALUES ('a',0). Notes: REPLACE and INSERT are the same, except that INSERT will return an error if a tuple already exists with the same primary key. The client sends to the server's read/write data port after converting from SQL to binary protocol.
+
+=item SAVE
+
+Syntax: SAVE COREDUMP | SNAPSHOT. Effect: The client tells the server to save the designated object. Example: SAVE SNAPSHOT. Notes: The client sends to the server's administrative port.
+
+=item SELECT
+
+Syntax: SELECT * FROM tuple-set-identifier WHERE field-identifier = literal [AND|OR field-identifier = literal...] [LIMIT numeric-literal [,numeric-literal]]. Effect: Client tells server to find the tuple or tuples identified in the WHERE clause. Example: SELECT * FROM t0 WHERE k0 = 5 AND k1 = 7 LIMIT 1. Notes: The client sends to the server's read/write data port.
+
+=item SET
+
+Syntax: SET INJECTION name-token state-token. Effect: In normal mode: error. Notes: This statement is only available in debug mode.
+
+=item SETOPT
+
+Syntax: SETOPT DELIMITER = string-literal. The string must be a value in single quotes. Effect: string becomes end-of-statement delimiter, so newline alone is not treated as end of statement. Example: SETOPT DELIMITER = '!'. Notes: The client sends nothing to the server.
+
+Syntax: SETOPT PAGER = string-literal. The string must be a value in single quotes. Effect: string becomes the pager that will be invoked for subsequent commands; usually the values are '/usr/bin/less' or '/bin/more' for the common Linux pagers. Example: SETOPT PAGER = '/usr/bin/less'. Notes: The client sends nothing to the server.
+
+=item SHOW
+
+Syntax: SHOW CONFIGURATION | FIBER | INFO | INJECTIONS | PALLOC | PLUGINS | SLAB | STAT. Effect: The client asks the server for information about environment or statistics. Example: SHOW INFO. Notes: The client sends to the server's administrative port. SHOW INJECTIONS is only available in debug mode.
+
+=item UPDATE
+
+Syntax: UPDATE tuple-set-identifier SET field-identifier = literal [,field-identifier = literal...] WHERE field-identifier = literal. Effect: Client tells server to change the tuple identified in the WHERE clause. Example: UPDATE t1 SET k1= 'K', k2 = 7 WHERE k0 = 0. Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
+
+For a condensed Backus-Naur Form [BNF] description of some of the statements, see doc/box-protocol.txt and doc/sql.txt.
+
+
+
+=back
+
+=head1 EXAMPLES
+
+
+Depending how one combines the tarantool client's options, there are in effect three modes of operation: "interactive", "print and play", or "replication" mode.
+
+In interactive mode, one types statements and gets results. One can specify a statement file when starting (tarantool < file_name) or one can specify a statement file with the LOADFILE statement: (LOADFILE file_name), but typically the statements are typed in by the user following prompts. Here is an example of an interactive-mode tarantool client session:
+
+ $ tarantool
+ localhost> INSERT INTO t0 VALUES ('X-1',100)
+ Insert OK, 1 rows affected
+ localhost> INSERT INTO t0 VALUES ('X-2',200,'On Order')
+ Insert OK, 1 rows affected
+ localhost> INSERT INTO t0 VALUES ('X-3',300,'')
+ Insert OK, 1 rows affected
+ localhost> UPDATE t0 SET k1 = 300 WHERE k0 = 'X-1'
+ Update OK, 1 rows affected
+ localhost> DELETE FROM t0 WHERE k0 = 'X-2'
+ Delete OK, 1 rows affected
+ localhost> SELECT * FROM t0 WHERE k0 = 'X-1'
+ Select OK, 1 rows affected
+ ['X-1', 300]
+ localhost> EXIT
+ $
+
+In print and play mode, one uses --cat and --play and --from and --to and --space options to print write-ahead-log contents, or to send write-ahead-log contents to the server. Here is an example of a print-and-play-mode tarantool client session:
+
+ $ tarantool --cat /home/user1/tarantool_test/work_dir/00000000000000000005.xlog --from 22 --to 26
+ Insert, lsn: 22, time: 1385327353.345869, len: 33, space: 0, cookie: 127.0.0.1:44787 ['X-1', 100]
+ Insert, lsn: 23, time: 1385327353.346745, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-2', 200, 8243105135088135759]
+ Insert, lsn: 24, time: 1385327353.347352, len: 34, space: 0, cookie: 127.0.0.1:44787 ['X-3', 300, '']
+ Update, lsn: 25, time: 1385327353.348209, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-1']
+ Delete, lsn: 26, time: 1385327353.348879, len: 28, space: 0, cookie: 127.0.0.1:44787 ['X-2']
+ $
+
+In replication mode, one connects as a replica, and then writes a binary log to a file.
+
+
diff --git a/doc/user/client-reference.xml b/doc/user/client-reference.xml
deleted file mode 100644
index bf5b996f9cf1c9bd6ccf9764d54222c3a17c94e8..0000000000000000000000000000000000000000
--- a/doc/user/client-reference.xml
+++ /dev/null
@@ -1,483 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="client-reference">
-
-<title>Client reference</title>
-
-<para>
-This appendix shows all legal syntax for the tarantool command-line client, with short notes and examples.
-Other client programs may have similar options and statement syntaxes.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Conventions used in this appendix</bridgehead>
-
-Tokens are character sequences which are treated as syntactic units within statements.
-
-Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
-Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
-A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>
-
-General form: <code>tarantool [<replaceable>option</replaceable>...] [<replaceable>statement</replaceable>]</code>.
-
-Statement will be described in a later section.
-Option is one of the following (in alphabetical order by the long form of the option):
-</para>
-
-<variablelist>
- <varlistentry>
- <term xml:id="client-reference-admin-port" xreflabel="client-reference-admin-port">--admin-port</term>
- <listitem><para>
- Syntax: short form: <code>-a <replaceable>port-number</replaceable></code>
- long form: <code>--a[dmin-port] [=] <replaceable>port-number</replaceable></code>.
- Effect: Client will look for the server on the port designated by port-number.
- Notes: This is the <quote>administrative</quote> port. The default value is 33015.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-bin" xreflabel="client-reference-bin">--bin</term>
- <listitem><para>
- Syntax: short form: <code>-B</code>
- long form: <code>--b[in]</code>.
- Effect: When displaying with the Lua printer, treat values with
- type NUM as if they are type STR, unless they are arguments
- in updates used for arithmetic.
- Example: <code>--bin</code>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-cat" xreflabel="client-reference-cat">--cat</term>
- <listitem><para>
- Syntax: short form: <code>-C <replaceable>file-name</replaceable></code>
- long form: <code>--c[at] <replaceable>file-name</replaceable></code>.
- Effect: Client will print the contents of the write-ahead log or snapshot designated by file-name.
- Example: <code>--cat /tarantool_user/work_dir/00000000000000000018.xlog</code>
- Notes: The client stops after displaying the contents. There is also a way to use --cat for Lua statements.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-delim" xreflabel="client-reference-delim">--delim</term>
- <listitem><para>
- Syntax: short form: <code>-D <replaceable>delimiter</replaceable></code>
- long form: <code>--d[elim] <replaceable>delimiter</replaceable></code>.
- Effect: If --cat is used, then put delimiter at end of each line
- of a Lua file. If --cat is not used, then require that
- all statements end with delimiter.
- Example: <code>--delim = '!'</code>
- Notes: See also the SETOPT DELIMITER statement.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-format" xreflabel="client-reference-format">--format</term>
- <listitem><para>
- Syntax: short form: <code>-M tarantool|raw</code>
- long form: <code>--fo[rmat] tarantool|raw</code>.
- Effect: set format for output from --cat
- Example: <code>--format tarantool</code>
- Notes: The default format is tarantool.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-from" xreflabel="client-reference-from">--from</term>
- <listitem><para>
- Syntax: short form: <code>-F <replaceable>log-sequence-number</replaceable></code>
- long form: <code>--fr[om] <replaceable>log-sequence-number</replaceable></code>.
- Effect: Play only what has a a log sequence number greater than or equal to log-sequence-number.
- Example: <code>--from 55</code>
- Notes: See also --play and --to.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-header" xreflabel="client-reference-header">--header</term>
- <listitem><para>
- Syntax: short form: <code>-H</code>
- long form: <code>--hea[der]</code>.
- Effect: Add a header if --format=raw.
- Example: <code>--header</code>
- Notes: The default is 'no header'.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-help" xreflabel="client-reference-help">--help</term>
- <listitem><para>
- Syntax: short form: <code>-?</code>
- long form: <code>--hel[p]</code>.
- Effect: Client displays a help message including a list of options.
- Example: <code>--help</code>
- Notes: The client stops after displaying the help.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-host" xreflabel="client-reference-host">--host</term>
- <listitem><para>
- Syntax: short form: <code>-h <replaceable>host-name</replaceable></code>
- long form: <code>--ho[st] [=] <replaceable>host-name</replaceable></code>.
- Effect: Client will look for the server on the computer designated by host-name.
- Example: <code>--host = 127.0.0.1</code>
- Notes: The default value is localhost.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-play" xreflabel="client-reference-play">--play</term>
- <listitem><para>
- Syntax: short form: <code>-P <replaceable>file-name</replaceable></code>
- long form: <code>--pl[ay] f<replaceable>file-name</replaceable></code>.
- Effect: Client will tell server to replay the write-ahead log designated by file-name.
- Example: <code>--play /tarantool_user/work_dir/00000000000000000018.xlog</code>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-port" xreflabel="client-reference-port">--port</term>
- <listitem><para>
- Syntax: short form: <code>-p <replaceable>port-number</replaceable></code>
- long form: <code>--po[rt] [=] <replaceable>port-number</replaceable></code>.
- Effect: Client will look for the server on the port designated by port-number.
- Example: <code>--port = 33013</code>
- Notes: This is the <quote>read/write data</quote> port. The default value is 33013.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-rpl" xreflabel="client-reference-rpl">--rpl</term>
- <listitem><para>
- Syntax: short form: <code>-R <replaceable>server-name</replaceable></code>
- long form: <code>--rpl <replaceable>server-name</replaceable></code>.
- Effect: Act as a replica for the server specified by server-name.
- Example: <code>--rpl = wombat</code>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-space" xreflabel="client-reference-space">--space</term>
- <listitem><para>
- Syntax: short form: <code>-S <replaceable>space-number</replaceable></code>
- Long form: <code>--s[pace] <replaceable>space-number</replaceable></code>.
- Effect: Play only what is applicable to the space designated by space-number.
- Example: <code>--space 0</code>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-to" xreflabel="client-reference-to">--to</term>
- <listitem><para>
- Syntax: short form: <code>-T <replaceable>log-sequence-number</replaceable></code>
- long form: <code>--t[o] <replaceable>log-sequence-number</replaceable></code>.
- Effect: Play only what has a log sequence number less than or equal to log-sequence-number.
- Example: <code>--to 66</code>
- Notes: See also --play and --from.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-version" xreflabel="client-reference-version">--version</term>
- <listitem><para>
- Syntax: short form: <code>-V</code>
- long form: <code>--v[ersion]</code>.
- Effect: Client displays version information.
- Example: <code>--version</code>
- Notes: The client stops after displaying the version.
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<bridgehead renderas="sect4">Tokens for use within statements</bridgehead>
-</para>
-<para>
-Keywords are: Character sequences containing only letters of the English alphabet.
- Examples: SELECT, INTO, FIBER.
- Notes: Keywords are case insensitive so SELECT and Select are the same thing.
-</para>
-<para>
-Tuple set identifiers are: Lower case letter 't' followed by one or more digits.
- Examples: t0, t55.
-</para>
-<para>
-Field identifiers are: Lower case letter 'k' followed by one or more digits.
- Examples: k0, k55.
-</para>
-<para>
-Procedure identifiers are: Any sequence of letters, digits, or underscores which is
- legal according to the rules for Lua identifiers.
-</para>
-<para>
-String literals are: Any sequence of zero or more characters enclosed in single quotes.
- Examples: 'Hello, world', 'A'.
-</para>
-<para>
-Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
- Examples: 55, -.
- Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
-</para>
-<para>
-Single-byte tokens are: * or , or ( or ).
- Examples: * , ( ).
-</para>
-<para>
-Tokens must be separated from each other by one or more spaces, except that
-spaces are not necessary around single-byte tokens or string literals.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Statements in alphabetical order</bridgehead>
-Although an initial statement may be entered on the tarantool command line,
-generally they are entered following the prompt in interactive mode while
-tarantool is running. (A prompt will be the name of the host and a greater-than
-sign, for example <code>localhost></code>). The end-of-statement marker is
-a newline (line feed).
-</para>
-
-<variablelist>
- <varlistentry>
- <term xml:id="client-reference-call" xreflabel="client-reference-call">CALL</term>
- <listitem><para>
- Syntax: <code>CALL <replaceable>procedure-identifier</replaceable> ()</code>.
- Effect: The client tells the server to execute the procedure identified by procedure-identifier.
- Example: <code>CALL proc50()</code>.
- Notes: The client sends to the server's read/write data port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-delete" xreflabel="client-reference-delete">DELETE</term>
- <listitem><para>
- Syntax: <code>DELETE FROM <replaceable>tuple-set-name</replaceable> WHERE <replaceable>field-name</replaceable> = <replaceable>literal</replaceable></code>.
- Effect: Client tells server to delete the tuple identified by the WHERE clause.
- Example: <code>DELETE FROM t0 WHERE k0='a'</code>.
- Notes: field-name must identify the primary key. The client sends to the server's read/write data port after converting from SQL to binary protocol.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-exit" xreflabel="client-reference-exit">EXIT</term>
- <listitem><para>
- Syntax: <code>E[XIT]</code>.
- Effect: The tarantool program stops.
- Example: <code>EXIT</code>.
- Notes: The QUIT statement does the same thing. The client sends nothing to the server.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-help2" xreflabel="client-reference-help2">HELP</term>
- <listitem><para>
- Syntax: <code>H[ELP]</code>.
- Effect: Client displays a message including a list of possible statements.
- Example: <code>HELP</code>.
- Notes: The client sends nothing to the server.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-insert" xreflabel="client-reference-insert">INSERT</term>
- <listitem><para>
- Syntax: <code>INSERT [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
- Effect: The client tells the server to add the tuple consisting of the literal values.
- Example: <code>INSERT INTO t0 VALUES ('a',0)</code>.
- Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-loadfile" xreflabel="client-reference-loadfile">LOADFILE</term>
- <listitem><para>
- Syntax: <code>LOADFILE <replaceable>string-literal</replaceable></code>.
- Effect: The client loads instructions from the file identified by string-literal.
- Example: <code>LOADFILE '/home/tarantool_user/file5.txt'</code>.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-lua" xreflabel="client-reference-lua">LUA</term>
- <listitem><para>
- Syntax: <code>LUA <replaceable>token</replaceable> [<replaceable>token</replaceable>...]</code>.
- Effect: The client tells the server to execute the tokens as Lua statements.
- Example: <code>LUA "hello".." world"</code>.
- Notes: The client sends to the server's read/write data port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-notee" xreflabel="client-reference-notee">NOTEE</term>
- <listitem><para>
- Syntax: <code>NOTEE</code>.
- Effect: The client ceases to write to a file, thus canceling the effect of the TEE statement.
- Example: <code>NOTEE</code>.
- Notes: The client sends nothing to the server.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-ping" xreflabel="client-reference-ping">PING</term>
- <listitem><para>
- Syntax: <code>PING</code>.
- Effect: The client sends a ping to the server.
- Example: <code>PING</code>.
- Notes: The client sends to the server's read/write data port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-quit" xreflabel="client-reference-quit">QUIT</term>
- <listitem><para>
- Syntax: <code>Q[UIT]</code>.
- Effect: The client stops. This statement is handled entirely by the client.
- Example: <code>QUIT</code>.
- Notes: The EXIT statement does the same thing. The client sends nothing to the server.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-reload" xreflabel="client-reference-reload">RELOAD</term>
- <listitem><para>
- Syntax: <code>RELOAD CONFIGURATION</code>.
- Effect: The client tells the server to re-read the configuration file.
- Example: <code>RELOAD CONFIGURATION</code>.
- Notes: The client sends to the server's administrative port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-replace" xreflabel="client-reference-replace">REPLACE</term>
- <listitem><para>
- Syntax; <code>REPLACE [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
- Effect: The client tells the server to add the tuple consisting of the literal values.
- Example: <code>REPLACE INTO t0 VALUES ('a',0)</code>.
- Notes: REPLACE and INSERT are the same, except that INSERT will return an error if a tuple already exists with the same primary key.
- The client sends to the server's read/write data port after converting from SQL to binary protocol.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-save" xreflabel="client-reference-save">SAVE</term>
- <listitem><para>
- Syntax: <code>SAVE COREDUMP | SNAPSHOT</code>.
- Effect: The client tells the server to save the designated object.
- Example: <code>SAVE SNAPSHOT</code>.
- Notes: The client sends to the server's administrative port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-select" xreflabel="client-reference-select">SELECT</term>
- <listitem><para>
- Syntax: <code>SELECT * FROM <replaceable>tuple-set-identifier</replaceable> WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [AND|OR <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] [LIMIT <replaceable>numeric-literal</replaceable> [,<replaceable>numeric-literal</replaceable>]</code>].
- Effect: Client tells server to find the tuple or tuples identified in the WHERE clause.
- Example: <code>SELECT * FROM t0 WHERE k0 = 5 AND k1 = 7 LIMIT 1</code>.
- Notes: The client sends to the server's read/write data port.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-set" xreflabel="client-reference-set">SET</term>
- <listitem><para>
- Syntax: <code>SET INJECTION <replaceable>name-token</replaceable> <replaceable>state-token</replaceable></code>.
- Effect: In normal mode: error.
- Notes: This statement is only available in debug mode.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-setopt" xreflabel="client-reference-setopt">SETOPT</term>
- <listitem><para>
- Syntax: <code>SETOPT DELIMITER = <replaceable>string-literal</replaceable></code>.
- The string must be a value in single quotes.
- Effect: string becomes end-of-statement delimiter, so newline alone is not treated as end of statement.
- Example: <code>SETOPT DELIMITER = '!'</code>.
- Notes: The client sends nothing to the server.
- </para>
- <para>
- Syntax: <code>SETOPT PAGER = <replaceable>string-literal</replaceable></code>.
- The string must be a value in single quotes.
- Effect: string becomes the pager that will be invoked for subsequent commands;
- usually the values are '/usr/bin/less' or '/bin/more' for the common
- Linux pagers.
- Example: <code>SETOPT PAGER = '/usr/bin/less'</code>.
- Notes: The client sends nothing to the server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-show" xreflabel="client-reference-show">SHOW</term>
- <listitem><para>
- Syntax: <code>SHOW CONFIGURATION | FIBER | INFO | INJECTIONS | PALLOC | PLUGINS | SLAB | STAT</code>.
- Effect: The client asks the server for information about environment or statistics.
- Example: <code>SHOW INFO</code>.
- Notes: The client sends to the server's administrative port.
- SHOW INJECTIONS is only available in debug mode.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-tee" xreflabel="client-reference-tee">TEE</term>
- <listitem><para>
- Syntax: <code>TEE <replaceable>string-literal</replaceable></code>.
- Effect: The client begins logging in the file identified by string-literal.
- Example: <code>TEE '/home/tarantool_user/log.txt'</code>.
- Notes: TEE may also be set up via an option on the command line. The client sends nothing to the server.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term xml:id="client-reference-update" xreflabel="client-reference-update">UPDATE</term>
- <listitem><para>
- Syntax: <code>UPDATE <replaceable>tuple-set-identifier</replaceable> SET <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [,<replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable></code>.
- Effect: Client tells server to change the tuple identified in the WHERE clause.
- Example: <code>UPDATE t1 SET k1= 'K', k2 = 7 WHERE k0 = 0</code>.
- Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-For a condensed Backus-Naur Form [BNF] description of some of the statements, see
- <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt"><filename>doc/box-protocol.txt</filename></link>
- and
- <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Modes</bridgehead>
-Depending how one combines the tarantool client's options, there are in effect three modes of operation:
-<quote>interactive</quote>, <quote>print and play</quote>, or <quote>replication</quote> mode.
-</para>
-<para>
-In <emphasis>interactive</emphasis> mode, one types statements and gets results.
-One can specify a statement file when starting
-(<code>tarantool < file_name</code>)
-or one can specify a statement file with the LOADFILE statement:
-(<code>LOADFILE file_name</code>), but typically the statements
-are typed in by the user following prompts.
-Here is an example of an interactive-mode tarantool client session:
-
-<programlisting>
-<prompt>$ </prompt>tarantool
-localhost> <userinput>INSERT INTO t0 VALUES ('X-1',100)</userinput>
-Insert OK, 1 rows affected
-localhost> <userinput>INSERT INTO t0 VALUES ('X-2',200,'On Order')</userinput>
-Insert OK, 1 rows affected
-localhost> <userinput>INSERT INTO t0 VALUES ('X-3',300,'')</userinput>
-Insert OK, 1 rows affected
-localhost> <userinput>UPDATE t0 SET k1 = 300 WHERE k0 = 'X-1'</userinput>
-Update OK, 1 rows affected
-localhost> <userinput>DELETE FROM t0 WHERE k0 = 'X-2'</userinput>
-Delete OK, 1 rows affected
-localhost> <userinput>SELECT * FROM t0 WHERE k0 = 'X-1'</userinput>
-Select OK, 1 rows affected
-['X-1', 300]
-localhost> <userinput>EXIT</userinput>
-<prompt>$ </prompt>
-</programlisting>
-
-</para>
-<para>
-In <emphasis>print and play</emphasis> mode,
-one uses --cat and --play and --from and --to and --space options
-to print write-ahead-log contents, or to send write-ahead-log
-contents to the server.
-Here is an example of a print-and-play-mode tarantool client session:
-<programlisting>
-<prompt>$ </prompt>tarantool --cat /home/user1/tarantool_test/work_dir/00000000000000000005.xlog --from 22 --to 26
-Insert, lsn: 22, time: 1385327353.345869, len: 33, space: 0, cookie: 127.0.0.1:44787 ['X-1', 100]
-Insert, lsn: 23, time: 1385327353.346745, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-2', 200, 8243105135088135759]
-Insert, lsn: 24, time: 1385327353.347352, len: 34, space: 0, cookie: 127.0.0.1:44787 ['X-3', 300, '']
-Update, lsn: 25, time: 1385327353.348209, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-1']
-Delete, lsn: 26, time: 1385327353.348879, len: 28, space: 0, cookie: 127.0.0.1:44787 ['X-2']
-<prompt>$ </prompt>
-</programlisting>
-</para>
-<para>
-In <emphasis>replication</emphasis> mode,
-one connects as a replica, and then writes
-a binary log to a file.
-</para>
-
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/connectors.xml b/doc/user/connectors.xml
index 35e47bf29610cd6a1163e5b1da68bed482fc245c..0ecb1664f20020c59dfaa3efb22664609ed0a795 100644
--- a/doc/user/connectors.xml
+++ b/doc/user/connectors.xml
@@ -18,6 +18,9 @@ The Tarantool API exists so that a client program can send a request packet
to the server, and receive a response. Here is an example of a what the client
would send for <command>INSERT INTO t0 VALUES ('A','BB')</command>. The BNF description of the components
is in file <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt" xlink:title="A complete BNF of Tarantool client/server protocol">doc/box-protocol.txt</link>.
+ A third-party contribution written in Lua for unpacking Tarantool messages is in file
+ <link xlink:href="https://github.com/negram/Tnt-dissector/blob/master/tarantool.dis.lua" xlink:title="tarantool.dis.lua">Tnt-dissector</link>.
+
</para>
<informaltable frame='topbot'>
<tgroup cols='5' align='left' colsep='1' rowsep='1'>
@@ -345,33 +348,31 @@ catch (Exception $e) {
<section xml:id="connector-python">
<title>Python</title>
<para>
- Here is a complete Python program that inserts ['A','BB'] into space[0] via the high-level Python API.
- To prepare, paste the code into a file named example.py and say:<code>
- export PYTHONPATH=<replaceable>tarantool-directory</replaceable>/test/lib</code>
- where <replaceable>tarantool-directory</replaceable>/test/lib = the directory that contains
- the necessary file <filename>box_connection.py</filename>. This will be
- the directory where Tarantool Python library files were placed at installation time
- for a source download.
-
+ Here is a complete Python program that inserts [99999,'BB'] into space[0] via the high-level Python API.
+ To prepare, paste the code into a file named example.py and install tarantool-python with either
+ <userinput><code>pip install tarantool</code></userinput> to install in <filename>/usr</filename> (requires root privilege)
+ or
+ <userinput><code>pip install tarantool --user</code></userinput> to install in <filename>~</filename> i.e. user's default directory.
Before trying to run, check that the server (tarantool_box) is running on localhost (127.0.0.1) and its primary port
is the default (33013) and space[0]'s primary key type is string (space[0].index[0].key_field[0].type = "STR" in configuration file).
To run, say <code>python example.py</code>.
- The program will connect to the server, send the request, and display <quote>Insert OK, 1 row affected</quote> if all went well.
- If the row already exists, the program will print <quote>Duplicate key exists in unique index 0</quote>.
+ The program will connect to the server, will send the request, and will not throw an exception if all went well.
+ If the row already exists, the program will throw DatabaseException(“Duplicate key exists in unique index 0â€).
</para>
<programlisting language="python">
-#!/usr/bin/python2
-from box_connection import BoxConnection
+#!/usr/bin/python
+from tarantool import Connection
-c = BoxConnection("127.0.0.1", 33013)
-result = c.execute("INSERT INTO t0 VALUES ('A','BB')")
+c = Connection("127.0.0.1", 33013)
+result = c.insert(0,(99999,'BB'))
print result
</programlisting>
<para>
The example program only shows one command and does not show all that's necessary for
good practice. For that, please see
- <link xlink:href="https://github.com/mailru/tarantool-python"><filename>http://github.com/mailru/tarantool-python</filename></link> and
- <link xlink:href="https://github.com/zlobspb/txtarantool"><filename>https://github.com/zlobspb/txtarantool</filename></link>.
+ <link xlink:href="http://tarantool-python.readthedocs.org/en/latest/"><filename>http://tarantool-python.readthedocs.org/en/latest/</filename></link>.
+ For an example of a Python API for <link xlink:href="https://github.com/tarantool/queue">Queue managers on Tarantool</link>, see
+ <link xlink:href="https://github.com/tarantool/tarantool-queue-python"><filename>https://github.com/tarantool/tarantool-queue-python</filename></link>.
</para>
</section>
diff --git a/doc/user/language-reference.xml b/doc/user/language-reference.xml
index 902720f459826d23409270cb2ed06a4545e349bb..49ad8c9e472c11cf862fdd87d6fb69f2b3956c74 100644
--- a/doc/user/language-reference.xml
+++ b/doc/user/language-reference.xml
@@ -236,13 +236,14 @@ fail: can't save snapshot, errno 17 (File exists)
</term>
<listitem><para>
<programlisting>
-localhost> box.info()
+<prompt>localhost></prompt> <userinput>show info</userinput>
---
info:
- version: "1.4.5-128-ga91962c"
+ version: "1.5.2-8-g54a279d"
uptime: 441524
pid: 12315
logger_pid: 12316
+ snapshot_pid: 0
lsn: 15481913304
recovery_lag: 0.000
recovery_last_update: 1306964594.980
@@ -273,8 +274,17 @@ info:
</varlistentry>
<varlistentry>
- <term xml:id="box.stat.show" xreflabel="box.stat()">
- <emphasis role="tntadmin">box.stat()</emphasis>
+ <term xml:id="show-index" xreflabel="SHOW INDEX">
+ <emphasis role="tntadmin">show index</emphasis>
+ </term>
+ <listitem><para>
+ Show the number of keys and the amount of memory used by each each index.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term xml:id="box.stat.show" xreflabel="box.stat.show()">
+ <emphasis role="tntadmin">box.stat.show()</emphasis>
</term>
<listitem><para>
Show the average number of requests per second, and the
@@ -314,6 +324,11 @@ statistics:
the % of <olink targetptr="slab_alloc_arena"/> that is
already distributed to the slab allocator.
</para>
+ <para>
+ <emphasis role="strong">bytes_waste</emphasis> contains
+ the amount of memory wasted by the slab allocator due to
+ internal fragmentation.
+ </para>
<para>
</para>
</listitem>
diff --git a/doc/user/lua-tutorial.xml b/doc/user/lua-tutorial.xml
index 1423ff19107974128d5df31e86159523a9ba2ecb..35f1ddc88d79e6e4f780bf29643cdc57a0dd9f9d 100644
--- a/doc/user/lua-tutorial.xml
+++ b/doc/user/lua-tutorial.xml
@@ -37,7 +37,7 @@ a runnning tarantool_box server, and a running tarantool client.
<para>
<bridgehead renderas="sect4">Delimiter</bridgehead>
We'll be making functions which go over one line. We don't want the client to send to the server after every line.
-So we <link linkend="client-reference-delim">declare a delimiter</link>.
+So we <link linkend="utility-tarantool-delim">declare a delimiter</link>.
This means <quote>Do not send to the server until you see an exclamation mark.</quote>
<programlisting>
@@ -56,7 +56,7 @@ lua function string_function()
return "hello world"
end!
</programlisting>
-The word <link linkend="client-reference-lua">LUA</link>
+The word <link linkend="utility-tarantool-lua">LUA</link>
is a Tarantool keyword that means <quote>we're about to go into Lua.</quote>
The function name is string_function.
The function has one executable statement, <code>return "hello world"</code>.
@@ -69,7 +69,7 @@ To confirm that the function works, we can say
<programlisting>
call string_function()!
</programlisting>
-The word <link linkend="client-reference-call">CALL</link> is a Tarantool keyword that means <quote>invoke the Lua function.</quote>
+The word <link linkend="utility-tarantool-call">CALL</link> is a Tarantool keyword that means <quote>invoke the Lua function.</quote>
The effect is that the string which the function returns will end up on the screen.
</para>
@@ -323,7 +323,7 @@ field will be 1. The second field will be a random 10-letter string.
Once again the string_function() can be invoked from main_function() which can be invoked with
call main_function(). But main_function() won't tell the whole story, because it does not
return t, it only puts t into the database. To confirm that something got inserted, we'll
-use a <link linkend="client-reference-select">SELECT statement</link>.
+use a <link linkend="utility-tarantool-select">SELECT statement</link>.
<programlisting>
call main_function()!
diff --git a/doc/user/plugins.xml b/doc/user/plugins.xml
index 0c612be35d152c2d59771198fcdc62933b9406f6..661b86b6e1f217502f3867b712ef2aab5b78ec04 100644
--- a/doc/user/plugins.xml
+++ b/doc/user/plugins.xml
@@ -19,7 +19,7 @@ two plugins that have already been created: the "SQL DBMS plugins" for
MySQL and PostgreSQL.
</para>
-<para>
+<para xml:id="plugin-sql-dbms-plugins">
<bridgehead renderas="sect4">SQL DBMS Plugins</bridgehead>
To call another DBMS from Tarantool, the essential requirements are:
another DBMS, and Tarantool.
@@ -44,16 +44,22 @@ can work on both SQL and Tarantool inside the same Lua routine.
</para>
<para>
+The connection method is
+<code>box.net.sql.connect('mysql'|'postgresql', <replaceable>host</replaceable>, <replaceable>port</replaceable>, <replaceable>user</replaceable>, <replaceable>password</replaceable>, <replaceable>database</replaceable>)</code>.
+The methods for select/insert/etc. are the same as the ones in <olink targetptr="sp-box-net-box">the box.net library</olink>.
+</para>
+
+<para xml:id="plugin-mysql-example">
<bridgehead renderas="sect4">MySQL Example</bridgehead>
This example assumes that MySQL 5.5 or MySQL 5.6 has been installed
-(recent MariaDB versions should also work), and the mysqld server has
-been started on the local host 127.0.0.1.
+(recent MariaDB versions should also work).
</para>
<para>
The example was run on a Linux machine where the base directory
had a copy of the Tarantool source on ~/tarantool-stable, and
-a copy of MySQL on ~/mysql-5.5. The mysqld server is already running.
+a copy of MySQL on ~/mysql-5.5. The mysqld server is already running
+on the local host 127.0.0.1.
</para>
<programlisting>
@@ -93,7 +99,6 @@ Bye
<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
<prompt>$ </prompt><userinput>cmake . -DWITH_MYSQL=on -DMYSQL_INCLUDE_DIR=~/mysql-5.5/include -DMYSQL_LIBRARIES=~/mysql-5.5/lib/libmysqlclient.so -DENABLE_CLIENT=true</userinput>
...
--- PostgreSQL client not found, box.net.sql(pg) disabled
-- Found MySQL includes: ~/mysql-5.5/include/mysql.h
-- Found MySQL library: ~/mysql-5.5/lib/libmysqlclient.so
-- box.net.sql(mysql) INC=~/mysql-5.5/include
@@ -161,10 +166,134 @@ plugins:
Call OK, 0 rows affected
# Observe the result. It contains "MySQL row".
-# So this is the row that was inserted with the mysql client.
+# So this is the row that was inserted into the MySQL database.
+# And now it's been selected with the Tarantool client.
+</programlisting>
+
+<para xml:id="plugin-postgresql-example">
+<bridgehead renderas="sect4">PostgreSQL Example</bridgehead>
+This example assumes that a recent version of PostgreSQL has been installed.
+The PostgreSQL library library and include files are also necessary.
+On Ubuntu they can be installed with <programlisting><prompt>$ </prompt><userinput>sudo apt-get install libpq-dev</userinput></programlisting>
+If that works, then cmake will find the necessary files without requiring any special user input.
+However, because not all platforms are alike, for this example the assumption is
+that the user must check that the appropriate PostgreSQL files are present and
+must explicitly state where they are when building Tarantool from source.
+</para>
+
+<para>
+The example was run on a Linux machine where the base directory
+had a copy of the Tarantool source on ~/tarantool-stable, and
+a copy of PostgreSQL on /usr. The postgres server is already running
+on the local host 127.0.0.1.
+</para>
+
+<programlisting>
+# Check that the include subdirectory exists by looking for /usr/include/postgresql/libpq-fe-h.
+<prompt>$ </prompt><userinput>[ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"</userinput>
+OK
+
+# Check that the library subdirectory exists and has the necessary .so file.
+<prompt>$ </prompt><userinput>[ -f /usr/lib/libpq.so ] && echo "OK" || echo "Error"</userinput>
+OK
+
+# Check that the psql client can connect using some factory defaults:
+# port = 5432, user = 'postgres', user password = 'postgres', database = 'postgres'.
+# These can be changed, provided one changes them in all places.
+# Insert a row in database postgres, and quit.
+<prompt>$ </prompt><userinput>~psql -h 127.0.0.1 -p 5432 -U postgres -d postgres</userinput>
+Password for user postgres:
+psql (9.3.0, server 9.3.2)
+SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
+Type "help" for help.
+
+<prompt>postgres=#</prompt> <userinput>CREATE TABLE test (s1 INT, s2 VARCHAR(50));</userinput>
+CREATE TABLE
+<prompt>postgres=#</prompt> <userinput>INSERT INTO test VALUES (1,'PostgreSQL row');</userinput>
+INSERT 0 1
+<prompt>postgres=#</prompt> <userinput>\q</userinput>
+<prompt>$ </prompt>
+
+# Build the Tarantool server. Make certain that "cmake" gets the right
+# paths for the PostgreSQL include directory and the PostgreSQL libpq
+# library which were checked earlier.
+<prompt>$ </prompt><userinput>cd ~/tarantool-stable</userinput>
+<prompt>$ </prompt><userinput>make clean</userinput>
+<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
+<prompt>$ </prompt><userinput>cmake . -DWITH_POSTGRESQL=on -DPostgreSQL_LIBRARY=/usr/lib/libpq.so -DPostgreSQL_INCLUDE_DIR=/usr/include/postgresql -DENABLE_CLIENT=true</userinput>
+...
+-- Found PostgreSQL: /usr/lib/libpq.so
+-- box.net.sql(pg): INC=/usr/include/postgresql;/usr/include/postgresql
+-- box.net.sql(pg): LIBS=pq
+...
+-- Configuring done
+-- Generating done
+-- Build files have been written to: ~/tarantool-stable
+<prompt>$ </prompt><userinput>make</userinput>
+...
+[ 49%] Built target core
+[ 50%] Building CXX object src/plugin/pg/CMakeFiles/pg.dir/pg.cc.o
+Linking CXX shared library libpg.so
+[ 50%] Built target pg
+...
+[100%] Built target xlog
+[100%] Built target man
+<prompt>$ </prompt>
+
+# Before starting Tarantool server, tell it where the PostgreSQL plugin is.
+<prompt>$ </prompt><userinput>export TARANTOOL_PLUGIN_DIR=~/tarantool-stable/src/plugin/pg</userinput>
+<prompt>$ </prompt>
+
+# Start the Tarantool server.
+# Run it in the background but let the initial display be in the foreground.
+# So it's possible to see the message that the plugin was loaded.
+<prompt>$ </prompt><userinput>~/tarantool-stable/src/box/tarantool_box&</userinput>
+2013-12-06 13:01:51.518 [23978] 1/sched C> version 1.5.1-290-g45b93e7
+2013-12-06 13:01:51.520 [23978] 1/sched I> Loading plugin: ~/tarantool-stable/src/plugin/pg/libpg.so
+2013-12-06 13:01:51.527 [23978] 1/sched I> Plugin 'postgresql' was loaded, version: 1
+...
+2013-12-06 13:01:51.531 [23978] 1/sched C> entering event loop
+
+# Type 'Enter' and then start the Tarantool client.
+<prompt>$ </prompt><userinput>~/tarantool-stable/client/tarantool/tarantool</userinput>
+<prompt>localhost> </prompt>
+
+# Say <quote>show plugins</quote>. Since all has gone well, this is certain to work.
+<prompt>localhost> </prompt> <userinput>show plugins</userinput>
+---
+plugins:
+ - { name: "postgresql", version: 1 }
+...
+
+# Create a Lua function that will connect to the PostgreSQL server,
+# retrieve one row, and display the row.
+# For explanations of the statement types used here, read the
+# Lua tutorial in the Tarantool user manual.
+<prompt>localhost> </prompt><userinput>SETOPT delimiter = '!'</userinput>
+<prompt>localhost> </prompt><userinput>lua function postgresql_select ()</userinput>
+ <prompt>-> </prompt><userinput> local dbh = box.net.sql.connect('pg', '127.0.0.1', 5432, 'postgres', 'postgres', 'postgres')</userinput>
+ <prompt>-> </prompt><userinput> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')</userinput>
+ <prompt>-> </prompt><userinput> for i, card in pairs(test) do</userinput>
+ <prompt>-> </prompt><userinput> print(card.s2)</userinput>
+ <prompt>-> </prompt><userinput> end</userinput>
+ <prompt>-> </prompt><userinput> end!</userinput>
+---
+...
+<prompt>localhost> </prompt><userinput>SETOPT delimiter = ''!</userinput>
+<prompt>localhost> </prompt>
+
+# Execute the Lua function.
+<prompt>localhost> </prompt><userinput>CALL postgresql_select()</userinput>
+2013-12-06 13:07:45.893 [23978] 102/iproto I> PostgreSQL row
+Call OK, 0 rows affected
+
+
+# Observe the result. It contains "PostgreSQL row".
+# So this is the row that was inserted into the PostgreSQL database.
# And now it's been selected with the Tarantool client.
</programlisting>
+
</appendix>
<!--
diff --git a/doc/user/server-administration.xml b/doc/user/server-administration.xml
index 3624ea001887e5d821d4cd944c7f34db8e812b5b..c2faaf467edacbe4b83b882756ef7e74bdff932d 100644
--- a/doc/user/server-administration.xml
+++ b/doc/user/server-administration.xml
@@ -24,6 +24,467 @@
</para>
</section>
+<section xml:id="utility-tarantool">
+
+<title>Utility <code>tarantool</code> — the main client</title>
+
+<para>
+This section shows all legal syntax for the tarantool command-line client, with short notes and examples.
+Other client programs may have similar options and statement syntaxes.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Conventions used in this section</bridgehead>
+
+Tokens are character sequences which are treated as syntactic units within statements.
+
+Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
+Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
+A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>
+
+General form: <code>tarantool [<replaceable>option</replaceable>...] [<replaceable>statement</replaceable>]</code>.
+
+Statement will be described in a later part of this section.
+Option is one of the following (in alphabetical order by the long form of the option):
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term xml:id="utility-tarantool-admin-port" xreflabel="utility-tarantool-admin-port">--admin-port</term>
+ <listitem><para>
+ Syntax: short form: <code>-a <replaceable>port-number</replaceable></code>
+ long form: <code>--a[dmin-port] [=] <replaceable>port-number</replaceable></code>.
+ Effect: Client will look for the server on the port designated by port-number.
+ Notes: This is the <quote>administrative</quote> port. The default value is 33015.
+ If --port is specified then there is no need to specify --admin-port, the client will discover it.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-bin" xreflabel="utility-tarantool-bin">--bin</term>
+ <listitem><para>
+ Syntax: short form: <code>-B</code>
+ long form: <code>--b[in]</code>.
+ Effect: When displaying with the Lua printer, treat values with
+ type NUM as if they are type STR, unless they are arguments
+ in updates used for arithmetic.
+ Example: <code>--bin</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-cat" xreflabel="utility-tarantool-cat">--cat</term>
+ <listitem><para>
+ Syntax: short form: <code>-C <replaceable>file-name</replaceable></code>
+ long form: <code>--c[at] <replaceable>file-name</replaceable></code>.
+ Effect: Client will print the contents of the write-ahead log or snapshot designated by file-name.
+ Example: <code>--cat /tarantool_user/work_dir/00000000000000000018.xlog</code>
+ Notes: The client stops after displaying the contents. There is also a way to use --cat for Lua statements.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-delim" xreflabel="utility-tarantool-delim">--delim</term>
+ <listitem><para>
+ Syntax: short form: <code>-D <replaceable>delimiter</replaceable></code>
+ long form: <code>--d[elim] <replaceable>delimiter</replaceable></code>.
+ Effect: If --cat is used, then put delimiter at end of each line
+ of a Lua file. If --cat is not used, then require that
+ all statements end with delimiter.
+ Example: <code>--delim = '!'</code>
+ Notes: See also the SETOPT DELIMITER statement.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-format" xreflabel="utility-tarantool-format">--format</term>
+ <listitem><para>
+ Syntax: short form: <code>-M tarantool|raw</code>
+ long form: <code>--fo[rmat] tarantool|raw</code>.
+ Effect: set format for output from --cat
+ Example: <code>--format tarantool</code>
+ Notes: The default format is tarantool.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-from" xreflabel="utility-tarantool-from">--from</term>
+ <listitem><para>
+ Syntax: short form: <code>-F <replaceable>log-sequence-number</replaceable></code>
+ long form: <code>--fr[om] <replaceable>log-sequence-number</replaceable></code>.
+ Effect: Play only what has a a log sequence number greater than or equal to log-sequence-number.
+ Example: <code>--from 55</code>
+ Notes: See also --play and --to.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-header" xreflabel="utility-tarantool-header">--header</term>
+ <listitem><para>
+ Syntax: short form: <code>-H</code>
+ long form: <code>--hea[der]</code>.
+ Effect: Add a header if --format=raw.
+ Example: <code>--header</code>
+ Notes: The default is 'no header'.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-help" xreflabel="utility-tarantool-help">--help</term>
+ <listitem><para>
+ Syntax: short form: <code>-?</code>
+ long form: <code>--hel[p]</code>.
+ Effect: Client displays a help message including a list of options.
+ Example: <code>--help</code>
+ Notes: The client stops after displaying the help.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-host" xreflabel="utility-tarantool-host">--host</term>
+ <listitem><para>
+ Syntax: short form: <code>-h <replaceable>host-name</replaceable></code>
+ long form: <code>--ho[st] [=] <replaceable>host-name</replaceable></code>.
+ Effect: Client will look for the server on the computer designated by host-name.
+ Example: <code>--host = 127.0.0.1</code>
+ Notes: The default value is localhost.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-play" xreflabel="utility-tarantool-play">--play</term>
+ <listitem><para>
+ Syntax: short form: <code>-P <replaceable>file-name</replaceable></code>
+ long form: <code>--pl[ay] f<replaceable>file-name</replaceable></code>.
+ Effect: Client will tell server to replay the write-ahead log designated by file-name.
+ Example: <code>--play /tarantool_user/work_dir/00000000000000000018.xlog</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-port" xreflabel="utility-tarantool-port">--port</term>
+ <listitem><para>
+ Syntax: short form: <code>-p <replaceable>port-number</replaceable></code>
+ long form: <code>--po[rt] [=] <replaceable>port-number</replaceable></code>.
+ Effect: Client will look for the server on the port designated by port-number.
+ Example: <code>--port = 33013</code>
+ Notes: This is the <quote>primary port</quote> also known as the <quote>read/write data</quote> port. The default value is 33013.
+ If --admin-port is specified then there is no need to specify --port, the client will discover it.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-rpl" xreflabel="utility-tarantool-rpl">--rpl</term>
+ <listitem><para>
+ Syntax: short form: <code>-R <replaceable>server-name</replaceable></code>
+ long form: <code>--rpl <replaceable>server-name</replaceable></code>.
+ Effect: Act as a replica for the server specified by server-name.
+ Example: <code>--rpl = wombat</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-space" xreflabel="utility-tarantool-space">--space</term>
+ <listitem><para>
+ Syntax: short form: <code>-S <replaceable>space-number</replaceable></code>
+ Long form: <code>--s[pace] <replaceable>space-number</replaceable></code>.
+ Effect: Play only what is applicable to the space designated by space-number.
+ Example: <code>--space 0</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-to" xreflabel="utility-tarantool-to">--to</term>
+ <listitem><para>
+ Syntax: short form: <code>-T <replaceable>log-sequence-number</replaceable></code>
+ long form: <code>--t[o] <replaceable>log-sequence-number</replaceable></code>.
+ Effect: Play only what has a log sequence number less than or equal to log-sequence-number.
+ Example: <code>--to 66</code>
+ Notes: See also --play and --from.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-version" xreflabel="utility-tarantool-version">--version</term>
+ <listitem><para>
+ Syntax: short form: <code>-V</code>
+ long form: <code>--v[ersion]</code>.
+ Effect: Client displays version information.
+ Example: <code>--version</code>
+ Notes: The client stops after displaying the version.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<bridgehead renderas="sect4">Tokens for use within statements</bridgehead>
+</para>
+<para>
+Keywords are: Character sequences containing only letters of the English alphabet.
+ Examples: SELECT, INTO, FIBER.
+ Notes: Keywords are case insensitive so SELECT and Select are the same thing.
+</para>
+<para>
+Tuple set identifiers are: Lower case letter 't' followed by one or more digits.
+ Examples: t0, t55.
+</para>
+<para>
+Field identifiers are: Lower case letter 'k' followed by one or more digits.
+ Examples: k0, k55.
+</para>
+<para>
+Procedure identifiers are: Any sequence of letters, digits, or underscores which is
+ legal according to the rules for Lua identifiers.
+</para>
+<para>
+String literals are: Any sequence of zero or more characters enclosed in single quotes.
+ Examples: 'Hello, world', 'A'.
+</para>
+<para>
+Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
+ Examples: 55, -.
+ Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
+</para>
+<para>
+Single-byte tokens are: * or , or ( or ).
+ Examples: * , ( ).
+</para>
+<para>
+Tokens must be separated from each other by one or more spaces, except that
+spaces are not necessary around single-byte tokens or string literals.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Statements in alphabetical order</bridgehead>
+Although an initial statement may be entered on the tarantool command line,
+generally they are entered following the prompt in interactive mode while
+tarantool is running. (A prompt will be the name of the host and a greater-than
+sign, for example <code>localhost></code>). The end-of-statement marker is
+a newline (line feed).
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term xml:id="utility-tarantool-call" xreflabel="utility-tarantool-call">CALL</term>
+ <listitem><para>
+ Syntax: <code>CALL <replaceable>procedure-identifier</replaceable> ()</code>.
+ Effect: The client tells the server to execute the procedure identified by procedure-identifier.
+ Example: <code>CALL proc50()</code>.
+ Notes: The client sends to the server's read/write data port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-delete" xreflabel="utility-tarantool-delete">DELETE</term>
+ <listitem><para>
+ Syntax: <code>DELETE FROM <replaceable>tuple-set-name</replaceable> WHERE <replaceable>field-name</replaceable> = <replaceable>literal</replaceable></code>.
+ Effect: Client tells server to delete the tuple identified by the WHERE clause.
+ Example: <code>DELETE FROM t0 WHERE k0='a'</code>.
+ Notes: field-name must identify the primary key. The client sends to the server's read/write data port after converting from SQL to binary protocol.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-exit" xreflabel="utility-tarantool-exit">EXIT</term>
+ <listitem><para>
+ Syntax: <code>E[XIT]</code>.
+ Effect: The tarantool program stops.
+ Example: <code>EXIT</code>.
+ Notes: The QUIT statement does the same thing. The client sends nothing to the server.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-help2" xreflabel="utility-tarantool-help2">HELP</term>
+ <listitem><para>
+ Syntax: <code>H[ELP]</code>.
+ Effect: Client displays a message including a list of possible statements.
+ Example: <code>HELP</code>.
+ Notes: The client sends nothing to the server.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-insert" xreflabel="utility-tarantool-insert">INSERT</term>
+ <listitem><para>
+ Syntax: <code>INSERT [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
+ Effect: The client tells the server to add the tuple consisting of the literal values.
+ Example: <code>INSERT INTO t0 VALUES ('a',0)</code>.
+ Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-loadfile" xreflabel="utility-tarantool-loadfile">LOADFILE</term>
+ <listitem><para>
+ Syntax: <code>LOADFILE <replaceable>string-literal</replaceable></code>.
+ Effect: The client loads instructions from the file identified by string-literal.
+ Example: <code>LOADFILE '/home/tarantool_user/file5.txt'</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-lua" xreflabel="utility-tarantool-lua">LUA</term>
+ <listitem><para>
+ Syntax: <code>LUA <replaceable>token</replaceable> [<replaceable>token</replaceable>...]</code>.
+ Effect: The client tells the server to execute the tokens as Lua statements.
+ Example: <code>LUA "hello".." world"</code>.
+ Notes: The client sends to the server's administrative port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-ping" xreflabel="utility-tarantool-ping">PING</term>
+ <listitem><para>
+ Syntax: <code>PING</code>.
+ Effect: The client sends a ping to the server.
+ Example: <code>PING</code>.
+ Notes: The client sends to the server's read/write data port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-quit" xreflabel="utility-tarantool-quit">QUIT</term>
+ <listitem><para>
+ Syntax: <code>Q[UIT]</code>.
+ Effect: The client stops. This statement is handled entirely by the client.
+ Example: <code>QUIT</code>.
+ Notes: The EXIT statement does the same thing. The client sends nothing to the server.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-reload" xreflabel="utility-tarantool-reload">RELOAD</term>
+ <listitem><para>
+ Syntax: <code>RELOAD CONFIGURATION</code>.
+ Effect: The client tells the server to re-read the configuration file.
+ Example: <code>RELOAD CONFIGURATION</code>.
+ Notes: The client sends to the server's administrative port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-replace" xreflabel="utility-tarantool-replace">REPLACE</term>
+ <listitem><para>
+ Syntax; <code>REPLACE [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
+ Effect: The client tells the server to add the tuple consisting of the literal values.
+ Example: <code>REPLACE INTO t0 VALUES ('a',0)</code>.
+ Notes: REPLACE and INSERT are the same, except that INSERT will return an error if a tuple already exists with the same primary key.
+ The client sends to the server's read/write data port after converting from SQL to binary protocol.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-save" xreflabel="utility-tarantool-save">SAVE</term>
+ <listitem><para>
+ Syntax: <code>SAVE COREDUMP | SNAPSHOT</code>.
+ Effect: The client tells the server to save the designated object.
+ Example: <code>SAVE SNAPSHOT</code>.
+ Notes: The client sends to the server's administrative port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-select" xreflabel="utility-tarantool-select">SELECT</term>
+ <listitem><para>
+ Syntax: <code>SELECT * FROM <replaceable>tuple-set-identifier</replaceable> WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [AND|OR <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] [LIMIT <replaceable>numeric-literal</replaceable> [,<replaceable>numeric-literal</replaceable>]</code>].
+ Effect: Client tells server to find the tuple or tuples identified in the WHERE clause.
+ Example: <code>SELECT * FROM t0 WHERE k0 = 5 AND k1 = 7 LIMIT 1</code>.
+ Notes: The client sends to the server's read/write data port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-set" xreflabel="utility-tarantool-set">SET</term>
+ <listitem><para>
+ Syntax: <code>SET INJECTION <replaceable>name-token</replaceable> <replaceable>state-token</replaceable></code>.
+ Effect: In normal mode: error.
+ Notes: This statement is only available in debug mode.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-setopt" xreflabel="utility-tarantool-setopt">SETOPT</term>
+ <listitem><para>
+ Syntax: <code>SETOPT DELIMITER = <replaceable>string-literal</replaceable></code>.
+ The string must be a value in single quotes.
+ Effect: string becomes end-of-statement delimiter, so newline alone is not treated as end of statement.
+ Example: <code>SETOPT DELIMITER = '!'</code>.
+ Notes: The client sends nothing to the server.
+ </para>
+ <para>
+ Syntax: <code>SETOPT PAGER = <replaceable>string-literal</replaceable></code>.
+ The string must be a value in single quotes.
+ Effect: string becomes the pager that will be invoked for subsequent commands;
+ usually the values are '/usr/bin/less' or '/bin/more' for the common
+ Linux pagers.
+ Example: <code>SETOPT PAGER = '/usr/bin/less'</code>.
+ Notes: The client sends nothing to the server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-show" xreflabel="utility-tarantool-show">SHOW</term>
+ <listitem><para>
+ Syntax: <code>SHOW CONFIGURATION | FIBER | INFO | INJECTIONS | PALLOC | PLUGINS | SLAB | STAT</code>.
+ Effect: The client asks the server for information about environment or statistics.
+ Example: <code>SHOW INFO</code>.
+ Notes: The client sends to the server's administrative port.
+ SHOW INJECTIONS is only available in debug mode.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="utility-tarantool-update" xreflabel="utility-tarantool-update">UPDATE</term>
+ <listitem><para>
+ Syntax: <code>UPDATE <replaceable>tuple-set-identifier</replaceable> SET <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [,<replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable></code>.
+ Effect: Client tells server to change the tuple identified in the WHERE clause.
+ Example: <code>UPDATE t1 SET k1= 'K', k2 = 7 WHERE k0 = 0</code>.
+ Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+For a condensed Backus-Naur Form [BNF] description of some of the statements, see
+ <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt"><filename>doc/box-protocol.txt</filename></link>
+ and
+ <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Modes</bridgehead>
+Depending how one combines the tarantool client's options, there are in effect three modes of operation:
+<quote>interactive</quote>, <quote>print and play</quote>, or <quote>replication</quote> mode.
+</para>
+<para>
+In <emphasis>interactive</emphasis> mode, one types statements and gets results.
+One can specify a statement file when starting
+(<code>tarantool < file_name</code>)
+or one can specify a statement file with the LOADFILE statement:
+(<code>LOADFILE file_name</code>), but typically the statements
+are typed in by the user following prompts.
+Here is an example of an interactive-mode tarantool client session:
+
+<programlisting>
+<prompt>$ </prompt>tarantool
+localhost> <userinput>INSERT INTO t0 VALUES ('X-1',100)</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>INSERT INTO t0 VALUES ('X-2',200,'On Order')</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>INSERT INTO t0 VALUES ('X-3',300,'')</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>UPDATE t0 SET k1 = 300 WHERE k0 = 'X-1'</userinput>
+Update OK, 1 rows affected
+localhost> <userinput>DELETE FROM t0 WHERE k0 = 'X-2'</userinput>
+Delete OK, 1 rows affected
+localhost> <userinput>SELECT * FROM t0 WHERE k0 = 'X-1'</userinput>
+Select OK, 1 rows affected
+['X-1', 300]
+localhost> <userinput>EXIT</userinput>
+<prompt>$ </prompt>
+</programlisting>
+
+</para>
+<para>
+In <emphasis>print and play</emphasis> mode,
+one uses --cat and --play and --from and --to and --space options
+to print write-ahead-log contents, or to send write-ahead-log
+contents to the server.
+Here is an example of a print-and-play-mode tarantool client session:
+<programlisting>
+<prompt>$ </prompt>tarantool --cat /home/user1/tarantool_test/work_dir/00000000000000000005.xlog --from 22 --to 26
+Insert, lsn: 22, time: 1385327353.345869, len: 33, space: 0, cookie: 127.0.0.1:44787 ['X-1', 100]
+Insert, lsn: 23, time: 1385327353.346745, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-2', 200, 8243105135088135759]
+Insert, lsn: 24, time: 1385327353.347352, len: 34, space: 0, cookie: 127.0.0.1:44787 ['X-3', 300, '']
+Update, lsn: 25, time: 1385327353.348209, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-1']
+Delete, lsn: 26, time: 1385327353.348879, len: 28, space: 0, cookie: 127.0.0.1:44787 ['X-2']
+<prompt>$ </prompt>
+</programlisting>
+</para>
+<para>
+In <emphasis>replication</emphasis> mode,
+one connects as a replica, and then writes
+a binary log to a file.
+</para>
+
+</section>
+
<section xml:id="tarantar">
<title>Utility <code>tarantar</code></title>
<para>
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index 40143a9ee9fa2ef8bf8c772898d71385b8c856fc..8e149a429fe57a2cb2298b5bdb629bdaac775180 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -477,44 +477,40 @@ localhost> <userinput>lua box.select(5, 1, 'firstname', 'lastname')</userinput>
<varlistentry>
<term>
- <emphasis role="lua" xml:id="box.update">box.update(space_no, key, format, ...)</emphasis>
+ <emphasis role="lua" xml:id="box.update">box.update(space_no, key, format, {field_no, value}...)</emphasis>
</term>
<listitem>
<para>
- Update a tuple identified by a primary
- <code>key</code>. If a key is multipart,
- it is passed in as a Lua table. Update arguments follow,
- described by <code>format</code>.
- The format and arguments are passed to
+ Update a tuple.
+ The <code>space_no</code> and <code>key</code> arguments
+ identify the tuple; if a key is multipart then it is
+ passed as a Lua table.
+ The <code>format</code> argument is a sequence of
+ pairs of characters, where the first character in each pair
+ is the operation specifier, and the second character in
+ each pair is the operation argument.
+ The <code>{field_no, value}</code> arguments are the
+ field numbers of affected fields and applicable values.
+ For some operations the field number can be -1, meaning
+ the last field in the tuple.
+ There must be a pair of {field_no, value} arguments
+ for each character pair in the format argument.
+ The format and {field_no, value} arguments are passed to
<code>box.pack()</code> and the result is sent
to <code>box.process()</code>.
- A correct <code>format</code> is a sequence of
- pairs: update operation, operation arguments. A
- single character of format describes either an
- operation which needs to take place or operation
- argument. A format specifier also works as a
- placeholder for the number of a field, which needs
- to be updated, or for an argument value.
- For example:
- <simplelist>
- <member><code>+p=p</code> — add a value
- to one field and assign another,
- </member>
- <member><code>:p</code> — splice a
- field: start at offset, cut length bytes, and add a
- string.</member>
- <member><code>#p</code> — delete specified
- number of fields.</member>
- <member><code>!p</code> — insert a field
- (before the one specified).</member>
- </simplelist>
- Possible format specifiers are: <quote>+</quote>
+ Possible operation specifiers are: <quote>+</quote>
for addition, <quote>-</quote> for subtraction,
<quote>&</quote> for bitwise AND,
<quote>|</quote> for bitwise OR, <quote>^</quote>
for bitwise exclusive OR (XOR), <quote>:</quote>
- for string splice and <quote>p</quote> for
- operation argument.
+ for string splice, <quote>!</quote> for insertion.
+ Possible operation arguments are: <quote>p</quote>.
+ Thus in the instruction <code>lua box.update(0,44,'+p=p',1,55,3,'x')</code>
+ the space number is 0, the primary-key value is 44,
+ the format is '+p=p' meaning "add a value to a field
+ and then assign a value to a field", the first affected field
+ is field 1 and the value which will be added to it is 55, the second affected field
+ is field 3 and the value which will be assigned to it is 'x'.
<bridgehead renderas="sect4">Returns</bridgehead>
Returns the updated tuple.
<bridgehead renderas="sect4">Example</bridgehead>
@@ -1315,7 +1311,7 @@ localhost> <userinput>lua t:transform(1,2,'x')</userinput>
then the result is returned.
</para>
<bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})
+ <programlisting>localhost> <userinput>lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})</userinput>
---
...
localhost> <userinput>lua t:slice(1,3)</userinput>
@@ -1898,32 +1894,29 @@ error: 'Iterator type is not supported'
<section xml:id="sp-box-fiber">
<title>Package <code>box.fiber</code></title>
- <para>Functions in this package allow you to create, run and
- manage existing <emphasis>fibers</emphasis>.
+ <para>Functions in this package allow for creating, running and
+ managing <emphasis>fibers</emphasis>.
</para>
<para>
-A fiber is an independent execution thread implemented
-using a mechanism of cooperative multitasking.
+A fiber is a set of instructions which are executed
+with cooperative multitasking. Fibers managed by the
+box.fiber library are associated with a user-supplied function
+called the <emphasis>fiber function</emphasis>.
A fiber has three possible states: running, suspended or dead.
-When a fiber is created with <code>box.fiber.create()</code>,
-it is suspended.
+When a fiber is created with <code>box.fiber.create()</code>, it is suspended.
When a fiber is started with <code>box.fiber.resume()</code>, it is running.
-When a fiber's control is yielded back to the caller with
-<code>box.fiber.yield()</code>, it is suspended.
-When a fiber ends (due to <code>return</code> or by reaching the
-end of the fiber function), it is dead.
+When a fiber yields control with <code>box.fiber.yield()</code>, it is suspended.
+When a fiber ends (because the fiber function ends), it is dead.
</para>
<para>
A fiber can also be attached or detached.
An attached fiber is a child of the creator,
and is running only if the creator has called
<code>box.fiber.resume()</code>. A detached fiber is a child of
-Tarantool internal <quote>sched</quote> fiber, and gets
+the Tarantool internal <quote>sched</quote> fiber, and gets
scheduled only if there is a libev event associated
with it.
- </para>
- <para>
To detach, a running fiber must invoke <code>box.fiber.detach()</code>.
A detached fiber loses connection with its parent forever.
</para>
@@ -1935,22 +1928,14 @@ which is a string. If there is more than one fiber with the given
name, the first fiber that matches is returned.
</para>
<para>
-Once fiber function is done or calls <code>return</code>,
-the fiber is considered dead. Its carcass is put into
-a fiber pool, and can be reused when another fiber is
-created.
- </para>
- <para>
A runaway fiber can be stopped with <code>box.fiber.cancel()</code>.
However, <code>box.fiber.cancel()</code> is advisory — it works
only if the runaway fiber calls <code>box.fiber.testcancel()</code>
once in a while. Most <code>box.*</code> hooks, such as <code>box.delete()</code>
or <code>box.update()</code>, do call <code>box.fiber.testcancel()</code>.
-<code>box.select()</code> doesn't.
- </para>
- <para>
+<code>box.select()</code> does not.
In practice, a runaway fiber can only become unresponsive
-if it does a lot of computations and doesn't check
+if it does many computations and does not check
whether it's been canceled.
<!--
In addition to the advisory cancellation, configuration parameter
@@ -1968,9 +1953,11 @@ sends an asynchronous wakeup event to the fiber,
and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs.
</para>
<para>Like all Lua objects, dead fibers are
- garbage collected: the garbage collector frees pool allocator
+ garbage collected. The garbage collector frees pool allocator
memory owned by the fiber, resets all fiber data, and returns
- the fiber to the fiber pool.</para>
+ the fiber (now called a fiber carcass) to the fiber pool.
+ The carcass can be reused when another fiber is created.
+ </para>
<variablelist xml:id="box.fiber">
<varlistentry>
<term>
@@ -1999,10 +1986,8 @@ and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs
<emphasis role="lua" xml:id="box.fiber.create">box.fiber.create(function) </emphasis>
</term>
<listitem><simpara>
- Create a fiber for a <code>function</code>.
+ Create a fiber for a <code>function</code>. There will be an error if the function does not exist or if a recursion limit is hit.
</simpara>
- <bridgehead renderas="sect4">Errors</bridgehead>
- <simpara>Can hit a recursion limit.</simpara>
</listitem>
</varlistentry>
@@ -2016,19 +2001,17 @@ and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs
<varlistentry>
<term>
- <emphasis role="lua" xml:id="box.fiber.yield" xreflabel="box.fiber.yield(...)">box.fiber.yield(...) </emphasis>
+ <emphasis role="lua" xml:id="box.fiber.yield" xreflabel="box.fiber.yield([arguments])">box.fiber.yield(...) </emphasis>
</term>
- <listitem><para>
- Yield control to the calling fiber, if the fiber
- is attached, or to sched otherwise.
- </para>
- <para>
- If the fiber is attached, whatever arguments are passed
- to this call, are passed on to the calling fiber.
+ <listitem><simpara>
+ If the fiber is attached, yield control to the calling fiber if the fiber
+ is attached; otherwise, yield to sched.
+ If the fiber is attached, arguments passed
+ to box.fiber.yield are passed on to the calling fiber.
If the fiber is detached, <code>box.fiber.yield()</code>
- returns back everything passed into it after temporarily
+ arguments passed to box.fiber.yield are returned after temporarily
yielding control back to the scheduler.
- </para></listitem>
+ </simpara></listitem>
</varlistentry>
<varlistentry>
@@ -2067,11 +2050,11 @@ and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs
<emphasis role="lua" xml:id="box.fiber.status">box.fiber.status(fiber)</emphasis>
</term>
<listitem><simpara>
- Returns the status of the fiber. If no argument is
- provided, the current fiber's status is returned. The
- status can be either <quote>dead</quote>,
- <quote>suspended</quote>, <quote>attached</quote>
- or <quote>running</quote>.
+ Returns the status of <code>fiber</code>. If no argument is
+ provided, the current fiber's status is returned. The
+ status can be one of: <quote>dead</quote>,
+ <quote>suspended</quote>, <quote>attached</quote>
+ or <quote>running</quote>.
</simpara></listitem>
</varlistentry>
@@ -2096,74 +2079,138 @@ and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs
</simpara></listitem>
</varlistentry>
</variablelist>
+
+<para>
+<bridgehead renderas="sect4">Example</bridgehead>
+Make the function which will be associated with the fiber.
+When this function gets invoked, it will immediately "detach"
+so it will be running independently of the caller, and then
+will enter an infinite loop ("while 0 == 0" is an infinite
+loop). Each iteration of the loop adds 1 to a global variable
+named gvar, then goes to sleep for 2 seconds,
+then yields. The sleep causes an implicit box.fiber.yield().<programlisting>
+<prompt>localhost></prompt><userinput> setopt delimiter = '!'</userinput>
+<prompt>localhost></prompt><userinput> lua function function_x ()</userinput>
+<prompt> -></prompt><userinput> box.fiber.detach()</userinput>
+<prompt> -></prompt><userinput> gvar = 0</userinput>
+<prompt> -></prompt><userinput> while 0 == 0 do</userinput>
+<prompt> -></prompt><userinput> gvar = gvar + 1</userinput>
+<prompt> -></prompt><userinput> box.fiber.sleep(2)</userinput>
+<prompt> -></prompt><userinput> end</userinput>
+<prompt> -></prompt><userinput> end!</userinput>
+---
+...
+<prompt>localhost></prompt><userinput> setopt delimiter = ''!</userinput></programlisting>
+Make the fiber and associate the function with it.
+ Get the id of the fiber (fid), to be used in later displays.<programlisting>
+<prompt>localhost></prompt><userinput> lua fiber_of_x = box.fiber.create(function_x)</userinput>
+---
+...
+<prompt>localhost></prompt><userinput> lua fid = box.fiber.id(fiber_of_x)</userinput>
+---
+...</programlisting>
+"Resume" the fiber. This causes invocation of the function.<programlisting>
+<prompt>localhost></prompt><userinput> lua box.fiber.resume(fiber_of_x)</userinput>
+---
+...</programlisting>
+Pause for a while, while the detached function runs. Then ...
+Display the fiber id, the fiber status, and gvar (gvar will have
+gone up a bit depending how long the pause lasted). The status is
+suspended because the fiber spends almost all its time sleeping or yielding.<programlisting>
+<prompt>localhost></prompt><userinput> lua print("fiber=",fid,". ",box.fiber.status(fiber_of_x),". gvar=",gvar)</userinput>
+---
+fiber=104. suspended. gvar=9
+...</programlisting>
+Pause for a while, while the detached function runs. Then ...
+Cancel the fiber. Then, once again ...
+Display the fiber id, the fiber status, and gvar (gvar will have
+gone up a bit more depending how long pause lasted). This time
+the status is dead because the cancel worked.<programlisting>
+<prompt>localhost></prompt><userinput> lua box.fiber.cancel(fiber_of_x)</userinput>
+---
+...
+<prompt>localhost></prompt><userinput> lua print("fiber=",fid,". ",box.fiber.status(fiber_of_x),". gvar=",gvar)</userinput>
+---
+fiber=104. dead. gvar=22
+...</programlisting>
+</para>
+
</section>
<!-- end of lib -->
<section xml:id="sp-box-session">
<title>Package <code>box.session</code></title>
- <para>Learn session state, set on-connect and
- on-disconnect triggers.
- </para>
<para>
-A session is an object associated with each client connection.
-Through this module, it's possible to query session state,
-as well as set a Lua chunk executed on a connect or disconnect
-event.
+ Query session state, write to a session-specific temporary
+ record, or set up triggers which will fire when a session
+ starts or ends. A <emphasis>session</emphasis> is an object associated with each client connection.
</para>
<variablelist>
<varlistentry>
<term>
<emphasis role="lua">box.session.id() </emphasis>
</term>
- <listitem><simpara>Return a unique monotonic identifier of
- the current session. The identifier can be used to check
- whether or not a session is alive. 0 means there is no
- session (e.g. a procedure is running in a detached
- fiber).
+ <listitem><simpara>Return the unique numeric identifier
+ (ID) for the current session. The result can be 0 meaning
+ there is no session (for example because a function is
+ running in a detached fiber).
</simpara></listitem>
</varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.fd(id) </emphasis>
- </term>
- <listitem><simpara>Return an integer file descriptor
- associated with the connected client.</simpara></listitem>
- </varlistentry>
-
<varlistentry>
<term>
<emphasis role="lua">box.session.exists(id) </emphasis>
</term>
- <listitem><simpara>Return true if a session is alive,
- false otherwise.</simpara></listitem>
+ <listitem><simpara>If the specified session exists, return true (1).
+ otherwise return false (0).</simpara></listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="lua">box.session.peer(id) </emphasis>
</term>
- <listitem><simpara>Return the host address and port for the session
- peer, for example "127.0.0.1:55457", or "0.0.0.0:0" if the session
- is not connected.</simpara></listitem>
+ <listitem><simpara>If the specified session exists, return the host
+ address and port of the session peer, for example "127.0.0.1:55457".
+ Otherwise return "0.0.0.0:0". The command is executed on the server,
+ so the "local name" is the server's host and administrative port,
+ and the "peer name" is the client's host and port.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="lua">box.session.storage</emphasis>
</term>
- <listitem><simpara>A virtual table that is local for each session.
- It can be used to store session-specific values. The lifetime is the
- same as the session's (until disconnect).
+ <listitem><simpara>A Lua table that can hold arbitrary
+ unordered session-specific names and values, which will last until
+ the session ends.
</simpara></listitem>
</varlistentry>
-
</variablelist>
+
+<para>
+<bridgehead renderas="sect4">Example</bridgehead><programlisting>
+<prompt>localhost></prompt><userinput> lua box.session.peer(box.session.id())</userinput>
+---
+ - 127.0.0.1:45129
+...
+<prompt>localhost></prompt><userinput> lua box.session.storage.random_memorandum = "Don't forget to buy eggs."</userinput>
+---
+...
+<prompt>localhost></prompt><userinput> lua box.session.storage.radius_of_mars = 3396</userinput>
+---
+...
+<prompt>localhost></prompt><userinput> lua for k,v in pairs(box.session.storage) do print(k,' ',v) end</userinput>
+---
+radius_of_mars 3396
+random_memorandum Don't forget to buy eggs.
+...</programlisting>
+</para>
+
<para>
-This module also makes it possible to define triggers on connect
-and disconnect events. Please see <olink targetptr="sp-box-session-triggers">
-the triggers chapter</olink> for details.
+See <olink targetptr="sp-box-session-triggers">the triggers chapter</olink>
+for instructions about defining triggers for connect and disconnect events
+ with <code>box.session.on_connect()</code> and <code>box.session.on_disconnect()</code>.
</para>
</section>
@@ -2171,6 +2218,19 @@ the triggers chapter</olink> for details.
<section xml:id="sp-box-ipc">
<title>Package <code>box.ipc</code> — inter procedure communication</title>
+ <para>
+ Send and receive messages between different procedures of a session.
+ </para>
+ <para>
+ Call <code>box.ipc.channel()</code> to allocate space and get a channel object, which will be
+ called <code>channel</code> for examples in this section.
+ Call the other box.ipc() routines, passing <code>channel</code>, to send messages, receive messages, or check ipc status.
+ Message exchange is synchronous.
+ The channel is garbage collected when no one is using it, as with any
+ other Lua object.
+ Object-oriented and functional APIs are equivalent, so <code>channel:put(message)</code>
+ is the same as <code>box.ipc.channel.put(channel, message)</code>.
+ </para>
<variablelist xml:id="box.ipc">
<simpara>
</simpara>
@@ -2178,19 +2238,11 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel(capacity)</emphasis></term>
<listitem>
<simpara>
- Create a new communication channel with
- predefined capacity. The channel can be used
- to synchronously exchange messages between
- stored procedures. The channel is garbage
- collected when no one is using it, just like any
- other Lua object. Channels can be worked with
- using functional or object-oriented syntax. For
- example, the following two lines are equivalent:
+ Create a new communication channel. The capacity should be
+ a positive integer as great as the maximum number of slots
+ (spaces for get or put or broadcast messages)
+ that might be pending at any given time.
</simpara>
-<programlisting>
- channel:put(message)
- box.ipc.channel.put(channel, message)
-</programlisting>
</listitem>
</varlistentry>
<varlistentry>
@@ -2198,12 +2250,12 @@ the triggers chapter</olink> for details.
<listitem>
<simpara>
Send a message using a channel. If the channel is full,
- <emphasis role="lua">box.ipc.channel.put()</emphasis>
+ <code>box.ipc.channel.put()</code>
blocks until there is a free slot in the channel.
- If <emphasis role="lua">timeout</emphasis> is provided,
+ If <code>timeout</code> is provided,
and the channel doesn't become empty for the duration
of the timeout,
- <emphasis role="lua">box.ipc.channel.put()</emphasis>
+ <code>box.ipc.channel.put()</code>
returns false. Otherwise it returns true.
</simpara>
</listitem>
@@ -2213,12 +2265,12 @@ the triggers chapter</olink> for details.
<listitem>
<simpara>
Fetch a message from a channel. If the channel is empty,
- <emphasis role="lua">box.ipc.channel.get()</emphasis>
+ <code>box.ipc.channel.get()</code>
blocks until there is a message.
- If <emphasis role="lua">timeout</emphasis> is provided,
+ If <code>timeout</code> is provided,
and there are no new messages for the duration
of the timeout,
- <emphasis role="lua">box.ipc.channel.get()</emphasis>
+ <code>box.ipc.channel.get()</code>
returns error.
</simpara>
</listitem>
@@ -2227,10 +2279,10 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel.broadcast(channel, message, timeout)</emphasis></term>
<listitem>
<simpara>
- If the channel is empty, is equivalent to
- <emphasis role="lua">box.ipc.channel.put()</emphasis>.
- Otherwise sends the message to all readers of the
- channel.
+ If the channel is empty, <code>box.ipc.channel.broadcast()</code> is equivalent to
+ <code>box.ipc.channel.put()</code>.
+ Otherwise, <code>box.ipc.channel.broadcast()</code> sends the message to all readers of the
+ channel.
</simpara>
</listitem>
</varlistentry>
@@ -2238,7 +2290,7 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel.is_empty(channel)</emphasis></term>
<listitem>
<simpara>
- Check if the channel is empty (has no messages).
+ Return true if the specified channel is empty (has no messages).
</simpara>
</listitem>
</varlistentry>
@@ -2246,7 +2298,7 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel.is_full(channel)</emphasis></term>
<listitem>
<simpara>
- Check if the channel is full (has no room for a new message).
+ Return true if the specified channel is full (has no room for a new message).
</simpara>
</listitem>
</varlistentry>
@@ -2254,8 +2306,10 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel.has_readers(channel)</emphasis></term>
<listitem>
<simpara>
- Check if the channel is empty and has readers waiting
- for a message.
+ Return true if the specified channel is empty and has readers waiting
+ for a message (because they have issued <code>box.ipc.channel.get()</code> and then
+ blocked).
+ Otherwise return false.
</simpara>
</listitem>
</varlistentry>
@@ -2263,9 +2317,14 @@ the triggers chapter</olink> for details.
<term><emphasis role="lua">box.ipc.channel.has_writers(channel)</emphasis></term>
<listitem>
<simpara>
- Check if the channel is full and has writers waiting
- for empty room.
+ Return true if the specified channel is full and has writers waiting
+ (because they have issued <code>box.ipc.channel.put()</code> and then blocked
+ due to lack of room). Otherwise return false.
</simpara>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
<bridgehead renderas="sect4">Example</bridgehead><programlisting>
local channel = box.ipc.channel(10)
function consumer_fiber()
@@ -2300,12 +2359,12 @@ function producer_fiber()
...
if channel:has_readers() then
- # there are some fibers that wait data
+ # there are some fibers that wait are waiting for data
end
...
if channel:has_writers() then
- # there are some fibers that wait readers
+ # there are some fibers that are waiting for readers
end
channel:put(task)
end
@@ -2323,9 +2382,7 @@ function producer2_fiber()
end
end
</programlisting>
- </listitem>
- </varlistentry>
-</variablelist>
+</para>
</section>
<!-- end of lib -->
@@ -2619,75 +2676,41 @@ end
<section xml:id="sp-box-net-box">
<title>Package <code>box.net.box</code> — working with networked Tarantool peers</title>
<simpara>
- Library <code>box.net</code> contains connectors
- to remote database systems, such as MariaDB or PostgreSQL.
- The first supported system is Tarantool itself.
+ The <code>box.net</code> library contains connectors to remote database systems.
+ One variant, <code>box.net.sql</code>, is for connecting to MySQL or MariaDB or PostgreSQL
+ — that variant is the subject of the <quote>SQL DBMS plugins</quote> appendix.
+ In this section the subject is the built-in variant, <code>box.net.box</code>.
+ This is for connecting to tarantool_box servers via a network.
</simpara>
<variablelist xml:id="box.net.box">
<simpara>
- The basic object provided by <code>box.net.box</code>
- library is a connection. A connection is created by
- calling <code>box.net.box.new()</code>. To
- execute remote requests, simply invoke methods of the
- connection object, a physical connection is established
- upon request and is re-established if necessary.
- When done, issue <code>conn:close()</code>. Connection
- objects are garbage collected just like any other objects
- in Lua, so an explicit destruction is not mandatory.
- However, since <code>close()</code> is a system call, it
- is a good programming practice to close a connection
- explicitly when it is no longer needed, to avoid lengthy
- stalls of the garbage collector.
- </simpara>
- <simpara>
- The library also provides a pre-created connection object
- to the local server, <code>box.net.self</code>. This
- connection is always <quote>established</quote>. The
- purpose of this object is to make polymorphic use of the
- <code>box.net.box</code> API easier. There is an
- important difference, however, between the embedded
- connection and a remote one. With the embedded connection,
- requests which do not modify data do not yield. When using
- a remote connection, it is important to keep in mind that
- any request can yield, and local database state may
- have changed by the time it returns.
+ Call <code>box.net.box.new()</code> to connect and get a connection object,
+ which will be called <code>conn</code> for examples in this section.
+ Call the other <code>box.net.box()</code> routines, passing <code>conn</code>,
+ to execute requests on the remote box.
+ Call <code>box.net.box.close(conn)</code> to disconnect.
+ Object-oriented and functional APIs are equivalent, so
+ <code>conn:close()</code> is the same as <code>box.net.box.close(conn)</code>.
</simpara>
+
<simpara>
- All <code>box.net.box</code> methods are fiber-safe. It's
+ All <code>box.net.box</code> methods are fiber-safe, that is, it is
safe to share and use the same connection object across
- multiple concurrent fibers. In fact, it's perhaps the
- best programming practice with Tarantool: when multiple
+ multiple concurrent fibers. In fact, it's perhaps the
+ best programming practice with Tarantool. When multiple
fibers use the same connection, all requests are pipelined
- through the same network socket, but each fiber gets a
- correct response back. Reducing the number of active sockets
+ through the same network socket, but each fiber gets back a
+ correct response. Reducing the number of active sockets
lowers the overhead of system calls and increases the
- overall server performance. There are, however cases, when
- a single connection is not enough: when it's necessary to
- prioritize requests, use different authentication ids,
- etc.
- </simpara>
- <simpara>
- All remote calls support execution timeouts. A specialized
- wrapper, <code>box.net.box.timeout()</code> allows setting
- a timeout. Using a wrapper object makes the remote
- connection API compatible with the local one, removing
- the need for a separate <code>timeout</code> argument, ignored
- by the local version. Once sent, a
- request can not be revoked from the remote server even if
- a timeout expires: the expired timeout only aborts the
- wait for the remote server response.
- <code>box.net.box.timeout()</code>,
- </simpara>
- <simpara>
- Object-oriented and functional APIs are equivalent:
- <code>conn:close()</code> is identical to
- <code>box.net.box.close(conn)</code>.
+ overall server performance. There are, however, cases when
+ a single connection is not enough — for example when it's necessary to
+ prioritize requests or to use different authentication ids.
</simpara>
<varlistentry>
<term>
<emphasis role="lua" xml:id="box.net.box.new">
- conn = box.net.box.new(host, port [, reconnect_interval])</emphasis>
+ conn = box.net.box.new(<replaceable>host</replaceable>, <replaceable>port</replaceable> [, <replaceable>reconnect_interval</replaceable>])</emphasis>
</term>
<listitem>
<para>
@@ -2697,155 +2720,220 @@ end
a disconnect. The argument
<code>reconnect_interval</code> (in seconds) is
responsible for the amount of time the server
- sleeps between failing attempts to reconnect. The
- returned object supports methods for making remote
- calls, such as select, update or delete.
+ sleeps between failing attempts to reconnect.
+ The returned <code>conn</code> object supports methods for making remote
+ requests, such as select, update or delete.
+ Example: <code>conn = box.net.box.new('localhost', 33013)</code>.
+ </para>
+ <para>
+ For the local tarantool_box server there is a pre-created always-established
+ connection object named <code>box.net.self</code>.
+ Its purpose is to make polymorphic use of the
+ <code>box.net.box</code> API easier. Therefore
+ <code>conn = box.net.box.new('localhost', 33013)</code> can
+ be replaced by <code>conn = box.net.box.self</code>.
+ However, there is an important difference between the embedded
+ connection and a remote one. With the embedded connection,
+ requests which do not modify data do not yield. When using
+ a remote connection, any request can yield, and local database state may
+ have changed by the time it returns.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="lua" xml:id="box.net.box.ping">
- conn:ping()</emphasis></term>
+ conn:ping()</emphasis></term>
<listitem>
<para>
Execute a PING command.
Returns <code>true</code> on success,
- <code>false</code> on error.
+ <code>false</code> on error. Example: <code>self:ping()</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="lua" xml:id="box.net.box.close">
- conn:close()</emphasis></term>
+ conn:close()</emphasis></term>
<listitem>
<para>
- Close a connection. The connection is also
- closed when it's garbage collected. It's still
- recommended to close connections explicitly,
- to spare the garbage collector from heavy work
- such as closing the socket.
+ Close a connection. Example: <code>conn:close()</code>.
+ </para>
+ <para>
+ Connection objects are garbage collected just like any other objects
+ in Lua, so an explicit destruction is not mandatory.
+ However, since <code>close()</code> is a system call, it
+ is good programming practice to close a connection
+ explicitly when it is no longer needed, to avoid lengthy
+ stalls of the garbage collector.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="lua" xml:id="box.net.box.select">
- conn:select(space_no, index_no, ...)</emphasis></term>
+ conn:select(<replaceable>space_no</replaceable>, <replaceable>index_no</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code
- xlink:href="#box.select">box.select(...)</code>.
- Please note, that unlike a local
- <code>box.select()</code> any call to a remote
- server yields, thus local data may change while
- remote <code>select()</code> is running.
+ <code>conn:select(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.select">box.select(...)</code>.
+ Please note this difference: a local <code>box.select()</code> does not yield,
+ but a remote <code>conn:select()</code> call does yield,
+ so local data may change while a remote <code>conn:select()</code> is running.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="lua" xml:id="box.net.box.select_limit">
- conn:select_limit(space_no, index_no, offset, limit, ...)</emphasis></term>
+ conn:select_limit(<replaceable>space_no</replaceable>, <replaceable>index_no</replaceable>, <replaceable>offset</replaceable>, <replaceable>limit</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code
- xlink:href="#box.select_limit">box.select_limit(...)</code>
+ <code>conn:select_limit(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.select_limit">box.select_limit(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="lua" xml:id="box.net.box.select_range">
- conn:select_range(space_no, index_no, limit, key, ...)</emphasis></term>
+ conn:select_range(<replaceable>space_no</replaceable>, <replaceable>index_no</replaceable>, <replaceable>limit</replaceable>, <replaceable>key</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code
- xlink:href="#box.select_range">box.select_range(...)</code>.
+ <code>conn:select_range(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.select_range">box.select_range(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.insert">conn:insert(space_no, ...)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.insert">
+ conn:insert(<replaceable>space_no</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code xlink:href="#box.insert">box.insert(...)</code>.
+ <code>conn:insert(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.insert">box.insert(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.replace">conn:replace(space_no, ...)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.replace">
+ conn:replace(<replaceable>space_no</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code xlink:href="#box.replace">box.replace(...)</code>.
+ <code>conn:replace(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.replace">box.replace(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.update">conn:update(...)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.update">
+ conn:update(<replaceable>space_no</replaceable>, <replaceable>key</replaceable>, <replaceable>format</replaceable>, ...)</emphasis></term>
<listitem>
<para>
- See <code
- xlink:href="#box.update">box.update(...)</code>.
+ <code>conn:update(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.update">box.update(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.delete">conn:delete(space_no, key)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.delete">
+ conn:delete(<replaceable>space_no</replaceable>, <replaceable>key</replaceable>)</emphasis></term>
<listitem>
<para>
- See <code xlink:href="#box.delete">box.delete(...)</code>.
+ <code>conn:delete(...)</code> is the remote-call equivalent of the local call <code xlink:href="#box.delete">box.delete(...)</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.call">conn:call(proc_name, ...)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.call">
+ conn:call(<replaceable>proc_name</replaceable> [, <replaceable>arguments</replaceable>])</emphasis></term>
<listitem>
- <para>Call a remote stored procedure, such as
- <code>box.select_reverse_range()</code>.
+ <para>
+ <code>conn:call('proc','1','2','3')</code> is the remote-call equivalent of <code>CALL proc('1','2','3')</code>.
+ That is, box.net.box.call is a remote stored-procedure call.
Please keep in mind that the call is using
the binary protocol to pack procedure arguments,
- and since the latter is type-agnostic it's recommended
- to pass all arguments of remote stored procedure as
- strings, for example:
-<programlisting>
- conn:call("box.select_reverse_range", "1", "4", "10", "Smith")
-</programlisting>
+ and the binary protocol is type agnostic, so it's recommended
+ to pass all arguments of remote stored procedure calls as
+ strings. Example: <code>conn:call("box.select_reverse_range", "1", "4", "10", "Smith")</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="lua" xml:id="box.net.box.timeout">conn:timeout(timeout)</emphasis></term>
+ <term><emphasis role="lua" xml:id="box.net.box.timeout">
+ conn:timeout(<replaceable>timeout</replaceable>)</emphasis></term>
<listitem>
<para>
- Returns a closure which is identical to the
- invoked function, except for the added timeout
- functionality.
-<programlisting>
--- wait for 'update' until it is finished
-local tuple = conn:update('1', 'key', ...)
-
--- send update but don't bother to wait for results
-local other = conn:timeout(0):update('1', 'arg1', ...)
-</programlisting>
- </para>
+ <code>timeout(...)</code> is a wrapper which sets a timeout for the request that follows it.
+ Example: <code>conn:timeout(0):update('1', 'arg1', 15)</code>.
+ </para>
+ <para>
+ All remote calls support execution timeouts.
+ Using a wrapper object makes the remote
+ connection API compatible with the local one, removing
+ the need for a separate <code>timeout</code> argument, which
+ the local version would ignore. Once a request is sent,
+ it cannot be revoked from the remote server even if
+ a timeout expires: the timeout expiration only aborts the
+ wait for the remote server response, not the request itself.
+ </para>
</listitem>
</varlistentry>
</variablelist>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>
--- connect to the local server
-local self = box.net.box.new('127.0.0.1', box.info.primary_port)
-self:insert("1", "Hello", "World")
+ <bridgehead renderas="sect4">Example showing use of most of the box.net.box methods</bridgehead>
+ <para>
+ This example will work with the sandbox configuration described in the preface.
+ That is, there is a space[0] with a numeric primary key.
+ Assume that the database is nearly empty.
+ Assume that the tarantool_box server is running on localhost 127.0.0.1:33013.
+<programlisting><prompt>localhost></prompt> <userinput> setopt delimiter = '!'</userinput>
+<prompt>localhost></prompt> <userinput> lua function example()</userinput>
+<prompt> -></prompt> <userinput> if self:ping() then</userinput>
+<prompt> -></prompt> <userinput> print("self:ping() succeeded (not surprising since self is a pre-established connection).")</userinput>
+<prompt> -></prompt> <userinput> end</userinput>
+<prompt> -></prompt> <userinput> if box.cfg.primary_port == 33013 then</userinput>
+<prompt> -></prompt> <userinput> print('The local server primary port number is 33013 (the default)')</userinput>
+<prompt> -></prompt> <userinput> else</userinput>
+<prompt> -></prompt> <userinput> print('The local server primary port number is not 33013, so connect will fail')</userinput>
+<prompt> -></prompt> <userinput> end</userinput>
+<prompt> -></prompt> <userinput> conn = box.net.box.new('127.0.0.1', 33013)</userinput>
+<prompt> -></prompt> <userinput> conn:delete(0,800)</userinput>
+<prompt> -></prompt> <userinput> print('conn:delete done on space[0].')</userinput>
+<prompt> -></prompt> <userinput> conn:insert(0,800,'data')</userinput>
+<prompt> -></prompt> <userinput> print('conn:insert done on space[0], index 0. primary key value = 800.')</userinput>
+<prompt> -></prompt> <userinput> wtuple = conn:select(0,0,800)</userinput>
+<prompt> -></prompt> <userinput> print('conn:select done on space[0], index 0. number of fields = ', #wtuple)</userinput>
+<prompt> -></prompt> <userinput> conn:delete(0,800)</userinput>
+<prompt> -></prompt> <userinput> print('conn:delete done on space[0].')</userinput>
+<prompt> -></prompt> <userinput> conn:replace(0,800,'New data','Extra data')</userinput>
+<prompt> -></prompt> <userinput> print('conn:replace done on space[0].')</userinput>
+<prompt> -></prompt> <userinput> conn:timeout(0):update(0,800,'=p=p=p',1, 'Field#1', 2,'Field#2', 3,'Field#3')</userinput>
+<prompt> -></prompt> <userinput> print('conn:update done on space[0], timed out after waiting 0 seconds for a return')</userinput>
+<prompt> -></prompt> <userinput> conn:close()</userinput>
+<prompt> -></prompt> <userinput> print('conn:close done')</userinput>
+<prompt> -></prompt> <userinput> end!</userinput>
+---
+...
+<prompt>localhost></prompt> <userinput> setopt delimiter = ''!</userinput>
+<prompt>localhost></prompt> <userinput> lua example()</userinput>
+---
+self:ping() succeeded (not surprising since self is a pre-established connection).
+The local server primary port number is 33013 (the default)
+conn:delete done on space[0].
+conn:insert done on space[0], index 0. primary key value = 800.
+conn:select done on space[0], index 0. number of fields = 2
+conn:delete done on space[0].
+conn:replace done on space[0].
+conn:update done on space[0], timed out after waiting 0 seconds for a return
+conn:close done
+...
+<prompt>localhost></prompt> <userinput> select * from t0 where k0 = 800 # Prove that the update succeeded.</userinput>
+Select OK, 1 rows affected
+[800, 'Field#1', 'Field#2', 'Field#3']
</programlisting>
+</para>
</section>
<section xml:id="sp-box-cfg">
diff --git a/doc/user/tutorial.xml b/doc/user/tutorial.xml
index 755c089b96c81756d3bf0c1b29a04c2927659445..abf6a265da1e4e96125cab731e88f807425eb055 100644
--- a/doc/user/tutorial.xml
+++ b/doc/user/tutorial.xml
@@ -392,6 +392,12 @@ These example scripts assume that the intent is to download from the master bran
the server and the client (but not the documentation), and run tests after build.
</para>
+<para>
+To build with SUSE 13.1, the steps are as described above, except that the appropriate YaST2 package names are:
+binutils-devel, libuuid-devel, cmake, ncurses-devel, lynx, jing, libxml2-devel, docbook_5, saxon, libxslt-devel.
+The python connector can be installed with <code>sudo easy_install pip</code> and <code>sudo pip install tarantool</code>.
+</para>
+
</section>
<section xml:id="getting-started-start-stop">
<title>Starting Tarantool and making your first database</title>
diff --git a/doc/user/user.xml b/doc/user/user.xml
index 131068aab3fb7b93fe84dcb4bd75ed4fc3b73463..05ba8bd1ab0e7622ea0fd966fddb115477042c1a 100644
--- a/doc/user/user.xml
+++ b/doc/user/user.xml
@@ -19,7 +19,6 @@
<xi:include href="proctitle.xml"/>
<xi:include href="errcode.xml"/>
<xi:include href="limitations.xml"/>
-<xi:include href="client-reference.xml"/>
<xi:include href="lua-tutorial.xml"/>
<xi:include href="plugins.xml"/>
<!--