← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mysql-5.6/trusty

« back to all changes in this revision

Viewing changes to storage/ndb/include/ndbapi/NdbTransaction.hpp

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-02-12 11:54:27 UTC
  • Revision ID: package-import@ubuntu.com-20140212115427-oq6tfsqxl1wuwehi
Tags: upstream-5.6.15
Import upstream version 5.6.15

Show diffs side-by-side

added added

removed removed

Lines of Context:
storage/ndb/include/ndbapi/NdbTransaction.hpp
 
1
/*
 
2
   Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
 
3
 
 
4
   This program is free software; you can redistribute it and/or modify
 
5
   it under the terms of the GNU General Public License as published by
 
6
   the Free Software Foundation; version 2 of the License.
 
7
 
 
8
   This program is distributed in the hope that it will be useful,
 
9
   but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
   GNU General Public License for more details.
 
12
 
 
13
   You should have received a copy of the GNU General Public License
 
14
   along with this program; if not, write to the Free Software
 
15
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
 
16
*/
 
17
 
 
18
#ifndef NdbTransaction_H
 
19
#define NdbTransaction_H
 
20
 
 
21
#include <ndb_types.h>
 
22
#include "NdbError.hpp"
 
23
#include "NdbDictionary.hpp"
 
24
#include "Ndb.hpp"
 
25
#include "NdbOperation.hpp"
 
26
#include "NdbIndexScanOperation.hpp"
 
27
 
 
28
class NdbTransaction;
 
29
class NdbScanOperation;
 
30
class NdbIndexScanOperation;
 
31
class NdbIndexOperation;
 
32
class NdbApiSignal;
 
33
class Ndb;
 
34
class NdbBlob;
 
35
class NdbInterpretedCode;
 
36
class NdbQueryImpl;
 
37
class NdbQueryDef;
 
38
class NdbQuery;
 
39
class NdbQueryParamValue;
 
40
class NdbLockHandle;
 
41
 
 
42
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
43
// to be documented later
 
44
/**
 
45
 * NdbAsynchCallback functions are used when executing asynchronous 
 
46
 * transactions (using NdbTransaction::executeAsynchPrepare, or 
 
47
 * NdbTransaction::executeAsynch).
 
48
 * The functions are called when the execute has finished.
 
49
 * See @ref secAsync for more information.
 
50
 */
 
51
typedef void (* NdbAsynchCallback)(int, NdbTransaction*, void*);
 
52
#endif
 
53
 
 
54
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
55
enum AbortOption {
 
56
  DefaultAbortOption = NdbOperation::DefaultAbortOption,
 
57
  CommitIfFailFree = NdbOperation::AbortOnError,         
 
58
  TryCommit = NdbOperation::AbortOnError,
 
59
  AbortOnError= NdbOperation::AbortOnError,
 
60
  CommitAsMuchAsPossible = NdbOperation::AO_IgnoreError,
 
61
  AO_IgnoreError= NdbOperation::AO_IgnoreError
 
62
};
 
63
enum ExecType { 
 
64
  NoExecTypeDef = -1,
 
65
  Prepare,
 
66
  NoCommit,
 
67
  Commit,
 
68
  Rollback
 
69
};
 
70
#endif
 
71
 
 
72
/**
 
73
 * @class NdbTransaction
 
74
 * @brief Represents a transaction.
 
75
 *
 
76
 * A transaction (represented by an NdbTransaction object) 
 
77
 * belongs to an Ndb object and is created using 
 
78
 * Ndb::startTransaction().
 
79
 * A transaction consists of a list of operations 
 
80
 * (represented by NdbOperation, NdbScanOperation, NdbIndexOperation,
 
81
 *  and NdbIndexScanOperation objects). 
 
82
 * Each operation access exactly one table.
 
83
 *
 
84
 * After getting the NdbTransaction object, 
 
85
 * the first step is to get (allocate) an operation given the table name using
 
86
 * one of the methods getNdbOperation(), getNdbScanOperation(),
 
87
 * getNdbIndexOperation(), or getNdbIndexScanOperation().
 
88
 * Then the operation is defined. 
 
89
 * Several operations can be defined on the same 
 
90
 * NdbTransaction object, they will in that case be executed in parallell.
 
91
 * When all operations are defined, the execute()
 
92
 * method sends them to the NDB kernel for execution.
 
93
 *
 
94
 * The execute() method returns when the NDB kernel has 
 
95
 * completed execution of all operations defined before the call to 
 
96
 * execute(). All allocated operations should be properly defined 
 
97
 * before calling execute().
 
98
 *
 
99
 * A call to execute() uses one out of three types of execution:
 
100
 *  -# NdbTransaction::NoCommit  Executes operations without committing them.
 
101
 *  -# NdbTransaction::Commit    Executes remaining operation and commits the 
 
102
 *                         complete transaction
 
103
 *  -# NdbTransaction::Rollback  Rollbacks the entire transaction.
 
104
 *
 
105
 * execute() is equipped with an extra error handling parameter. 
 
106
 * There are two alternatives:
 
107
 * -# NdbTransaction::AbortOnError (default).
 
108
 *    The transaction is aborted if there are any error during the
 
109
 *    execution
 
110
 * -# NdbTransaction::AO_IgnoreError
 
111
 *    Continue execution of transaction even if operation fails
 
112
 *
 
113
 */
 
114
 
 
115
/* FUTURE IMPLEMENTATION:
 
116
 * Later a prepare mode will be added when Ndb supports Prepare-To-Commit
 
117
 * The NdbTransaction can deliver the Transaction Id of the transaction.
 
118
 * After committing a transaction it is also possible to retrieve the 
 
119
 * global transaction checkpoint which the transaction was put in.
 
120
 *
 
121
 * FUTURE IMPLEMENTATION:
 
122
 * There are three methods for acquiring the NdbOperation. 
 
123
 * -# The first method is the normal where a table name is
 
124
 *    provided. In this case the primary key must be supplied through
 
125
 *    the use of the NdbOperation::equal methods on the NdbOperation object.
 
126
 * -# The second method provides the tuple identity of the tuple to be
 
127
 *    read.  The tuple identity contains a table identifier and will
 
128
 *    thus be possible to use to ensure the attribute names provided
 
129
 *    are correct.  If an object-oriented layer is put on top of NDB
 
130
 *    Cluster it is essential that all tables derived from a base
 
131
 *    class has the same attributes with the same type and the same
 
132
 *    name. Thus the application can use the tuple identity and need
 
133
 *    not known the table of the tuple.  As long as the table is
 
134
 *    derived from the known base class everything is ok.
 
135
 *    It is not possible to provide any primary key since it is 
 
136
 *    already supplied with the call to NdbTransaction::getNdbOperation. 
 
137
 * -# The third method is used when a scanned tuple is to be transferred to 
 
138
 *    another transaction. In this case it is not possible to define the 
 
139
 *    primary key since it came along from the scanned tuple.
 
140
 *
 
141
 */
 
142
 
 
143
class NdbRecord;
 
144
 
 
145
class NdbTransaction
 
