MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbTransaction
class.
None
None
A transaction is represented in the NDB API by an
NdbTransaction
object, which belongs to
an Ndb
object and is
created using
Ndb::startTransaction()
. A
transaction consists of a list of operations represented by
the NdbOperation
class, or
by one of its
subclasses—NdbScanOperation
,
NdbIndexOperation
, or
NdbIndexScanOperation
. Each
operation access exactly one table.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.65 NdbTransaction class methods and descriptions
Name | Description |
---|---|
close() |
Closes a transaction |
commitStatus() |
Gets the transaction's commit status |
deleteTuple() |
Delete a tuple using NdbRecord |
execute() |
Executes a transaction |
executePendingBlobOps() |
Executes a transaction in NoCommit mode if it
includes any blob part operations of the specified
types that are not yet executed. |
getGCI() |
Gets a transaction's global checkpoint ID (GCI) |
getMaxPendingBlobReadBytes() |
Get the current blob read batch size |
getMaxPendingBlobWriteBytes() |
Get the current blob write batch size |
getNdbError() |
Gets the most recent error |
getNdbErrorLine() |
Gets the line number where the most recent error occurred |
getNdbErrorOperation() |
Gets the most recent operation which caused an error |
getNextCompletedOperation() |
Gets operations that have been executed; used for finding errors |
getNdbOperation() |
Gets an NdbOperation |
getNdbScanOperation() |
Gets an NdbScanOperation |
getNdbIndexOperation() |
Gets an NdbIndexOperation |
getNdbIndexScanOperation() |
Gets an NdbIndexScanOperation |
getTransactionId() |
Gets the transaction ID |
insertTuple() |
Insert a tuple using NdbRecord |
readTuple() |
Read a tuple using NdbRecord |
refresh() |
Keeps a transaction from timing out |
releaseLockHandle() |
Release an NdbLockHandle object once it is no longer
needed |
scanIndex() |
Perform an index scan using NdbRecord |
scanTable() |
Perform a table scan using NdbRecord |
setMaxPendingBlobReadBytes() |
Set the blob read batch size |
setMaxPendingBlobWriteBytes() |
Set the blob write batch size |
setSchemaObjectOwnerChecks() |
Enable or disable schema object ownership checks |
unlock() |
Create an unlock operation on the current transaction |
updateTuple() |
Update a tuple using NdbRecord |
writeTuple() |
Write a tuple using NdbRecord |
The methods
readTuple()
,
insertTuple()
,
updateTuple()
,
writeTuple()
,
deleteTuple()
,
scanTable()
,
and
scanIndex()
require the use of
NdbRecord
.
NdbTransaction
defines 2 public types as
shown in the following table:
Table 2.66 NdbTransaction class types and descriptions
Name | Description |
---|---|
CommitStatusType() |
Describes the transaction's commit status |
ExecType() |
Determines whether the transaction should be committed or rolled back |
Using Transactions.
After obtaining an NdbTransaction
object, it
is employed as follows:
An operation is allocated to the transaction using any one of the following methods:
getNdbOperation()
getNdbScanOperation()
getNdbIndexOperation()
getNdbIndexScanOperation()
Calling one of these methods defines the operation. Several
operations can be defined on the same
NdbTransaction
object, in which case they
are executed in parallel. When all operations are defined, the
execute()
method sends them to the NDB
kernel for
execution.
The execute()
method returns when the NDB
kernel has
completed execution of all operations previously defined.
All allocated operations should be properly defined
before calling the
execute()
method.
execute()
operates in one of the three modes listed here:
NdbTransaction::NoCommit
: Executes
operations without committing them.
NdbTransaction::Commit
: Executes any
remaining operation and then commits the complete
transaction.
NdbTransaction::Rollback
: Rolls back
the entire transaction.
execute()
is
also equipped with an extra error handling parameter, which
provides the two alternatives listed here:
NdbOperation::AbortOnError
: Any error
causes the transaction to be aborted. This is the default
behavior.
NdbOperation::AO_IgnoreError
: The
transaction continues to be executed even if one or more
of the operations defined for that transaction fails.
This method closes a transaction. It is equivalent to
calling
Ndb::closeTransaction()
.
If the transaction has not yet been committed, it is aborted when this method is called. See Ndb::startTransaction().
void close ( void )
None.
None.
This method gets the transaction's commit status.
CommitStatusType commitStatus ( void )
None.
The commit status of the transaction, a value of type
CommitStatusType
.
This section provides information about the
CommitStatusType
data type.
This type is used to describe a transaction's commit status.
Possible values are shown, along with descriptions, in the following table:
Table 2.67 NdbTransaction::CommitStatusType values and descriptions
Name | Description |
---|---|
NotStarted |
The transaction has not yet been started. |
Started |
The transaction has started, but is not yet committed. |
Committed |
The transaction has completed, and has been committed. |
Aborted |
The transaction was aborted. |
NeedAbort |
The transaction has encountered an error, but has not yet been aborted. |
A transaction's commit status ca be read using
commitStatus()
.
Deletes a tuple using
NdbRecord
.
const NdbOperation* deleteTuple ( const NdbRecord*key_rec
, const char*key_row
, const NdbRecord*result_rec
, char*result_row
, const unsigned char*result_mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
This method takes the following parameters:
key_rec
is a pointer to an
NdbRecord
for either a
table or an index. If on a table, then the delete
operation uses a primary key; if on an index, then the
operation uses a unique key. In either case, the
key_rec
must include all
columns of the key.
The key_row
passed to this
method defines the primary or unique key of the tuple to
be deleted, and must remain valid until
execute()
is called.
The result_rec
is the
NdbRecord
to be used.
The result_row
can be
NULL
if no attributes are to be
returned.
The result_mask
, if not
NULL
, defines a subset of attributes
to be read and returned to the client. The mask is
copied, and so does not need to remain valid after the
call to this method returns.
OperationOptions
(opts
) can be used to provide
more finely-grained control of operation definitions. An
OperationOptions
structure is passed
with flags indicating which operation definition options
are present. Not all operation types support all
operation options; for the options supported by each
type of operation, see
NdbTransaction::readTuple().
The optional sizeOfOptions
parameter provides backward compatibility of this
interface with previous definitions of the
OperationOptions
structure. If an unusual size is detected by the
interface implementation, it can use this to determine
how to interpret the passed
OperationOptions
structure. To enable
this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions)
for the value of this argument.
A const
pointer to the
NdbOperation
representing
this write operation. The operation can be checked for
errors if necessary.
This section provides information about the
ExecType
data type.
This type sets the transaction's execution type; that
is, whether it should execute, execute and commit, or abort.
It is used as a parameter to the
execute()
method. (See
NdbTransaction::execute().)
Possible values are shown, along with descriptions, in the following table:
Table 2.68 NdbTransaction::ExecType values and descriptions
Name | Description |
---|---|
NoCommit |
The transaction should execute, but not commit. |
Commit |
The transaction should execute and be committed. |
Rollback |
The transaction should be rolled back. |
This method is used to execute a transaction.
int execute ( ExecTypeexecType
, NdbOperation::AbortOptionabortOption
= NdbOperation::DefaultAbortOption, intforce
= 0 )
The execute()
method takes the three
parameters listed here:
The execution type (ExecType
value);
see NdbTransaction::ExecType, for
more information and possible values.
An abort option
(NdbOperation::AbortOption
value).
Errors arising from this method are found with
NdbOperation::getNdbError()
rather than
NdbTransaction::getNdbError()
.
information.
A force
parameter, which
determines when operations should be sent to the
NDB
Kernel. It takes ones of the
values listed here:
0
: Nonforced; detected by the
adaptive send algorithm.
1
: Forced; detected by the
adaptive send algorithm.
2
: Nonforced; not detected by the
adaptive send algorithm.
See Section 1.4.4, “The Adaptive Send Algorithm”, for more information.
Returns 0
on success, or
-1
on failure. The fact that the
transaction did not abort does not necessarily mean that
each operation was successful; you must check each operation
individually for errors.
This method reports a failure if and only if the transaction was aborted. The transaction's error information is set in such cases to reflect the actual error code and category.
In the case where a NoDataFound error is a possibility, you must check for it explicitly, as shown in this example:
Ndb_cluster_connection myConnection; if( myConnection.connect(4, 5, 1) ) { cout << "Unable to connect to cluster within 30 secs." << endl; exit(-1); } Ndb myNdb(&myConnection, "test"); // define operations... myTransaction = myNdb->startTransaction(); if(myTransaction->getNdbError().classification == NdbError:NoDataFound) { cout << "No records found." << endl; // ... } myNdb->closeTransaction(myTransaction);
This method executes the transaction with
ExecType
equal to NoCommit
if there remain any
blob part operations of the given types which have not yet
been executed.
int executePendingBlobOps
(
Uint8 flags
= 0xFF
)
The flags
argument is the result
of a bitwise OR
, equal to 1
<<
, where
optype
optype
is an
NdbOperation::Type
. The
default corresponds to
NdbOperation::Type::PrimaryKeyAccess
.
Returns 0
on success, or
-1
on failure. The fact that the
transaction did not abort does not necessarily mean that
each operation was successful; you must check each operation
individually for errors.
This method retrieves the transaction's global checkpoint ID (GCI).
Each committed transaction belongs to a GCI. The log for the committed transaction is saved on disk when a global checkpoint occurs.
By comparing the GCI of a transaction with the value of the latest GCI restored in a restarted NDB Cluster, you can determine whether or not the transaction was restored.
Whether or not the global checkpoint with this GCI has been saved on disk cannot be determined by this method.
The GCI for a scan transaction is undefined, since no updates are performed in scan transactions.
No GCI is available until
execute()
has been called with ExecType::Commit
.
int getGCI ( void )
None.
The transaction's GCI, or -1
if none
is available.
Gets the current batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.
Uint32 getMaxPendingBlobReadBytes ( void ) const
None.
The current blob read batch size, in bytes. See NdbTransaction::setMaxPendingBlobReadBytes(), for more information.
Gets the current batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.
Uint32 getMaxPendingBlobWriteBytes ( void ) const
None.
The current blob write batch size, in bytes. See NdbTransaction::setMaxPendingBlobWriteBytes(), for more information.
For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.
This method return the line number where the most recent error occurred.
int getNdbErrorLine ( void )
None.
The line number of the most recent error.
For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.
This method retrieves the operation that caused an error.
To obtain more information about the actual error, use the
NdbOperation::getNdbError()
method of the NdbOperation
object returned by
getNdbErrorOperation()
.
NdbOperation* getNdbErrorOperation ( void )
None.
A pointer to an
NdbOperation
.
For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.
This method is used to create an
NdbIndexOperation
associated with a given table.
All index operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.
NdbIndexOperation* getNdbIndexOperation
(
const NdbDictionary::Index* index
)
The Index
object on which
the operation is to be performed.
A pointer to the new
NdbIndexOperation
.
This method is used to create an
NdbIndexScanOperation
associated with a given table.
All index scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.
NdbIndexScanOperation* getNdbIndexScanOperation
(
const NdbDictionary::Index* index
)
The Index
object on which
the operation is to be performed.
A pointer to the new
NdbIndexScanOperation
.
This method is used to create an
NdbOperation
associated
with a given table.
All operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.
NdbOperation* getNdbOperation
(
const NdbDictionary::Table* table
)
The Table
object on which
the operation is to be performed.
A pointer to the new
NdbOperation
.
This method is used to create an
NdbScanOperation
associated
with a given table.
All scan operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.
NdbScanOperation* getNdbScanOperation
(
const NdbDictionary::Table* table
)
The Table
object on which
the operation is to be performed.
A pointer to the new
NdbScanOperation
.
This method is used to retrieve a transaction's completed operations. It is typically used to fetch all operations belonging to a given transaction to check for errors.
NdbTransaction::getNextCompletedOperation(NULL)
returns the transaction's first
NdbOperation
object;
NdbTransaction::getNextCompletedOperation(
returns the myOp
)NdbOperation
object defined after
NdbOperation
myOp
.
This method should only be used after the transaction has been executed, but before the transaction has been closed.
const NdbOperation* getNextCompletedOperation
(
const NdbOperation* op
) const
This method requires a single parameter
op
, which is an operation
(NdbOperation
object), or
NULL
.
The operation following op
, or
the first operation defined for the transaction if
getNextCompletedOperation()
was called
using NULL
.
This method is used to obtain the transaction ID.
Uint64 getTransactionId ( void )
None.
The transaction ID, as an unsigned 64-bit integer.
Inserts a tuple using
NdbRecord
.
const NdbOperation* insertTuple ( const NdbRecord*key_rec
, const char*key_row
, const NdbRecord*attr_rec
, const char*attr_row
, const unsigned char*mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
const NdbOperation* insertTuple ( const NdbRecord*combined_rec
, const char*combined_row
, const unsigned char*mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
insertTuple()
takes the following
parameters:
A pointer to an
NdbRecord
indicating
the record (key_rec
) to be
inserted.
This method can also be called using a single
NdbRecord
pointer and
single char
pointer
(combined_rec
,
combined_row
) where the
single NdbRecord
represents record and attribute and data.
A row (key_row
) of data to be
inserted.
A pointer to an
NdbRecord
indicating an
attribute (attr_rec
) to be
inserted.
A row (attr_row
) of data to
be inserted as the attribute.
A mask
which can be used to
filter the columns to be inserted.
OperationOptions
(opts
) can be used to provide
more finely-grained control of operation definitions. An
OperationOptions
structure is passed
with flags indicating which operation definition options
are present. Not all operation types support all
operation options; for the options supported by each
type of operation, see
NdbTransaction::readTuple().
The optional sizeOfOptions
parameter is used to preserve backward compatibility of
this interface with previous definitions of the
OperationOptions
structure. If an unusual size is detected by the
interface implementation, it can use this to determine
how to interpret the passed
OperationOptions
structure. To enable
this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions)
for the value of this argument.
A const
pointer to the
NdbOperation
representing
this insert operation.
This method reads a tuple using
NdbRecord
objects.
const NdbOperation* readTuple ( const NdbRecord*key_rec
, const char*key_row
, const NdbRecord*result_rec
, char*result_row
, NdbOperation::LockModelock_mode
= NdbOperation::LM_Read, const unsigned char*result_mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
This method takes the following parameters:
key_rec
is a pointer to an
NdbRecord
for either a
table or an index. If on a table, then the operation
uses a primary key; if on an index, then the operation
uses a unique key. In either case, the
key_rec
must include all
columns of the key.
The key_row
passed to this
method defines the primary or unique key of the affected
tuple, and must remain valid until
execute()
is called.
The mask, if not NULL
, defines a
subset of attributes to read, update, or insert. Only if
(mask[
is set is the column affected. The mask
is copied by the methods, so need not remain valid after
the call returns.
attrId
>> 3] &
(1<<(attrId
&
7)))
result_rec
is a pointer to an
NdbRecord
used to hold
the result
result_row
defines a buffer
for the result data.
lock_mode
specifies the lock
mode in effect for the operation. See
NdbOperation::LockMode, for
permitted values and other information.
result_mask
defines a subset
of attributes to read. Only if mask[attrId
>> 3] & (1<<(attrId & 7))
is set is the column affected. The mask is copied, and
so need not remain valid after the method call returns.
OperationOptions
(opts
) can be used to provide
more finely-grained control of operation definitions. An
OperationOptions
structure is passed
with flags indicating which operation definition options
are present. Not all operation types support all
operation options; the options supported for each type
of operation are shown in the following table:
Table 2.69 Operation types for NdbTransaction::readTuple() OperationOptions (opts) parameter, with operation options supported by each type
Operation type (Method) | OperationOptions Flags
Supported |
---|---|
readTuple() |
OO_ABORTOPTION , OO_GETVALUE ,
OO_PARTITION_ID ,
OO_INTERPRETED |
insertTuple() |
OO_ABORTOPTION , OO_SETVALUE ,
OO_PARTITION_ID ,
OO_ANYVALUE |
updateTuple() |
OO_ABORTOPTION , OO_SETVALUE ,
OO_PARTITION_ID ,
OO_INTERPRETED ,
OO_ANYVALUE |
writeTuple() |
OO_ABORTOPTION , OO_SETVALUE ,
OO_PARTITION_ID ,
OO_ANYVALUE |
deleteTuple() |
OO_ABORTOPTION , OO_GETVALUE ,
OO_PARTITION_ID ,
OO_INTERPRETED ,
OO_ANYVALUE |
The optional sizeOfOptions
parameter is used to preserve backward compatibility of
this interface with previous definitions of the
OperationOptions
structure. If an unusual size is detected by the
interface implementation, it can use this to determine
how to interpret the passed
OperationOptions
structure. To enable
this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions)
for the value of this argument.
A pointer to the
NdbOperation
representing
this read operation (this can be used to check for errors).
This method updates the transaction's timeout counter, and thus avoids aborting due to transaction timeout.
It is not advisable to take a lock on a record and maintain it for a extended time since this can impact other transactions.
int refresh ( void )
None.
Returns 0
on success,
-1
on failure.
This method is used to release a lock handle (see
NdbOperation::getLockHandle) when it is
no longer required. For
NdbRecord
primary key read
operations, this cannot be called until the associated read
operation has been executed.
All lock handles associated with a given transaction are released when that transaction is closed.
int releaseLockHandle
(
const NdbLockHandle* lockHandle
)
The NdbLockHandle
object to be released.
0 on success.
Perform an index range scan of a table, with optional ordering.
NdbIndexScanOperation* scanIndex ( const NdbRecord*key_record
, const NdbRecord*result_record
, NdbOperation::LockModelock_mode
= NdbOperation::LM_Read, const unsigned char*result_mask
= 0, const NdbIndexScanOperation::IndexBound*bound
= 0, const NdbScanOperation::ScanOptions*options
= 0, Uint32sizeOfOptions
= 0 )
The key_record
describes the
index to be scanned. It must be a key record for the
index; that is, it must specify, at a minimum, all of
the key columns of the index. The
key_record
must be created
from the index to be scanned (and not from the
underlying table).
The result_record
describes
the rows to be returned from the scan. For an ordered
index scan, result_record
must be a key record for the index to be scanned; that
is, it must include (at a minimum) all of the columns in
the index (the full index key is needed by the NDB API
for merge-sorting the ordered rows returned from each
fragment).
Like the key_record
, the
result_record
must be created
from the underlying table, and not from the index to be
scanned. Both the key_record
and result_record
NdbRecord
structures
must stay in place until the scan operation is closed.
The result_mask
pointer is
optional. If it is present, only those columns for which
the corresponding bits (by attribute ID order) in
result_mask
are set are
actually retrieved in the scan. The
result_mask
is copied
internally, so in contrast to
result_record
it need not be
valid when execute()
is invoked.
A single
IndexBound
can be specified either in this call or in a separate
call to
NdbIndexScanOperation::setBound()
.
To perform a multi-range read, the
scan_flags
in the
ScanOptions
structure must include SF_MULTIRANGE
.
Additional bounds can be added using successive calls to
NdbIndexScanOperation::setBound()
.
To specify an equals bound, use the same row pointer for
the low_key
and
high_key
with the low and
high inclusive bits set.
For multi-range scans, the
low_key
and
high_key
pointers must be
unique. In other words, it is not permissible to reuse
the same row buffer for several different range bounds
within a single scan. However, it is permissible to use
the same row pointer as
low_key
and
high_key
in order to specify
an equals bound; it is also permissible to reuse the
rows after the scanIndex()
method
returns—that is, they need not remain valid until
execute()
time (unlike the
NdbRecord
pointers).
To specify additional options, pass a
ScanOptions
structure.
The sizeOfOptions
exists to
enable backward compatability for this interface. This
parameter indicates the size of the
ScanOptions
structure at the time the
client was compiled, and enables detection of the use of
an old-style ScanOptions
structure.
If this functionality is not required, this argument can
be left set to 0.
The current
NdbIndexScanOperation
,
which can be used for error checking.
This method performs a table scan, using an
NdbRecord
object to read
out column data.
NdbScanOperation* scanTable ( const NdbRecord*result_record
, NdbOperation::LockModelock_mode
= NdbOperation::LM_Read, const unsigned char*result_mask
= 0, Uint32scan_flags
= 0, Uint32parallel
= 0, Uint32batch
= 0 )
The scanTable()
method takes the
following parameters:
A pointer to an
NdbRecord
for storing
the result. This
result_record
must remain
valid until after the
execute()
call has been made.
The lock_mode
in effect for
the operation. See
NdbOperation::LockMode, for
permitted values and other information.
The result_mask
pointer is
optional. If it is present, only those columns for which
the corresponding bits (by attribute ID order) in
result_mask
are set are
actually retrieved in the scan. The
result_mask
is copied
internally, so in contrast to
result_record
it need not be
valid when execute()
is invoked.
scan_flags
can be used to
impose ordering and sorting conditions for scans. See
NdbScanOperation::ScanFlag, for a
list of permitted values.
The parallel
argument is the
desired parallelism, or 0
for maximum
parallelism (receiving rows from all fragments in
parallel), which is the default.
batch
determines whether
batching is employed. The default is 0 (off).
A pointer to the
NdbScanOperation
representing this scan. The operation can be checked for
errors if necessary.
Sets the batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.
void setMaxPendingBlobReadBytes
(
Uint32 bytes
)
The batch size, as the number of
bytes
. Using 0 causes blob read
batching to be disabled, which is the default behavior (for
backward compatibility).
None.
blob read batching can also be controlled in the
mysql client and other MySQL client
application using the MySQL Server's
--ndb-blob-read-batch-bytes
option and its associated MySQL Server system variables.
Sets the batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.
void setMaxPendingBlobWriteBytes
(
Uint32 bytes
)
The batch size, as the number of
bytes
. Using 0 causes blob write
batching to be disabled, which is the default behavior (for
backward compatibility).
None.
blob write batching can also be controlled in the
mysql client and other MySQL client
application using the MySQL Server's
--ndb-blob-write-batch-bytes
option and its associated MySQL Server system variables.
Enables or disables a schema object ownership check when
multiple
Ndb_cluster_connection
objects are in use. When this check is enabled, objects used
by this transaction are checked to make sure that they
belong to the NdbDictionary
owned by this connection. This is done by acquiring the
schema objects of the same names from the connection and
comparing these with the schema objects passed to the
transaction. If they do not match, an error is returned.
This method is available for debugging purposes beginning with NDB 7.3.9 and NDB 7.4.4. (Bug #19875977) You should be aware that enabling this check carries a performance penalty and for this reason you should avoid doing so in a production setting.
void setSchemaObjOwnerChecks
(
bool runChecks
)
A single parameter runChecks
. Use
true
to enable ownership checks,
false
to disable them.
None.
This method creates an unlock operation on the current
transaction; when executed, the unlock operation removes the
lock referenced by the NdbLockHandle
(see
NdbOperation::getLockHandle) passed to
the method.
const NdbOperation* unlock ( const NdbLockHandle*lockHandle
, NdbOperation::AbortOptionao
= NdbOperation::DefaultAbortOption )
A pointer to a lock handle; in addition, optionally, an
AbortOption
value ao
.
In the event that the unlock operation fails—for
example, due to the row already being unlocked—the
AbortOption
specifies how this is handled, the default being that errors
cause transactions to abort.
A pointer to an
NdbOperation
(the unlock
operation created).
Updates a tuple using an
NdbRecord
object.
const NdbOperation* updateTuple ( const NdbRecord*key_rec
, const char*key_row
, const NdbRecord*attr_rec
, const char*attr_row
, const unsigned char*mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
updateTuple()
takes the following
parameters:
key_rec
is a pointer to an
NdbRecord
for either a
table or an index. If on a table, then the operation
uses a primary key; if on an index, then the operation
uses a unique key. In either case, the
key_rec
must include all
columns of the key.
The key_row
passed to this
method defines the primary or unique key of the affected
tuple, and must remain valid until
execute()
is called.
attr_rec
is an
NdbRecord
referencing
the attribute to be updated.
For unique index operations, the
attr_rec
must refer to the
underlying table of the index, not to the index
itself.
attr_row
is a buffer
containing the new data for the update.
The mask
, if not
NULL
, defines a subset of attributes
to be updated. The mask is copied, and so does not need
to remain valid after the call to this method returns.
OperationOptions
(opts
) can be used to provide
more finely-grained control of operation definitions. An
OperationOptions
structure is passed
with flags indicating which operation definition options
are present. Not all operation types support all
operation options; for the options supported by each
type of operation, see
NdbTransaction::readTuple().
The optional sizeOfOptions
parameter is used to preserve backward compatibility of
this interface with previous definitions of the
OperationOptions
structure. If an unusual size is detected by the
interface implementation, it can use this to determine
how to interpret the passed
OperationOptions
structure. To enable
this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions)
for the value of this argument.
The NdbOperation
representing this operation (can be used to check for
errors).
This method is used with
NdbRecord
to write a tuple
of data.
const NdbOperation* writeTuple ( const NdbRecord*key_rec
, const char*key_row
, const NdbRecord*attr_rec
, const char*attr_row
, const unsigned char*mask
= 0, const NdbOperation::OperationOptions*opts
= 0, Uint32sizeOfOptions
= 0 )
This method takes the following parameters:
key_rec
is a pointer to an
NdbRecord
for either a
table or an index. If on a table, then the operation
uses a primary key; if on an index, then the operation
uses a unique key. In either case, the
key_rec
must include all
columns of the key.
The key_row
passed to this
method defines the primary or unique key of the tuple to
be written, and must remain valid until
execute()
is called.
attr_rec
is an
NdbRecord
referencing
the attribute to be written.
For unique index operations, the
attr_rec
must refer to the
underlying table of the index, not to the index itself.
attr_row
is a buffer
containing the new data.
The mask
, if not
NULL
, defines a subset of attributes
to be written. The mask is copied, and so does not need
to remain valid after the call to this method returns.
OperationOptions
(opts
) can be used to provide
more finely-grained control of operation definitions. An
OperationOptions
structure is passed
with flags indicating which operation definition options
are present. Not all operation types support all
operation options; for the options supported by each
type of operation, see
NdbTransaction::readTuple().
The optional sizeOfOptions
parameter is used to provide backward compatibility of
this interface with previous definitions of the
OperationOptions
structure. If an unusual size is detected by the
interface implementation, it can use this to determine
how to interpret the passed
OperationOptions
structure. To enable
this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions)
for the value of this argument.
A const
pointer to the
NdbOperation
representing
this write operation. The operation can be checked for
errors if and as necessary.