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

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 DBA User Guide
  15.  *
  16.  * @section secIntro Introduction
  17.  * DBA is an API to access the NDB Cluster.
  18.  * 
  19.  * DBA supports transactions using an asynchronous execution model.
  20.  * Everything but transactions is synchronous.
  21.  *
  22.  * DBA uses the concept of bindings to simplify database access.
  23.  * A <em>binding</em> is a relation between a database table and 
  24.  * one or several C structs.
  25.  * A binding is created initially and then used multiple time during
  26.  * application execution.
  27.  *
  28.  * Each of the data accessing functions in DBA is implemented as a
  29.  * transaction, i.e. the call will either fully complete or 
  30.  * nothing happens (the transaction fails).
  31.  *
  32.  * DBA also supports "read as much as possible" with bulk read.
  33.  * With bulk read the application can specify a set of primary keys and 
  34.  * try to read all of the corresponding rows. The bulk read will not fail 
  35.  * if a row does not exist but will instead inform the application using a 
  36.  * RowFoundIndicator variable.
  37.  *
  38.  * A <em>request</em> is a transaction or a bulk read.
  39.  *
  40.  * @section secError Error Handling
  41.  * When a synchronous method in DBA fails these methods are applicable:
  42.  * -# DBA_GetLatestError()
  43.  * -# DBA_GetLatestNdbError()
  44.  * -# DBA_GetLatestErrorMsg()
  45.  *
  46.  * The DBA_GetLatestErrorMsg() will then return a description of 
  47.  * what has failed.
  48.  *
  49.  * For asynchronous methods the application should:
  50.  * -# check that the RequestId returned by function is not 
  51.  *    @ref DBA_INVALID_REQID
  52.  * -# check Status supplied in callback (see @ref DBA_AsyncCallbackFn_t)
  53.  * 
  54.  * If @ref DBA_INVALID_REQID is returned, 
  55.  * the details of error can be found using
  56.  * "latest"-functions.
  57.  *
  58.  * If error is indicated in callback (using Status), when the 
  59.  * "latest"-functions are <b>NOT</b> applicable.
  60.  *
  61.  * @section secExamples Example Programs
  62.  *
  63.  * - @ref common.hpp
  64.  * - @ref basic.cpp
  65.  * - @ref br_test.cpp
  66.  * - @ref ptr_binding_test.cpp
  67.  *
  68.  */
  69. /**
  70.  * @page basic.cpp basic.cpp
  71.  * @include basic.cpp 
  72.  */
  73. /**
  74.  * @page common.hpp common.hpp
  75.  * @include common.hpp
  76.  */
  77. /**
  78.  * @page br_test.cpp br_test.cpp
  79.  * @include br_test.cpp 
  80.  */
  81. /**
  82.  * @page ptr_binding_test.cpp ptr_binding_test.cpp 
  83.  * @include ptr_binding_test.cpp 
  84.  */
  85. /** @addtogroup DBA
  86.  *  @{
  87.  */
  88. /****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/
  89. #ifndef DBA_H
  90. #define DBA_H
  91. /* --- Include files ---- */
  92. #include <ndb_global.h>
  93. #include <defs/pcn_types.h>
  94. /* --- Types and definitions --- */
  95. /**
  96.  * Possible error status for DBA functions.
  97.  */
  98. typedef enum {
  99.   DBA_NO_ERROR = 0,         /**< Success */
  100.     
  101.   DBA_NOT_IMPLEMENTED = -1, /**< Function not implemented */
  102.   DBA_NDB_ERROR = -2,       /**< Uncategorised error from NDB */
  103.   DBA_ERROR = -3,           /**< Uncategorised error from DBA implementation */
  104.   
  105.   DBA_APPLICATION_ERROR = 1,    /**< Function called with invalid argument(s)
  106.    or other application errors */
  107.   DBA_NO_DATA = 2,              /**< No row with specified PK existed */
  108.   DBA_CONSTRAINT_VIOLATION = 3, /**< There already exists a row with that PK*/ 
  109.   
  110.   DBA_SCHEMA_ERROR = 4,        /**< Table already exists */
  111.   DBA_INSUFFICIENT_SPACE = 5,  /**< The DB is full */
  112.   DBA_TEMPORARY_ERROR = 6,     /**< Some temporary problem occured */
  113.   DBA_TIMEOUT = 7,             /**< The request timed out, probably due to 
  114.   dead-lock */
  115.   DBA_OVERLOAD = 8,            /**< The DB is overloaded */
  116.   DBA_UNKNOWN_RESULT = 9       /**< It is unknown wheater transaction was
  117.   commited or aborted */
  118. } DBA_Error_t;
  119. /**
  120.  * Error code. This is the error code that is returned by NDB.
  121.  * Not to be confused by the status returned by the DBA implementation.
  122.  */
  123. typedef int DBA_ErrorCode_t;
  124. /**
  125.  * DBA column types
  126.  */
  127. typedef enum {
  128.   DBA_CHAR,                      /**< String */
  129.   DBA_INT                        /**< Integer */
  130. } DBA_DataTypes_t;
  131. /**
  132.  * Column description.
  133.  * Used for creating tables.
  134.  */
  135. typedef struct DBA_ColumnDesc {
  136.   
  137.     const char*      Name;       /**< Name of table column */
  138.     DBA_DataTypes_t  DataType;   /**< Datatype of table column*/
  139.     Size_t           Size;       /**< Column size in bytes */
  140.     Boolean_t        IsKey;      /**< True if column is part of primary key */
  141. } DBA_ColumnDesc_t;
  142. /**
  143.  * Used to simplify binding definitions. See @ref DBA_ColumnBinding
  144.  * for example.
  145.  * 
  146.  * @param ColName Name of column in db table
  147.  * @param Type Column/field type.
  148.  * @param Struct Structure
  149.  * @param Field Field in structure
  150.  * @return Arg list for defining binding of type @ref DBA_Binding_t
  151.  */
  152. #define DBA_BINDING( ColName, Type, Struct, Field ) 
  153.    { ColName, Type, PCN_SIZE_OF( Struct, Field ), 
  154.      PCN_OFFSET_OF( Struct, Field ), 0, 0 }
  155. /**
  156.  * Used to simplify ptr binding definitions. See @ref DBA_ColumnBinding
  157.  * for example.
  158.  * 
  159.  * @param Struct Structure
  160.  * @param Field Field in structure
  161.  * @return Arg list for defining binding of type @ref DBA_Binding_t
  162.  */
  163. #define DBA_BINDING_PTR(Struct, Field, ColBindings, NbCBindings) 
  164.    { 0, DBA_CHAR, NbCBindings, PCN_OFFSET_OF( Struct, Field ), 
  165.      1, ColBindings }
  166. /**
  167.  * The @ref DBA_ColumnBinding_t is used to describe a binding between one
  168.  * column and one field of a C struct.
  169.  *
  170.  *<pre>
  171.  * typedef struct Address {
  172.  *   char StreetName[30];
  173.  *   int  StreetNumber;
  174.  * } Address_t;
  175.  *
  176.  * typdef struct Person {
  177.  *   char        Name[30];
  178.  *   Address_t * AddressPtr;
  179.  * } Person_t; </pre>
  180.  *
  181.  *
  182.  * For example, if the field Name of a Person_t data structure is
  183.  * bound to the column "NAME", the corresponding binding would be
  184.  * defined as:
  185.  *
  186.  *<pre>
  187.  * DBA_ColumnBinding_t NameBinding =
  188.  *   DBA_BINDING( "name", DBA_CHAR, Person_t, Name ); </pre>
  189.  *
  190.  *
  191.  * There is also the @ref DBA_BINDING_PTR which is used when 
  192.  * several linked structures should be put into one table.
  193.  *
  194.  * For example, if data in a Person_t data structure should be saved
  195.  * in the same table as the Address_t data structure 
  196.  * (as the address belongs to the person), the corresponding binding would be
  197.  * defined as:
  198.  *
  199.  *<pre>
  200.  * DBA_ColumnBinding_t AddrBinding[AddrLen]; This binding describes how the 
  201.  *                                            fields in the Address_t 
  202.  *                                            structure is linked to the 
  203.  *                                            table PERSON_ADDRESS
  204.  *
  205.  * DBA_ColumnBinding_t AddressBinding = 
  206.  *   DBA_BINDING_PTR(Person_t, AddressPtr, AddrBinding, AddrLen); </pre>
  207.  *
  208.  *
  209.  */
  210. struct DBA_ColumnBinding {
  211.   const char*                Name;      /**< Name of table column */
  212.   DBA_DataTypes_t            DataType;  /**< Type of member in structure */
  213.   Size_t                     Size;      /**< Size in bytes of member
  214.    or no of @ref DBA_ColumnBinding's 
  215.    when doing ptr binding */
  216.   Size_t                     Offset;    /**< Offset of the member */
  217.   
  218.   Boolean_t                  Ptr;       /**< True if binding is of ptr type */
  219.   const struct DBA_ColumnBinding * SubBinding;  /**< Address of Binding Ptr 
  220.    valid if Ptr is true */
  221. };
  222. /**
  223.  * Typedef: @ref DBA_ColumnBinding
  224.  */
  225. typedef struct DBA_ColumnBinding DBA_ColumnBinding_t;
  226. /**
  227.  * A @ref DBA_Binding_t object is used to establish a binding between 
  228.  * one or more columns of a table to the fields of C structs.
  229.  *
  230.  * It is used with insert, and update and read transactions to define
  231.  * on which columns of the table the operations is performed, and to
  232.  * which members of a C data structure they map.
  233.  *
  234.  * All key columns must be bound to a field of the struct.
  235.  *
  236.  * The function @ref DBA_CreateBinding is used to create this binding.
  237.  */
  238. typedef struct DBA_Binding DBA_Binding_t;
  239. /* --- Exported functions --- */
  240. /**
  241.  * Set DBA configuration parameter
  242.  *<pre>
  243.  * Id Description                 Default Min  Max
  244.  * == =========================== ======= ==== ====
  245.  * 0  NBP Interval                   10    4   -
  246.  * 1  Operations/Bulkread          1000    1   5000
  247.  * 2  Start transaction timeout       0    0   -
  248.  * 3  Force send algorithm            1    0   2
  249.  *</pre>
  250.  * @return Status
  251.  */
  252. DBA_Error_t DBA_SetParameter(int ParameterId, int Value);
  253. /**
  254.  * Set DBA configuration parameter.
  255.  * See @ref DBA_SetParameter for description of parameters.
  256.  *
  257.  * @return Status
  258.  */
  259. DBA_Error_t DBA_GetParameter(int ParameterId, int * Value);
  260. /**
  261.  * Initialize DBA library and connect to NDB Cluster.
  262.  *
  263.  * @return Status
  264.  */
  265. DBA_Error_t DBA_Open( ); 
  266. /**
  267.  * Close connection to NDB cluster and free allocated memory.
  268.  * 
  269.  * @return Error status
  270.  */
  271. DBA_Error_t DBA_Close(void); 
  272. /**
  273.  * Get latest DBA error.
  274.  *
  275.  * @note Only applicable to synchronous methods
  276.  */
  277. DBA_Error_t DBA_GetLatestError();
  278. /**
  279.  * Get latest NDB error.
  280.  *
  281.  * @note Only applicable to synchronous methods
  282.  */
  283. DBA_ErrorCode_t DBA_GetLatestNdbError();
  284. /**
  285.  * Get latest error string associated with DBA_GetLatestError().
  286.  *
  287.  * @note String must not be free by caller of this method.
  288.  * @note Only applicable to synchronous methods.
  289.  */
  290. const char * DBA_GetLatestErrorMsg();
  291. /**
  292.  * Get error msg associated with code
  293.  *
  294.  * @note String must not be free by caller of this method
  295.  */
  296. const char * DBA_GetErrorMsg(DBA_Error_t);
  297. /**
  298.  * Get error msg associated with code
  299.  *
  300.  * @note String must not be free by caller of this method
  301.  */
  302. const char * DBA_GetNdbErrorMsg(DBA_ErrorCode_t);
  303. /**
  304.  * Create a table.
  305.  * 
  306.  * @param TableName Name of table to create.
  307.  * @param NbColumns numbers of columns.
  308.  * @param Columns Column descriptions.
  309.  * @return Status.
  310.  */
  311. DBA_Error_t 
  312. DBA_CreateTable( const char* TableName, int NbColumns, 
  313.  const DBA_ColumnDesc_t Columns[] );
  314. /**
  315.  * Destroy a table.
  316.  * 
  317.  * @param TableName Table name.
  318.  * @return Status.
  319.  * @note Not implemented
  320.  */
  321. DBA_Error_t 
  322. DBA_DropTable( const char* TableName );
  323. /**
  324.  * Test for existence of a table.
  325.  * 
  326.  * @param TableName Table name.
  327.  * @return Boolean value indicating if table exists or not.
  328.  */
  329. Boolean_t 
  330. DBA_TableExists( const char* TableName );
  331. /**
  332.  * Define a binding between the columns of a table and a C structure.
  333.  * 
  334.  * @param TableName table
  335.  * @param NbCol number of columns bindings
  336.  * @param ColBinding bindings
  337.  * @param StructSz Sizeof structure.
  338.  * @return Created binding, or NULL if binding could not be created.
  339.  */
  340. DBA_Binding_t*
  341. DBA_CreateBinding( const char* TableName, 
  342.     int NbCol, const DBA_ColumnBinding_t ColsBinding[], 
  343.     Size_t StructSz );
  344. /**
  345.  * Destroys a @ref DBA_Binding_t allocated with @ref
  346.  * DBA_CreateBinding.  
  347.  *
  348.  * @param pBinding Pointer to binding.
  349.  * @return Status.
  350.  */
  351. DBA_Error_t 
  352. DBA_DestroyBinding( DBA_Binding_t* Binding );
  353. /**
  354.  * Used to identify a pending db request
  355.  */
  356. typedef long DBA_ReqId_t;
  357. /**
  358.  * An asynchronous call returning this means that the function was called
  359.  * with invalid arguments. The application should check error status
  360.  * with DBA_GetLatestError() etc.
  361.  */
  362. #define DBA_INVALID_REQID 0
  363. /**
  364.  * Callback function for transactions. 
  365.  * Will be called in NBP process (Newton Batch Process).
  366.  *
  367.  * @note The implementation of the callback function is not allowed to
  368.  * make an asynchronous database call.
  369.  *
  370.  * @param ReqId Request identifier
  371.  * @param Status Status of the request 
  372.  * @param ErrorCode Error code given by NDB
  373.  * @see DBA_Error_t
  374.  */
  375. typedef void (*DBA_AsyncCallbackFn_t)( DBA_ReqId_t ReqId,
  376.        DBA_Error_t Status,
  377.        DBA_ErrorCode_t ErrorCode );
  378. /**
  379.  * Insert row(s) in the table (one transaction)
  380.  * 
  381.  * @param pBinding Binding between table columns and struct fields.
  382.  * @param pData Array of pointers to structures. 
  383.  * @param NbRows No of rows to insert (i.e. length of pData array)
  384.  * @return Request identifier
  385.  *
  386.  * @note All the table columns must be part of the binding.
  387.  */
  388. DBA_ReqId_t
  389. DBA_InsertRows( const DBA_Binding_t* pBinding, const void * const pData[],
  390. int NbRows,
  391. DBA_AsyncCallbackFn_t CbFunc );
  392. /**
  393.  * Insert row(s) in the table (one transaction)
  394.  * 
  395.  * @param pBinding Binding between table columns and struct fields.
  396.  * @param pData Array of structures. 
  397.  * @param NbRows No of rows to insert (i.e. length of pData array)
  398.  * @return Request identifier
  399.  *
  400.  * @note All the table columns must be part of the binding.
  401.  */
  402. DBA_ReqId_t
  403. DBA_ArrayInsertRows( const DBA_Binding_t* pBinding, const void * pData,
  404.      int NbRows,
  405.      DBA_AsyncCallbackFn_t CbFunc );
  406. /**
  407.  * Update row(s) in the table (one transaction)
  408.  * 
  409.  * @param pBinding Binding between table columns and struct fields.
  410.  * @param pData Array of pointers to structures. Fields that are part of the 
  411.  *              key are used to generate the where clause, the
  412.  *              other fields are used to update the row.
  413.  * @param NbRows No of rows to update (i.e. length of pData array).
  414.  * @return Request identifier
  415.  */
  416. DBA_ReqId_t
  417. DBA_UpdateRows( const DBA_Binding_t* pBinding, const void * const pData[],
  418. int NbRows,
  419. DBA_AsyncCallbackFn_t CbFunc );
  420. /**
  421.  * Update row(s) in the table (one transaction)
  422.  * 
  423.  * @param pBinding Binding between table columns and struct fields.
  424.  * @param pData Array of structures. Fields that are part of the 
  425.  *              key are used to generate the where clause, the
  426.  *              other fields are used to update the row.
  427.  * @param NbRows No of rows to update (i.e. length of pData array).
  428.  * @return Request identifier
  429.  */
  430. DBA_ReqId_t
  431. DBA_ArrayUpdateRows( const DBA_Binding_t* pBinding, const void * pData,
  432.      int NbRows,
  433.      DBA_AsyncCallbackFn_t CbFunc );
  434. /**
  435.  * Delete row(s) from the table (one transaction)
  436.  * 
  437.  * @param pBinding Binding between table columns and struct fields.
  438.  * @param pData Array of pointers to structures. 
  439.  *              Only fields part of the primary key needs to be set.
  440.  * @param NbRows No of rows to delete (i.e. length of pData array)
  441.  * @return Request identifier
  442.  */
  443. DBA_ReqId_t
  444. DBA_DeleteRows( const DBA_Binding_t* pBinding, const void * const pData[],
  445. int NbRows,
  446. DBA_AsyncCallbackFn_t CbFunc );
  447. /**
  448.  * Delete row(s) from the table (one transaction)
  449.  * 
  450.  * @param pBinding Binding between table columns and struct fields.
  451.  * @param pData Array of structures. Only fields part of the primary
  452.  *              key needs to be set.
  453.  * @param NbRows No of rows to delete (i.e. length of pData array)
  454.  * @return Request identifier
  455.  */
  456. DBA_ReqId_t
  457. DBA_ArrayDeleteRows( const DBA_Binding_t* pBinding, const void * pData,
  458.      int NbRows,
  459.      DBA_AsyncCallbackFn_t CbFunc );
  460. /**
  461.  * Updates/Inserts row(s) in the table (one transaction)
  462.  * 
  463.  * @param pBinding Binding between table columns and struct fields.
  464.  * @param pData Array of pointers to structures.
  465.  * @param NbRows No of rows to update/insert (i.e. length of pData array)
  466.  * @return Request identifier
  467.  * @note All the table columns must be part of the binding.
  468.  */
  469. DBA_ReqId_t
  470. DBA_WriteRows( const DBA_Binding_t* pBinding, const void * const pData[],
  471.        int NbRows,
  472.        DBA_AsyncCallbackFn_t CbFunc );
  473. /**
  474.  * Update/Insert row(s) in the table (one transaction)
  475.  * 
  476.  * @param pBinding Binding between table columns and struct fields.
  477.  * @param pData Array of structures. 
  478.  * @param NbRows No of rows to update/insert (i.e. length of pData array)
  479.  * @return Request identifier
  480.  * @note All the table columns must be part of the binding.
  481.  */
  482. DBA_ReqId_t
  483. DBA_ArrayWriteRows( const DBA_Binding_t* pBinding, const void * pData,
  484.     int NbRows,
  485.     DBA_AsyncCallbackFn_t CbFunc );
  486. /**
  487.  * Read row(s) from a table of the database (one transaction)
  488.  * 
  489.  * @param pBinding Binding between table columns and struct fields.
  490.  * @param pData Array of pointers to structures. 
  491.  *              Only fields part of the primary key needs to be set.
  492.  *              The other fields in the binding will be populated.
  493.  * @param NbRows No of rows to read (i.e. length of pData array)
  494.  * @return Request identifier
  495.  */
  496. DBA_ReqId_t
  497. DBA_ReadRows( const DBA_Binding_t* pBinding, void * const pData[],
  498.       int NbRows,
  499.       DBA_AsyncCallbackFn_t CbFunc );
  500. /**
  501.  * Read row(s) from a table of the database (one transaction)
  502.  * 
  503.  * @param pBinding Binding between table columns and struct fields.
  504.  * @param pData Array of structures. 
  505.  *              Only fields part of the primary key needs to be set.
  506.  *              The other fields in the binding will be populated.
  507.  * @param NbRows No of rows to read (i.e. length of pData array)
  508.  * @return Request identifier
  509.  */
  510. DBA_ReqId_t
  511. DBA_ArrayReadRows( const DBA_Binding_t* pBinding, void * pData,
  512.    int NbRows,
  513.    DBA_AsyncCallbackFn_t CbFunc );
  514. /****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/
  515. /**
  516.  * Insert <b>one</b> row for each specified binding (as one transaction).
  517.  * 
  518.  * @param pBindings Array of pointers to bindings.
  519.  * @param pData Array of pointers to structures. 
  520.  * @param NbBindings No of bindings (tables) to insert into,
  521.  *        i.e. length of arrays pBindings and pData
  522.  * @return Request identifier
  523.  * @note It is valid to specify the same binding twice 
  524.  *       (with corresponding data pointer) if you want to insert two
  525.  *       rows in one table 
  526.  */
  527. DBA_ReqId_t
  528. DBA_MultiInsertRow(const DBA_Binding_t * const pBindings[],
  529.    const void * const pData[],
  530.    int NbBindings,
  531.    DBA_AsyncCallbackFn_t CbFunc );
  532. /**
  533.  * Update <b>one</b> row for each specified binding (as one transaction).
  534.  * 
  535.  * @param pBindings Array of pointers to bindings.
  536.  * @param pData Array of pointers to structures. 
  537.  * @param NbBindings No of bindings (tables) to insert into
  538.  *        i.e. length of arrays pBindings and pData
  539.  * @return Request identifier
  540.  * @note It is valid to specify the same binding twice 
  541.  *       (with corresponding data pointer) if you want to update two
  542.  *       rows in one table 
  543.  */
  544. DBA_ReqId_t
  545. DBA_MultiUpdateRow(const DBA_Binding_t * const pBindings[],
  546.    const void * const pData[],
  547.    int NbBindings,
  548.    DBA_AsyncCallbackFn_t CbFunc );
  549. /**
  550.  * Update/insert <b>one</b> row for each specified binding (as one transaction).
  551.  * 
  552.  * @param pBindings Array of pointers to bindings.
  553.  * @param pData Array of pointers to structures. 
  554.  * @param NbBindings No of bindings (tables) to insert into
  555.  *        i.e. length of arrays pBindings and pData
  556.  * @return Request identifier
  557.  * @note It is valid to specify the same binding twice 
  558.  *       (with corresponding data pointer) if you want to update/insert two
  559.  *       rows in one table 
  560.  */
  561. DBA_ReqId_t
  562. DBA_MultiWriteRow(const DBA_Binding_t * const pBindings[],
  563.   const void * const pData[],
  564.   int NbBindings,
  565.   DBA_AsyncCallbackFn_t CbFunc );
  566. /**
  567.  * Delete <b>one</b> row for each specified binding (as one transaction).
  568.  * 
  569.  * @param pBindings Array of pointers to bindings.
  570.  * @param pData Array of pointers to structures. 
  571.  * @param NbBindings No of bindings (tables) to insert into
  572.  *        i.e. length of arrays pBindings and pData
  573.  * @return Request identifier
  574.  * @note It is valid to specify the same binding twice 
  575.  *       (with corresponding data pointer) if you want to delete two
  576.  *       rows in one table 
  577.  */
  578. DBA_ReqId_t
  579. DBA_MultiDeleteRow(const DBA_Binding_t * const pBindings[],
  580.    const void * const pData[],
  581.    int NbBindings,
  582.    DBA_AsyncCallbackFn_t CbFunc );
  583. /**
  584.  * Read <b>one</b> row for each specified binding (as one transaction).
  585.  * 
  586.  * @param pBindings Array of pointers to bindings.
  587.  * @param pData Array of pointers to structures. 
  588.  * @param NbBindings No of bindings (tables) to insert into
  589.  *        i.e. length of arrays pBindings and pData
  590.  * @return Request identifier
  591.  * @note It is valid to specify the same binding twice 
  592.  *       (with corresponding data pointer) if you want to read two
  593.  *       rows in one table 
  594.  */
  595. DBA_ReqId_t
  596. DBA_MultiReadRow(const DBA_Binding_t * const pBindings[],
  597.  void * const pData[],
  598.  int NbBindings,
  599.  DBA_AsyncCallbackFn_t CbFunc );
  600. /****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/
  601. /**
  602.  * A structure used for bulk reads.
  603.  * The structure contains a pointer to the data and an indicator.
  604.  * After the bulk read has completed, the indicator is set to 1 if the row
  605.  * was found and to 0 if the row was not found.
  606.  *
  607.  */
  608. typedef struct DBA_BulkReadResultSet {
  609.   void * DataPtr;               /**< Pointer to data. Only fields part of 
  610.    primary key members needs
  611.    to be set before bulk read. */
  612.   Boolean_t RowFoundIndicator;  /**< This indicator has a valid value
  613.    only after bulk read has completed.
  614.    If the value is 1 then the row was found */
  615. } DBA_BulkReadResultSet_t;
  616. /**
  617.  * Read rows from a table of the database (potentially multiple transactions)
  618.  * The users should for each NbRows specify the fields part of the primary key
  619.  *
  620.  * @param pBinding Binding between table columns and struct fields.
  621.  * @param pData Array of DBA_BulkReadResultSet_t, with DataPtr pointing to 
  622.  *              structure. Only the fields which are part of the 
  623.  *              primary key need be set.
  624.  *              The RowFoundIndicator will be set when the request returns.
  625.  * @param NbRows No of rows to read (i.e. length of pData array)
  626.  * @return Request identifier
  627.  *
  628.  */
  629. DBA_ReqId_t
  630. DBA_BulkReadRows(const DBA_Binding_t * pBinding,
  631.  DBA_BulkReadResultSet_t pData[],
  632.  int NbRows,
  633.  DBA_AsyncCallbackFn_t CbFunc );
  634. /**
  635.  * Read rows from several tables of the database in potentially multiple 
  636.  * transactions.
  637.  *
  638.  *<pre>
  639.  * The pData array <b>must</b> be organized as follows:
  640.  *   NbRows with DataPtr pointing to structure of type pBindings[0]
  641.  *   NbRows with DataPtr pointing to structure of type pBindings[1]
  642.  *   ... </pre>
  643.  * Meaning that the pData array must be (NbBindings * NbRows) in length.
  644.  *
  645.  * The user should for each (NbRows * NbBindings) specify the primary key 
  646.  * fields.
  647.  *
  648.  * @param pBindings Array of pointers to bindings 
  649.  * @param pData Array of DBA_BulkReadResultSet_t. 
  650.  *              With DataPtr pointing to structure. Only the fields which 
  651.  *              are part of the key need be set.
  652.  *              The RowFoundIndicator will be set when the operations returns.
  653.  * @param NbBindings No of bindings (i.e. length of pBindings array)
  654.  * @param NbRows No of rows per binding to read
  655.  * @return Request identifier
  656.  */
  657. DBA_ReqId_t
  658. DBA_BulkMultiReadRows(const DBA_Binding_t * const pBindings[],
  659.       DBA_BulkReadResultSet_t pData[],
  660.       int NbBindings,
  661.       int NbRows,
  662.       DBA_AsyncCallbackFn_t CbFunc );
  663. /** @} */
  664. #endif