146
{
 
147
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
148
  friend class Ndb;
 
149
  friend class NdbOperation;
 
150
  friend class NdbScanOperation;
 
151
  friend class NdbIndexOperation;
 
152
  friend class NdbIndexScanOperation;
 
153
  friend class NdbBlob;
 
154
  friend class ha_ndbcluster;
 
155
  friend class NdbQueryImpl;
 
156
  friend class NdbQueryOperationImpl;
 
157
#endif
 
158
 
 
159
public:
 
160
#ifdef NDBAPI_50_COMPAT
 
161
  enum AbortOption {
 
162
    DefaultAbortOption = NdbOperation::DefaultAbortOption,
 
163
    CommitIfFailFree = NdbOperation::AbortOnError,         
 
164
    TryCommit = NdbOperation::AbortOnError,
 
165
    AbortOnError= NdbOperation::AbortOnError,
 
166
    CommitAsMuchAsPossible = NdbOperation::AO_IgnoreError,
 
167
    AO_IgnoreError= NdbOperation::AO_IgnoreError
 
168
  };
 
169
#endif
 
170
 
 
171
 
 
172
  /**
 
173
   * Execution type of transaction
 
174
   */
 
175
  enum ExecType {
 
176
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
177
    NoExecTypeDef=
 
178
    ::NoExecTypeDef,            ///< Erroneous type (Used for debugging only)
 
179
    Prepare= ::Prepare,         ///< <i>Missing explanation</i>
 
180
#endif
 
181
    NoCommit=                   ///< Execute the transaction as far as it has
 
182
                                ///< been defined, but do not yet commit it
 
183
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
184
    ::NoCommit
 
185
#endif
 
186
    ,Commit=                    ///< Execute and try to commit the transaction
 
187
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
188
    ::Commit
 
189
#endif
 
190
    ,Rollback                   ///< Rollback transaction
 
191
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
192
    = ::Rollback
 
193
#endif
 
194
  };
 
195
 
 
196
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
197
  /**
 
198
   * Convenience method to fetch this transaction's Ndb* object 
 
199
   */
 
200
  Ndb * getNdb() { 
 
201
    return theNdb; 
 
202
  }
 
203
#endif
 
204
 
 
205
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
206
  /**
 
207
   * Get an NdbOperation for a table.
 
208
   * Note that the operation has to be defined before it is executed.
 
209
   *
 
210
   * @note All operations within the same transaction need to 
 
211
   *       be initialized with this method.
 
212
   * 
 
213
   * @param  aTableName   The table name.
 
214
   * @return  Pointer to an NdbOperation object if successful, otherwise NULL.
 
215
   */
 
216
  NdbOperation* getNdbOperation(const char* aTableName);
 
217
#endif
 
218
 
 
219
  /**
 
220
   * Get an NdbOperation for a table.
 
221
   * Note that the operation has to be defined before it is executed.
 
222
   *
 
223
   * @note All operations within the same transaction need to 
 
224
   *       be initialized with this method.
 
225
   * 
 
226
   * @param  aTable  
 
227
   *         A table object (fetched by NdbDictionary::Dictionary::getTable)
 
228
   * @return  Pointer to an NdbOperation object if successful, otherwise NULL.
 
229
   */
 
230
  NdbOperation* getNdbOperation(const NdbDictionary::Table * aTable);
 
231
 
 
232
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
233
  /**
 
234
   * Get an operation from NdbScanOperation idlelist and 
 
235
   * get the NdbTransaction object which
 
236
   * was fetched by startTransaction pointing to this operation.
 
237
   *
 
238
   * @param  aTableName  The table name.
 
239
   * @return pointer to an NdbOperation object if successful, otherwise NULL
 
240
   */
 
241
  NdbScanOperation* getNdbScanOperation(const char* aTableName);
 
242
#endif
 
243
 
 
244
  /**
 
245
   * Get an operation from NdbScanOperation idlelist and 
 
246
   * get the NdbTransaction object which
 
247
   * was fetched by startTransaction pointing to this operation.
 
248
   *
 
249
   * @param  aTable  
 
250
   *         A table object (fetched by NdbDictionary::Dictionary::getTable)
 
251
   * @return pointer to an NdbOperation object if successful, otherwise NULL
 
252
   */
 
253
  NdbScanOperation* getNdbScanOperation(const NdbDictionary::Table * aTable);
 
254
 
 
255
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
256
  /**
 
257
   * Get an operation from NdbIndexScanOperation idlelist and 
 
258
   * get the NdbTransaction object which
 
259
   * was fetched by startTransaction pointing to this operation.
 
260
   *
 
261
   * @param  anIndexName  The name of the index to use for scanning
 
262
   * @param  aTableName  The name of the table to scan
 
263
   * @return pointer to an NdbOperation object if successful, otherwise NULL
 
264
   */
 
265
  NdbIndexScanOperation* getNdbIndexScanOperation(const char* anIndexName,
 
266
                                                  const char* aTableName);
 
267
  NdbIndexScanOperation* getNdbIndexScanOperation
 
268
  (const NdbDictionary::Index *anIndex, const NdbDictionary::Table *aTable);
 
269
#endif
 
270
  
 
271
  /**
 
272
   * Get an operation from NdbIndexScanOperation idlelist and 
 
273
   * get the NdbTransaction object which
 
274
   * was fetched by startTransaction pointing to this operation.
 
275
   *
 
276
   * @param  anIndex  
 
277
             An index object (fetched by NdbDictionary::Dictionary::getIndex).
 
278
   * @return pointer to an NdbOperation object if successful, otherwise NULL
 
279
   */
 
280
  NdbIndexScanOperation* getNdbIndexScanOperation
 
281
  (const NdbDictionary::Index *anIndex);
 
282
  
 
283
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
284
  /**
 
285
   * Get an operation from NdbIndexOperation idlelist and 
 
286
   * get the NdbTransaction object that
 
287
   * was fetched by startTransaction pointing to this operation.
 
288
   *
 
289
   * @param   anIndexName   The index name (as created by createIndex).
 
290
   * @param   aTableName    The table name.
 
291
   * @return                Pointer to an NdbIndexOperation object if 
 
292
   *                        successful, otherwise NULL
 
293
   */
 
294
  NdbIndexOperation* getNdbIndexOperation(const char*  anIndexName,
 
295
                                          const char*  aTableName);
 
296
  NdbIndexOperation* getNdbIndexOperation(const NdbDictionary::Index *anIndex,
 
297
                                          const NdbDictionary::Table *aTable);
 
298
#endif
 
299
 
 
300
  /**
 
301
   * Get an operation from NdbIndexOperation idlelist and 
 
302
   * get the NdbTransaction object that
 
303
   * was fetched by startTransaction pointing to this operation.
 
304
   *
 
305
   * @param   anIndex
 
306
   *          An index object (fetched by NdbDictionary::Dictionary::getIndex).
 
307
   * @return              Pointer to an NdbIndexOperation object if 
 
308
   *                      successful, otherwise NULL
 
309
   */
 
310
  NdbIndexOperation* getNdbIndexOperation(const NdbDictionary::Index *anIndex);
 
311
 
 
312
  /** 
 
313
   * @name Execute Transaction
 
314
   * @{
 
315
   */
 
316
 
 
317
  /**
 
318
   * Executes transaction.
 
319
   *
 
320
   * @param execType     Execution type:<br>
 
321
   *                     ExecType::NoCommit executes operations without 
 
322
   *                                        committing them.<br>
 
323
   *                     ExecType::Commit  executes remaining operations and 
 
324
   *                                       commits the complete transaction.<br>
 
325
   *                     ExecType::Rollback rollbacks the entire transaction.
 
326
   * @param abortOption  Handling of error while excuting
 
327
   *                     AbortOnError - Abort transaction if an operation fail
 
328
   *                     AO_IgnoreError  - Accept failing operations
 
329
   *                     DefaultAbortOption - Use per-operation abort option
 
330
   * @param force        When operations should be sent to NDB Kernel.
 
331
   *                     (See @ref secAdapt.)
 
332
   *                     - 0: non-force, adaptive algorithm notices it 
 
333
   *                          (default); 
 
334
   *                     - 1: force send, adaptive algorithm notices it; 
 
335
   *                     - 2: non-force, adaptive algorithm do not notice 
 
336
   *                          the send.
 
337
   * @return 0 if successful otherwise -1.
 
338
   */
 
339
#ifndef NDBAPI_50_COMPAT
 
340
  int execute(ExecType execType,
 
341
              NdbOperation::AbortOption = NdbOperation::DefaultAbortOption,
 
342
              int force = 0 );
 
343
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
344
  int execute(::ExecType execType,
 
345
              ::AbortOption abortOption = ::DefaultAbortOption,
 
346
              int force = 0 ) {
 
347
    return execute ((ExecType)execType,
 
348
                    (NdbOperation::AbortOption)abortOption,
 
349
                    force); }
 
350
#endif
 
351
#else
 
352
  /**
 
353
   * 50 compability layer
 
354
   *   Check 50-docs for sematics
 
355
   */
 
356
 
 
357
  int execute(ExecType execType, NdbOperation::AbortOption, int force);
 
358
  
 
359
  int execute(NdbTransaction::ExecType execType,
 
360
              NdbTransaction::AbortOption abortOption = AbortOnError,
 
361
              int force = 0) 
 
362
    {
 
363
      int ret = execute ((ExecType)execType,
 
364
                         (NdbOperation::AbortOption)abortOption,
 
365
                         force); 
 
366
      if (ret || (abortOption != AO_IgnoreError && theError.code))
 
367
        return -1;
 
368
      return 0;
 
369
    }
 
370
#endif
 
371
 
 
372
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
373
  // to be documented later
 
374
  /**
 
375
   * Prepare an asynchronous transaction.
 
376
   *
 
377
   * See @ref secAsync for more information on
 
378
   * how to use this method.
 
379
   *
 
380
   * @param execType   Execution type:<br>
 
381
   *        ExecType::NoCommit executes operations without committing them.<br>
 
382
   *        ExecType::Commit   executes remaining operations and commits the 
 
383
   *                           complete transaction.<br>
 
384
   *        ExecType::Rollback rollbacks the entire transaction.
 
385
   * @param callback       A callback method.  This method gets 
 
386
   *                        called when the transaction has been 
 
387
   *                        executed.  See @ref ndbapi_async1.cpp 
 
388
   *                        for an example on how to specify and use 
 
389
   *                        a callback method.
 
390
   * @param anyObject       A void pointer.  This pointer is forwarded to the 
 
391
   *                        callback method and can be used to give 
 
392
   *                        the callback method some data to work on.
 
393
   *                        It is up to the application programmer 
 
394
   *                        to decide on the use of this pointer.
 
395
   * @param abortOption     see @ref execute
 
396
   */
 
397
#ifndef NDBAPI_50_COMPAT
 
398
  void executeAsynchPrepare(ExecType          execType,
 
399
                            NdbAsynchCallback callback,
 
400
                            void*             anyObject,
 
401
                            NdbOperation::AbortOption = NdbOperation::DefaultAbortOption);
 
402
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
403
  void executeAsynchPrepare(::ExecType       execType,
 
404
                            NdbAsynchCallback callback,
 
405
                            void*             anyObject,
 
406
                            ::AbortOption ao = ::DefaultAbortOption) {
 
407
    executeAsynchPrepare((ExecType)execType, callback, anyObject,
 
408
                         (NdbOperation::AbortOption)ao); }
 
409
#endif
 
410
#else
 
411
  /**
 
412
   * 50 compability layer
 
413
   *   Check 50-docs for sematics
 
414
   */
 
415
  void executeAsynchPrepare(ExecType          execType,
 
416
                            NdbAsynchCallback callback,
 
417
                            void*             anyObject,
 
418
                            NdbOperation::AbortOption);
 
419
 
 
420
  void executeAsynchPrepare(NdbTransaction::ExecType execType,
 
421
                            NdbAsynchCallback callback,
 
422
                            void *anyObject,
 
423
                            NdbTransaction::AbortOption abortOption = NdbTransaction::AbortOnError)
 
424
    {
 
425
      executeAsynchPrepare((ExecType)execType, callback, anyObject,
 
426
                           (NdbOperation::AbortOption)abortOption);
 
427
    }
 
428
#endif
 
429
 
 
430
  /**
 
431
   * Prepare and send an asynchronous transaction.
 
432
   *
 
433
   * This method perform the same action as 
 
434
   * NdbTransaction::executeAsynchPrepare
 
435
   * but also sends the operations to the NDB kernel.
 
436
   *
 
437
   * See NdbTransaction::executeAsynchPrepare for information
 
438
   * about the parameters of this method.
 
439
   *
 
440
   * See @ref secAsync for more information on
 
441
   * how to use this method.
 
442
   */
 
443
#ifndef NDBAPI_50_COMPAT
 
444
  void executeAsynch(ExecType            aTypeOfExec,
 
445
                     NdbAsynchCallback   aCallback,
 
446
                     void*               anyObject,
 
447
                     NdbOperation::AbortOption = NdbOperation::DefaultAbortOption,
 
448
                     int forceSend= 0);
 
449
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
 
450
  void executeAsynch(::ExecType         aTypeOfExec,
 
451
                     NdbAsynchCallback   aCallback,
 
452
                     void*               anyObject,
 
453
                     ::AbortOption abortOption= ::DefaultAbortOption,
 
454
                     int forceSend= 0)
 
455
  { executeAsynch((ExecType)aTypeOfExec, aCallback, anyObject,
 
456
                  (NdbOperation::AbortOption)abortOption, forceSend); }
 
457
#endif
 
458
#else
 
459
  /**
 
460
   * 50 compability layer
 
461
   *   Check 50-docs for sematics
 
462
   */
 
463
  void executeAsynch(ExecType            aTypeOfExec,
 
464
                     NdbAsynchCallback   aCallback,
 
465
                     void*               anyObject,
 
466
                     NdbOperation::AbortOption = NdbOperation::DefaultAbortOption,
 
467
                     int forceSend= 0);
 
468
  void executeAsynch(NdbTransaction::ExecType aTypeOfExec,
 
469
                     NdbAsynchCallback aCallback,
 
470
                     void* anyObject,
 
471
                     NdbTransaction::AbortOption abortOption = AbortOnError)
 
472
    {
 
473
      executeAsynch((ExecType)aTypeOfExec, aCallback, anyObject,
 
474
                    (NdbOperation::AbortOption)abortOption, 0);
 
475
    }
 
476
#endif
 
477
#endif
 
478
 
 
479
  /**
 
480
   * Refresh
 
481
   * Update timeout counter of this transaction 
 
482
   * in the database. If you want to keep the transaction 
 
483
   * active in the database longer than the
 
484
   * transaction abort timeout.
 
485
   * @note It's not advised to take a lock on a record and keep it
 
486
   *       for a extended time since this can impact other transactions.
 
487
   *
 
488
   */
 
489
  int refresh();
 
490
 
 
491
  /**
 
492
   * Close transaction
 
493
   *
 
494
   * @note Equivalent to to calling Ndb::closeTransaction()
 
495
   */
 
496
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
497
  /**
 
498
   * @note It is not allowed to call NdbTransaction::close after sending the
 
499
   *       transaction asynchronously before the callback method has 
 
500
   *       been called.
 
501
   *       (The application should keep track of the number of 
 
502
   *       outstanding transactions and wait until all of them 
 
503
   *       has completed before calling NdbTransaction::close).
 
504
   *       If the transaction is not committed it will be aborted.
 
505
   */
 
506
#endif
 
507
  void close();
 
508
 
 
509
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
510
  /**
 
511
   * Restart transaction
 
512
   *
 
513
   *   Once a transaction has been completed successfully
 
514
   *     it can be started again wo/ calling closeTransaction/startTransaction
 
515
   *
 
516
   *  @note This method also releases completed operations
 
517
   *
 
518
   *  @note This method does not close open scans, 
 
519
   *        c.f. NdbScanOperation::close()
 
520
   *
 
521
   *  @note This method can only be called _directly_ after commit
 
522
   *        and only if commit is successful
 
523
   */
 
524
  int restart();
 
525
#endif
 
526
 
 
527
  /** @} *********************************************************************/
 
528
 
 
529
  /** 
 
530
   * @name Meta Information
 
531
   * @{
 
532
   */
 
533
 
 
534
  /**
 
535
   * Get global checkpoint identity (GCI) of transaction.
 
536
   *
 
537
   * Each committed transaction belong to a GCI.  
 
538
   * The log for the committed transaction is saved on 
 
539
   * disk when a global checkpoint occurs.
 
540
   * 
 
541
   * Whether or not the global checkpoint with this GCI has been 
 
542
   * saved on disk or not cannot be determined by this method.
 
543
   *
 
544
   * By comparing the GCI of a transaction with the value 
 
545
   * last GCI restored in a restarted NDB Cluster one can determine
 
546
   * whether the transaction was restored or not.
 
547
   *
 
548
   * @note Global Checkpoint Identity is undefined for scan transactions 
 
549
   *       (This is because no updates are performed in scan transactions.)
 
550
   *
 
551
   * @return 0 if GCI is available, and stored in <em>gciptr</em>
 
552
             -1 if GCI is not available.
 
553
   *         (Note that there has to be an NdbTransaction::execute call 
 
554
   *         with Ndb::Commit for the GCI to be available.)
 
555
   */
 
556
  int getGCI(Uint64 * gciptr);
 
557
 
 
558
  /**
 
559
   * Deprecated...in favor of getGCI(Uint64*)
 
560
   */
 
561
  int getGCI();
 
562
                        
 
563
  /**
 
564
   * Get transaction identity.
 
565
   *
 
566
   * @return  Transaction id.
 
567
   */
 
568
  Uint64        getTransactionId();
 
569
 
 
570
  /**
 
571
   * The commit status of the transaction.
 
572
   */
 
573
  enum CommitStatusType { 
 
574
    NotStarted,                   ///< Transaction not yet started
 
575
    Started,                      ///< <i>Missing explanation</i>
 
576
    Committed,                    ///< Transaction has been committed
 
577
    Aborted,                      ///< Transaction has been aborted
 
578
    NeedAbort                     ///< <i>Missing explanation</i>
 
579
  };
 
580
 
 
581
  /**
 
582
   * Get the commit status of the transaction.
 
583
   *
 
584
   * @return  The commit status of the transaction
 
585
   */
 
586
  CommitStatusType commitStatus();
 
587
 
 
588
  /** @} *********************************************************************/
 
589
 
 
590
  /** 
 
591
   * @name Error Handling
 
592
   * @{
 
593
   */
 
594
 
 
595
  /**
 
596
   * Get error object with information about the latest error.
 
597
   *
 
598
   * @return An error object with information about the latest error.
 
599
   */
 
600
  const NdbError & getNdbError() const;
 
601
 
 
602
  /**
 
603
   * Get the latest NdbOperation which had an error. 
 
604
   * This method is used on the NdbTransaction object to find the
 
605
   * NdbOperation causing an error.  
 
606
   * To find more information about the
 
607
   * actual error, use method NdbOperation::getNdbError()
 
608
   * on the returned NdbOperation object.
 
609
   *
 
610
   * @return The NdbOperation causing the latest error.
 
611
   * @deprecated Use the const NdbOperation returning variant.
 
612
   */
 
613
  NdbOperation* getNdbErrorOperation();
 
614
 
 
615
  /**
 
616
   * Get the latest NdbOperation which had an error. 
 
617
   * This method is used on the NdbTransaction object to find the
 
618
   * NdbOperation causing an error.  
 
619
   * To find more information about the
 
620
   * actual error, use method NdbOperation::getNdbError()
 
621
   * on the returned NdbOperation object.
 
622
   *
 
623
   * @return The NdbOperation causing the latest error.
 
624
   */
 
625
  const NdbOperation* getNdbErrorOperation() const;
 
626
 
 
627
  /** 
 
628
   * Get the method number where the latest error occured.
 
629
   * 
 
630
   * @return Line number where latest error occured.
 
631
   */
 
632
  int getNdbErrorLine();
 
633
 
 
634
  /**
 
635
   * Get completed (i.e. executed) operations of a transaction
 
636
   *
 
637
   * This method should only be used <em>after</em> a transaction 
 
638
   * has been executed.  
 
639
   * - NdbTransaction::getNextCompletedOperation(NULL) returns the
 
640
   *   first NdbOperation object.
 
641
   * - NdbTransaction::getNextCompletedOperation(op) returns the
 
642
   *   NdbOperation object defined after the NdbOperation "op".
 
643
   * 
 
644
   * This method is typically used to fetch all NdbOperation:s of 
 
645
   * a transaction to check for errors (use NdbOperation::getNdbError 
 
646
   * to fetch the NdbError object of an NdbOperation).
 
647
   * 
 
648
   * @note This method should only be used after the transaction has been 
 
649
   *       executed and before the transaction has been closed.
 
650
   * 
 
651
   * @param   op Operation, NULL means get first operation
 
652
   * @return  Operation "after" op
 
653
   */
 
654
  const NdbOperation * getNextCompletedOperation(const NdbOperation * op)const;
 
655
 
 
656
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
657
  const NdbOperation* getFirstDefinedOperation()const{return theFirstOpInList;}
 
658
  const NdbOperation* getLastDefinedOperation()const{return theLastOpInList;}
 
659
 
 
660
  /** @} *********************************************************************/
 
661
 
 
662
  /**
 
663
   * Execute the transaction in NoCommit mode if there are any not-yet
 
664
   * executed blob part operations of given types.  Otherwise do
 
665
   * nothing.  The flags argument is bitwise OR of (1 << optype) where
 
666
   * optype comes from NdbOperation::OperationType.  Only the basic PK
 
667
   * ops are used (read, insert, update, delete).
 
668
   */
 
669
  int executePendingBlobOps(Uint8 flags = 0xFF);
 
670
 
 
671
  /**
 
672
   * Get nodeId of TC for this transaction
 
673
   */
 
674
  Uint32 getConnectedNodeId(); // Get Connected node id
 
675
#endif
 
676
 
 
677
  /*
 
678
   * NdbRecord primary key and unique key operations.
 
679
   *
 
680
   * If the key_rec passed in is for a table, the operation will be a primary
 
681
   * key operation. If it is for an index, it will be a unique key operation
 
682
   * using that index.
 
683
   *
 
684
   * The key_row passed in defines the primary or unique key of the affected
 
685
   * tuple, and must remain valid until execute() is called. The key_rec must
 
686
   * include all columns of the key.
 
687
   *
 
688
   * The mask, if != NULL, defines a subset of attributes to read, update, or
 
689
   * insert. Only if (mask[attrId >> 3] & (1<<(attrId & 7))) is set is the
 
690
   * column affected. The mask is copied by the methods, so need not remain
 
691
   * valid after the call returns.
 
692
   *
 
693
   * For unique index operations, the attr_rec must refer to the underlying
 
694
   * table of the index.
 
695
   *
 
696
   * OperationOptions can be used to give finer-grained control of operation
 
697
   * definition.  An OperationOptions structure is passed with flags
 
698
   * indicating which operation definition options are present.  Not all
 
699
   * operation types support all operation options.  See the definition of
 
700
   * the OperationOptions structure for more information on individual options.
 
701
   *
 
702
   *   Operation type        Supported OperationOptions flags
 
703
   *   --------------        --------------------------------
 
704
   *   readTuple             OO_ABORTOPTION, OO_GETVALUE,
 
705
   *                         OO_PARTITION_ID, OO_INTERPRETED
 
706
   *   insertTuple           OO_ABORTOPTION, OO_SETVALUE, 
 
707
   *                         OO_PARTITION_ID, OO_ANYVALUE
 
708
   *   updateTuple           OO_ABORTOPTION, OO_SETVALUE,
 
709
   *                         OO_PARTITION_ID, OO_INTERPRETED,
 
710
   *                         OO_ANYVALUE
 
711
   *   writeTuple            OO_ABORTOPTION, OO_SETVALUE,
 
712
   *                         OO_PARTITION_ID, OO_ANYVALUE
 
713
   *   deleteTuple           OO_ABORTOPTION, OO_GETVALUE,
 
714
   *                         OO_PARTITION_ID, OO_INTERPRETED,
 
715
   *                         OO_ANYVALUE
 
716
   *
 
717
   * The sizeOfOptions optional parameter is used to allow this interface
 
718
   * to be backwards compatible with previous definitions of the OperationOptions
 
719
   * structure.  If an unusual size is detected by the interface implementation, 
 
720
   * it can use this to determine how to interpret the passed OperationOptions 
 
721
   * structure.  To enable this functionality, the caller should pass 
 
722
   * sizeof(NdbOperation::OperationOptions) for this argument.
 
723
   */
 
724
  const NdbOperation *readTuple(const NdbRecord *key_rec, const char *key_row,
 
725
                                const NdbRecord *result_rec, char *result_row,
 
726
                                NdbOperation::LockMode lock_mode= NdbOperation::LM_Read,
 
727
                                const unsigned char *result_mask= 0,
 
728
                                const NdbOperation::OperationOptions *opts = 0,
 
729
                                Uint32 sizeOfOptions = 0);
 
730
  const NdbOperation *insertTuple(const NdbRecord *key_rec, const char *key_row,
 
731
                                  const NdbRecord *attr_rec, const char *attr_row,
 
732
                                  const unsigned char *mask= 0,
 
733
                                  const NdbOperation::OperationOptions *opts = 0,
 
734
                                  Uint32 sizeOfOptions = 0);
 
735
  const NdbOperation *insertTuple(const NdbRecord *combined_rec, const char *combined_row,
 
736
                                  const unsigned char *mask = 0,
 
737
                                  const NdbOperation::OperationOptions *opts = 0,
 
738
                                  Uint32 sizeOfOptions = 0);
 
739
  const NdbOperation *updateTuple(const NdbRecord *key_rec, const char *key_row,
 
740
                                  const NdbRecord *attr_rec, const char *attr_row,
 
741
                                  const unsigned char *mask= 0,
 
742
                                  const NdbOperation::OperationOptions *opts = 0,
 
743
                                  Uint32 sizeOfOptions = 0);
 
744
  const NdbOperation *writeTuple(const NdbRecord *key_rec, const char *key_row,
 
745
                                 const NdbRecord *attr_rec, const char *attr_row,
 
746
                                 const unsigned char *mask= 0,
 
747
                                 const NdbOperation::OperationOptions *opts = 0,
 
748
                                 Uint32 sizeOfOptions = 0);
 
749
  const NdbOperation *deleteTuple(const NdbRecord *key_rec, const char *key_row,
 
750
                                  const NdbRecord *result_rec, char *result_row = 0,
 
751
                                  const unsigned char *result_mask = 0,
 
752
                                  const NdbOperation::OperationOptions *opts = 0,
 
753
                                  Uint32 sizeOfOptions = 0);
 
754
 
 
755
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
756
  const NdbOperation *refreshTuple(const NdbRecord *key_rec, const char *key_row,
 
757
                                   const NdbOperation::OperationOptions *opts = 0,
 
758
                                   Uint32 sizeOfOptions = 0);
 
759
#endif
 
760
 
 
761
  /**
 
762
   * Scan a table, using NdbRecord to read out column data.
 
763
   *
 
764
   * The NdbRecord pointed to by result_record must remain valid until 
 
765
   * the scan operation is closed.
 
766
   *
 
767
   * The result_mask pointer is optional, if present only columns for
 
768
   * which the corresponding bit (by attribute id order) in result_mask
 
769
   * is set will be retrieved in the scan. The result_mask is copied
 
770
   * internally, so in contrast to result_record need not be valid at
 
771
   * execute().
 
772
   * 
 
773
   * A ScanOptions structure can be passed, specifying extra options.  See
 
774
   * the definition of the NdbScanOperation::ScanOptions structure for 
 
775
   * more information.
 
776
   *
 
777
   * To enable backwards compatability of this interface, a sizeOfOptions
 
778
   * parameter can be passed.  This parameter indicates the size of the
 
779
   * ScanOptions structure at the time the client was compiled, and enables
 
780
   * detection of the use of an old ScanOptions structure.  If this 
 
781
   * functionality is not required, it can be left set to zero.
 
782
   */
 
783
  NdbScanOperation *
 
784
  scanTable(const NdbRecord *result_record,
 
785
            NdbOperation::LockMode lock_mode= NdbOperation::LM_Read,
 
786
            const unsigned char *result_mask= 0,
 
787
            const NdbScanOperation::ScanOptions *options = 0,
 
788
            Uint32 sizeOfOptions = 0);
 
789
 
 
790
  /**
 
791
   * Do an index range scan (optionally ordered) of a table.
 
792
   *
 
793
   * The key_record describes the index to be scanned. It must be a key record
 
794
   * for the index, ie. it must specify (at least) all the key columns of the
 
795
   * index. And it must be created from the index to be scanned (not from the
 
796
   * underlying table).
 
797
   *
 
798
   * The result_record describes the rows to be returned from the scan. For an
 
799
   * ordered index scan, result_record must be a key record for the index to
 
800
   * be scanned, that is it must include at least all of the columns in the
 
801
   * index (the reason is that the full index key is needed by NDBAPI for merge 
 
802
   * sorting the ordered rows returned from each fragment).  The result_record
 
803
   * must be created from the underlying table, not from the index to be scanned.
 
804
   *
 
805
   * Both the key_record and result_record NdbRecord structures must stay
 
806
   * in-place until the scan operation is closed.
 
807
   *
 
808
   * A single IndexBound can either be specified in this call or in a separate
 
809
   * call to NdbIndexScanOperation::setBound().  To perform a multi range read, 
 
810
   * the scan_flags in the ScanOptions structure must include SF_MULTIRANGE.  
 
811
   * Additional bounds can then be added using multiple calls to 
 
812
   * NdbIndexScanOperation::setBound().
 
813
   * 
 
814
   * To specify an equals bound, use the same row pointer for the low_key and
 
815
   * high_key with the low and high inclusive bits set.
 
816
   *
 
817
   * A ScanOptions structure can be passed, specifying extra options.  See
 
818
   * the definition of the ScanOptions structure for more information.
 
819
   *
 
820
   * To enable backwards compatability of this interface, a sizeOfOptions
 
821
   * parameter can be passed.  This parameter indicates the size of the
 
822
   * ScanOptions structure at the time the client was compiled, and enables
 
823
   * detection of the use of an old ScanOptions structure.  If this functionality
 
824
   * is not required, it can be left set to zero.
 
825
   * 
 
826
   */
 
827
  NdbIndexScanOperation *
 
828
  scanIndex(const NdbRecord *key_record,
 
829
            const NdbRecord *result_record,
 
830
            NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
 
831
            const unsigned char *result_mask = 0,
 
832
            const NdbIndexScanOperation::IndexBound *bound = 0,
 
833
            const NdbScanOperation::ScanOptions *options = 0,
 
834
            Uint32 sizeOfOptions = 0);
 
835
 
 
836
  /**
 
837
   * Add a prepared NdbQueryDef to transaction for execution.
 
838
   *
 
839
   * If the NdbQueryDef contains parameters,
 
840
   * (built with NdbQueryBilder::paramValue()) the value of these
 
841
   * parameters are specified in the 'paramValue' array. Parameter values
 
842
   * Should be supplied in the same order as the related paramValue's
 
843
   * was defined.
 
844
   */
 
845
  NdbQuery*
 
846
  createQuery(const NdbQueryDef* query,
 
847
              const NdbQueryParamValue paramValue[]= 0,
 
848
              NdbOperation::LockMode lock_mode= NdbOperation::LM_Read);
 
849
 
 
850
  /* LockHandle methods */
 
851
  /*
 
852
   * Shared or Exclusive locks taken by read operations in a transaction
 
853
   * are normally held until the transaction commits or aborts.
 
854
   * Shared or Exclusive *read* locks can be released before transaction
 
855
   * commit or abort time by requesting a LockHandle when defining the
 
856
   * read operation.  Any time after the read operation has been executed,
 
857
   * the LockHandle can be used to create a new Unlock operation.  When
 
858
   * the Unlock operation is executed, the row lock placed by the read
 
859
   * operation will be released.
 
860
   * 
 
861
   * The steps are :
 
862
   *  1) Define the primary key read operation in the normal way
 
863
   *     with lockmode LM_Read or LM_Exclusive
 
864
   *
 
865
   *  2) Call NdbOperation::getLockHandle() during operation definition
 
866
   *     (Or set the OO_LOCKHANDLE operation option when calling
 
867
   *      NdbTransaction::readTuple() for NdbRecord)
 
868
   *  
 
869
   *  3) Call NdbTransaction::execute()
 
870
   *                         (Row will be locked from here as normal)
 
871
   *  
 
872
   *  4) Use the read data, make zero or more calls to 
 
873
   *     NdbTransaction::execute() etc.
 
874
   *  
 
875
   *  5) Call NdbTransaction::unlock(NdbLockHandle*), passing in the
 
876
   *     const LockHandle* from 2) to create an Unlock operation.
 
877
   *  
 
878
   *  6) Call NdbTransaction::execute()
 
879
   *                         (Row will be unlocked from here)
 
880
   * 
 
881
   * Notes
 
882
   * - As with other operation types, Unlock operations can be batched.
 
883
   * - Each LockHandle object refers to a lock placed on a row by a single 
 
884
   *   primary key read operation.  A single row in the database may have 
 
885
   *   concurrent multiple lock holders (of mode LM_Read) and may have 
 
886
   *   multiple lock holders pending (LM_Exclusive), so releasing the
 
887
   *   claim of one lock holder may not result in a change to the 
 
888
   *   observable lock status of the row.
 
889
   * - LockHandles are supported for Scan lock takeover operations - the
 
890
   *   lockhandle must be requested before the locktakeover is executed.
 
891
   * - LockHandles and Unlock operations are not supported for Unique Index
 
892
   *   read operations.
 
893
   */
 
894
 
 
895
  /* unlock
 
896
   * 
 
897
   * This method creates an Unlock operation on the current transaction.
 
898
   * When executed, the Unlock operation will remove the lock referenced
 
899
   * by the passed LockHandle.
 
900
   * 
 
901
   * The unlock operation can fail, for example due to the row being 
 
902
   * unlocked already.  In this scenario, the AbortOption specifies how 
 
903
   * this will be handled.
 
904
   * The default is that errors will cause transaction abort.
 
905
   */
 
906
  const NdbOperation* unlock(const NdbLockHandle* lockHandle,
 
907
                             NdbOperation::AbortOption ao = NdbOperation::DefaultAbortOption);
 
908
  
 
909
  /* releaseLockHandle
 
910
   * This method is used to release a LockHandle object once it
 
911
   * is no longer required.
 
912
   * For NdbRecord primary key read operations, this cannot be
 
913
   * called until the associated read operation has executed.
 
914
   * All LockHandles associated with a transaction are released
 
915
   * when it is closed.
 
916
   */
 
917
  int releaseLockHandle(const NdbLockHandle* lockHandle);
 
918
 
 
919
  /* Get maximum number of pending Blob read/write bytes before
 
920
   * an automatic execute() occurs 
 
921
   */
 
922
  Uint32 getMaxPendingBlobReadBytes() const;
 
923
  Uint32 getMaxPendingBlobWriteBytes() const;
 
924
 
 
925
  /* Set maximum number of pending Blob read/write bytes before
 
926
   * an automatic execute() occurs
 
927
   */
 
928
  void setMaxPendingBlobReadBytes(Uint32 bytes);
 
929
  void setMaxPendingBlobWriteBytes(Uint32 bytes);
 
930
 
 
931
private:                                                
 
932
  /**
 
933
   * Release completed operations
 
934
   */
 
935
  void releaseCompletedOperations();
 
936
  void releaseCompletedQueries();
 
937
 
 
938
  typedef Uint64 TimeMillis_t;
 
939
  /**************************************************************************
 
940
   *    These methods are service methods to other classes in the NDBAPI.   *
 
941
   **************************************************************************/
 
942
 
 
943
  /**************************************************************************
 
944
   *    These are the create and delete methods of this class.              *
 
945
   **************************************************************************/
 
946
  NdbTransaction(Ndb* aNdb); 
 
947
  ~NdbTransaction();
 
948
 
 
949
  int init();           // Initialize connection object for new transaction
 
950
 
 
951
  int executeNoBlobs(ExecType execType, 
 
952
                     NdbOperation::AbortOption = NdbOperation::DefaultAbortOption,
 
953
                     int force = 0 );
 
954
  
 
955
  /**
 
956
   * Set Connected node id 
 
957
   * and sequence no
 
958
   */
 
959
  void setConnectedNodeId( Uint32 nodeId, Uint32 sequence); 
 
960
 
 
961
  void          setMyBlockReference( int );       // Set my block refrerence
 
962
  void          setTC_ConnectPtr( Uint32 );       // Sets TC Connect pointer
 
963
  int           getTC_ConnectPtr();               // Gets TC Connect pointer
 
964
  void          setBuddyConPtr(Uint32);           // Sets Buddy Con Ptr
 
965
  Uint32        getBuddyConPtr();                 // Gets Buddy Con Ptr
 
966
  NdbTransaction* next();                         // Returns the next pointer
 
967
  void          next(NdbTransaction*);            // Sets the next pointer
 
968
 
 
969
  enum ConStatusType { 
 
970
    NotConnected,
 
971
    Connecting,
 
972
    Connected,
 
973
    DisConnecting,
 
974
    ConnectFailure
 
975
  };
 
976
  ConStatusType Status();                 // Read the status information
 
977
  void          Status(ConStatusType);    // Set the status information
 
978
 
 
979
  Uint32        get_send_size();                  // Get size to send
 
980
  void          set_send_size(Uint32);            // Set size to send;
 
981
  
 
982
  int  receiveTCSEIZECONF(const NdbApiSignal* anApiSignal);
 
983
  int  receiveTCSEIZEREF(const NdbApiSignal* anApiSignal);
 
984
  int  receiveTCRELEASECONF(const NdbApiSignal* anApiSignal);
 
985
  int  receiveTCRELEASEREF(const NdbApiSignal* anApiSignal);
 
986
  int  receiveTC_COMMITCONF(const class TcCommitConf *, Uint32 len);
 
987
  int  receiveTCKEYCONF(const class TcKeyConf *, Uint32 aDataLength);
 
988
  int  receiveTCKEY_FAILCONF(const class TcKeyFailConf *);
 
989
  int  receiveTCKEY_FAILREF(const NdbApiSignal* anApiSignal);
 
990
  int  receiveTC_COMMITREF(const NdbApiSignal* anApiSignal);
 
991
  int  receiveTCROLLBACKCONF(const NdbApiSignal* anApiSignal);
 
992
  int  receiveTCROLLBACKREF(const NdbApiSignal* anApiSignal);
 
993
  int  receiveTCROLLBACKREP(const NdbApiSignal* anApiSignal);
 
994
  int  receiveTCINDXREF(const NdbApiSignal*);
 
995
  int  receiveSCAN_TABREF(const NdbApiSignal*);
 
996
  int  receiveSCAN_TABCONF(const NdbApiSignal*, const Uint32*, Uint32 len);
 
997
 
 
998
  int   doSend();                       // Send all operations
 
999
  int   sendROLLBACK();                 // Send of an ROLLBACK
 
1000
  int   sendTC_HBREP();                 // Send a TCHBREP signal;
 
1001
  int   sendCOMMIT();                   // Send a TC_COMMITREQ signal;
 
1002
  void  setGCI(int GCI);                // Set the global checkpoint identity
 
1003
 
 
1004
  int   OpCompleteFailure();
 
1005
  int   OpCompleteSuccess();
 
1006
 
 
1007
  void  OpSent();                       // Operation Sent with success
 
1008
  
 
1009
  // Free connection related resources and close transaction
 
1010
  void          release();              
 
1011
 
 
1012
  // Release all operations in connection
 
1013
  void          releaseOperations();    
 
1014
 
 
1015
  // Release all cursor operations in connection
 
1016
  void releaseOps(NdbOperation*);       
 
1017
  void releaseQueries(NdbQueryImpl*);
 
1018
  void releaseScanOperations(NdbIndexScanOperation*);   
 
1019
  bool releaseScanOperation(NdbIndexScanOperation** listhead,
 
1020
                            NdbIndexScanOperation** listtail,
 
1021
                            NdbIndexScanOperation* op);
 
1022
  void          releaseLockHandles();
 
1023
  
 
1024
  // Set the transaction identity of the transaction
 
1025
  void          setTransactionId(Uint64 aTransactionId);
 
1026
 
 
1027
  // Indicate something went wrong in the definition phase
 
1028
  void          setErrorCode(int anErrorCode);          
 
1029
 
 
1030
  // Indicate something went wrong in the definition phase
 
1031
  void          setOperationErrorCode(int anErrorCode); 
 
1032
 
 
1033
  // Indicate something went wrong in the definition phase
 
1034
  void          setOperationErrorCodeAbort(int anErrorCode, int abortOption = -1);
 
1035
 
 
1036
  int           checkMagicNumber();                    // Verify correct object
 
1037
  NdbOperation* getNdbOperation(const class NdbTableImpl* aTable,
 
1038
                                NdbOperation* aNextOp = 0,
 
1039
                                bool useRec= false);
 
1040
 
 
1041
  NdbIndexScanOperation* getNdbScanOperation(const class NdbTableImpl* aTable);
 
1042
  NdbIndexOperation* getNdbIndexOperation(const class NdbIndexImpl* anIndex, 
 
1043
                                          const class NdbTableImpl* aTable,
 
1044
                                          NdbOperation* aNextOp = 0,
 
1045
                                          bool useRec= false);
 
1046
  NdbIndexScanOperation* getNdbIndexScanOperation(const NdbIndexImpl* index,
 
1047
                                                  const NdbTableImpl* table);
 
1048
  
 
1049
  NdbOperation *setupRecordOp(NdbOperation::OperationType type,
 
1050
                              NdbOperation::LockMode lock_mode,
 
1051
                              NdbOperation::AbortOption default_ao,
 
1052
                              const NdbRecord *key_record,
 
1053
                              const char *key_row,
 
1054
                              const NdbRecord *attribute_record,
 
1055
                              const char *attribute_row,
 
1056
                              const unsigned char *mask,
 
1057
                              const NdbOperation::OperationOptions *opts,
 
1058
                              Uint32 sizeOfOptions,
 
1059
                              const NdbLockHandle* lh = 0);
 
1060
 
 
1061
  void          handleExecuteCompletion();
 
1062
  
 
1063
  /****************************************************************************
 
1064
   * These are the private variables of this class.
 
1065
   ****************************************************************************/
 
1066
 
 
1067
  Uint32 ptr2int();
 
1068
  Uint32 theId;
 
1069
 
 
1070
  // Keeps track of what the send method should do.
 
1071
  enum SendStatusType { 
 
1072
    NotInit,  
 
1073
    InitState,  
 
1074
    sendOperations,  
 
1075
    sendCompleted, 
 
1076
    sendCOMMITstate, 
 
1077
    sendABORT, 
 
1078
    sendABORTfail, 
 
1079
    sendTC_ROLLBACK,  
 
1080
    sendTC_COMMIT, 
 
1081
    sendTC_OP       
 
1082
  };
 
1083
  SendStatusType theSendStatus; 
 
1084
  NdbAsynchCallback  theCallbackFunction;    // Pointer to the callback function
 
1085
  void*              theCallbackObject;      // The callback object pointer
 
1086
  Uint32             theTransArrayIndex;     // Current index in a transaction 
 
1087
                                             // array for this object
 
1088
  TimeMillis_t       theStartTransTime;      // Start time of the transaction
 
1089
 
 
1090
  NdbError theError;            // Errorcode on transaction
 
1091
  int      theErrorLine;        // Method number of last error in NdbOperation
 
1092
  NdbOperation* theErrorOperation; // The NdbOperation where the error occurred
 
1093
 
 
1094
  Ndb*          theNdb;                      // Pointer to Ndb object      
 
1095
  NdbTransaction* theNext;                   // Next pointer. Used in idle list.
 
1096
 
 
1097
  NdbOperation* theFirstOpInList;           // First operation in defining list.
 
1098
  NdbOperation* theLastOpInList;            // Last operation in defining list.
 
1099
 
 
1100
  NdbOperation* theFirstExecOpInList;       // First executing operation in list
 
1101
  NdbOperation* theLastExecOpInList;        // Last executing operation in list.
 
1102
 
 
1103
 
 
1104
  NdbOperation* theCompletedFirstOp;        // First & last operation in completed 
 
1105
  NdbOperation* theCompletedLastOp;         // operation list.
 
1106
 
 
1107
  Uint32        theNoOfOpSent;                          // How many operations have been sent       
 
1108
  Uint32        theNoOfOpCompleted;                     // How many operations have completed
 
1109
  Uint32        theMyRef;                               // Our block reference          
 
1110
  Uint32        theTCConPtr;                            // Transaction Co-ordinator connection pointer.
 
1111
  Uint64        theTransactionId;                       // theTransactionId of the transaction
 
1112
  Uint64        theGlobalCheckpointId;                  // The gloabl checkpoint identity of the transaction
 
1113
  Uint64 *p_latest_trans_gci;                           // Reference to latest gci for connection
 
1114
  ConStatusType theStatus;                              // The status of the connection         
 
1115
  enum CompletionStatus { 
 
1116
    NotCompleted,
 
1117
    CompletedSuccess,
 
1118
    CompletedFailure,
 
1119
    DefinitionFailure
 
1120
  } theCompletionStatus;          // The Completion status of the transaction
 
1121
  CommitStatusType theCommitStatus;                     // The commit status of the transaction
 
1122
  Uint32        theMagicNumber;                         // Magic Number to verify correct object
 
1123
                                                        // Current meanings :
 
1124
                                                        //   0x00FE11DC : NdbTransaction not in use
 
1125
                                                        //   0x37412619 : NdbTransaction in use
 
1126
                                                        //   0x00FE11DF : NdbTransaction for scan operation
 
1127
                                                        //                scan definition not yet complete
 
1128
  Uint32        thePriority;                            // Transaction Priority
 
1129
 
 
1130
  enum ReturnType {  ReturnSuccess,  ReturnFailure };
 
1131
  ReturnType    theReturnStatus;                        // Did we have any read/update/delete failing
 
1132
                                                        // to find the tuple.
 
1133
  bool theTransactionIsStarted; 
 
1134
  bool theInUseState;
 
1135
  bool theSimpleState;
 
1136
 
 
1137
  enum ListState {  
 
1138
    NotInList, 
 
1139
    InPreparedList, 
 
1140
    InSendList, 
 
1141
    InCompletedList 
 
1142
  } theListState;
 
1143
 
 
1144
  Uint32 theDBnode;       // The database node we are connected to  
 
1145
  Uint32 theNodeSequence; // The sequence no of the db node
 
1146
  bool theReleaseOnClose;
 
1147
 
 
1148
  /**
 
1149
   * handle transaction spanning
 
1150
   *   multiple TC/db nodes
 
1151
   *
 
1152
   * 1) Bitmask with used nodes
 
1153
   * 2) Bitmask with nodes failed during op
 
1154
   */
 
1155
  Uint32 m_db_nodes[2];
 
1156
  Uint32 m_failed_db_nodes[2];
 
1157
  
 
1158
  int report_node_failure(Uint32 id);
 
1159
 
 
1160
  // Scan operations
 
1161
  bool m_waitForReply;     
 
1162
  NdbIndexScanOperation* m_theFirstScanOperation;
 
1163
  NdbIndexScanOperation* m_theLastScanOperation;
 
1164
  
 
1165
  NdbIndexScanOperation* m_firstExecutedScanOp;
 
1166
 
 
1167
  // Scan operations or queries:
 
1168
  // The operation or query actually performing the scan.
 
1169
  // (Only one of theScanningOp/m_scanningQuery be non-NULL,
 
1170
  //  which indirectly indicates the type)
 
1171
  NdbScanOperation* theScanningOp;
 
1172
 
 
1173
  Uint32 theBuddyConPtr;
 
1174
  // optim: any blobs
 
1175
  bool theBlobFlag;
 
1176
  Uint8 thePendingBlobOps;
 
1177
  Uint32 maxPendingBlobReadBytes;
 
1178
  Uint32 maxPendingBlobWriteBytes;
 
1179
  Uint32 pendingBlobReadBytes;
 
1180
  Uint32 pendingBlobWriteBytes;
 
1181
  inline bool hasBlobOperation() { return theBlobFlag; }
 
1182
 
 
1183
  static void sendTC_COMMIT_ACK(class NdbImpl *, NdbApiSignal *,
 
1184
                                Uint32 transId1, Uint32 transId2, 
 
1185
                                Uint32 aBlockRef);
 
1186
 
 
1187
  void completedFail(const char * s);
 
1188
#ifdef VM_TRACE
 
1189
  void printState();
 
1190
#endif
 
1191
  bool checkState_TransId(const Uint32 * transId) const;
 
1192
 
 
1193
  void remove_list(NdbOperation*& head, NdbOperation*);
 
1194
  void define_scan_op(NdbIndexScanOperation*);
 
1195
 
 
1196
  NdbLockHandle* m_theFirstLockHandle;
 
1197
  NdbLockHandle* m_theLastLockHandle;
 
1198
 
 
1199
  NdbLockHandle* getLockHandle();
 
1200
 
 
1201
  friend class HugoOperations;
 
1202
  friend struct Ndb_free_list_t<NdbTransaction>;
 
1203
 
 
1204
  NdbTransaction(const NdbTransaction&); // Not impl.
 
1205
  NdbTransaction&operator=(const NdbTransaction&);
 
1206
 
 
1207
  // Query operation (aka multicursor)
 
1208
  NdbQueryImpl* m_firstQuery;        // First query in defining list.
 
1209
  NdbQueryImpl* m_firstExecQuery;    // First query to send for execution
 
1210
  NdbQueryImpl* m_firstActiveQuery;  // First query actively executing, or completed
 
1211
 
 
1212
  // Scan operations or queries:
 
1213
  // The operation or query actually performing the scan.
 
1214
  // (Only one of theScanningOp/m_scanningQuery be non-NULL,
 
1215
  //  which indirectly indicates the type)
 
1216
  NdbQueryImpl* m_scanningQuery;
 
1217
 
 
1218
  Uint32 m_tcRef;
 
1219
};
 
