This section provides information about the
NdbOperation
class.
- Parent class
None
- Child classes
- Description
NdbOperation
represents a “generic” data operation. Its subclasses represent more specific types of operations. See NdbOperation::Type for a listing of operation types and their correspondingNdbOperation
subclasses.- Methods
-
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.48 NdbOperation class methods and descriptions
Name Description deleteTuple()
Removes a tuple from a table equal()
Defines a search condition using equality getBlobHandle()
Used to access blob attributes getLockHandle()
Gets a lock handle for the operation getLockMode()
Gets the operation's lock mode getNdbError()
Gets the latest error getNdbErrorLine()
Gets the number of the method where the latest error occurred getTableName()
Gets the name of the table used for this operation getTable()
Gets the table object used for this operation getNdbTransaction()
Gets the NdbTransaction
object for this operationgetType()
Gets the type of operation getValue()
Allocates an attribute value holder for later access insertTuple()
Adds a new tuple to a table readTuple()
Reads a tuple from a table setValue()
Defines an attribute to set or update updateTuple()
Updates an existing tuple in a table writeTuple()
Inserts or updates a tuple This class has no public constructor. To create an instance of
NdbOperation
, you must useNdbTransaction::getNdbOperation()
. - Types
-
The
NdbOperation
class defines three public types, shown in the following table:Table 2.49 NdbOperation class types and descriptions
Name Description AbortOption
Determines whether a failed operation causes failure of the transaction of which it is part LockMode
The type of lock used when performing a read operation Type
Operation access types
For more information about the use of
NdbOperation
, see
Section 1.4.2.3.2, “Single-row operations”.
This section provides information about the
AbortOption
data type.
- Description
This type is used to determine whether failed operations should force a transaction to be aborted. It is used as an argument to the
execute()
method—see NdbTransaction::execute(), for more information.- Enumeration values
-
Possible values are shown, along with descriptions, in the following table:
Table 2.50 NdbOperation::AbortOption type values and descriptions
Name Description AbortOnError
A failed operation causes the transaction to abort. AO_IgnoreOnError
Failed operations are ignored; the transaction continues to execute. DefaultAbortOption
The AbortOption
value is set according to the operation type:Read operations:
AO_IgnoreOnError
Scan takeover or DML operations:
AbortOnError
See NdbTransaction::execute(), for more information.
- Description
This method defines the
NdbOperation
as aDELETE
operation. When theNdbTransaction::execute()
method is invoked, the operation deletes a tuple from the table.- Signature
virtual int deleteTuple ( void )
- Parameters
None.
- Return value
Returns
0
on success,-1
on failure.
- Description
-
This method defines a search condition with an equality. The condition is true if the attribute has the given value. To set search conditions on multiple attributes, use several calls to
equal()
; in such cases all of them must be satisfied for the tuple to be selected.If the attribute is of a fixed size, its value must include all bytes. In particular a
Char
value must be native-space padded. If the attribute is of variable size, its value must start with 1 or 2 little-endian length bytes (2 if its type isLong*
).When using
insertTuple()
, you may also define the search key withsetValue()
. See NdbOperation::setValue(). - Signature
-
There are 10 versions of
equal()
, each having slightly different parameters. All of these are shown here:int equal ( const char* name, const char* value ) int equal ( const char* name, Int32 value ) int equal ( const char* name, Uint32 value ) int equal ( const char* name, Int64 value ) int equal ( const char* name, Uint64 value ) int equal ( Uint32 id, const char* value ) int equal ( Uint32 id, Int32 value ) int equal ( Uint32 id, Uint32 value ) int equal ( Uint32 id, Int64 value ) int equal ( Uint32 id, Uint64 value )
- Parameters
-
This method requires two parameters:
-
The first parameter can be either of the following:
The
name
of the attribute (a string)The
id
of the attribute (an unsigned 32-bit integer)
-
The second parameter is the attribute
value
to be tested. This value can be any one of the following 5 types:String
32-bit integer
Unsigned 32-bit integer
64-bit integer
Unsigned 64-bit integer
-
- Return value
Returns
-1
in the event of an error.
- Description
This method is used in place of
getValue()
orsetValue()
for blob attributes. It creates a blob handle (NdbBlob
object). A second call with the same argument returns the previously created handle. The handle is linked to the operation and is maintained automatically.- Signature
-
This method has two forms, depending on whether it is called with the name or the ID of the blob attribute:
virtual NdbBlob* getBlobHandle ( const char* name )
or
virtual NdbBlob* getBlobHandle ( Uint32 id )
- Parameters
-
This method takes a single parameter, which can be either one of the following:
The
name
of the attributeThe
id
of the attribute
- Return value
Regardless of parameter type used, this method return a pointer to an instance of
NdbBlob
.
- Description
Returns a pointer to the current operation's lock handle. When used with
NdbRecord
, the lock handle must first be requested with theOO_LOCKHANDLE
operation option. For other operations, this method can be used alone. In any case, theNdbLockHandle
object returned by this method cannot be used until the operation has been executed.- Signature
-
const NdbLockHandle* getLockHandle ( void ) const
or
const NdbLockHandle* getLockHandle ( void )
- Parameters
None.
- Return value
Pointer to an
NdbLockHandle
that can be used by theNdbTransaction
methodsunlock()
andreleaseLockHandle()
.
Using lock handle methods.
Shared or exclusive locks taken by read operations in a
transaction are normally held until the transaction commits or
aborts. Such locks can be released before a transaction commits
or aborts by requesting a lock handle when defining the read
operation. Once the read operation has been executed, an
NdbLockHandle
can be used to create a new
unlock operation (with
NdbTransaction::unlock()
). When
the unlock operation is executed, the row lock placed by the
read operation is released.
The steps required to release these locks are listed here:
Define the primary key read operation in the normal way with
LockMode
set toLM_Read
orLM_Exclusive
.Call
NdbOperation::getLockHandle()
during operation definition, or, forNdbrecord
, set theOO_LOCKHANDLE
operation option when callingNdbTransaction::readTuple()
.Call
NdbTransaction::execute()
; the row is now locked from this point on, as normal.(Use data, possibly making calls to
NdbTransaction::execute()
.)Call
NdbTransaction::unlock()
, passing in theconst NdbLockHandle
obtained previously to create an unlock operation.Call
NdbTransaction::execute()
; this unlocks the row.
Notes:
As with other operation types, unlock operations can be batched.
Each
NdbLockHandle
object refers to a lock placed on a row by a single primary key read operation. A single row in the database may have concurrent multiple lock holders (modeLM_Read
) and may have multiple lock holders pending (LM_Exclusive
), so releasing the claim of one lock holder may not result in a change to the observable lock status of the row.Lock handles are supported for scan lock takeover operations; the lock handle must be requested before the lock takeover is executed.
Lock handles and unlock operations are not supported for unique index read operations.
- Description
This method gets the operation's lock mode.
- Signature
LockMode getLockMode ( void ) const
- Parameters
None.
- Return value
A
LockMode
value. See NdbOperation::LockMode.
- Description
This method retrieves the method number in which the latest error occurred.
- Signature
int getNdbErrorLine ( void ) const
- Parameters
None.
- Return value
The method number (an integer).
- Description
This method is used to retrieve the table object associated with the operation.
- Signature
const NdbDictionary::Table* getTable ( void ) const
- Parameters
None.
- Return value
A pointer to an instance of
Table
.
- Description
This method retrieves the name of the table used for the operation.
- Signature
const char* getTableName ( void ) const
- Parameters
None.
- Return value
The name of the table.
- Description
Gets the
NdbTransaction
object for this operation.- Signature
virtual NdbTransaction* getNdbTransaction ( void ) const
- Parameters
None.
- Return value
A pointer to an
NdbTransaction
object.
- Description
This method is used to retrieve the access type for this operation.
- Signature
Type getType ( void ) const
- Parameters
None.
- Return value
A
Type
value.
- Description
-
This method prepares for the retrieval of an attribute value. The NDB API allocates memory for an
NdbRecAttr
object that is later used to obtain the attribute value. This can be done by using one of the manyNdbRecAttr
accessor methods, the exact method to be used depending on the attribute's data type. (This includes the genericNdbRecAttr::aRef()
method, which retrieves the data aschar*
, regardless of its actual type. You should be aware that this is not type-safe, and requires an explicit cast from the user.)This method does not fetch the attribute value from the database; the
NdbRecAttr
object returned by this method is not readable or printable before callingNdbTransaction::execute()
.If a specific attribute has not changed, the corresponding
NdbRecAttr
has the stateUNDEFINED
. This can be checked by usingNdbRecAttr::isNULL()
, which in such cases returns-1
. - Signature
-
There are three versions of this method, each having different parameters:
NdbRecAttr* getValue ( const char* name, char* value = 0 ) NdbRecAttr* getValue ( Uint32 id, char* value = 0 ) NdbRecAttr* getValue ( const NdbDictionary::Column* col, char* value = 0 )
- Parameters
-
All three forms of this method have two parameters, the second parameter being optional (defaults to
0
). They differ only with regard to the type of the first parameter, which can be any one of the following:The attribute
name
The attribute
id
The table
column
on which the attribute is defined
In all three cases, the second parameter is a character buffer in which a non-
NULL
attribute value is returned. In the event that the attribute isNULL
, is it stored only in theNdbRecAttr
object returned by this method.If no
value
is specified in thegetValue()
method call, or if 0 is passed as the value, then theNdbRecAttr
object provides memory management for storing the received data. If the maximum size of the received data is above a small fixed size,malloc()
is used to store it: For small sizes, a small, fixed internal buffer (32 bytes in extent) is provided. This storage is managed by theNdbRecAttr
instance; it is freed when the operation is released, such as at transaction close time; any data written here that you wish to preserve should be copied elsewhere before this freeing of memory takes place.If you pass a non-zero pointer for
value
, then it is assumed that this points to an portion of memory which is large enough to hold the maximum value of the column; any returned data is written to that location. The pointer should be at least 32-bit aligned.Index columns cannot be used in place of table columns with this method. In cases where a table column is not available, you can use the attribute name, obtained with
getName()
, for this purpose instead. - Return value
A pointer to an
NdbRecAttr
object to hold the value of the attribute, or aNULL
pointer, indicating an error.
Retrieving integers.
Integer values can be retrieved from both the
value
buffer passed as this
method's second parameter, and from the
NdbRecAttr
object itself. On
the other hand, character data is available from
NdbRecAttr
if no buffer has
been passed in to getValue()
(see
NdbRecAttr::aRef()). However, character data
is written to the buffer only if one is provided, in which case
it cannot be retrieved from the
NdbRecAttr
object that was
returned. In the latter case,
NdbRecAttr::aRef()
returns a
buffer pointing to an empty string.
Accessing bit values.
The following example shows how to check a given bit from the
value
buffer. Here,
op
is an operation
(NdbOperation
object),
name
is the name of the column from which to
get the bit value, and trans
is an
NdbTransaction
object:
Uint32 buf[];
op->getValue(name, buf); /* bit column */
trans->execute();
if(buf[X/32] & 1 << (X & 31)) /* check bit X */
{
/* bit X set */
}
This section provides information about the
GetValueSpec
data structure.
- Parent class
- Description
This structure is used to specify an extra value to obtain as part of an
NdbRecord
operation.- Members
-
The elements making up this structure are shown in the following table:
Table 2.51 GetValueSpec structure member names, types, and descriptions
Name Type Description column
const
Column
*To specify an extra value to read, the caller must provide this, as well as (optionally NULL
)appStorage
pointer.appStorage
void*
If this pointer is null, then the received value is stored in memory managed by the NdbRecAttr
object. Otherwise, the received value is stored at the location pointed to (and is still accessable using theNdbRecAttr
object).ImportantIt is the caller's responsibility to ensure that the following conditions are met:
appStorage
points to sufficient space to store any returned data.Memory pointed to by
appStorage
is not reused or freed until after theexecute()
call returns.
recAttr
NdbRecAttr
*After the operation is defined, recAttr
contains a pointer to theNdbRecAttr
object for receiving the data.Blob reads cannot be specified using
GetValueSpec
.
For more information, see Section 2.3.22, “The NdbRecord Interface”.
- Description
This method defines the
NdbOperation
to be anINSERT
operation. When theNdbTransaction::execute()
method is called, this operation adds a new tuple to the table.- Signature
virtual int insertTuple ( void )
- Parameters
None.
- Return value
Returns
0
on success,-1
on failure.
This section provides information about the
LockMode
data type.
- Description
This type describes the lock mode used when performing a read operation.
- Enumeration values
-
Possible values for this type are shown, along with descriptions, in the following table:
Table 2.52 NdbOperation::LockMode type values and descriptions
Name Description LM_Read
Read with shared lock LM_Exclusive
Read with exclusive lock LM_CommittedRead
Ignore locks; read last committed LM_SimpleRead
Read with shared lock, but release lock directly There is also support for dirty reads (
LM_Dirty
), but this is normally for internal purposes only, and should not be used for applications deployed in a production setting.
This section provides information about the
OperationOptions
data structure.
- Parent class
- Description
-
These options are passed to the
NdbRecord
-based primary key and scan takeover operation methods defined in theNdbTransaction
andNdbScanOperation
classes.Most
NdbTransaction::*Tuple()
methods (see Section 2.3.25, “The NdbTransaction Class”) take a supplementarysizeOfOptions
parameter. This is optional, and is intended to permit the interface implementation to remain backward compatible with older un-recompiled clients that may pass an older (smaller) version of theOperationOptions
structure. This effect is achieved by passingsizeof(OperationOptions)
into this parameter.Each option type is marked as present by setting the corresponding bit in
optionsPresent
. (Only the option types marked inoptionsPresent
need have sensible data.) All data is copied out of theOperationOptions
structure (and any subtended structures) at operation definition time. If no options are required, thenNULL
may be passed instead. - Members
-
The elements making up this structure are shown in the following table:
Table 2.53 NdbOperation::OperationOptions structure member names, types, and description
Name Type Description optionsPresent
Uint64
Which flags are present. [...] Flags
:The accepted names and values are shown in the following list:
OO_ABORTOPTION
:0x01
OO_GETVALUE
:0x02
OO_SETVALUE
:0x04
OO_PARTITION_ID
:0x08
OO_INTERPRETED
:0x10
OO_ANYVALUE
:0x20
OO_CUSTOMDATA
:0x40
OO_LOCKHANDLE
:0x80
-
OO_QUEUABLE
0x100
-
OO_NOT_QUEUABLE
0x200
-
OO_DEFERRED_CONSTAINTS
0x400
-
OO_DISABLE_FK
0x800
-
OO_NOWAIT
0x1000
Type of flags. abortOption
AbortOption
An operation-specific abort option; necessary only if the default abortoption behavior is not satisfactory. extraGetValues
GetValueSpec
Extra column values to be read. numExtraGetValues
Uint32
Number of extra column values to be read. extraSetValues
SetValueSpec
Extra column values to be set. numExtraSetValues
Uint32
Number of extra column values to be set. partitionId
Uint32
Limit the scan to the partition having this ID; alternatively, you can supply an PartitionSpec
here. For index scans, partitioning information can be supplied for each range.interpretedCode
NdbInterpretedCode
Interpeted code to execute as part of the scan. anyValue
Uint32
An anyValue
to be used with this operation. This is used by NDB Cluster Replication to store the SQL node's server ID. By starting the SQL node with the--server-id-bits
option (which causes only some of theserver_id
's bits to be used for uniquely identifying it) set to less than 32, the remaining bits can be used to store user data.customData
void*
Data pointer to associate with this operation. partitionInfo
PartitionSpec
Partition information for bounding this scan. sizeOfPartInfo
Uint32
Size of the bounding partition information.
For more information, see Section 2.3.22, “The NdbRecord Interface”.
- Description
This method defines the
NdbOperation
as aREAD
operation. When theNdbTransaction::execute()
method is invoked, the operation reads a tuple.- Signature
virtual int readTuple ( LockMode mode )
- Parameters
mode
specifies the locking mode used by the read operation. See NdbOperation::LockMode, for possible values.- Return value
Returns
0
on success,-1
on failure.
- Description
-
This method defines an attribute to be set or updated.
There are a number of
NdbOperation::setValue()
methods that take a certain type as input (pass by value rather than passing a pointer). It is the responsibility of the application programmer to use the correct types.The NDB API does check that the application sends a correct length to the interface as given in the length parameter. A
char*
value can contain any data type or any type of array. If the length is not provided, or if it is set to zero, then the API assumes that the pointer is correct, and does not check it.To set a
NULL
value, use the following construct:setValue("ATTR_NAME", (char*)NULL);
When you use
insertTuple()
, the NDB API automatically detects that it is supposed to useequal()
instead.In addition, it is not necessary when using
insertTuple()
to usesetValue()
on key attributes before other attributes. - Signature
-
There are 14 versions of
NdbOperation::setValue()
, each with slightly different parameters, as listed here:int setValue ( const char* name, const char* value ) int setValue ( const char* name, Int32 value ) int setValue ( const char* name, Uint32 value ) int setValue ( const char* name, Int64 value ) int setValue ( const char* name, Uint64 value ) int setValue ( const char* name, float value ) int setValue ( const char* name, double value ) int setValue ( Uint32 id, const char* value ) int setValue ( Uint32 id, Int32 value ) int setValue ( Uint32 id, Uint32 value ) int setValue ( Uint32 id, Int64 value ) int setValue ( Uint32 id, Uint64 value ) int setValue ( Uint32 id, float value ) int setValue ( Uint32 id, double value )
- Parameters
-
This method requires the following two parameters:
-
The first parameter identifies the attribute to be set, and may be either one of the following:
The attribute
name
(a string)The attribute
id
(an unsigned 32-bit integer)
-
The second parameter is the
value
to which the attribute is to be set; its type may be any one of the following 7 types:String (
const char*
)32-bit integer
Unsigned 32-bit integer
64-bit integer
Unsigned 64-bit integer
Double
Float
See NdbOperation::equal(), for important information regarding the value's format and length.
-
- Return value
Returns
-1
in the event of failure.
This section provides information about the
SetValueSpec
data structure.
- Parent class
- Description
This structure is used to specify an extra value to set as part of an
NdbRecord
operation.- Members
-
The elements making up this structure are shown in the following table:
Table 2.54 NdbOperation::SetValueSpec attributes, with types and descriptions
Name Type Description column
Column
To specify an extra value to read, the caller must provide this, as well as (optionally NULL
)appStorage
pointer.value
void*
This must point to the value to be set, or to NULL
if the attribute is to be set toNULL
. The value pointed to is copied when the operation is defined, and need not remain in place until execution time.
Blob values cannot be set using SetValueSpec
.
For more information, see Section 2.3.22, “The NdbRecord Interface”.
This section provides information about the
Type
data type.
- Description
Type
is used to describe the operation access type. Each access type is supported byNdbOperation
or one of its subclasses, as shown in the following table:- Enumeration values
-
Possible values are shown, along with descriptions, in the following table:
Table 2.55 NdbOperation::Type data type values and descriptions
Name Description Applicable Class PrimaryKeyAccess
A read, insert, update, or delete operation using the table's primary key NdbOperation
UniqueIndexAccess
A read, update, or delete operation using a unique index NdbIndexOperation
TableScan
A full table scan NdbScanOperation
OrderedIndexScan
An ordered index scan NdbIndexScanOperation
- Description
This method defines the
NdbOperation
as anUPDATE
operation. When theNdbTransaction::execute()
method is invoked, the operation updates a tuple found in the table.- Signature
virtual int updateTuple ( void )
- Parameters
None.
- Return value
Returns
0
on success,-1
on failure.
- Description
This method defines the
NdbOperation
as aWRITE
operation. When theNdbTransaction::execute()
method is invoked, the operation writes a tuple to the table. If the tuple already exists, it is updated; otherwise an insert takes place.- Signature
virtual int writeTuple ( void )
- Parameters
None.
- Return value
Returns
0
on success,-1
on failure.