Author: jstephens
Date: 2006-06-25 12:06:50 +0200 (Sun, 25 Jun 2006)
New Revision: 2498
Log:
Renaming chapter file to match ID, fixing xinclude in main file to match.
Added:
trunk/ndbapi/getting-started.xml
Copied: trunk/ndbapi/getting-started.xml (from rev 2496, trunk/ndbapi/tips-tricks-problems.xml)
===================================================================
--- trunk/ndbapi/getting-started.xml (rev 0)
+++ trunk/ndbapi/getting-started.xml 2006-06-25 10:06:50 UTC (rev 2498)
@@ -0,0 +1,784 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % ndb.entities SYSTEM "ndb.en.ent">
+ %ndb.entities;
+]>
+<!--
+ <chapter id="tips-tricks-problems">
+
+ <title>TIPS, TRICKS, AND COMMON PROBLEMS</title>
+
+ <abstract>
+
+ <para></para>
+
+ </abstract>
+-->
+<chapter id="getting-started">
+
+ <title>GETTING STARTED WITH THE <literal>NDB</literal> API</title>
+
+ <abstract>
+
+ <para>
+ This chapter discusses preparations for writing an
+ <literal>NDB</literal> API application.
+ </para>
+
+ </abstract>
+
+ <section id="getting-started-compiling">
+
+ <title>Compiling and Linking <literal>NDB</literal> API Programs</title>
+
+ <abstract>
+
+ <para>
+ This section provides information on compiling and linking
+ <literal>NDB</literal> API applications, ioncluding requirements
+ and compiler and linker options.
+ </para>
+
+ </abstract>
+
+ <section id="getting-started-requirements">
+
+ <title>General Requirements</title>
+
+ <para>
+ To use the <literal>NDB</literal> API with MySQL, you must have
+ the <literal>NDB</literal> client library and its header files
+ installed alongside the regular MySQL client libraries and
+ headers. These are automatically installed when you build MySQL
+ using the <option>--with-ndbcluster</option>
+ <command>configure</command> option or when using a MySQL binary
+ package that supports the <literal>NDBCluster</literal> storage
+ engine.
+ </para>
+
+ <note>
+ <para>
+ MySQL 4.1 does not install the required
+ <literal>NDB</literal>-specific header files. You should use
+ MySQL 5.0 or later when writing <literal>NDB</literal> API
+ applications, and this Guide is targeted for use with MySQL
+ 5.1.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="getting-started-compiler-options">
+
+ <title>Compiler Options</title>
+
+ <formalpara>
+
+ <title>Header Files</title>
+
+ <para>
+ In order to compile source files that use the
+ <literal>NDB</literal> API, you must ensure that the necessary
+ header files can be found. Header files specific to the
+ <literal>NDB</literal> API are installed in the follwoing
+ subdirectories of the MySQL <filename>include</filename>
+ directory:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <filename>include/mysql/storage/ndb/ndbapi</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>include/mysql/storage/ndb/mgmapi</filename>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Compiler Flags</title>
+
+ <para>
+ The MySQL-specific compiler flags needed can be determined
+ using the <command>mysql_config</command> utility that is part
+ of the MySQL installation:
+
+<programlisting>
+$ mysql_config --cflags
+-I/usr/local/mysql/include/mysql -Wreturn-type -Wtrigraphs -W -Wformat
+-Wsign-compare -Wunused -mcpu=pentium4 -march=pentium4
+</programlisting>
+
+ This sets the include path for the MySQL header files but not
+ for those specific to the <literal>NDB</literal> API. The
+ <option>--include</option> option to
+ <command>mysql_config</command> returns the generic include
+ path switch:
+
+<programlisting>
+shell> mysql_config --include
+-I/usr/local/mysql/include/mysql
+</programlisting>
+
+ It is necessary to add the subdirectory paths explicitly, so
+ that adding all the needed compile flags to the
+ <literal>CXXFLAGS</literal> shell variable should look
+ something like this:
+
+<programlisting>
+CFLAGS="$CFLAGS "`mysql_config --cflags`
+CFLAGS="$CFLAGS "`mysql_config --include`storage/ndb
+CFLAGS="$CFLAGS "`mysql_config --include`storage/ndb/ndbapi
+CFLAGS="$CFLAGS "`mysql_config --include`storage/ndb/mgmapi
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <tip>
+ <para>
+ If you do not intend to use the Cluster management functions,
+ the last line in the previous example can be omitted. However,
+ if you are interested in the management functions only, and do
+ not want or need to access Cluster data except from MySQL,
+ then you can omit the line referencing the
+ <filename>ndbapi</filename> directory.
+ </para>
+ </tip>
+
+ </section>
+
+ <section id="getting-started-linker-options">
+
+ <title>Linker Options</title>
+
+ <para>
+ <literal>NDB</literal> API applications must be linked against
+ both the MySQL and <literal>NDB</literal> client libraries. The
+ <literal>NDB</literal> client library also requires some
+ functions from the <literal>mystrings</literal> library, so this
+ must belinked in as well.
+ </para>
+
+ <para>
+ The necessary linker flags for the MySQL client library are
+ returned by <command>mysql_config
+ <option>--libs</option></command>. For multithreaded
+ applications you should use the <option>--libs_r</option>
+ instead:
+
+<programlisting>
+$ mysql_config --libs_r
+-L/usr/local/mysql-5.1/lib/mysql -lmysqlclient_r -lz -lpthread -lcrypt
+-lnsl -lm -lpthread -L/usr/lib -lssl -lcrypto
+</programlisting>
+ </para>
+
+ <para>
+ To link a NdbAPI application you have to add
+ <option>-lndbclient</option> and <option>-lmystrings</option> to
+ these options. Adding all the required linker flags to the
+ <literal>LDFLAGS</literal> variable should look something like
+ this:
+
+<programlisting>
+LDFLAGS="$LDFLAGS "`mysql_config --libs_r`
+LDFLAGS="$LDFLAGS -lndbclient -lmystrings"
+</programlisting>
+ </para>
+
+ </section>
+
+ <section id="getting-started-autotools">
+
+ <title>Using Autotools</title>
+
+ <para>
+ It is often faster and simpler to use GNU autotools than to
+ write your own makefiles. In this section, we provide an
+ autoconf macro <literal>WITH_MYSQL</literal> that can be used to
+ add a <option>--with-mysql</option> option to a configure file,
+ and that automatically sets the correct compiler and linker
+ flags for given MySQL installation.
+ </para>
+
+ <para>
+ All of the examples in this chapter include a common
+ <filename>mysql.m4</filename> file defining
+ <literal>WITH_MYSQL</literal>. A typical complete example
+ consists of the actual source file and the the following helper
+ files:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <filename>acinclude</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>configure.in</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>Makefile.m4</filename>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <command>automake</command> also requires that you provide
+ <filename>README</filename>, <filename>NEWS</filename>,
+ <filename>AUTHORS</filename>, and <filename>ChangeLog</filename>
+ files; however, these can be left empty.
+ </para>
+
+ <para>
+ To create all necessary build files, run the following:
+
+<programlisting>
+aclocal
+autoconf
+automake -a -c
+configure --with-mysql=/mysql/prefix/path
+</programlisting>
+
+ Normally, this needs to be done only once, after which
+ <command>make</command> will accomodate any file changes.
+ </para>
+
+ <formalpara>
+
+ <title>Example 1-1: <filename>acinclude.m4</filename></title>
+
+ <para>
+<programlisting>
+m4_include([../mysql.m4])
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example 1-2: <filename>configure.in</filename></title>
+
+ <para>
+<programlisting>
+AC_INIT(example, 1.0)
+AM_INIT_AUTOMAKE(example, 1.0)
+WITH_MYSQL()
+AC_OUTPUT(Makefile)
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example 1-3: <filename>Makefile.am</filename></title>
+
+ <para>
+<programlisting>
+bin_PROGRAMS = example
+example_SOURCES = example.cc
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example 1-4: <literal>WITH_MYSQL</literal> source for inclusion in
+ <filename>acinclude.m4</filename></title>
+
+ <para>
+<programlisting>
+dnl
+dnl configure.in helper macros
+dnl
+
+AC_DEFUN([WITH_MYSQL], [
+ AC_MSG_CHECKING(for mysql_config executable)
+
+ AC_ARG_WITH(mysql, [ --with-mysql=PATH path to mysql_config binary or mysql prefix dir], [
+ if test -x $withval -a -f $withval
+ then
+ MYSQL_CONFIG=$withval
+ elif test -x $withval/bin/mysql_config -a -f $withval/bin/mysql_config
+ then
+ MYSQL_CONFIG=$withval/bin/mysql_config
+ fi
+ ], [
+ if test -x /usr/local/mysql/bin/mysql_config -a -f /usr/local/mysql/bin/mysql_config
+ then
+ MYSQL_CONFIG=/usr/local/mysql/bin/mysql_config
+ elif test -x /usr/bin/mysql_config -a -f /usr/bin/mysql_config
+ then
+ MYSQL_CONFIG=/usr/bin/mysql_config
+ fi
+ ])
+
+ if test "x$MYSQL_CONFIG" = "x"
+ then
+ AC_MSG_RESULT(not found)
+ exit 3
+ else
+ AC_PROG_CC
+ AC_PROG_CXX
+
+ # add regular MySQL C flags
+ ADDFLAGS=`$MYSQL_CONFIG --cflags`
+ # add NdbAPI specific C flags
+ IBASE=`$MYSQL_CONFIG --include`
+ ADDFLAGS="$ADDFLAGS $IBASE/ndb"
+ ADDFLAGS="$ADDFLAGS $IBASE/ndb/ndbapi"
+ ADDFLAGS="$ADDFLAGS $IBASE/ndb/mgmapi"
+
+ CFLAGS="$CFLAGS $ADDFLAGS"
+ CXXFLAGS="$CXXFLAGS $ADDFLAGS"
+
+ LDFLAGS="$LDFLAGS "`$MYSQL_CONFIG --libs_r`" -lndbclient -lmystrings"
+
+ AC_MSG_RESULT($MYSQL_CONFIG)
+ fi
+
+
+])
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ </section>
+
+ <section id="getting-started-connecting">
+
+ <title>Connecting to the Cluster</title>
+
+ <abstract>
+
+ <para>
+ This section covers connecting an <literal>NDB</literal> API
+ application to a MySQL CLuster.
+ </para>
+
+ </abstract>
+
+ <section id="getting-started-include-files">
+
+ <title>Include Files</title>
+
+ <para>
+ <literal>NDB</literal> API applications require one or more of
+ the following include files:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Applications accessing Cluster data via the
+ <literal>NDB</literal> API must include the file
+ <filename>NdbApi.hpp</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Applications making use of both the <literal>NDB</literal>
+ API and the regular MySQL client API also need to include
+ <filename>mysql.h</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Applications that use cluster management functions need
+ the include file <filename>mgmapi.h</filename>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </section>
+
+ <section id="getting-started-initialisation">
+
+ <title>API Initialisation and Cleanup</title>
+
+ <para>
+ Before using the <literal>NDB</literal> API, it must first be
+ initialised by calling the <literal>ndb_init()</literal>
+ function. Once an <literal>NDB</literal> API application is
+ complete, call <literal>ndb_end(0)</literal> to perform a
+ cleanup.
+ </para>
+
+ </section>
+
+ <section id="getting-started-establishing-connection">
+
+ <title>Establishing the Connection</title>
+
+ <para>
+ To establish a connection to the server, it is necessary to
+ create an instance of <literal>Ndb_cluster_connection</literal>,
+ whose constructor takes as its argument a cluster connectstring;
+ if no connectstring is given, <literal>localhost</literal> is
+ assumed.
+ </para>
+
+ <para>
+ The cluster connection is not actually initiated until the
+ <literal>Ndb_cluster_connection::connect()</literal> method is
+ called. When invoked without any arguments, the connection
+ attempt is retried each 1 second indefinitely until successful,
+ and no reporting is done. See
+ <xref linkend="class-ndb-cluster-connection"/>, for details.
+ </para>
+
+ <para>
+ By default an API node will connect to the
+ <quote>nearest</quote> data node — usually a data node
+ running on the same machine, due to the fact that shared memory
+ transport can be used instead of the slower TCP/IP. This may
+ lead to poor load distribution in some cases, so it is possible
+ to enforce a round-robin node connection scheme by calling the
+ <literal>set_optimized_node_selection()</literal> method with
+ <literal>0</literal> as its argument prior to calling
+ <literal>connect()</literal>. (See
+ <xref linkend="class-ndb-cluster-connection-set-optimized-node-selection"/>.)
+ </para>
+
+ <para>
+ The <literal>connect()</literal> method initiates a connection
+ to a cluster management node only — it does not wait for
+ any connections to data nodes to be made. This can be
+ accomplished by using <literal>wait_until_ready()</literal>
+ after calling <literal>connect()</literal>. The
+ <literal>wait_until_ready()</literal> method waits up to a given
+ number of seconds for a connection to a data node to be
+ established.
+ </para>
+
+ <para>
+ In the following example, initialisation and connection are
+ handled in the two functions <literal>example_init()</literal>
+ and <literal>example_end()</literal>, which will be included in
+ subsequent examples via the file
+ <filename>example_connection.h</filename>.
+ </para>
+
+ <formalpara>
+
+ <title>Example 2-1: Connection example</title>
+
+ <para>
+<programlisting>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <NdbApi.hpp>
+
+#define CONNECTSTR "localhost"
+
+Ndb_cluster_connection* example_init()
+{
+ Ndb_cluster_connection* conn;
+
+ // initialize MySQL and Ndb client libraries
+ if( ndb_init() )
+ {
+ exit(EXIT_FAILURE);
+ }
+
+ // prepare connection to cluster
+ conn = new Ndb_cluster_connection(CONNECTSTR);
+
+ // initiate connection
+ if( conn->connect(4, 5, 1) )
+ {
+ fprintf(stderr, "Unable to connect to cluster within 30 seconds.");
+ exit(EXIT_FAILURE);
+ }
+
+ // wait for data (ndbd) nodes
+ if(conn->wait_until_ready(30, 0) < 0)
+ {
+ fprintf(stderr, "Cluster was not ready within 30 seconds.\n");
+ exit(EXIT_FAILURE);
+ }
+
+ return conn;
+}
+
+void example_end(Ndb_cluster_connection conn)
+{
+ // terminate connection
+ delete conn;
+
+ // shut down MySQL and Ndb client libraries
+ ndb_end(2);
+}
+
+
+int main(int argc, char** argv)
+{
+ Ndb_cluster_connection* conn;
+
+ conn = example_connect();
+
+ printf("Connection established.");
+
+ example_end(conn);
+
+ return EXIT_SUCCESS;
+}
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ </section>
+
+
+ <section id="getting-started-mysql-ndb-mapping">
+ <title>Mapping MySQL Database Object Names and Types to <literal>NDB</literal></title>
+
+ <abstract>
+ <para>
+ This section discusses NDB naming and other conventions
+ with regard to database objects.
+ </para>
+ </abstract>
+
+ <formalpara>
+ <title>Databases and Schemas</title>
+ <para>
+ Databases and schemas are not represented by objects as
+ such in the <literal>NDB</literal> API. Instead, they are
+ modeled as attributes of <literal>Table</literal> and
+ <literal>Index</literal> objects. The value of the
+ <literal>database</literal> attribute of one of these
+ objects is always the same as the name of the MySQL
+ database to which the table or index belongs. The value of
+ the <literal>schema</literal> attribute of a
+ <literal>Table</literal> or <literal>Index</literal>
+ object is always '<literal>def</literal>' (for
+ <quote>default</quote>).
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Tables</title>
+ <para>
+ MySQL table names are directly mapped to
+ <literal>NDB</literal> table names without modification.
+ Table names starting with '<literal>NDB$</literal>'
+ are reserved for internal use>, as is the
+ <literal>SYSTAB_0</literal> table in the
+ <literal>sys</literal> database.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+ <title>Indexes</title>
+ <para>There are two different type of NDB indexes:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <firstterm>Hash indexes</firstterm> are unique, but
+ not ordered.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <firstterm>B-tree indexes</firstterm> are ordered,
+ but allow duplicate values.
+ </para>
+ </listitem>
+ </itemizedlist>
+ Names of unique indexes and primary keys are handled as
+ follows:
+ <itemizedlist>
+ <listitem>
+ <para>
+ For a MySQL <literal>UNIQUE</literal> index, both a
+ BTree and a hash index are created. The B-tree
+ index uses the MySQL name for the index; the name
+ for the hash index is generated by appending
+ '<literal>$unique</literal>' to the index name.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For a MySQL primary key only a B-tree index is
+ created. This index is given the name
+ <literal>PRIMARY</literal>. There is no extra hash;
+ however, the uniquneess of the primary key is
+ guaranteed by making the MySQL key the internal
+ primary key of the <literal>NDB</literal> table.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Column Names and Values</title>
+ <para>
+ <literal>NDB</literal> column names are the same as their MySQL names.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Datatypes</title>
+ <para>
+ MySQL datatypes are stored in <literal>NDB</literal>
+ columns as follows:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The MySQL <literal>TINYINT</literal>,
+ <literal>SMALLINT</literal>, <literal>INT</literal>,
+ and <literal>BIGINT</literal> datatypes map to
+ <literal>NDB</literal> types having the same names
+ and storage requirements as their MySQL
+ counterparts.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The MySQL <literal>FLOAT</literal> and
+ <literal>DOUBLE</literal> datatypes are mapped to
+ <literal>NDB</literal> types having the same names
+ and storage requirements.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The storage space required for a MySQL
+ <literal>CHAR</literal> column is determined by the
+ maximum number of characters and the column's
+ character set. For most (but not all) character
+ sets, each character takes one byte of storage. When
+ using UTF-8, each character requires three bytes.
+ You can find the number of bytes needed per
+ character in a given character set by checking the
+ <literal>Maxlen</literal> column in the output of
+ <literal>SHOW CHARACTER SET</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In MySQL 5.1, the storage requirements for a
+ <literal>VARCHAR</literal> column depend on whether
+ the column is stored in memory or on disk:
+ <itemizedlist>
+ <listitem>
+ <para>
+ For in-memory columns,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For Disk Data columns,
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+
+ </section>
+
+
+
+
+<!--
+ <section id="getting-started-reading-data">
+ <title></title>
+
+ <section id="getting-started-beginning-transaction">
+ <title></title>
+ </section>
+
+ <section id="getting-started-preparing-read">
+ <title></title>
+ </section>
+
+ <section id="getting-started-performing-read">
+ <title></title>
+ </section>
+
+ <section id="getting-started-fetching-results">
+ <title></title>
+ </section>
+
+
+ </section>
+-->
+
+<!--
+ <section id="tips-tricks-common-problems">
+
+ <title>Common Problems</title>
+
+ <abstract>
+
+ <para>
+ Discusses some of the issues most often encountered when trying
+ to develop new NDB API applications, and offers possible
+ solutions to these.
+ </para>
+
+ </abstract>
+
+ </section>
+
+ <section id="tips-tricks">
+
+ <title>Tips & Tricks</title>
+
+ <abstract>
+
+ <para>
+ Performing common tasks using the NDB API classes; optimising
+ NDB API code.
+ </para>
+
+ </abstract>
+
+ </section>
+-->
+
+</chapter>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2498 - trunk/ndbapi | jon | 25 Jun |