1220
 
 
1221
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
1222
 
 
1223
inline
 
1224
Uint32
 
1225
NdbTransaction::get_send_size()
 
1226
{
 
1227
  return 0;
 
1228
}
 
1229
 
 
1230
inline
 
1231
void
 
1232
NdbTransaction::set_send_size(Uint32 send_size)
 
1233
{
 
1234
  (void)send_size; //unused
 
1235
  return;
 
1236
}
 
1237
 
 
1238
#ifdef NDB_NO_DROPPED_SIGNAL
 
1239
#include <stdlib.h>
 
1240
#endif
 
1241
 
 
1242
inline
 
1243
int
 
1244
NdbTransaction::checkMagicNumber()
 
1245
{
 
1246
  if (theMagicNumber == 0x37412619)
 
1247
    return 0;
 
1248
  else {
 
1249
#ifdef NDB_NO_DROPPED_SIGNAL
 
1250
    abort();
 
1251
#endif
 
1252
    return -1;
 
1253
  }
 
1254
}
 
1255
 
 
1256
inline
 
1257
bool
 
1258
NdbTransaction::checkState_TransId(const Uint32 * transId) const {
 
1259
  const Uint32 tTmp1 = transId[0];
 
1260
  const Uint32 tTmp2 = transId[1];
 
1261
  Uint64 tRecTransId = (Uint64)tTmp1 + ((Uint64)tTmp2 << 32);
 
1262
  bool b = theStatus == Connected && theTransactionId == tRecTransId;
 
1263
  return b;
 
1264
}
 
