summaryrefslogtreecommitdiff
path: root/storage/ndb/include/newtonapi/dba.h
blob: b02a7abb8af3a62bc2acc612258bdeb0650df565 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
/* Copyright (c) 2003-2005 MySQL AB
   Use is subject to license terms

   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; version 2 of the License.

   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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 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