diff options
Diffstat (limited to 'storage/ndb/include/newtonapi/dba.h')
| -rw-r--r-- | storage/ndb/include/newtonapi/dba.h | 730 |
1 files changed, 730 insertions, 0 deletions
diff --git a/storage/ndb/include/newtonapi/dba.h b/storage/ndb/include/newtonapi/dba.h new file mode 100644 index 00000000000..4cfc0ec8eb9 --- /dev/null +++ b/storage/ndb/include/newtonapi/dba.h @@ -0,0 +1,730 @@ +/* Copyright (C) 2003 MySQL AB + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ + +/** + * @mainpage DBA User Guide + * + * @section secIntro Introduction + * DBA is an API to access the NDB Cluster. + * + * DBA supports transactions using an asynchronous execution model. + * Everything but transactions is synchronous. + * + * DBA uses the concept of bindings to simplify database access. + * A <em>binding</em> is a relation between a database table and + * one or several C structs. + * A binding is created initially and then used multiple time during + * application execution. + * + * Each of the data accessing functions in DBA is implemented as a + * transaction, i.e. the call will either fully complete or + * nothing happens (the transaction fails). + * + * DBA also supports "read as much as possible" with bulk read. + * With bulk read the application can specify a set of primary keys and + * try to read all of the corresponding rows. The bulk read will not fail + * if a row does not exist but will instead inform the application using a + * RowFoundIndicator variable. + * + * A <em>request</em> is a transaction or a bulk read. + * + * @section secError Error Handling + * When a synchronous method in DBA fails these methods are applicable: + * -# DBA_GetLatestError() + * -# DBA_GetLatestNdbError() + * -# DBA_GetLatestErrorMsg() + * + * The DBA_GetLatestErrorMsg() will then return a description of + * what has failed. + * + * For asynchronous methods the application should: + * -# check that the RequestId returned by function is not + * @ref DBA_INVALID_REQID + * -# check Status supplied in callback (see @ref DBA_AsyncCallbackFn_t) + * + * If @ref DBA_INVALID_REQID is returned, + * the details of error can be found using + * "latest"-functions. + * + * If error is indicated in callback (using Status), when the + * "latest"-functions are <b>NOT</b> applicable. + * + * @section secExamples Example Programs + * + * - @ref common.hpp + * - @ref basic.cpp + * - @ref br_test.cpp + * - @ref ptr_binding_test.cpp + * + */ + +/** + * @page basic.cpp basic.cpp + * @include basic.cpp + */ + +/** + * @page common.hpp common.hpp + * @include common.hpp + */ + +/** + * @page br_test.cpp br_test.cpp + * @include br_test.cpp + */ + +/** + * @page ptr_binding_test.cpp ptr_binding_test.cpp + * @include ptr_binding_test.cpp + */ + +/** @addtogroup DBA + * @{ + */ + +/****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/ + +#ifndef DBA_H +#define DBA_H + +/* --- Include files ---- */ + +#include <ndb_global.h> +#include <defs/pcn_types.h> + +/* --- Types and definitions --- */ + +/** + * Possible error status for DBA functions. + */ +typedef enum { + DBA_NO_ERROR = 0, /**< Success */ + + DBA_NOT_IMPLEMENTED = -1, /**< Function not implemented */ + DBA_NDB_ERROR = -2, /**< Uncategorised error from NDB */ + DBA_ERROR = -3, /**< Uncategorised error from DBA implementation */ + + DBA_APPLICATION_ERROR = 1, /**< Function called with invalid argument(s) + or other application errors */ + DBA_NO_DATA = 2, /**< No row with specified PK existed */ + DBA_CONSTRAINT_VIOLATION = 3, /**< There already exists a row with that PK*/ + + DBA_SCHEMA_ERROR = 4, /**< Table already exists */ + DBA_INSUFFICIENT_SPACE = 5, /**< The DB is full */ + DBA_TEMPORARY_ERROR = 6, /**< Some temporary problem occured */ + DBA_TIMEOUT = 7, /**< The request timed out, probably due to + dead-lock */ + DBA_OVERLOAD = 8, /**< The DB is overloaded */ + DBA_UNKNOWN_RESULT = 9 /**< It is unknown wheater transaction was + commited or aborted */ +} DBA_Error_t; + +/** + * Error code. This is the error code that is returned by NDB. + * Not to be confused by the status returned by the DBA implementation. + */ +typedef int DBA_ErrorCode_t; + +/** + * DBA column types + */ +typedef enum { + DBA_CHAR, /**< String */ + DBA_INT /**< Integer */ +} DBA_DataTypes_t; + + +/** + * Column description. + * Used for creating tables. + */ +typedef struct DBA_ColumnDesc { + + const char* Name; /**< Name of table column */ + DBA_DataTypes_t DataType; /**< Datatype of table column*/ + Size_t Size; /**< Column size in bytes */ + Boolean_t IsKey; /**< True if column is part of primary key */ + +} DBA_ColumnDesc_t; + +/** + * Used to simplify binding definitions. See @ref DBA_ColumnBinding + * for example. + * + * @param ColName Name of column in db table + * @param Type Column/field type. + * @param Struct Structure + * @param Field Field in structure + * @return Arg list for defining binding of type @ref DBA_Binding_t + */ +#define DBA_BINDING( ColName, Type, Struct, Field ) \ + { ColName, Type, PCN_SIZE_OF( Struct, Field ), \ + PCN_OFFSET_OF( Struct, Field ), 0, 0 } + +/** + * Used to simplify ptr binding definitions. See @ref DBA_ColumnBinding + * for example. + * + * @param Struct Structure + * @param Field Field in structure + * @return Arg list for defining binding of type @ref DBA_Binding_t + */ +#define DBA_BINDING_PTR(Struct, Field, ColBindings, NbCBindings) \ + { 0, DBA_CHAR, NbCBindings, PCN_OFFSET_OF( Struct, Field ), \ + 1, ColBindings } + +/** + * The @ref DBA_ColumnBinding_t is used to describe a binding between one + * column and one field of a C struct. + * + *<pre> + * typedef struct Address { + * char StreetName[30]; + * int StreetNumber; + * } Address_t; + * + * typdef struct Person { + * char Name[30]; + * Address_t * AddressPtr; + * } Person_t; </pre> + * + * + * For example, if the field Name of a Person_t data structure is + * bound to the column "NAME", the corresponding binding would be + * defined as: + * + *<pre> + * DBA_ColumnBinding_t NameBinding = + * DBA_BINDING( "name", DBA_CHAR, Person_t, Name ); </pre> + * + * + * There is also the @ref DBA_BINDING_PTR which is used when + * several linked structures should be put into one table. + * + * For example, if data in a Person_t data structure should be saved + * in the same table as the Address_t data structure + * (as the address belongs to the person), the corresponding binding would be + * defined as: + * + *<pre> + * DBA_ColumnBinding_t AddrBinding[AddrLen]; This binding describes how the + * fields in the Address_t + * structure is linked to the + * table PERSON_ADDRESS + * + * DBA_ColumnBinding_t AddressBinding = + * DBA_BINDING_PTR(Person_t, AddressPtr, AddrBinding, AddrLen); </pre> + * + * + */ +struct DBA_ColumnBinding { + const char* Name; /**< Name of table column */ + DBA_DataTypes_t DataType; /**< Type of member in structure */ + Size_t Size; /**< Size in bytes of member + or no of @ref DBA_ColumnBinding's + when doing ptr binding */ + Size_t Offset; /**< Offset of the member */ + + Boolean_t Ptr; /**< True if binding is of ptr type */ + const struct DBA_ColumnBinding * SubBinding; /**< Address of Binding Ptr + valid if Ptr is true */ +}; + +/** + * Typedef: @ref DBA_ColumnBinding + */ +typedef struct DBA_ColumnBinding DBA_ColumnBinding_t; + +/** + * A @ref DBA_Binding_t object is used to establish a binding between + * one or more columns of a table to the fields of C structs. + * + * It is used with insert, and update and read transactions to define + * on which columns of the table the operations is performed, and to + * which members of a C data structure they map. + * + * All key columns must be bound to a field of the struct. + * + * The function @ref DBA_CreateBinding is used to create this binding. + */ +typedef struct DBA_Binding DBA_Binding_t; + +/* --- Exported functions --- */ + +/** + * Set DBA configuration parameter + *<pre> + * Id Description Default Min Max + * == =========================== ======= ==== ==== + * 0 NBP Interval 10 4 - + * 1 Operations/Bulkread 1000 1 5000 + * 2 Start transaction timeout 0 0 - + * 3 Force send algorithm 1 0 2 + *</pre> + * @return Status + */ +DBA_Error_t DBA_SetParameter(int ParameterId, int Value); + +/** + * Set DBA configuration parameter. + * See @ref DBA_SetParameter for description of parameters. + * + * @return Status + */ +DBA_Error_t DBA_GetParameter(int ParameterId, int * Value); + +/** + * Initialize DBA library and connect to NDB Cluster. + * + * @return Status + */ +DBA_Error_t DBA_Open( ); + +/** + * Close connection to NDB cluster and free allocated memory. + * + * @return Error status + */ +DBA_Error_t DBA_Close(void); + +/** + * Get latest DBA error. + * + * @note Only applicable to synchronous methods + */ +DBA_Error_t DBA_GetLatestError(); + +/** + * Get latest NDB error. + * + * @note Only applicable to synchronous methods + */ +DBA_ErrorCode_t DBA_GetLatestNdbError(); + +/** + * Get latest error string associated with DBA_GetLatestError(). + * + * @note String must not be free by caller of this method. + * @note Only applicable to synchronous methods. + */ +const char * DBA_GetLatestErrorMsg(); + +/** + * Get error msg associated with code + * + * @note String must not be free by caller of this method + */ +const char * DBA_GetErrorMsg(DBA_Error_t); + +/** + * Get error msg associated with code + * + * @note String must not be free by caller of this method + */ +const char * DBA_GetNdbErrorMsg(DBA_ErrorCode_t); + +/** + * Create a table. + * + * @param TableName Name of table to create. + * @param NbColumns numbers of columns. + * @param Columns Column descriptions. + * @return Status. + */ +DBA_Error_t +DBA_CreateTable( const char* TableName, int NbColumns, + const DBA_ColumnDesc_t Columns[] ); + +/** + * Destroy a table. + * + * @param TableName Table name. + * @return Status. + * @note Not implemented + */ +DBA_Error_t +DBA_DropTable( const char* TableName ); + + +/** + * Test for existence of a table. + * + * @param TableName Table name. + * @return Boolean value indicating if table exists or not. + */ +Boolean_t +DBA_TableExists( const char* TableName ); + +/** + * Define a binding between the columns of a table and a C structure. + * + * @param TableName table + * @param NbCol number of columns bindings + * @param ColBinding bindings + * @param StructSz Sizeof structure. + * @return Created binding, or NULL if binding could not be created. + */ +DBA_Binding_t* +DBA_CreateBinding( const char* TableName, + int NbCol, const DBA_ColumnBinding_t ColsBinding[], + Size_t StructSz ); + +/** + * Destroys a @ref DBA_Binding_t allocated with @ref + * DBA_CreateBinding. + * + * @param pBinding Pointer to binding. + * @return Status. + */ +DBA_Error_t +DBA_DestroyBinding( DBA_Binding_t* Binding ); + +/** + * Used to identify a pending db request + */ +typedef long DBA_ReqId_t; + +/** + * An asynchronous call returning this means that the function was called + * with invalid arguments. The application should check error status + * with DBA_GetLatestError() etc. + */ +#define DBA_INVALID_REQID 0 + +/** + * Callback function for transactions. + * Will be called in NBP process (Newton Batch Process). + * + * @note The implementation of the callback function is not allowed to + * make an asynchronous database call. + * + * @param ReqId Request identifier + * @param Status Status of the request + * @param ErrorCode Error code given by NDB + * @see DBA_Error_t + */ +typedef void (*DBA_AsyncCallbackFn_t)( DBA_ReqId_t ReqId, + DBA_Error_t Status, + DBA_ErrorCode_t ErrorCode ); +/** + * Insert row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of pointers to structures. + * @param NbRows No of rows to insert (i.e. length of pData array) + * @return Request identifier + * + * @note All the table columns must be part of the binding. + */ +DBA_ReqId_t +DBA_InsertRows( const DBA_Binding_t* pBinding, const void * const pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Insert row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of structures. + * @param NbRows No of rows to insert (i.e. length of pData array) + * @return Request identifier + * + * @note All the table columns must be part of the binding. + */ +DBA_ReqId_t +DBA_ArrayInsertRows( const DBA_Binding_t* pBinding, const void * pData, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Update row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of pointers to structures. Fields that are part of the + * key are used to generate the where clause, the + * other fields are used to update the row. + * @param NbRows No of rows to update (i.e. length of pData array). + * @return Request identifier + */ +DBA_ReqId_t +DBA_UpdateRows( const DBA_Binding_t* pBinding, const void * const pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Update row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of structures. Fields that are part of the + * key are used to generate the where clause, the + * other fields are used to update the row. + * @param NbRows No of rows to update (i.e. length of pData array). + * @return Request identifier + */ +DBA_ReqId_t +DBA_ArrayUpdateRows( const DBA_Binding_t* pBinding, const void * pData, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Delete row(s) from the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of pointers to structures. + * Only fields part of the primary key needs to be set. + * @param NbRows No of rows to delete (i.e. length of pData array) + * @return Request identifier + */ +DBA_ReqId_t +DBA_DeleteRows( const DBA_Binding_t* pBinding, const void * const pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + + +/** + * Delete row(s) from the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of structures. Only fields part of the primary + * key needs to be set. + * @param NbRows No of rows to delete (i.e. length of pData array) + * @return Request identifier + */ +DBA_ReqId_t +DBA_ArrayDeleteRows( const DBA_Binding_t* pBinding, const void * pData, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Updates/Inserts row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of pointers to structures. + * @param NbRows No of rows to update/insert (i.e. length of pData array) + * @return Request identifier + * @note All the table columns must be part of the binding. + */ +DBA_ReqId_t +DBA_WriteRows( const DBA_Binding_t* pBinding, const void * const pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Update/Insert row(s) in the table (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of structures. + * @param NbRows No of rows to update/insert (i.e. length of pData array) + * @return Request identifier + * @note All the table columns must be part of the binding. + */ +DBA_ReqId_t +DBA_ArrayWriteRows( const DBA_Binding_t* pBinding, const void * pData, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Read row(s) from a table of the database (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of pointers to structures. + * Only fields part of the primary key needs to be set. + * The other fields in the binding will be populated. + * @param NbRows No of rows to read (i.e. length of pData array) + * @return Request identifier + */ +DBA_ReqId_t +DBA_ReadRows( const DBA_Binding_t* pBinding, void * const pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Read row(s) from a table of the database (one transaction) + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of structures. + * Only fields part of the primary key needs to be set. + * The other fields in the binding will be populated. + * @param NbRows No of rows to read (i.e. length of pData array) + * @return Request identifier + */ +DBA_ReqId_t +DBA_ArrayReadRows( const DBA_Binding_t* pBinding, void * pData, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/ + +/** + * Insert <b>one</b> row for each specified binding (as one transaction). + * + * @param pBindings Array of pointers to bindings. + * @param pData Array of pointers to structures. + * @param NbBindings No of bindings (tables) to insert into, + * i.e. length of arrays pBindings and pData + * @return Request identifier + * @note It is valid to specify the same binding twice + * (with corresponding data pointer) if you want to insert two + * rows in one table + */ +DBA_ReqId_t +DBA_MultiInsertRow(const DBA_Binding_t * const pBindings[], + const void * const pData[], + int NbBindings, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Update <b>one</b> row for each specified binding (as one transaction). + * + * @param pBindings Array of pointers to bindings. + * @param pData Array of pointers to structures. + * @param NbBindings No of bindings (tables) to insert into + * i.e. length of arrays pBindings and pData + * @return Request identifier + * @note It is valid to specify the same binding twice + * (with corresponding data pointer) if you want to update two + * rows in one table + */ +DBA_ReqId_t +DBA_MultiUpdateRow(const DBA_Binding_t * const pBindings[], + const void * const pData[], + int NbBindings, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Update/insert <b>one</b> row for each specified binding (as one transaction). + * + * @param pBindings Array of pointers to bindings. + * @param pData Array of pointers to structures. + * @param NbBindings No of bindings (tables) to insert into + * i.e. length of arrays pBindings and pData + * @return Request identifier + * @note It is valid to specify the same binding twice + * (with corresponding data pointer) if you want to update/insert two + * rows in one table + */ +DBA_ReqId_t +DBA_MultiWriteRow(const DBA_Binding_t * const pBindings[], + const void * const pData[], + int NbBindings, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Delete <b>one</b> row for each specified binding (as one transaction). + * + * @param pBindings Array of pointers to bindings. + * @param pData Array of pointers to structures. + * @param NbBindings No of bindings (tables) to insert into + * i.e. length of arrays pBindings and pData + * @return Request identifier + * @note It is valid to specify the same binding twice + * (with corresponding data pointer) if you want to delete two + * rows in one table + */ +DBA_ReqId_t +DBA_MultiDeleteRow(const DBA_Binding_t * const pBindings[], + const void * const pData[], + int NbBindings, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Read <b>one</b> row for each specified binding (as one transaction). + * + * @param pBindings Array of pointers to bindings. + * @param pData Array of pointers to structures. + * @param NbBindings No of bindings (tables) to insert into + * i.e. length of arrays pBindings and pData + * @return Request identifier + * @note It is valid to specify the same binding twice + * (with corresponding data pointer) if you want to read two + * rows in one table + */ +DBA_ReqId_t +DBA_MultiReadRow(const DBA_Binding_t * const pBindings[], + void * const pData[], + int NbBindings, + DBA_AsyncCallbackFn_t CbFunc ); + +/****** THIS LINE IS 80 CHARACTERS WIDE - DO *NOT* EXCEED 80 CHARACTERS! ****/ + +/** + * A structure used for bulk reads. + * The structure contains a pointer to the data and an indicator. + * After the bulk read has completed, the indicator is set to 1 if the row + * was found and to 0 if the row was not found. + * + */ +typedef struct DBA_BulkReadResultSet { + void * DataPtr; /**< Pointer to data. Only fields part of + primary key members needs + to be set before bulk read. */ + Boolean_t RowFoundIndicator; /**< This indicator has a valid value + only after bulk read has completed. + If the value is 1 then the row was found */ +} DBA_BulkReadResultSet_t; + +/** + * Read rows from a table of the database (potentially multiple transactions) + * The users should for each NbRows specify the fields part of the primary key + * + * @param pBinding Binding between table columns and struct fields. + * @param pData Array of DBA_BulkReadResultSet_t, with DataPtr pointing to + * structure. Only the fields which are part of the + * primary key need be set. + * The RowFoundIndicator will be set when the request returns. + * @param NbRows No of rows to read (i.e. length of pData array) + * @return Request identifier + * + */ +DBA_ReqId_t +DBA_BulkReadRows(const DBA_Binding_t * pBinding, + DBA_BulkReadResultSet_t pData[], + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** + * Read rows from several tables of the database in potentially multiple + * transactions. + * + *<pre> + * The pData array <b>must</b> be organized as follows: + * NbRows with DataPtr pointing to structure of type pBindings[0] + * NbRows with DataPtr pointing to structure of type pBindings[1] + * ... </pre> + * Meaning that the pData array must be (NbBindings * NbRows) in length. + * + * The user should for each (NbRows * NbBindings) specify the primary key + * fields. + * + * @param pBindings Array of pointers to bindings + * @param pData Array of DBA_BulkReadResultSet_t. + * With DataPtr pointing to structure. Only the fields which + * are part of the key need be set. + * The RowFoundIndicator will be set when the operations returns. + * @param NbBindings No of bindings (i.e. length of pBindings array) + * @param NbRows No of rows per binding to read + * @return Request identifier + */ +DBA_ReqId_t +DBA_BulkMultiReadRows(const DBA_Binding_t * const pBindings[], + DBA_BulkReadResultSet_t pData[], + int NbBindings, + int NbRows, + DBA_AsyncCallbackFn_t CbFunc ); + +/** @} */ + +#endif |