1265
 
 
1266
/************************************************************************************************
 
1267
void setTransactionId(Uint64 aTransactionId);
 
1268
 
 
1269
Remark:        Set the transaction identity. 
 
1270
************************************************************************************************/
 
1271
inline
 
1272
void
 
1273
NdbTransaction::setTransactionId(Uint64 aTransactionId)
 
1274
{
 
1275
  theTransactionId = aTransactionId;
 
1276
}
 
1277
 
 
1278
inline
 
1279
void                    
 
1280
NdbTransaction::setConnectedNodeId(Uint32 aNode, Uint32 aSequenceNo)
 
1281
{
 
1282
  theDBnode = aNode;
 
1283
  theNodeSequence = aSequenceNo;
 
1284
}       
 
1285
/******************************************************************************
 
1286
int getConnectedNodeId();
 
1287
 
 
1288
Return Value:   Return  theDBnode.
 
1289
Remark:         Get Connected node id. 
 
1290
******************************************************************************/
 
1291
inline
 
1292
Uint32                  
 
1293
NdbTransaction::getConnectedNodeId()
 
1294
{
 
1295
  return theDBnode;
 
1296
}       
 
1297
/******************************************************************************
 
1298
void setMyBlockReference(int aBlockRef);
 
1299
 
 
1300
Parameters:     aBlockRef: The block refrerence.
 
1301
Remark:         Set my block refrerence. 
 
1302
******************************************************************************/
 
