Author: jstephens
Date: 2006-07-02 08:25:13 +0200 (Sun, 02 Jul 2006)
New Revision: 2585
Log:
Added NdbError struct & types descriptions
Updated Makefile
Tweaks in template, .ent files
Modified:
trunk/ndbapi/Makefile
trunk/ndbapi/class-template.xml
trunk/ndbapi/errors.xml
trunk/ndbapi/ndb.en.ent
Modified: trunk/ndbapi/Makefile
===================================================================
--- trunk/ndbapi/Makefile 2006-07-02 06:22:22 UTC (rev 2584)
+++ trunk/ndbapi/Makefile 2006-07-02 06:25:13 UTC (rev 2585)
@@ -31,7 +31,7 @@
NDBAPI_SRCS_EXTRA = ndb.en.ent
-NDBAPI_SRCS = $(NDBAPI_SRCS_EXTRA) ndbapi.xml overview.xml getting-started.xml mgm-api.xml ndb-classes.xml images/Ndb-class.png images/Ndb-cluster-connection-class.png images/NdbBlob-class.png images/NdbDictionary-classes.png images/NdbDictionary-Dictionary-class.png images/NdbDictionary-Column-class.png images/NdbDictionary-Object-class.png images/NdbDictionary-Object-Datafile-class.png images/NdbDictionary-Object-Event-class.png images/NdbDictionary-Object-Index-class.png images/NdbDictionary-Object-LogfileGroup-class.png images/NdbDictionary-Object-Table-class.png images/NdbDictionary-Object-Tablespace-class.png images/NdbDictionary-Object-Undofile-class.png images/NdbDictionary-AutoGrowSpecification-struct.png images/NdbEventOperation-class.png images/NdbOperation-subclasses.png images/NdbOperation-class.png images/NdbOperation-class.png images/NdbScanOperation-class.png images/NdbIndexScanOperation-class.png errors.xml examples.xml
+NDBAPI_SRCS = $(NDBAPI_SRCS_EXTRA) ndbapi.xml overview.xml getting-started.xml mgm-api.xml ndb-classes.xml images/Ndb-class.png images/Ndb-cluster-connection-class.png images/NdbBlob-class.png images/NdbDictionary-classes.png images/NdbDictionary-Dictionary-class.png images/NdbDictionary-Column-class.png images/NdbDictionary-Object-class.png images/NdbDictionary-Object-Datafile-class.png images/NdbDictionary-Object-Event-class.png images/NdbDictionary-Object-Index-class.png images/NdbDictionary-Object-LogfileGroup-class.png images/NdbDictionary-Object-Table-class.png images/NdbDictionary-Object-Tablespace-class.png images/NdbDictionary-Object-Undofile-class.png images/NdbDictionary-AutoGrowSpecification-struct.png images/NdbEventOperation-class.png images/NdbOperation-subclasses.png images/NdbOperation-class.png images/NdbOperation-class.png images/NdbScanOperation-class.png images/NdbIndexScanOperation-class.png errors.xml images/NdbError-struct.png examples.xml
ndbapi-prepped.xml: $(NDBAPI_SRCS)
Modified: trunk/ndbapi/class-template.xml
===================================================================
--- trunk/ndbapi/class-template.xml 2006-07-02 06:22:22 UTC (rev 2584)
+++ trunk/ndbapi/class-template.xml 2006-07-02 06:25:13 UTC (rev 2585)
@@ -129,8 +129,6 @@
<title>The <literal>...::...</literal> Type</title>
- </abstract>
-
<formalpara>
<title>Description</title>
Modified: trunk/ndbapi/errors.xml
===================================================================
--- trunk/ndbapi/errors.xml 2006-07-02 06:22:22 UTC (rev 2584)
+++ trunk/ndbapi/errors.xml 2006-07-02 06:25:13 UTC (rev 2585)
@@ -12,8 +12,11 @@
<abstract>
<para>
- Discusses reporting and handling of errors potentially generated
- in NDB API applications.
+ This chapter discusses reporting and handling of errors
+ potentially generated in NDB API applications. It includes
+ information about the <literal>NdbError</literal> data structure,
+ which is used to model errors, and about NDB API error codes,
+ classifications, and messages.
</para>
</abstract>
@@ -25,12 +28,460 @@
<abstract>
<para>
- Contains status and other information about errors, including
- error codes, classifications, and messages.
+ This section discusses the <literal>NdbError</literal> data
+ structure, which contains status and other information about
+ errors, including error codes, classifications, and messages.
</para>
</abstract>
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ An <literal>NdbError</literal> consists of six parts:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>Error status</emphasis>: This describes the
+ impact of an error on the application, and reflects what
+ the application should do when the error is encountered.
+ </para>
+
+ <para>
+ The error status is described by a value of the
+ <literal>Status</literal> type. See
+ <xref linkend="struct-ndberror-status"/>, for possible
+ <literal>Status</literal> values and how they should be
+ interpreted.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Error classification</emphasis>: This represents
+ a logical error type or grouping.
+ </para>
+
+ <para>
+ The error classification is described by a value of the
+ <literal>Classificaton</literal> type. See
+ <xref linkend="struct-ndberror-classification"/>, for
+ possible classifications and their interpretation.
+ Additional information is provided in
+ <xref linkend="ndb-error-classifications"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Error code</emphasis>: This is an NDB API
+ internal error code which uniquely identifies the error.
+ </para>
+
+ <important>
+ <para>
+ It is <emphasis>not</emphasis> recommended to write
+ application programs which are dependent on specific
+ error codes. Instead, applications should check error
+ status and classification. More information about errors
+ can also be obtained by checking error messages and
+ (when available) error detail messages. However —
+ like error codes — these error messages and error
+ detail messages are subject to change.
+ </para>
+ </important>
+
+ <para>
+ A listing of current error codes, broken down by
+ classification, is provided in
+ <xref linkend="ndb-error-codes"/>. This listing will be
+ updated periodically, or you can check the file
+ <filename>storage/ndb/src/ndbapi/ndberror.c</filename> in
+ the MySQL 5.1 sources.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>MySQL Error code</emphasis>: This is the
+ corresponding MySQL Server error code. MySQL error codes
+ are not discussed in this document; please see the
+ <ulink url="&refman-base-url;/error-messages-server.html">MySQL
+ Manual</ulink> for information about these.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Error message</emphasis>: This is a generic,
+ context-independent description of the error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Error details</emphasis>: This can often provide
+ additional information (not found in the error message)
+ about an error, specific to the circumstances under which
+ the error is encountered. However, it is not available in
+ all cases.
+ </para>
+
+ <para>
+ Where not specified, the error detail message is
+ <literal>NULL</literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <important>
+ <para>
+ Specific NDB API error codes, messages, and detail messages are
+ subject to change without notice.
+ </para>
+ </important>
+
+ <formalpara>
+
+ <title>Definition</title>
+
+ <para>
+ The NdbError structure contains the following members, whose
+ types are as shown:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+<programlisting>
+Status status
+</programlisting>
+
+ The error status.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<programlisting>
+Classification classification
+</programlisting>
+
+ The error type (classification).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<programlisting>
+int code
+</programlisting>
+
+ The NDB API error code.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<programlisting>
+int mysql_code
+</programlisting>
+
+ The MySQL error code.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<programlisting>
+const char* message
+</programlisting>
+
+ The error message.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<programlisting>
+char* details
+</programlisting>
+
+ The error detail message.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ See the Description for more information about these members and
+ their types.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Public Types</title>
+
+ <para>
+ <literal>NdbError</literal> defines two datatypes:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>Status</literal>: The error status. See
+ <xref linkend="struct-ndberror-status"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>Classification</literal>: Type of or logical
+ groupings for the error. See
+ <xref linkend="struct-ndberror-classification"/>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Structure Diagram</title>
+
+ <para>
+ This diagram shows all the available members and types of
+ <literal>NdbError</literal> structure:
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/NdbError-struct.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase lang="en">Public members and types of the
+ <literal>NdbError</literal> structure.</phrase>
+ </textobject>
+ </mediaobject>
+ </para>
+
+ </formalpara>
+
+ <section id="struct-ndberror-types">
+
+ <title><literal>NdbError</literal> Types</title>
+
+ <abstract>
+
+ <para>
+ This section discusses the <literal>Status</literal> and
+ <literal>Classification</literal> datatypes defined by
+ <literal>NdbError</literal>.
+ </para>
+
+ </abstract>
+
+ <section id="struct-ndberror-status">
+
+ <title>The <literal>NdbError::Status</literal> Type</title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This type is used to describe an error's status.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Enumeration Values</title>
+
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65*"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>Success</literal></entry>
+ <entry>No error has occurred</entry>
+ </row>
+ <row>
+ <entry><literal>TemporaryError</literal></entry>
+ <entry>A temporary and usually recoverable error; the application should retry
+ the operation giving rise to the error</entry>
+ </row>
+ <row>
+ <entry><literal>PermanentError</literal></entry>
+ <entry>Permanent error; not recoverable</entry>
+ </row>
+ <row>
+ <entry><literal>UnknownResult</literal></entry>
+ <entry>The operation's result or status is unknown</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ </formalpara>
+
+ <note>
+ <para>
+ Related information specific to certain error conditions may
+ be found in <xref linkend="ndb-error-classifications"/>.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="struct-ndberror-classification">
+
+ <title>The <literal>NdbError::Classification</literal> Type</title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This type describes the type of error, or the logical group
+ to which it belongs.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Enumeration Values</title>
+
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65*"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>NoError</literal></entry>
+ <entry>Indicates success (no error occurred)</entry>
+ </row>
+ <row>
+ <entry><literal>ApplicationError</literal></entry>
+ <entry>An error occurred in an application program</entry>
+ </row>
+ <row>
+ <entry><literal>NoDataFound</literal></entry>
+ <entry>A read operation failed due to one or more missing records.</entry>
+ </row>
+ <row>
+ <entry><literal>ConstraintViolation</literal></entry>
+ <entry>A constraint violation occurred, such as attempting to insert a tuple
+ having a primary key value already in use in the
+ target table.</entry>
+ </row>
+ <row>
+ <entry><literal>SchemaError</literal></entry>
+ <entry>An error took place when trying to create or use a table.</entry>
+ </row>
+ <row>
+ <entry><literal>InsufficientSpace</literal></entry>
+ <entry>There was insufficient memory for data or indexes.</entry>
+ </row>
+ <row>
+ <entry><literal>TemporaryResourceError</literal></entry>
+ <entry>This type of error is typically encountered when there are too many
+ active transactions.</entry>
+ </row>
+ <row>
+ <entry><literal>NodeRecoveryError</literal></entry>
+ <entry>This is a temporary failure which was likely caused by a node recovery
+ in progress, some examples being when information
+ sent between an application and
+ <literal>NDB</literal> is lost, or when there is a
+ distribution change.</entry>
+ </row>
+ <row>
+ <entry><literal>OverloadError</literal></entry>
+ <entry>This type of error is often caused when there is insufficent logfile
+ space.</entry>
+ </row>
+ <row>
+ <entry><literal>TimeoutExpired</literal></entry>
+ <entry>A timeout, often caused by a deadlock.</entry>
+ </row>
+ <row>
+ <entry><literal>UnknownResultError</literal></entry>
+ <entry>It is not known whether a transaction was committed.</entry>
+ </row>
+ <row>
+ <entry><literal>InternalError</literal></entry>
+ <entry>A serious error has occurred in <literal>NDB</literal> itself.</entry>
+ </row>
+ <row>
+ <entry><literal>FunctionNotImplemented</literal></entry>
+ <entry>The application attempted to use a function which is not yet
+ implemented.</entry>
+ </row>
+ <row>
+ <entry><literal>UnknownErrorCode</literal></entry>
+ <entry>This is seen where the <literal>NDB</literal> error handler cannot
+ determine the correct error code to report.</entry>
+ </row>
+ <row>
+ <entry><literal>NodeShutdown</literal></entry>
+ <entry>This is caused by a node shutdown.</entry>
+ </row>
+ <row>
+ <entry><literal>SchemaObjectExists</literal></entry>
+ <entry>The application attempted to create a schema object that already exists.</entry>
+ </row>
+ <row>
+ <entry><literal>InternalTemporary</literal></entry>
+ <entry>A request was sent to a non-master node.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ </formalpara>
+
+ <note>
+ <para>
+ Related information specific to certain error conditions may
+ be found in <xref linkend="ndb-error-codes"/>, and in
+ <xref linkend="ndb-error-classifications"/>.
+ </para>
+ </note>
+
+ </section>
+
+ </section>
+
</section>
<section id="ndb-error-messages">
Modified: trunk/ndbapi/ndb.en.ent
===================================================================
--- trunk/ndbapi/ndb.en.ent 2006-07-02 06:22:22 UTC (rev 2584)
+++ trunk/ndbapi/ndb.en.ent 2006-07-02 06:25:13 UTC (rev 2585)
@@ -4,7 +4,7 @@
-->
-<!ENTITY title "MySQL® NDB API DEVELOPERS' GUIDE">
+<!ENTITY title "MySQL® <literal>NDB</literal> API DEVELOPERS' GUIDE">
<!ENTITY subtitle "VERSION &version; (<?dbtimestamp format='Y-m-d'?>)">
<!ENTITY version "2.0">
<!ENTITY refman-base-url "http://dev.mysql.com/doc/refman/5.1/en/">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2585 - trunk/ndbapi | jon | 2 Jul |
