Ndb.hpp
上传用户:romrleung
上传日期:2022-05-23
资源大小:18897k
文件大小:64k
源码类别:

MySQL数据库

开发平台:

Visual C++

  1. /* Copyright (C) 2003 MySQL AB
  2.    This program is free software; you can redistribute it and/or modify
  3.    it under the terms of the GNU General Public License as published by
  4.    the Free Software Foundation; either version 2 of the License, or
  5.    (at your option) any later version.
  6.    This program is distributed in the hope that it will be useful,
  7.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  8.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  9.    GNU General Public License for more details.
  10.    You should have received a copy of the GNU General Public License
  11.    along with this program; if not, write to the Free Software
  12.    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
  13. /**
  14.    @mainpage                            NDB API Programmers' Guide
  15.    This guide assumes a basic familiarity with NDB Cluster concepts.
  16.    Some of the fundamental ones are described in section @ref secConcepts.
  17.    
  18.    The <em>NDB API</em> is an NDB Cluster application interface 
  19.    that implements both synchronous and asynchronous transactions.
  20.    The NDB API consists of the following fundamental classes:
  21.    - Ndb is the main class representing the database, 
  22.    - NdbConnection represents a transaction, 
  23.    - NdbOperation represents a transaction operation using primary key,
  24.    - NdbIndexOperation represents a transaction operation using a secondary
  25.      index,
  26.    - NdbRecAttr represents the value of an attribute, and
  27.    - NdbDictionary represents meta information about tables and attributes.
  28.    - NdbError represents an error condition
  29.    There are also some auxiliary classes.
  30.      
  31.    The main structure of an application program is as follows:
  32.    -# Construct and initialize Ndb object(s).
  33.    -# Define and execute (synchronous or asynchronous) transactions.
  34.    -# Delete Ndb objects
  35.    The main structure of a transaction is as follows:
  36.    -# Start transaction
  37.    -# Add and define operations (associated with the transaction)
  38.    -# Execute transaction
  39.    The execute can be of two different types, 
  40.    <em>Commit</em> or <em>NoCommit</em>.
  41.    (The execute can also be divided into three 
  42.    steps: prepare, send, and poll to get asynchronous
  43.    transactions.  More about this later.)
  44.    
  45.    If the execute is of type NoCommit, 
  46.    then the application program executes part of a transaction,
  47.    but without committing the transaction.
  48.    After a NoCommit type of execute, the program can continue 
  49.    to add and define more operations to the transaction
  50.    for later execution.
  51.    If the execute is of type Commit, then the transaction is
  52.    committed and no further adding and defining of operations 
  53.    is allowed.
  54.    @section secSync                     Synchronous Transactions
  55.   
  56.    Synchronous transactions are defined and executed in the following way.
  57.   
  58.     -# Start (create) transaction (the transaction will be 
  59.        referred to by an NdbConnection object, 
  60.        typically created by Ndb::startTransaction).
  61.        At this step the transaction is being defined.
  62.        It is not yet sent to the NDB kernel.
  63.     -# Add and define operations to the transaction 
  64.        (using NdbConnection::getNdbOperation and
  65.        methods from class NdbOperation).
  66.        The transaction is still not sent to the NDB kernel.
  67.     -# Execute the transaction (using NdbConnection::execute).
  68.     -# Close the transaction (using Ndb::closeTransaction).
  69.   
  70.    See example program in section @ref ndbapi_example1.cpp.
  71.    To execute several parallel synchronous transactions, one can either 
  72.    use multiple Ndb objects in several threads or start multiple 
  73.    applications programs.  
  74.    Another way to execute several parallel transactions is to use
  75.    asynchronous transactions.
  76.   
  77.   
  78.    @section secNdbOperations            Operations
  79.    Each transaction (NdbConnection object) consist of a list of 
  80.    operations (NdbOperation or NdbIndexOperation objects.  
  81.    NdbIndexOperation is used for accessing tables through secondary indexes).   
  82.    Operations are of two different kinds:
  83.    -# standard operations, and
  84.    -# interpreted program operations.
  85.    <h3>Standard Operations</h3>
  86.    After the operation is created using NdbConnection::getNdbOperation
  87.    (or NdbConnection::getNdbIndexOperation),
  88.    it is defined in the following three steps:
  89.    -# Defining standard operation type
  90.       (e.g. using NdbOperation::readTuple)
  91.    -# Specifying search conditions 
  92.       (e.g. using NdbOperation::equal)
  93.    -# Specify attribute actions 
  94.       (e.g. using NdbOperation::getValue)
  95.    Example code (using an NdbOperation):
  96.    @code
  97.      MyOperation = MyConnection->getNdbOperation("MYTABLENAME"); // 1. Create
  98.      if (MyOperation == NULL) APIERROR(MyConnection->getNdbError());
  99.     
  100.      MyOperation->readTuple();                  // 2. Define type of operation
  101.      MyOperation->equal("ATTR1", i);            // 3. Specify Search Conditions
  102.     
  103.      MyRecAttr = MyOperation->getValue("ATTR2", NULL);   // 4. Attribute Actions
  104.      if (MyRecAttr == NULL) APIERROR(MyConnection->getNdbError());
  105.    @endcode
  106.    For more examples, see @ref ndbapi_example1.cpp and @ref ndbapi_example2.cpp.
  107.    Example code using an NdbIndexOperation:
  108.    @code
  109.      MyOperation =                              // 1. Create
  110.       MyConnection->getNdbIndexOperation("MYINDEX", "MYTABLENAME");
  111.      if (MyOperation == NULL) APIERROR(MyConnection->getNdbError());
  112.      MyOperation->readTuple();                  // 2. Define type of operation
  113.      MyOperation->equal("ATTR1", i);            // 3. Specify Search Conditions
  114.      MyRecAttr = MyOperation->getValue("ATTR2", NULL); // 4. Attribute Actions 
  115.      if (MyRecAttr == NULL) APIERROR(MyConnection->getNdbError());
  116.    @endcode
  117.    For more examples, see @ref ndbapi_example4.cpp.
  118.    <h4>Step 1: Define Standard Operation Type</h4>
  119.    The following types of standard operations exist:
  120.     -# NdbOperation::insertTuple : 
  121.        inserts a non-existing tuple
  122.     -# NdbOperation::writeTuple : 
  123.        updates an existing tuple if is exists,
  124.        otherwise inserts a new tuple
  125.     -# NdbOperation::updateTuple : 
  126.        updates an existing tuple
  127.     -# NdbOperation::deleteTuple : 
  128.        deletes an existing tuple
  129.     -# NdbOperation::readTuple : 
  130.        reads an existing tuple
  131.     -# NdbOperation::readTupleExclusive : 
  132.        reads an existing tuple using an exclusive lock
  133.     -# NdbOperation::simpleRead : 
  134.        reads an existing tuple (using shared read lock),
  135.        but releases lock immediately after read
  136.     -# NdbOperation::committedRead : 
  137.        reads committed tuple
  138.     -# NdbOperation::dirtyUpdate : 
  139.        updates an existing tuple, but releases lock immediately
  140.        after read (uses dirty lock)
  141.     -# NdbOperation::dirtyWrite : 
  142.        updates or writes a tuple, but releases lock immediately
  143.        after read (uses dirty lock)
  144.    All of these operations operate on the unique tuple key.
  145.    (When NdbIndexOperation is used then all of these operations 
  146.    operate on a defined secondary index.)
  147.    Some comments:
  148.    - NdbOperation::simpleRead and 
  149.      NdbOperation::committedRead can execute on the same transaction
  150.      as the above operations but will release its locks immediately
  151.      after reading the tuple. 
  152.      NdbOperation::simpleRead will always read the latest version 
  153.      of the tuple. 
  154.      Thus it will wait until it can acquire a shared read lock on 
  155.      the tuple. 
  156.      NdbOperation::committedRead will read the latest committed 
  157.      version of the tuple. 
  158.      <br>
  159.      Both NdbOperation::simpleRead and NdbOperation::committedRead 
  160.      are examples of consistent reads which are not repeatable.
  161.      All reads read the latest version if updates were made by the same
  162.      transaction.
  163.      Errors on simple read are only reported by the NdbOperation object.
  164.      These error codes are not transferred to the NdbConnection object.
  165.    - NdbOperation::dirtyUpdate and NdbOperation::dirtyWrite 
  166.      will execute in the same transaction
  167.      but will release the lock immediately after updating the
  168.      tuple.
  169.      It will wait on the lock until it can acquire an exclusive
  170.      write lock.
  171.      In a replicated version of NDB Cluster NdbOperation::dirtyUpdate 
  172.      can lead to inconsistency between the replicas.
  173.      Examples of when it could be used is
  174.      to update statistical counters on tuples which are "hot-spots".
  175.    @note If you want to define multiple operations within the same transaction,
  176.          then you need to call NdbConnection::getNdbOperation 
  177.  (or NdbConnection::getNdbIndexOperation) for each
  178.          operation.
  179.    <h4>Step 2: Specify Search Conditions</h4>
  180.    The search condition is used to select tuples.
  181.    (In the current NdbIndexOperation implementation 
  182.    this means setting the value of
  183.    the secondary index attributes of the wanted tuple.)
  184.    If a tuple identity is used, then NdbOperation::setTupleId 
  185.    is used to define the search key when inserting new tuples.
  186.    Otherwise, NdbOperation::equal is used.
  187.    
  188.    For NdbOperation::insertTuple it is also allowed to define the 
  189.    search key by using NdbOperation::setValue.
  190.    The NDB API will automatically detect that it is
  191.    supposed to use NdbOperation::equal instead. 
  192.    For NdbOperation::insertTuple it is not necessary to use
  193.    NdbOperation::setValue on key attributes before other attributes.
  194.    <h4>Step 3: Specify Attribute Actions</h4>
  195.    Now it is time to define which attributes should be read or updated.
  196.    Deletes can neither read nor set values, read can only read values and
  197.    updates can only set values.
  198.    Normally the attribute is defined by its name but it is
  199.    also possible to use the attribute identity to define the
  200.    attribute.
  201.    The mapping from name to identity is performed by the Table object.
  202.    NdbIndexOperation::getValue returns an NdbRecAttr object
  203.    containing the read value.
  204.    To get the value, there is actually two methods.
  205.    The application can either
  206.    - use its own memory (passed through a pointer aValue) to
  207.      NdbIndexOperation::getValue, or
  208.    - receive the attribute value in an NdbRecAttr object allocated
  209.      by the NDB API.
  210.    The NdbRecAttr object is released when Ndb::closeTransaction
  211.    is called.
  212.    Thus, the application can not reference this object after
  213.    Ndb::closeTransaction have been called.
  214.    The result of reading data from an NdbRecAttr object before
  215.    calling NdbConnection::execute is undefined.
  216.    <h3>Interpreted Program Operations</h3>
  217.    The following types of interpreted program operations exist:
  218.     -# NdbOperation::interpretedUpdateTuple :
  219.        updates a tuple using an interpreted program
  220.     -# NdbOperation::interpretedDeleteTuple :
  221.        delete a tuple using an interpreted program
  222.     -# NdbOperation::openScanRead : 
  223.        scans a table with read lock on each tuple
  224.     -# NdbOperation::openScanExclusive : 
  225.        scans a table with exclusive update lock on each tuple
  226.    The operations interpretedUpdateTuple and interpretedDeleteTuple both
  227.    work using the unique tuple key.
  228.    These <em>interpreted programs</em> 
  229.    make it possible to perform computations
  230.    inside the NDB Cluster Kernel instead of in the application
  231.    program.
  232.    This is sometimes very effective, since no intermediate results
  233.    are sent to the application, only the final result.
  234.   <h3>Interpreted Update and Delete</h3>
  235.    Operations for interpreted updates and deletes must follow a
  236.    certain order when defining operations on a tuple.
  237.    As for read and write operations,
  238.    one must first define the operation type and then the search key.
  239.    -# The first step is to define the initial readings.
  240.       In this phase it is only allowed to use the
  241.       NdbOperation::getValue method.
  242.       This part might be empty.
  243.    -# The second step is to define the interpreted part.
  244.       The methods supported are the methods listed below except
  245.       NdbOperation::def_subroutine and NdbOperation::ret_sub
  246.       which can only be used in a subroutine.
  247.       NdbOperation::incValue and NdbOperation::subValue
  248.       increment and decrement attributes
  249.       (currently only unsigned integers supported).
  250.       This part can also be empty since interpreted updates
  251.       can be used for reading and updating the same tuple.
  252.       <p>
  253.       Even though getValue and setValue are not really interpreted
  254.       program instructions, it is still allowed to use them as
  255.       the last instruction of the program.
  256.       (If a getValue or setValue is found when an interpret_exit_ok
  257.       could have been issued then the interpreted_exit_ok
  258.       will be inserted.
  259.       A interpret_exit_ok should be viewed as a jump to the first
  260.       instruction after the interpreted instructions.)
  261.    -# The third step is to define all updates without any
  262.       interpreted program instructions.
  263.       Here a set of NdbOperation::setValue methods are called.
  264.       There might be zero such calls.
  265.    -# The fourth step is the final readings.
  266.       The initial readings reads the initial value of attributes
  267.       and the final readings reads them after their updates.
  268.       There might be zero NdbOperation::getValue calls.
  269.    -# The fifth step is possible subroutine definitions using
  270.       NdbOperation::def_subroutine and NdbOperation::ret_sub.
  271.    @subsection secScan              Scanning 
  272.    The most common use of interpreted programs is for scanning
  273.    tables.  Scanning is a search of all tuples in a table.  
  274.    Tuples which satisfy conditions (a search filter) 
  275.    stated in the interpreted program 
  276.    are sent to the application.
  277.    Reasons for using scan transactions include
  278.    need to use a search key different from the primary key
  279.    and any secondary index.
  280.    Or that the query needs to access so many tuples so that 
  281.    it is more efficient to scan the entire table.
  282.    Scanning can also be used to update information.  
  283.    The scanning transaction itself is however 
  284.    not allowed to update any tuples.
  285.    To do updates via scanning transactions, the tuples 
  286.    need to be handed over to another transaction which is 
  287.    executing the actual update.
  288.    Even though a scan operation is part of a transaction, 
  289.    the scan transaction is not a normal transaction.
  290.    The locks are <em>not</em> kept throughout the entire 
  291.    scan transaction, since this would imply non-optimal performance.  
  292.    <em>
  293.    A transaction containing a scan operation can only 
  294.    contain that operation.  
  295.    No other operations are allowed in the same transaction.
  296.    </em>
  297.    The NdbOperation::openScanRead operation 
  298.    only sets a temporary read lock while
  299.    reading the tuple. 
  300.    The tuple lock is released already when the
  301.    result of the read reaches the application. 
  302.    The NdbOperation::openScanExclusive operation sets an 
  303.    exclusive lock on the tuple 
  304.    and sends the result to the application. 
  305.    Thus when the application reads the data it is still
  306.    locked with the exclusive lock. 
  307.    If the application desires to update the tuple it may transfer
  308.    the tuple to another transaction which updates the tuple.
  309.    The updating transaction can consist of a combination of tuples 
  310.    received from the scan and normal operations. 
  311.    For transferred operations it is not necessary to provide the
  312.    primary key.  It is part of the transfer. 
  313.    You only need to give the operation type and the 
  314.    actions to perform on the tuple.
  315.    The scan transaction starts like a usual transaction,
  316.    but is of the following form:
  317.     -# Start transaction
  318.     -# Get NdbOperation for the table to be scanned
  319.     -# Set the operation type using NdbOperation::openScanRead or 
  320.        NdbOperation::openScanExclusive
  321.     -# Search conditions are defined by an interpreted program
  322.        (setValue and write_attr are not allowed, since scan transactions
  323.        are only allowed to read information).
  324.        The instruction interpret_exit_nok does in this case
  325.        not abort the transaction, it only skips the tuple and 
  326.        proceeds with the next.  
  327.        The skipped tuple will not be reported to the application.
  328.     -# Call NdbConnection::executeScan to define (and start) the scan.
  329.     -# Call NdbConnection::nextScanResult to proceed with next tuple.  
  330.        When calling NdbConnection::nextScanResult, the lock on any 
  331.        previous tuples are released.
  332.        <br>
  333.        If the tuple should be updated then it must be transferred over
  334.        to another updating transaction.  
  335.        This is performed by calling
  336.        NdbOperation::takeOverForUpdate or takeOverForDelete on 
  337.        the scanning transactions NdbOperation object with the updating 
  338.        transactions NdbConnection object as parameter.  
  339.        <p>
  340.        If NdbOperation::takeOverFor* returns NULL then the 
  341.        operation was not successful, otherwise it returns a reference
  342.        to the NdbOperation which the updating transaction has received
  343.     -# Use Ndb::closeTransaction as usual to close the transaction. 
  344.        This can be performed even if there are more tuples to scan.
  345.    See also example program in section @ref select_all.cpp.
  346.    However, a new scan api is under development, using NdbScanOperation
  347.    and NdbScanFilter. NdbScanFilter makes it easier to define a search
  348.    criteria and is recommended instead of using Interpreted Programs.
  349.    The scan transaction starts like a usual transaction,
  350.    but is of the following form:
  351.     -# Start transaction
  352.     -# Get NdbScanOperation for the table to be scanned
  353.     -# NdbScanOperation::readTuplesExclusive returns a handle to a 
  354.        NdbResultSet. 
  355.     -# Search conditions are defined by NdbScanFilter
  356.     -# Call NdbConnection::execute(NoCommit) to start the scan.
  357.     -# Call NdbResultSet::nextResult to proceed with next tuple.  
  358.        When calling NdbResultSet::nextResult(false), the lock on any 
  359.        previous tuples are released and the next tuple cached in the API
  360.        is fetched. 
  361.        <br>
  362.        If the tuple should be updated then define a new update operation 
  363.        (NdbOperation) using NdbResultSet::updateTuple().
  364.        The new update operation can the be used to modify the tuple.
  365.        When nextResult(false) returns != 0, then no more tuples 
  366.        are cached in the API. Updated tuples is now commit using 
  367.        NdbConnection::execute(Commit).
  368.        After the commit, more tuples are fetched from NDB using 
  369.        nextResult(true).
  370.     -# Use Ndb::closeTransaction as usual to close the transaction. 
  371.        This can be performed even if there are more tuples to scan.
  372.        See the scan example program in @ref ndbapi_scan.cppn for example
  373.        usage of the new scan api.
  374.    <h3>Interpreted Programs</h3>
  375.    Interpretation programs are executed in a
  376.    register-based virtual machine.
  377.    The virtual machine has eight 64 bit registers numbered 0-7.
  378.    Each register contains type information which is used both
  379.    for type conversion and for type checking.
  380.    @note Arrays are currently <b>not</b> supported in the virtual machine.
  381.          Currently only unsigned integers are supported and of size
  382.          maximum 64 bits.
  383.    All errors in the interpretation program will cause a
  384.    transaction abort, but will not affect any other transactions.
  385.    The following are legal interpreted program instructions:
  386.    -# incValue        : Add to an attribute
  387.    -# subValue        : Subtract from an attribute
  388.    -# def_label       : Define a label in the interpreted program
  389.    -# add_reg         : Add two registers
  390.    -# sub_reg         : Subtract one register from another
  391.    -# load_const_u32  : Load an unsigned 32 bit value into a register
  392.    -# load_const_u64  : Load an unsigned 64 bit value into a register
  393.    -# load_const_null : Load a NULL value into a register
  394.    -# read_attr       : Read attribute value into a register
  395.    -# write_attr      : Write a register value into an attribute
  396.    -# branch_ge       : Compares registers and possibly jumps to specified label
  397.    -# branch_gt       : Compares registers and possibly jumps to specified label
  398.    -# branch_le       : Compares registers and possibly jumps to specified label
  399.    -# branch_lt       : Compares registers and possibly jumps to specified label
  400.    -# branch_eq       : Compares registers and possibly jumps to specified label
  401.    -# branch_ne       : Compares registers and possibly jumps to specified label
  402.    -# branch_ne_null  : Jumps if register does not contain NULL value
  403.    -# branch_eq_null  : Jumps if register contains NULL value
  404.    -# branch_label    : Unconditional jump to label
  405.    -# interpret_exit_ok  : Exit interpreted program
  406.                            (approving tuple if used in scan)
  407.    -# interpret_exit_nok : Exit interpreted program
  408.                            (disqualifying tuple if used in scan)
  409.    There are also three instructions for subroutines, which
  410.    are described in the next section.
  411.    @subsection subsubSub                Interpreted Programs: Subroutines
  412.    The following are legal interpreted program instructions for
  413.    subroutines:
  414.    -# NdbOperation::def_subroutine : 
  415.       Defines start of subroutine in interpreted program code
  416.    -# NdbOperation::call_sub : 
  417.       Calls a subroutine
  418.    -# NdbOperation::ret_sub : 
  419.       Return from subroutine
  420.    The virtual machine executes subroutines using a stack for
  421.    its operation.
  422.    The stack allows for up to 24 subroutine calls in succession.
  423.    Deeper subroutine nesting will cause an abort of the transaction.
  424.    All subroutines starts with the instruction
  425.    NdbOperation::def_subroutine and ends with the instruction
  426.    NdbOperation::ret_sub.
  427.    If it is necessary to return earlier in the subroutine
  428.    it has to be done using a branch_label instruction
  429.    to a label defined right before the 
  430.    NdbOperation::ret_sub instruction.
  431.    @note The subroutines are automatically numbered starting with 0.
  432.          The parameter used by NdbOperation::def_subroutine 
  433.  should match the automatic numbering to make it easier to 
  434.  debug the interpreted program.
  435.    @section secAsync                    Asynchronous Transactions
  436.    The asynchronous interface is used to increase the speed of
  437.    transaction executing by better utilizing the connection
  438.    between the application and the NDB Kernel.
  439.    The interface is used to send many transactions 
  440.    at the same time to the NDB kernel.  
  441.    This is often much more efficient than using synchronous transactions.
  442.    The main reason for using this method is to ensure that 
  443.    Sending many transactions at the same time ensures that bigger 
  444.    chunks of data are sent when actually sending and thus decreasing 
  445.    the operating system overhead.
  446.    The synchronous call to NdbConnection::execute 
  447.    normally performs three main steps:<br>
  448.    -# <b>Prepare</b> 
  449.       Check transaction status
  450.       - if problems, abort the transaction
  451.       - if ok, proceed
  452.    -# <b>Send</b> 
  453.       Send the defined operations since last execute
  454.       or since start of transaction.
  455.    -# <b>Poll</b>
  456.       Wait for response from NDB kernel.
  457.    The asynchronous method NdbConnection::executeAsynchPrepare 
  458.    only perform step 1.
  459.    (The abort part in step 1 is only prepared for.  The actual 
  460.    aborting of the transaction is performed in a later step.)
  461.    Asynchronous transactions are defined and executed 
  462.    in the following way.
  463.    -# Start (create) transactions (same way as for the 
  464.        synchronous transactions)
  465.    -# Add and define operations (also as in the synchronous case)
  466.    -# <b>Prepare</b> transactions 
  467.        (using NdbConnection::executeAsynchPrepare or 
  468.        NdbConnection::executeAsynch)
  469.    -# <b>Send</b> transactions to NDB Kernel
  470.        (using Ndb::sendPreparedTransactions, 
  471.        NdbConnection::executeAsynch, or Ndb::sendPollNdb)
  472.    -# <b>Poll</b> NDB kernel to find completed transactions 
  473.        (using Ndb::pollNdb or Ndb::sendPollNdb)
  474.    -# Close transactions (same way as for the synchronous transactions)
  475.    See example program in section @ref ndbapi_example2.cpp.
  476.    
  477.    This prepare-send-poll protocol actually exists in four variants:
  478.    - (Prepare-Send-Poll).  This is the one-step variant provided
  479.      by synchronous transactions.
  480.    - (Prepare-Send)-Poll.  This is the two-step variant using
  481.      NdbConnection::executeAsynch and Ndb::pollNdb.
  482.    - Prepare-(Send-Poll).  This is the two-step variant using
  483.      NdbConnection::executeAsynchPrepare and Ndb::sendPollNdb.
  484.    - Prepare-Send-Poll.  This is the three-step variant using
  485.      NdbConnection::executeAsynchPrepare, Ndb::sendPreparedTransactions, and
  486.      Ndb::pollNdb.
  487.   
  488.    Transactions first has to be prepared by using method
  489.    NdbConnection::executeAsynchPrepare or NdbConnection::executeAsynch.
  490.    The difference between these is that 
  491.    NdbConnection::executeAsynch also sends the transaction to 
  492.    the NDB kernel.
  493.    One of the arguments to these methods is a callback method.
  494.    The callback method is executed during polling (item 5 above).
  495.   
  496.    Note that NdbConnection::executeAsynchPrepare does not 
  497.    send the transaction to the NDB kernel.  When using 
  498.    NdbConnection::executeAsynchPrepare, you either have to call 
  499.    Ndb::sendPreparedTransactions or Ndb::sendPollNdb to send the 
  500.    database operations.
  501.    (Ndb::sendPollNdb also polls Ndb for completed transactions.)
  502.   
  503.    The methods Ndb::pollNdb and Ndb::sendPollNdb checks if any 
  504.    sent transactions are completed.  The method Ndb::sendPollNdb 
  505.    also send all prepared transactions before polling NDB.
  506.    Transactions still in the definition phase (i.e. items 1-3 above, 
  507.    transactions which has not yet been sent to the NDB kernel) are not 
  508.    affected by poll-calls.
  509.    The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
  510.    will return when:
  511.     -# at least 'minNoOfEventsToWakeup' of the transactions
  512.        are finished processing, and
  513.     -# all of these transactions have executed their 
  514.        callback methods.
  515.   
  516.    The poll method returns the number of transactions that 
  517.    have finished processing and executed their callback methods.
  518.   
  519.    @note When an asynchronous transaction has been started and sent to
  520.          the NDB kernel, it is not allowed to execute any methods on
  521.          objects belonging to this transaction until the transaction
  522.          callback method have been executed.
  523.          (The transaction is stated and sent by either
  524.  NdbConnection::executeAsynch or through the combination of
  525.          NdbConnection::executeAsynchPrepare and either
  526.          Ndb::sendPreparedTransactions or Ndb::sendPollNdb).
  527.    More about how transactions are send the NDB Kernel is 
  528.    available in section @ref secAdapt.
  529.    @section secError                    Error Handling
  530.    Errors can occur when
  531.    -# operations are being defined, or when the
  532.    -# transaction is being executed.
  533.    One recommended way to handle a transaction failure 
  534.    (i.e. an error is reported) is to:
  535.    -# Rollback transaction (NdbConnection::execute with a special parameter)
  536.    -# Close transaction
  537.    -# Restart transaction (if the error was temporary)
  538.    @note Transaction are not automatically closed when an error occur.
  539.    Several errors can occur when a transaction holds multiple 
  540.    operations which are simultaneously executed.
  541.    In this case the application has to go through the operation
  542.    objects and query for their NdbError objects to find out what really
  543.    happened.
  544.    NdbConnection::getNdbErrorOperation returns a reference to the 
  545.    operation causing the latest error.
  546.    NdbConnection::getNdbErrorLine delivers the method number of the 
  547.    erroneous method in the operation.
  548.    @code
  549.      theConnection = theNdb->startTransaction();
  550.      theOperation = theConnection->getNdbOperation("TEST_TABLE");
  551.      if (theOperation == NULL) goto error;
  552.      theOperation->readTuple();
  553.      theOperation->setValue("ATTR_1", at1);
  554.      theOperation->setValue("ATTR_2", at1); //Here an error occurs
  555.      theOperation->setValue("ATTR_3", at1);
  556.      theOperation->setValue("ATTR_4", at1);
  557.     
  558.      if (theConnection->execute(Commit) == -1) {
  559.        errorLine = theConnection->getNdbErrorLine();
  560.        errorOperation = theConnection->getNdbErrorOperation();
  561.    @endcode
  562.    Here errorLine will be 3 as the error occurred in the third method 
  563.    on the operation object.
  564.    Getting errorLine == 0 means that the error occurred when executing the 
  565.    operations.
  566.    Here errorOperation will be a pointer to the theOperation object.
  567.    NdbConnection::getNdbError will return the NdbError object 
  568.    including holding information about the error.
  569.    Since errors could have occurred even when a commit was reported,
  570.    there is also a special method, NdbConnection::commitStatus,
  571.    to check the commit status of the transaction.
  572. *******************************************************************************/
  573. /**
  574.  * @page ndbapi_example1.cpp ndbapi_example1.cpp
  575.  * @include ndbapi_example1.cpp 
  576.  */
  577. /**
  578.  * @page ndbapi_example2.cpp ndbapi_example2.cpp
  579.  * @include ndbapi_example2.cpp 
  580.  */
  581. /**
  582.  * @page ndbapi_example3.cpp ndbapi_example3.cpp
  583.  * @include ndbapi_example3.cpp 
  584.  */
  585. /**
  586.  * @page ndbapi_example4.cpp ndbapi_example4.cpp
  587.  * @include ndbapi_example4.cpp 
  588.  */
  589. /**
  590.  * @page select_all.cpp select_all.cpp
  591.  * @include select_all.cpp 
  592.  */
  593. /**
  594.  * @page ndbapi_async.cpp ndbapi_async.cpp
  595.  * @include ndbapi_async.cpp
  596.  */
  597. /**
  598.  * @page ndbapi_scan.cpp ndbapi_scan.cpp
  599.  * @include ndbapi_scan.cpp
  600.  */
  601. /**
  602.    @page secAdapt  Adaptive Send Algorithm
  603.    At the time of "sending" the transaction 
  604.    (using NdbConnection::execute, NdbConnection::executeAsynch, 
  605.    Ndb::sendPreparedTransactions, or Ndb::sendPollNdb), the transactions 
  606.    are in reality <em>not</em> immediately transfered to the NDB Kernel.  
  607.    Instead, the "sent" transactions are only kept in a 
  608.    special send list (buffer) in the Ndb object to which they belong.
  609.    The adaptive send algorithm decides when transactions should
  610.    be transfered to the NDB kernel.
  611.   
  612.    For each of these "sent" transactions, there are three 
  613.    possible states:
  614.    -# Waiting to be transfered to NDB Kernel.
  615.    -# Has been transfered to the NDB Kernel and is currently 
  616.       being processed.
  617.    -# Has been transfered to the NDB Kernel and has 
  618.       finished processing.
  619.       Now it is waiting for a call to a poll method.  
  620.       (When the poll method is invoked, 
  621.       then the transaction callback method will be executed.)
  622.       
  623.    The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
  624.    will return when:
  625.    -# at least 'minNoOfEventsToWakeup' of the transactions
  626.       in the send list have transitioned to state 3 as described above, and 
  627.    -# all of these transactions have executed their callback methods.
  628.   
  629.   
  630.    Since the NDB API is designed as a multi-threaded interface, 
  631.    it is desirable to transfer database operations from more than 
  632.    one thread at a time. 
  633.    The NDB API keeps track of which Ndb objects are active in transfering
  634.    information to the NDB kernel and the expected amount of threads to 
  635.    interact with the NDB kernel.
  636.    Note that an Ndb object should be used in at most one thread. 
  637.    Two different threads should <em>not</em> use the same Ndb object.
  638.   
  639.    There are four reasons leading to transfering of database 
  640.    operations:
  641.    -# The NDB Transporter (TCP/IP, OSE, SCI or shared memory)
  642.       decides that a buffer is full and sends it off. 
  643.       The buffer size is implementation dependent and
  644.       might change between NDB Cluster releases.
  645.       On TCP/IP the buffer size is usually around 64 kByte and 
  646.       on OSE/Delta it is usually less than 2000 bytes. 
  647.       In each Ndb object there is one buffer per DB node, 
  648.       so this criteria of a full buffer is only 
  649.       local to the connection to one DB node.
  650.    -# Statistical information on the transfered information
  651.       may force sending of buffers to all DB nodes.
  652.    -# Every 10 ms a special send-thread checks whether 
  653.       any send activity has occurred.  If not, then the thread will 
  654.       force sending to all nodes. 
  655.       This means that 20 ms is the maximum time database operations 
  656.       are waiting before being sent off. The 10 millisecond limit 
  657.       is likely to become a configuration parameter in
  658.       later releases of NDB Cluster.
  659.       However, to support faster than 10 ms checks, 
  660.       there has to be support from the operating system.
  661.    -# When calling NdbConnection::execute synchronously or calling any 
  662.       of the poll-methods, there is a force parameter that overrides the 
  663.       adaptive algorithm and forces the send to all nodes.
  664.    @note The times mentioned above are examples.  These might 
  665.          change in later releases of NDB Cluster.
  666. */
  667. /**
  668.    @page secConcepts  NDB Cluster Concepts
  669.    The <em>NDB Kernel</em> is the collection of database (DB) nodes
  670.    belonging to an NDB Cluster.
  671.    The application programmer can for most purposes view the
  672.    set of all DB nodes as one entity.
  673.    Each DB node has three main components:
  674.    - TC : The transaction coordinator
  675.    - ACC : The index storage
  676.    - TUP : The data storage
  677.    When the application program executes a transaction,
  678.    it connects to one TC on one DB node.  
  679.    Usually, the programmer does not need to specify which TC to use, 
  680.    but some cases when performance is important,
  681.    transactions can be hinted to use a certain TC.  
  682.    (If the node with the TC is down, then another TC will 
  683.    automatically take over the work.)
  684.    Every DB node has an ACC and a TUP which stores 
  685.    the index and the data part of the database.
  686.    Even though one TC is responsible for the transaction,
  687.    several ACCs and TUPs on other DB nodes might be involved in the 
  688.    execution of the transaction.
  689.    @section secNdbKernelConnection   Selecting Transaction Coordinator 
  690.    The default method is round robin, 
  691.    where each new set of transactions
  692.    is placed on the next DB node.
  693.    The application chooses a TC for a number of transactions
  694.    and then lets the next TC (on the next DB node) carry out
  695.    the next set of transactions.
  696.    
  697.    The application programmer can however hint the NDB API which 
  698.    transaction coordinator to use
  699.    by providing a <em>distribution key</em> (usually the primary key).
  700.    By using the primary key as distribution key, 
  701.    the transaction will be placed on the node where the primary replica
  702.    of that record resides.
  703.    Note that this is only a hint, the system can be 
  704.    reconfigured and then the NDB API will choose a transaction
  705.    coordinator without using the hint.
  706.    For more information, see NdbDictionary::Column::setDistributionKey.
  707.    @section secRecordStruct          Record Structure 
  708.    NDB Cluster is a relational database with tables of records.
  709.    Table rows represent tuples of relational data stored as records.
  710.    When created, the attribute schema of the table is specified,
  711.    and thus each record of the table has the same schema.
  712.    
  713.    @subsection secKeys               Tuple Keys
  714.    Each record has from zero up to four attributes which belong
  715.    to the primary key of the table.
  716.    If no attribute belongs to the primary key, then
  717.    the NDB Cluster creates an attribute named <em>NDB$TID</em>
  718.    which stores a tuple identity.
  719.    The <em>tuple key</em> of a table is thus either 
  720.    the primary key attributes or the special NDB$TID attribute.
  721.    @subsection secArrays             Array Attributes
  722.    A table attribute in NDB Cluster can be of <em>array type</em>.
  723.    This means that the attribute consists of an array of 
  724.    <em>elements</em>.  The <em>attribute size</em> is the size
  725.    of one element of the array (expressed in bits) and the 
  726.    <em>array size</em> is the number of elements of the array.
  727.    
  728.    @section secTrans                 Transactions
  729.    Transactions are committed to main memory, 
  730.    and are committed to disk after a global checkpoint, GCP.
  731.    Since all data is (in most NDB Cluster configurations) 
  732.    synchronously replicated and stored on multiple NDB nodes,
  733.    the system can still handle processor failures without loss 
  734.    of data.
  735.    However, in the case of a system failure (e.g. the whole system goes down), 
  736.    then all (committed or not) transactions after the latest GCP are lost.
  737.    @subsection secConcur                Concurrency Control
  738.    NDB Cluster uses pessimistic concurrency control based on locking.
  739.    If a requested lock (implicit and depending on database operation)
  740.    cannot be attained within a specified time, 
  741.    then a timeout error occurs.
  742.    Concurrent transactions (parallel application programs, thread-based 
  743.    applications, or applications with asynchronous transactions)
  744.    sometimes deadlock when they try to access the same information.
  745.    Applications need to be programmed so that timeout errors
  746.    occurring due to deadlocks are handled.  This generally
  747.    means that the transaction encountering timeout
  748.    should be rolled back and restarted.
  749. */
  750. #ifndef Ndb_H
  751. #define Ndb_H
  752. #include <ndb_types.h>
  753. #include <ndbapi_limits.h>
  754. #include <ndb_cluster_connection.hpp>
  755. #include <NdbError.hpp>
  756. #include <NdbDictionary.hpp>
  757. class NdbObjectIdMap;
  758. class NdbOperation;
  759. class NdbEventOperationImpl;
  760. class NdbScanOperation;
  761. class NdbIndexScanOperation;
  762. class NdbIndexOperation;
  763. class NdbConnection;
  764. class NdbApiSignal;
  765. class NdbRecAttr;
  766. class NdbLabel;
  767. class NdbBranch;
  768. class NdbSubroutine;
  769. class NdbCall;
  770. class Table;
  771. class BaseString;
  772. class NdbEventOperation;
  773. class NdbBlob;
  774. class NdbReceiver;
  775. template <class T> struct Ndb_free_list_t;
  776. typedef void (* NdbEventCallback)(NdbEventOperation*, Ndb*, void*);
  777. #if defined NDB_OSE
  778. /**
  779.  * Default time to wait for response after request has been sent to 
  780.  * NDB Cluster (Set to 10 seconds usually, but to 100 s in 
  781.  * the OSE operating system)
  782.  */
  783. #define WAITFOR_RESPONSE_TIMEOUT 100000 // Milliseconds
  784. #else
  785. #define WAITFOR_RESPONSE_TIMEOUT 120000 // Milliseconds
  786. #endif
  787. #define NDB_MAX_INTERNAL_TABLE_LENGTH NDB_MAX_DATABASE_NAME_SIZE + 
  788.                                       NDB_MAX_SCHEMA_NAME_SIZE + 
  789.                                       NDB_MAX_TAB_NAME_SIZE*2
  790. /**
  791.  * @class Ndb 
  792.  * @brief Represents the NDB kernel and is the main class of the NDB API.
  793.  *
  794.  * Always start your application program by creating an Ndb object. 
  795.  * By using several Ndb objects it is possible to design 
  796.  * a multi-threaded application, but note that Ndb objects 
  797.  * cannot be shared by several threads. 
  798.  * Different threads should use different Ndb objects. 
  799.  * A thread might however use multiple Ndb objects.
  800.  * Currently there is a limit of maximum 128 Ndb objects 
  801.  * per application process.
  802.  *
  803.  * @note It is not allowed to call methods in the NDB API 
  804.  *       on the same Ndb object in different threads 
  805.  *       simultaneously (without special handling of the 
  806.  *       Ndb object).
  807.  *
  808.  * @note The Ndb object is multi-thread safe in the following manner. 
  809.  *       Each Ndb object can ONLY be handled in one thread. 
  810.  *       If an Ndb object is handed over to another thread then the 
  811.  *       application must ensure that a memory barrier is used to 
  812.  *       ensure that the new thread see all updates performed by 
  813.  *       the previous thread. 
  814.  *       Semaphores, mutexes and so forth are easy ways of issuing memory 
  815.  *       barriers without having to bother about the memory barrier concept.
  816.  *
  817.  * If one Ndb object is used to handle parallel transactions through the 
  818.  * asynchronous programming interface, please read the notes regarding
  819.  * asynchronous transactions (Section @ref secAsync).
  820.  * The asynchronous interface provides much higher performance 
  821.  * in some situations, but is more complicated for the application designer. 
  822.  *
  823.  * @note Each Ndb object should either use the methods for 
  824.  *       asynchronous transaction or the methods for 
  825.  *       synchronous transactions but not both.
  826.  */
  827. class Ndb
  828. {
  829.   friend class NdbReceiver;
  830.   friend class NdbOperation;
  831.   friend class NdbEventOperationImpl;
  832.   friend class NdbConnection;
  833.   friend class Table;
  834.   friend class NdbApiSignal;
  835.   friend class NdbIndexOperation;
  836.   friend class NdbScanOperation;
  837.   friend class NdbIndexScanOperation;
  838.   friend class NdbDictionaryImpl;
  839.   friend class NdbDictInterface;
  840.   friend class NdbBlob;
  841. public:
  842.   /** 
  843.    * @name General 
  844.    * @{
  845.    */
  846.   /**
  847.    * The starting point of your application code is to create an 
  848.    * Ndb object.  
  849.    * This object represents the NDB kernel and is the main
  850.    * object used in interaction with the NDB kernel.
  851.    *
  852.    * @param aCatalogName is the name of the catalog you want to use.
  853.    * @note The catalog name provides a name space for the tables and
  854.    *       indexes created in any connection from the Ndb object.
  855.    * @param aSchemaName is the name of the schema you 
  856.    *        want to use. It is optional and defaults to the "def" schema.
  857.    * @note The schema name provides an additional name space 
  858.    *       for the tables and indexes created in a given catalog.
  859.    * @note The methods get/setDatabaseName and get/setDatabaseSchemaName
  860.    *       are equivalent to get/setCatalogName and get/setSchemaName.
  861.    *       The get/setDatabaseName and get/setDatabaseSchemaName are
  862.    *       deprecated.
  863.    */
  864.   Ndb(const char* aCatalogName = "", const char* aSchemaName = "def");
  865.   Ndb(Ndb_cluster_connection *ndb_cluster_connection,
  866.       const char* aCatalogName = "", const char* aSchemaName = "def");
  867.   ~Ndb();
  868.   /**
  869.    * The current catalog name can be fetched by getCatalogName.
  870.    *
  871.    * @return the current catalog name
  872.    */
  873.   const char * getCatalogName() const;
  874.   /**
  875.    * The current catalog name can be set by setCatalogName.
  876.    *
  877.    * @param aCatalogName is the new name of the current catalog
  878.    */
  879.   void setCatalogName(const char * aCatalogName);
  880.   /**
  881.    * The current schema name can be fetched by getSchemaName.
  882.    *
  883.    * @return the current schema name
  884.    */
  885.   const char * getSchemaName() const;
  886.   /**
  887.    * The current schema name can be set by setSchemaName.
  888.    *
  889.    * @param aSchemaName is the new name of the current schema
  890.    */
  891.   void setSchemaName(const char * aSchemaName);
  892.   /**
  893.    * The current database name can be fetched by getDatabaseName.
  894.    *
  895.    * @return the current database name
  896.    */
  897.   const char * getDatabaseName() const;
  898.   /**
  899.    * The current database name can be set by setDatabaseName.
  900.    *
  901.    * @param aDatabaseName is the new name of the current database
  902.    */
  903.   void setDatabaseName(const char * aDatabaseName);
  904.   /**
  905.    * The current database schema name can be fetched by getDatabaseSchemaName.
  906.    *
  907.    * @return the current database schema name
  908.    */
  909.   const char * getDatabaseSchemaName() const;
  910.   /**
  911.    * The current database schema name can be set by setDatabaseSchemaName.
  912.    *
  913.    * @param aDatabaseSchemaName is the new name of the current database schema
  914.    */
  915.   void setDatabaseSchemaName(const char * aDatabaseSchemaName);
  916.   /**
  917.    * Before anything else it is necessary to initialize (start)
  918.    * the Ndb object.
  919.    *
  920.    * @param  maxNoOfTransactions 
  921.    *         Maximum number of parallel 
  922.    *         NdbConnection objects that should be handled by the Ndb object.
  923.    *         A value larger than 1024 will be downgraded to 1024. 
  924.    *         This means that one Ndb object can handle at most 1024 parallel
  925.    *         transactions. 
  926.    * @return 0 if successful, -1 otherwise.
  927.    *
  928.    * @note   The internal implementation multiplies this value 
  929.    *         with 3.
  930.    */
  931.   int init(int maxNoOfTransactions = 4);
  932.   /**
  933.    * Wait for Ndb object to successfully set-up connections to 
  934.    * the NDB kernel. 
  935.    * Starting to use the Ndb object without using this method 
  936.    * gives unspecified behavior. 
  937.    * 
  938.    * @param  timeout  The maximum time we will wait for 
  939.    *                  the initiation process to finish.
  940.    *                  Timeout is expressed in seconds.
  941.    * @return  0: Ndb is ready and timeout has not occurred.<br>
  942.    *          -1: Timeout has expired
  943.    */
  944.   int waitUntilReady(int timeout = 60);
  945.   /** @} *********************************************************************/
  946.   /** 
  947.    * @name Meta Information
  948.    * @{
  949.    */
  950.   /**
  951.    * Query the database for schema information 
  952.    * (without performing any transaction).
  953.    *
  954.    * @return Object containing meta information about all tables 
  955.    *         in NDB Cluster.
  956.    */
  957.   class NdbDictionary::Dictionary* getDictionary() const;
  958.   
  959.   NdbEventOperation* createEventOperation(const char* eventName,
  960.   const int bufferLength);
  961.   int dropEventOperation(NdbEventOperation*);
  962.   void monitorEvent(NdbEventOperation *, NdbEventCallback, void*);
  963.   int pollEvents(int aMillisecondNumber);
  964.   /**
  965.    * Get the application node identity.  
  966.    *
  967.    * Each node (DB nodes, Applications, and Management Servers) 
  968.    * has its own node identity in the NDB Cluster.
  969.    * See documentation for the management server configuration file.
  970.    *
  971.    * @return Node id of this application.
  972.    */
  973.   int getNodeId();
  974.   /** @} *********************************************************************/
  975.   /** 
  976.    * @name Starting and Closing Transactions
  977.    * @{
  978.    */
  979.   /**
  980.    * This method returns an NdbConnection which caters for the transaction. 
  981.    * When the transaction is completed it must be closed. 
  982.    * The Ndb::closeTransaction also return the NdbConnection object 
  983.    * and all other memory related to the transaction. 
  984.    * Failure to close the transaction will lead to memory leakage. 
  985.    * The transaction must be closed independent of its outcome, i.e.
  986.    * even if there is an error.
  987.    * 
  988.    * NDB API can be hinted to select a particular transaction coordinator.
  989.    * The default method is round robin where each set of new transactions 
  990.    * is placed on the next NDB kernel node. 
  991.    * By providing a distribution key (usually the primary key
  992.    * of the mostly used table of the transaction) for a record
  993.    * the transaction will be placed on the node where the primary replica
  994.    * of that record resides. 
  995.    * Note that this is only a hint, the system can
  996.    * be under reconfiguration and then the NDB API 
  997.    * will use select the transaction coordinator without using 
  998.    * this hint.
  999.    *
  1000.    * Placing the transaction coordinator close
  1001.    * to the actual data used in the transaction can in many cases
  1002.    * improve performance significantly. This is particularly true for
  1003.    * systems using TCP/IP. A system using Solaris and a 500 MHz processor
  1004.    * has a cost model for TCP/IP communication which is:
  1005.    *
  1006.    *   30 microseconds + (100 nanoseconds * no of Bytes)
  1007.    *
  1008.    * This means that if we can ensure that we use "popular" links we increase
  1009.    * buffering and thus drastically reduce the communication cost.
  1010.    * Systems using SCI has a different cost model which is:
  1011.    *
  1012.    *   5 microseconds + (10 nanoseconds *  no of Bytes)
  1013.    *
  1014.    * Thus SCI systems are much less dependent on selection of 
  1015.    * transaction coordinators. 
  1016.    * Typically TCP/IP systems spend 30-60% of the time during communication,
  1017.    * whereas SCI systems typically spend 5-10% of the time during
  1018.    * communication. 
  1019.    * Thus SCI means that less care from the NDB API programmer is
  1020.    * needed and great scalability can be achieved even for applications using
  1021.    * data from many parts of the database.
  1022.    *
  1023.    * A simple example is an application that uses many simple updates where
  1024.    * a transaction needs to update one record. 
  1025.    * This record has a 32 bit primary key, 
  1026.    * which is also the distribution key. 
  1027.    * Then the keyData will be the address of the integer 
  1028.    * of the primary key and keyLen will be 4.
  1029.    *
  1030.    * @note Transaction priorities are not yet supported.
  1031.    *
  1032.    * @param  prio     The priority of the transaction.<br>
  1033.    *                  Priority 0 is the highest priority and is used
  1034.    *                  for short transactions with requirements on low delay.<br>
  1035.    *                  Priority 1 is a medium priority for short transactions.
  1036.    *                  <br>
  1037.    *                  Priority 2 is a medium priority for long transactions.<br>
  1038.    *                  Priority 3 is a low priority for long transactions.<br>
  1039.    *                  <em>This parameter is not currently used,
  1040.    *                      and can be set to any value</em>
  1041.    * @param  keyData  Pointer to distribution key
  1042.    * @param  keyLen   Length of distribution key expressed in bytes
  1043.    * 
  1044.    * @return NdbConnection object, or NULL if method failed.
  1045.    */
  1046.   NdbConnection* startTransaction(Uint32        prio = 0, 
  1047.   const char *  keyData = 0, 
  1048.   Uint32        keyLen = 0);
  1049.   /**
  1050.    * When a transactions is completed, the transaction has to be closed.
  1051.    *
  1052.    * @note It is not allowed to call Ndb::closeTransaction after sending the
  1053.    *       transaction asynchronously with either 
  1054.    *       Ndb::sendPreparedTransactions or
  1055.    *       Ndb::sendPollNdb before the callback method has been called.
  1056.    *       (The application should keep track of the number of 
  1057.    *       outstanding transactions and wait until all of them 
  1058.    *       has completed before calling Ndb::closeTransaction).
  1059.    *       If the transaction is not committed it will be aborted.
  1060.    */
  1061.   void closeTransaction(NdbConnection* aConnection);
  1062.   
  1063.   /** @} *********************************************************************/
  1064.   /** 
  1065.    * @name Asynchronous Transactions
  1066.    * @{
  1067.    */
  1068.   /**
  1069.    * Wait for prepared transactions.
  1070.    * Will return as soon as at least 'minNoOfEventsToWakeUp' 
  1071.    * of them have completed, or the maximum time given as timeout has passed.
  1072.    *
  1073.    * @param aMillisecondNumber Maximum time to wait for transactions
  1074.    *                           to complete.
  1075.    *                           Polling without wait is achieved by setting the 
  1076.    *                           timer to zero.
  1077.    *                           Time is expressed in milliseconds.
  1078.    * @param minNoOfEventsToWakeup Minimum number of transactions 
  1079.    *            which has to wake up before the poll-call will return.
  1080.    *            If minNoOfEventsToWakeup is
  1081.    *            set to a value larger than 1 then this is the minimum 
  1082.    *            number of transactions that need to complete before the 
  1083.    *            poll will return.
  1084.    *            Setting it to zero means that one should wait for all
  1085.    *            outstanding transactions to return before waking up.
  1086.    * @return Number of transactions polled.
  1087.    */
  1088.   int  pollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
  1089.       int minNoOfEventsToWakeup = 1);
  1090.   /**
  1091.    * This send method will send all prepared database operations. 
  1092.    * The default method is to do it non-force and instead
  1093.    * use the adaptive algorithm.  (See Section @ref secAdapt.)
  1094.    * The second option is to force the sending and 
  1095.    * finally there is the third alternative which is 
  1096.    * also non-force but also making sure that the 
  1097.    * adaptive algorithm do not notice the send. 
  1098.    * In this case the sending will be performed on a 
  1099.    * cyclical 10 millisecond event.
  1100.    *
  1101.    * @param forceSend When operations should be sent to NDB Kernel.
  1102.    *                  (See @ref secAdapt.)
  1103.    *                  - 0: non-force, adaptive algorithm notices it (default); 
  1104.    *                  - 1: force send, adaptive algorithm notices it; 
  1105.    *                  - 2: non-force, adaptive algorithm do not notice the send.
  1106.    */
  1107.   void sendPreparedTransactions(int forceSend = 0);
  1108.   /**
  1109.    * This is a send-poll variant that first calls 
  1110.    * Ndb::sendPreparedTransactions and then Ndb::pollNdb. 
  1111.    * It is however somewhat faster than calling the methods 
  1112.    * separately, since some mutex-operations are avoided. 
  1113.    * See documentation of Ndb::pollNdb and Ndb::sendPreparedTransactions
  1114.    * for more details.
  1115.    *
  1116.    * @param aMillisecondNumber Timeout specifier
  1117.    *            Polling without wait is achieved by setting the 
  1118.    *            millisecond timer to zero.
  1119.    * @param minNoOfEventsToWakeup Minimum number of transactions 
  1120.    *            which has to wake up before the poll-call will return.
  1121.    *            If minNoOfEventsToWakeup is
  1122.    *            set to a value larger than 1 then this is the minimum 
  1123.    *            number of transactions that need to complete before the 
  1124.    *            poll-call will return.
  1125.    *            Setting it to zero means that one should wait for all
  1126.    *            outstanding transactions to return before waking up.
  1127.    * @param forceSend When operations should be sent to NDB Kernel.
  1128.    *                  (See @ref secAdapt.)
  1129.    * - 0: non-force, adaptive algorithm notices it (default); 
  1130.    * - 1: force send, adaptive algorithm notices it; 
  1131.    * - 2: non-force, adaptive algorithm does not notice the send.
  1132.    * @return Number of transactions polled.
  1133.    */
  1134.   int  sendPollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
  1135.    int minNoOfEventsToWakeup = 1,
  1136.    int forceSend = 0);
  1137.   
  1138.   /** @} *********************************************************************/
  1139.   /** 
  1140.    * @name Error Handling
  1141.    * @{
  1142.    */
  1143.   /**
  1144.    * Get the NdbError object
  1145.    *
  1146.    * The NdbError object is valid until you call a new NDB API method.
  1147.    */
  1148.   const NdbError & getNdbError() const;
  1149.   
  1150.   /**
  1151.    * Get a NdbError object for a specific error code
  1152.    *
  1153.    * The NdbError object is valid until you call a new NDB API method.
  1154.    */
  1155.   const NdbError & getNdbError(int errorCode);
  1156.   /**
  1157.    * setConnectString
  1158.    * @param connectString - the connectString has the following format:
  1159.    * @code
  1160.    * "nodeid=<ID>;host=host://<HOSTNAME>:<PORT>;
  1161.    *  host=host://<HOSTNAME2>:<PORT>;..."
  1162.    * @endcode
  1163.    * or
  1164.    * @code
  1165.    * "nodeid=<ID>;host=<HOSTNAME>:<PORT>;host=<HOSTNAME2>:<PORT>;..."
  1166.    * @endcode
  1167.    */
  1168.   static void setConnectString(const char * connectString);
  1169.   bool usingFullyQualifiedNames();
  1170.   /** @} *********************************************************************/
  1171. #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  1172.   /**
  1173.    * Different types of tampering with the NDB Cluster.
  1174.    * <b>Only for debugging purposes only.</b>
  1175.    */
  1176.   enum TamperType { 
  1177.     LockGlbChp = 1,               ///< Lock GCP
  1178.     UnlockGlbChp,                 ///< Unlock GCP
  1179.     CrashNode,                    ///< Crash an NDB node
  1180.     ReadRestartGCI,               ///< Request the restart GCI id from NDB Cluster
  1181.     InsertError                   ///< Execute an error in NDB Cluster 
  1182.                                   ///< (may crash system)
  1183.   };
  1184.   /**
  1185.    * For testing purposes it is possible to tamper with the NDB Cluster
  1186.    * (i.e. send a special signal to DBDIH, the NDB distribution handler).
  1187.    * <b>This feature should only used for debugging purposes.</b>
  1188.    * In a release versions of NDB Cluster,
  1189.    * this call always return -1 and does nothing.
  1190.    * 
  1191.    * @param aAction Action to be taken according to TamperType above
  1192.    *
  1193.    * @param aNode  Which node the action will be taken
  1194.    *              -1:   Master DIH.
  1195.    *            0-16:   Nodnumber.
  1196.    * @return -1 indicates error, other values have meaning dependent 
  1197.    *          on type of tampering.
  1198.    */
  1199.   int NdbTamper(TamperType aAction, int aNode);  
  1200. #endif
  1201. #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  1202.   /**
  1203.    * Return a unique tuple id for a table.  The id sequence is
  1204.    * ascending but may contain gaps.
  1205.    *
  1206.    * @param aTableName table name
  1207.    *
  1208.    * @param cacheSize number of values to cache in this Ndb object
  1209.    *
  1210.    * @return tuple id or 0 on error
  1211.    */
  1212.   Uint64 getAutoIncrementValue(const char* aTableName, 
  1213.        Uint32 cacheSize = 1);
  1214.   Uint64 getAutoIncrementValue(const NdbDictionary::Table * aTable, 
  1215.        Uint32 cacheSize = 1);
  1216.   Uint64 readAutoIncrementValue(const char* aTableName);
  1217.   Uint64 readAutoIncrementValue(const NdbDictionary::Table * aTable);
  1218.   bool setAutoIncrementValue(const char* aTableName, Uint64 val, 
  1219.      bool increase = false);
  1220.   bool setAutoIncrementValue(const NdbDictionary::Table * aTable, Uint64 val, 
  1221.      bool increase = false);
  1222.   Uint64 getTupleIdFromNdb(const char* aTableName, 
  1223.    Uint32 cacheSize = 1000);
  1224.   Uint64 getTupleIdFromNdb(Uint32 aTableId, 
  1225.    Uint32 cacheSize = 1000);
  1226.   Uint64 readTupleIdFromNdb(Uint32 aTableId);
  1227.   bool setTupleIdInNdb(const char* aTableName, Uint64 val, 
  1228.        bool increase);
  1229.   bool setTupleIdInNdb(Uint32 aTableId, Uint64 val, bool increase);
  1230.   Uint64 opTupleIdOnNdb(Uint32 aTableId, Uint64 opValue, Uint32 op);
  1231. #endif
  1232. #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  1233.   /**
  1234.    */
  1235.   NdbConnection* hupp( NdbConnection* );
  1236.   Uint32 getReference() const { return theMyRef;}
  1237.   struct Free_list_usage
  1238.   {
  1239.     const char * m_name;
  1240.     Uint32 m_created;
  1241.     Uint32 m_free;
  1242.     Uint32 m_sizeof;
  1243.   };
  1244.   Free_list_usage * get_free_list_usage(Free_list_usage*);
  1245. #endif
  1246.   
  1247. /*****************************************************************************
  1248.  * These are service routines used by the other classes in the NDBAPI.
  1249.  ****************************************************************************/
  1250. private:
  1251.   
  1252.   void setup(Ndb_cluster_connection *ndb_cluster_connection,
  1253.      const char* aCatalogName, const char* aSchemaName);
  1254.   void connected(Uint32 block_reference);
  1255.  
  1256.   NdbConnection*  startTransactionLocal(Uint32 aPrio, Uint32 aFragmentId); 
  1257. // Connect the connection object to the Database.
  1258.   int NDB_connect(Uint32 tNode);
  1259.   NdbConnection* doConnect(Uint32 nodeId); 
  1260.   void    doDisconnect();  
  1261.   
  1262.   NdbReceiver*         getNdbScanRec();// Get a NdbScanReceiver from idle list
  1263.   NdbLabel* getNdbLabel(); // Get a NdbLabel from idle list
  1264.   NdbBranch*            getNdbBranch(); // Get a NdbBranch from idle list
  1265.   NdbSubroutine* getNdbSubroutine();// Get a NdbSubroutine from idle
  1266.   NdbCall* getNdbCall(); // Get a NdbCall from idle list
  1267.   NdbApiSignal*         getSignal(); // Get an operation from idle list
  1268.   NdbRecAttr*         getRecAttr(); // Get a receeive attribute object from
  1269. // idle list of the Ndb object.
  1270.   NdbOperation*  getOperation(); // Get an operation from idle list
  1271.   NdbIndexScanOperation* getScanOperation(); // Get a scan operation from idle
  1272.   NdbIndexOperation*  getIndexOperation();// Get an index operation from idle
  1273.   class NdbGlobalEventBufferHandle* getGlobalEventBufferHandle();
  1274.   NdbBlob*              getNdbBlob();// Get a blob handle etc
  1275.   void releaseSignal(NdbApiSignal* anApiSignal);
  1276.   void                  releaseSignalsInList(NdbApiSignal** pList);
  1277.   void releaseNdbScanRec(NdbReceiver* aNdbScanRec);
  1278.   void releaseNdbLabel(NdbLabel* anNdbLabel);
  1279.   void releaseNdbBranch(NdbBranch* anNdbBranch);
  1280.   void releaseNdbSubroutine(NdbSubroutine* anNdbSubroutine);
  1281.   void releaseNdbCall(NdbCall* anNdbCall);
  1282.   void releaseRecAttr (NdbRecAttr* aRecAttr);
  1283.   void   releaseOperation(NdbOperation* anOperation);
  1284.   void   releaseScanOperation(NdbIndexScanOperation*);
  1285.   void                  releaseNdbBlob(NdbBlob* aBlob);
  1286.   void                  check_send_timeout();
  1287.   void                  remove_sent_list(Uint32);
  1288.   Uint32                insert_completed_list(NdbConnection*);
  1289.   Uint32                insert_sent_list(NdbConnection*);
  1290.   // Handle a received signal. Used by both
  1291.   // synchronous and asynchronous interface
  1292.   void handleReceivedSignal(NdbApiSignal* anApiSignal, struct LinearSectionPtr ptr[3]);
  1293.   
  1294.   // Receive response signals
  1295.   int receiveResponse(int waitTime = WAITFOR_RESPONSE_TIMEOUT);
  1296.   int sendRecSignal(Uint16 aNodeId,
  1297.       Uint32 aWaitState,
  1298.       NdbApiSignal* aSignal,
  1299.                                       Uint32 nodeSequence);
  1300.   
  1301.   // Sets Restart GCI in Ndb object
  1302.   void RestartGCI(int aRestartGCI);
  1303.   // Get block number of this NDBAPI object
  1304.   int getBlockNumber();
  1305.   
  1306.   /****************************************************************************
  1307.    * These are local service routines used by this class.
  1308.    ***************************************************************************/
  1309.   
  1310.   int createConIdleList(int aNrOfCon);
  1311.   int  createOpIdleList( int nrOfOp );
  1312.   void freeOperation();          // Free the first idle operation.
  1313.   void freeScanOperation();      // Free the first idle scan operation.
  1314.   void freeIndexOperation();     // Free the first idle index operation.
  1315.   void freeNdbCon(); // Free the first idle connection.
  1316.   void freeSignal(); // Free the first idle signal
  1317.   void freeRecAttr(); // Free the first idle receive attr obj
  1318.   void freeNdbLabel(); // Free the first idle NdbLabel obj
  1319.   void freeNdbBranch();// Free the first idle NdbBranch obj
  1320.   void freeNdbSubroutine();// Free the first idle NdbSubroutine obj
  1321.   void freeNdbCall();     // Free the first idle NdbCall obj
  1322.   void freeNdbScanRec();   // Free the first idle NdbScanRec obj
  1323.   void  freeNdbBlob();      // Free the first etc
  1324.   NdbConnection* getNdbCon(); // Get a connection from idle list
  1325.   
  1326.   /**
  1327.    * Get a connected NdbConnection to nodeId
  1328.    *   Returns NULL if none found
  1329.    */
  1330.   NdbConnection* getConnectedNdbConnection(Uint32 nodeId);
  1331.   // Release and disconnect from DBTC a connection
  1332.   // and seize it to theConIdleList
  1333.   void releaseConnectToNdb (NdbConnection* aConnectConnection);
  1334.   // Release a connection to idle list
  1335.   void  releaseNdbCon (NdbConnection* aConnection);
  1336.   
  1337.   int checkInitState(); // Check that we are initialized
  1338.   void report_node_failure(Uint32 node_id);           // Report Failed node
  1339.   void report_node_failure_completed(Uint32 node_id); // Report Failed node(NF comp.)
  1340.   void checkFailedNode(); // Check for failed nodes
  1341.   int   NDB_connect();     // Perform connect towards NDB Kernel
  1342.   // Release arrays of NdbConnection pointers
  1343.   void  releaseTransactionArrays();     
  1344.   Uint32  pollCompleted(NdbConnection** aCopyArray);
  1345.   void    sendPrepTrans(int forceSend);
  1346.   void    reportCallback(NdbConnection** aCopyArray, Uint32 aNoOfComplTrans);
  1347.   void    waitCompletedTransactions(int milliSecs, int noOfEventsToWaitFor);
  1348.   void    completedTransaction(NdbConnection* aTransaction);
  1349.   void    completedScanTransaction(NdbConnection* aTransaction);
  1350.   void    abortTransactionsAfterNodeFailure(Uint16 aNodeId);
  1351.   static
  1352.   const char * externalizeTableName(const char * internalTableName, bool fullyQualifiedNames);
  1353.   const char * externalizeTableName(const char * internalTableName);
  1354.   const char * internalizeTableName(const char * externalTableName);
  1355.   static
  1356.   const char * externalizeIndexName(const char * internalIndexName, bool fullyQualifiedNames);
  1357.   const char * externalizeIndexName(const char * internalIndexName);
  1358.   const char * internalizeIndexName(const NdbTableImpl * table,
  1359.     const char * externalIndexName);
  1360.   static
  1361.   const BaseString getDatabaseFromInternalName(const char * internalName);
  1362.   static 
  1363.   const BaseString getSchemaFromInternalName(const char * internalName);
  1364.   void*              int2void     (Uint32 val);
  1365.   NdbReceiver*       void2rec     (void* val);
  1366.   NdbConnection*     void2con     (void* val);
  1367.   NdbOperation*      void2rec_op  (void* val);
  1368.   NdbIndexOperation* void2rec_iop (void* val);
  1369. /******************************************************************************
  1370.  * These are the private variables in this class.
  1371.  *****************************************************************************/
  1372.   NdbConnection**       thePreparedTransactionsArray;
  1373.   NdbConnection**       theSentTransactionsArray;
  1374.   NdbConnection**       theCompletedTransactionsArray;
  1375.   Uint32                theNoOfPreparedTransactions;
  1376.   Uint32                theNoOfSentTransactions;
  1377.   Uint32                theNoOfCompletedTransactions;
  1378.   Uint32                theNoOfAllocatedTransactions;
  1379.   Uint32                theMaxNoOfTransactions;
  1380.   Uint32                theMinNoOfEventsToWakeUp;
  1381.   Uint32                theNextConnectNode;
  1382.   bool fullyQualifiedNames;
  1383.   // Ndb database name.
  1384.   char                  theDataBase[NDB_MAX_DATABASE_NAME_SIZE];
  1385.   // Ndb database schema name.  
  1386.   char                  theDataBaseSchema[NDB_MAX_SCHEMA_NAME_SIZE];
  1387.   char                  prefixName[NDB_MAX_INTERNAL_TABLE_LENGTH];
  1388.   char *                prefixEnd;
  1389.   class NdbImpl * theImpl;
  1390.   class NdbDictionaryImpl* theDictionary;
  1391.   class NdbGlobalEventBufferHandle* theGlobalEventBufferHandle;
  1392.   NdbConnection* theTransactionList;
  1393.   NdbConnection**       theConnectionArray;
  1394.   Uint32   theMyRef;        // My block reference  
  1395.   Uint32   theNode;         // The node number of our node
  1396.   
  1397.   Uint64               the_last_check_time;
  1398.   Uint64               theFirstTransId;
  1399.   
  1400.   // The tupleId is retreived from DB the 
  1401.   // tupleId is unique for each tableid. 
  1402.   Uint64               theFirstTupleId[2048]; 
  1403.   Uint64               theLastTupleId[2048];           
  1404.   Uint32 theRestartGCI; // the Restart GCI used by DIHNDBTAMPER
  1405.   
  1406.   NdbError              theError;
  1407.   Int32                 theNdbBlockNumber;
  1408.   enum InitType {
  1409.     NotConstructed,
  1410.     NotInitialised,
  1411.     StartingInit,
  1412.     Initialised,
  1413.     InitConfigError
  1414.   } theInitState;
  1415.   NdbApiSignal* theCommitAckSignal;
  1416. #ifdef POORMANSPURIFY
  1417.   int cfreeSignals;
  1418.   int cnewSignals;
  1419.   int cgetSignals;
  1420.   int creleaseSignals;
  1421. #endif
  1422.   static void executeMessage(void*, NdbApiSignal *, 
  1423.      struct LinearSectionPtr ptr[3]);
  1424.   static void statusMessage(void*, Uint32, bool, bool);
  1425. #ifdef VM_TRACE
  1426.   void printState(const char* fmt, ...);
  1427. #endif
  1428. };
  1429. #endif