1303
inline
 
1304
void                    
 
1305
NdbTransaction::setMyBlockReference(int aBlockRef)      
 
1306
{
 
1307
  theMyRef = aBlockRef;
 
1308
}
 
1309
/******************************************************************************
 
1310
void  setTC_ConnectPtr(Uint32 aTCConPtr);
 
1311
 
 
1312
Parameters:     aTCConPtr: The connection pointer.
 
1313
Remark:         Sets TC Connect pointer. 
 
1314
******************************************************************************/
 
1315
inline
 
1316
void                    
 
1317
NdbTransaction::setTC_ConnectPtr(Uint32 aTCConPtr)
 
1318
{
 
1319
  theTCConPtr = aTCConPtr;
 
1320
}
 
1321
 
 
1322
/******************************************************************************
 
1323
int  getTC_ConnectPtr();
 
1324
 
 
1325
Return Value:   Return  theTCConPtr.
 
1326
Remark:         Gets TC Connect pointer. 
 
1327
******************************************************************************/
 
1328
inline
 
1329
int                     
 
1330
NdbTransaction::getTC_ConnectPtr()
 
1331
{
 
1332
  return theTCConPtr;
 
1333
}
 
1334
 
 
1335
inline
 
1336
void
 
1337
NdbTransaction::setBuddyConPtr(Uint32 aBuddyConPtr)
 
1338
{
 
1339
  theBuddyConPtr = aBuddyConPtr;
 
1340
}
 
1341
 
 
1342
inline
 
1343
Uint32 NdbTransaction::getBuddyConPtr()
 
1344
{
 
1345
  return theBuddyConPtr;
 
1346
}
 
1347
 
 
1348
/******************************************************************************
 
1349
NdbTransaction* next();
 
1350
 
 
1351
inline
 
1352
void
 
1353
NdbTransaction::setBuddyConPtr(Uint32 aBuddyConPtr)
 
1354
{
 
1355
  theBuddyConPtr = aBuddyConPtr;
 
1356
}
 
1357
 
 
1358
inline
 
1359
Uint32 NdbTransaction::getBuddyConPtr()
 
1360
{
 
1361
  return theBuddyConPtr;
 
1362
}
 
1363
 
 
1364
Return Value:   Return  next pointer to NdbTransaction object.
 
1365
Remark:         Get the next pointer. 
 
1366
******************************************************************************/
 
1367
inline
 
1368
NdbTransaction*
 
1369
NdbTransaction::next()
 
1370
{
 
1371
  return theNext;
 
1372
}
 
1373
 
 
1374
/******************************************************************************
 
1375
void next(NdbTransaction aTransaction);
 
1376
 
 
1377
Parameters:     aTransaction: The connection object. 
 
1378
Remark:         Sets the next pointer. 
 
1379
******************************************************************************/
 
1380
inline
 
1381
void
 
1382
NdbTransaction::next(NdbTransaction* aTransaction)
 
1383
{
 
1384
  theNext = aTransaction;
 
1385
}
 
1386
 
 
1387
/******************************************************************************
 
1388
ConStatusType  Status();
 
1389
 
 
1390
Return Value    Return the ConStatusType.       
 
1391
Parameters:     aStatus:  The status.
 
1392
Remark:         Sets Connect status. 
 
1393
******************************************************************************/
 
1394
inline
 
1395
NdbTransaction::ConStatusType                   
 
1396
NdbTransaction::Status()
 
1397
{
 
1398
  return theStatus;
 
1399
}
 
1400
 
 
1401
/******************************************************************************
 
1402
void  Status(ConStatusType aStatus);
 
1403
 
 
1404
Parameters:     aStatus: The status.
 
1405
Remark:         Sets Connect status. 
 
1406
******************************************************************************/
 
1407
inline
 
1408
void                    
 
1409
NdbTransaction::Status( ConStatusType aStatus )
 
1410
{
 
1411
  theStatus = aStatus;
 
1412
}
 
1413
 
 
1414
 
 
1415
/******************************************************************************
 
1416
void OpSent();
 
1417
 
 
1418
Remark:       An operation was sent with success that expects a response.
 
1419
******************************************************************************/
 
1420
inline
 
1421
void 
 
1422
NdbTransaction::OpSent()
 
1423
{
 
1424
  theNoOfOpSent++;
 
1425
}
 
1426
 
 
1427
/******************************************************************************
 
1428
void executePendingBlobOps();
 
1429
******************************************************************************/
 
1430
inline
 
1431
int
 
1432
NdbTransaction::executePendingBlobOps(Uint8 flags)
 
1433
{
 
1434
  if (thePendingBlobOps & flags) {
 
1435
    // not executeNoBlobs because there can be new ops with blobs
 
1436
    return execute(NoCommit);
 
1437
  }
 
1438
  return 0;
 
1439
}
 
1440
 
 
1441
inline
 
1442
Uint32
 
1443
NdbTransaction::ptr2int(){
 
1444
  return theId;
 
1445
}
 
1446
 
 
1447
typedef NdbTransaction NdbConnection;
 
1448
 
 
1449
#endif // ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
1450
 
 
1451
#endif