MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbOperation
class.
Beginning with NDB 8.0.30, NdbOperation
supports
an interpreted code API similar to that implemented by
NdbInterpretedCode
. See
NdbOperation Interpreted Code API, for more
information.
None
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 corresponding
NdbOperation
subclasses.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.49 NdbOperation class methods and descriptions
Name | Description |
---|---|
add_reg() |
Add and store contents of two registers |
branch_col_and_mask_eq_mask() |
Branch if column value AND bitmask equals bitmask |
branch_col_and_mask_ne_mask() |
Branch if column value AND bitmask does not equal
bitmask |
branch_col_and_mask_eq_zero() |
Branch if column value AND bitmask equals zero |
branch_col_and_mask_ne_zero() |
Branch if column value AND bitmask does not equal
zero |
branch_col_eq() |
Branch if column is equal to specified value |
branch_col_eq_null() |
Branch if column is NULL |
branch_col_ge() |
Branch if column is greater than or equal to than specified value |
branch_col_gt() |
Branch if column is greater than specified value |
branch_col_le() |
Branch if column is less than or equal to specified value |
branch_col_like() |
Branch if column value matches wildcard pattern |
branch_col_lt() |
Branch if column is less than specified value |
branch_col_ne() |
Branch if column is not equal to specified value |
branch_col_ne_null() |
Branch if column is not NULL |
branch_col_notlike() |
Branch if column value does not match wildcard pattern |
branch_eq() |
Branch if first register value equal to second register value |
branch_eq_null() |
Branch if register value is null |
branch_ge() |
Branch if first register value is greater than or equal to second register value |
branch_gt() |
Branch if first register value is greater than second register value |
branch_label() |
Jump to label in interpeted progam |
branch_le() |
Branch if first register value is less than second register value |
branch_lt() |
Branch if first register value is less than or equal to second register value |
branch_ne() |
Branch if first register value not equal to second register value |
branch_ne_null() |
Branch if register value is not null |
call_sub() |
Call interpreted program subroutine |
def_label() |
Define jump label in interpreted program operation |
def_subroutine() |
Define interpreted program subroutine |
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
operation |
getType() |
Gets the type of operation |
getValue() |
Allocates an attribute value holder for later access |
incValue() |
Adds value to attribute |
insertTuple() |
Adds a new tuple to a table |
interpret_exit_last_row() |
Terminate transaction |
interpret_exit_nok() |
Exit interpreted program with status NOT OK |
interpret_exit_ok() |
Exit interpreted program with status OK |
interpretedDeleteTuple() |
Delete tuple using interpreted program |
interpretedUpdateTuple() |
Update tuple using interpreted program |
interpretedWriteTuple() |
Write tuple using interpreted program |
load_const_u32() |
Load 32-bit constant value into register |
load_const_u64() |
Load 64-bit constant value into register |
load_const_null() |
Load NULL into register |
read_attr() |
Read given attribute into register |
readTuple() |
Reads a tuple from a table |
ret_sub() |
Return from interpreted program subroutine |
setValue() |
Defines an attribute to set or update |
sub_reg() |
Store difference of two register values |
subValue() |
Subtracts value from attribute |
updateTuple() |
Updates an existing tuple in a table |
write_attr() |
Write given attribute from register |
writeTuple() |
Inserts or updates a tuple |
This class has no public constructor. To create an instance
of NdbOperation
, you must
use
NdbTransaction::getNdbOperation()
.
The NdbOperation
class defines three
public types, shown in the following table:
Table 2.50 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”.
NdbOperation
in NDB 8.0.30 and later supports
an interpreted code API similar to that used with
NdbInterpretedCode
.
To start with, use one of
updateTuple()
,
writeTuple()
, or
deleteTuple()
to
define the operation as an operation of a given type (update,
write, or delete). This is the operation that is to be performed
by an interpreted program; the interpreted program itself is
assembled from various register, comparison, and branch
instructions.
The interpreted program is not a separate
NdbInterpretedCode
object,
although it behaves much like one. Instructions are assigned to
the NdbOperation
instance (for example,
myNdbOp->branch_col_lt(col1id, val1, col2id,
val2)
). To run the interpreted program, call
NdbTransaction::execute()
.
Another difference between the NdbOperation
interpreted code API implementation and that supported by
NdbInterpretedCode
is that the
order of arguments for analogous methods is not necessarily the
same. One such pair of methods is listed here:
In
NdbOperation::branch_col_lt(
, comparison
happens like this, using the second and first arguments passed
to the method, in that order:
ColId
,
val
,
len
,
bool
,
Label
)
if(val
<ColId_value
) branch_toLabel
NdbInterpretedCode::branch_col_lt(
, compares the
first argument passed with the third, like this:
*val
,
Uint32, attrId
,
Label
)
if(val
<attrId_value
) branch_toLabel
Branch column method comparisons.
The branch column methods such as
branch_col_le()
compare a supplied value with the value of a column. These
methods act on the first two arguments from right to left, so
that, for example, branch_col_le(myColId, myValue, 8,
true, myLabel)
acts as shown by the following
pseudocode:
if(myValue <= value(myColId)) goto myLabel;
Bitwise logical comparisons. These comparison types are supported only for the bitfield type, and can be used to test bitfield columns against bit patterns. The value passed in is a bitmask which is bitwise-ANDed with the column data. Bitfields are passed in and out of the NDB API as 32-bit words with bits set from least significant bit (LSB) to most significant bit (MSB). The platform's endianness controls which byte contains the LSB: for x86, this is the first (0th) byte; for SPARC and PPC platforms, it is the last (3rd) byte.
You can set bit n
of a bitmask to 1
from a Uint32*
mask like this:
mask[n >> 5] |= (1 << (n & 31))
Four different sorts of branching on bitwise comparison are supported by the methods listed here:
branch_col_and_mask_eq_mask()
:
Branch if column value AND mask == mask
(all masked bits set in value).
branch_col_and_mask_ne_mask()
:
Branch if column value AND mask != mask
(not all masked bits are set in value).
branch_col_and_mask_eq_zero()
:
Branch if column value AND mask == 0
(no
masked bits are set in value).
branch_col_and_mask_ne_zero()
:
Branch if column value AND mask != 0
(some
masked bits are set in value).
See the descriptions of the individual methods for more information.
This section provides information about the
AbortOption
data type.
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.
Possible values are shown, along with descriptions, in the following table:
Table 2.51 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:
|
See NdbTransaction::execute(), for more information.
Add contents of two registers; store result in a third register.
int add_reg ( Uint32RegSource1
, Uint32RegSource2
, Uint32RegDest
)
RegSource1
Register containing first value to be added.
RegSource2
Register containing second value to be added.
RegDest
Register in which to store the result.
0 on success, otherwise -1.
Branch to a label in an interpreted program if the specified
column is NULL
.
int branch_col_eq_null ( Uint32ColId
, Uint32Label
)
ColId
ID of the column to check.
Label
am
Label to jump to if the column is
NULL
.
0 on success, otherwise -1.
Branch to a label in an interpreted program if the specified
column is not NULL
.
int branch_col_ne_null ( Uint32ColId
, Uint32Label
)
ColId
ID of the column to check.
Label
am
Label to jump to if the column is not
NULL
.
none
Branch to a label in an interpreted program if a given value is equal to the value of the specified column.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_eg()
compares its second
argument with the first, in that order.
int branch_col_eq ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if val
is
equal to the column value.
0 on success, -1 otherwise.
Branch to a label in an interpreted program if a given value is not equal to the value of the specified column.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_ne()
compares its second
argument with the first, in that order.
int branch_col_ne ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if column value is not equal to
val
.
0 on success, else -1.
Branch to a label in an interpreted program if a given value is less than a column value.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_lt()
compares its second
argument with the first, in that order.
int branch_col_lt ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if val
is
less than the column value.
0 on success, otherwise -1.
Branch to a label in an interpreted program if a given value is less than or equal to a column value.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_le()
compares its second
argument with the first, in that order.
int branch_col_le ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if val
is
less than or equal to the column value.
On success, 0; otherwise, -1.
Branch to a label in an interpreted program if a given value is greater than a column value.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_gt()
compares its second
argument with the first, in that order.
int branch_col_gt ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if val
is
greater than the column value.
0 on success, -1 otherwise.
Branch to a label in an interpreted program if a given value is greater than or equal to a column value.
Like the other
NdbOperation::branch_col_*()
methods,
branch_col_ge()
compares its second
argument with the first, in that order.
int branch_col_ge ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column to compare.
val
Value to be compared.
len
Length of val
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if val
is
greater than or equal to the column value.
0 if successful, else -1.
Branch if the column value matches a wildcard pattern. This
method and
branch_col_notlike()
each support the wildcards used by the MySQL
LIKE
operator:
%
for any string of 0 or more characters,
and _
for any single character.
The column's type must be one of
CHAR
,
VARCHAR
,
BINARY
, or
VARBINARY
.
int branch_col_like ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column whose value is to be compared.
val
Pattern to match.
len
Length of pattern value.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if column value matches pattern.
0 on success, otherwise -1.
Branch if the column value does not match the given wildcard
pattern. This method and
branch_col_like()
each support the same wildcards %
(0 or
more characters) and _
(any one
character) as the MySQL LIKE
operator.
The column's type must be one of
CHAR
,
VARCHAR
,
BINARY
, or
VARBINARY
.
int branch_col_notlike ( Uint32ColId
, const void*val
, Uint32len
, bool, Uint32Label
)
ColId
ID of column whose value is to be compared.
val
Pattern to match.
len
Length of pattern value.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Label to jump to if column value does not match pattern.
0 on success, -1 otherwise.
Branch if the value of a column in a logical bitwise
AND
with a bitmask is equal to the
bitmask.
See also Bitwise logical comparisons.
int branch_col_and_mask_eq_mask ( Uint32ColId
, const void*mask
, Uint32len
, bool, Uint32Label
)
ColId
Use the value of the column having this ID.
mask
Bitmask to compare with column value.
len
Length of mask
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Branch to jump to if the result of the
AND
operation is the same as the
mask.
0 on success, -1 otherwise.
Branch if the value of a column in a logical bitwise
AND
with a bitmask is not equal to the
bitmask.
See also Bitwise logical comparisons.
int branch_col_and_mask_ne_mask ( Uint32ColId
, const void*mask
, Uint32len
, bool, Uint32Label
)
ColId
Use the value of the column having this ID.
mask
Bitmask to compare with column value.
len
Length of mask
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Branch to jump to if the result of the
AND
operation is not equal to the
mask.
On success 0, else -1.
Branch if the value of a column in a logical bitwise
AND
with a bitmask is equal to 0.
See also Bitwise logical comparisons.
int branch_col_and_mask_eq_zero ( Uint32ColId
, const void*mask
, Uint32len
, bool, Uint32Label
)
ColId
Use the value of the column having this ID.
mask
Bitmask to compare with column value.
len
Length of mask
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Branch to jump to if the result of the
AND
operation is equal to 0.
0 on success, -1 otherwise.
Branch if the value of a column in a logical bitwise
AND
with a bitmask is not equal to 0.
See also Bitwise logical comparisons.
int branch_col_and_mask_ne_zero ( Uint32ColId
, const void*mask
, Uint32len
, bool, Uint32Label
)
ColId
Use the value of the column having this ID.
mask
Bitmask to compare with column value.
len
Length of mask
.
-
Boolean true
or
false
required for legacy reasons,
but no longer used.
Label
Branch to jump to if the result of the
AND
operation is not equal to 0.
Returns 0 on success, -1 otherwise.
Define a search condition in an interpreted program. Compares the right-hand register value with the left; branch to a label if the RH value is greater than or equal to the LH value.
This method, like the other
NdbOperation
branch on comparison
methods, compares the two register values from right to
left.
int branch_ge ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
Register value compared with
RegRvalue
.
RegRvalue
Compare value of this register with
RegLvalue
; branch to the
label if this value is greater than or equal to
RegLvalue
.
Label
Label to branch to if
RegRvalue
is greater than
or equal to RegLvalue
.
0 on success, -1 otherwise.
Define a search condition in an interpreted program. Compares the right-hand register value with the left; branch to a label if the RH value is greater than the LH value.
This method, like the other
NdbOperation
branch on comparison
methods, compares the two register values from right to
left.
int branch_gt ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
Register value compared with
RegRvalue
.
RegRvalue
Compare value of this register with
RegLvalue
; branch to the
label if this value is greater than
RegLvalue
.
Label
Label to branch to if
RegRvalue
is greater than
RegLvalue
.
0 on success, -1 otherwise.
Define a search condition in an interpreted program. Compares the right-hand register value with the left; branch to a label if the RH value is less than the LH value.
This method, like the other
NdbOperation
branch on comparison
methods, compares the two register values from right to
left.
int branch_le ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
Register value compared with
RegRvalue
.
RegRvalue
Compare value of this register with
RegLvalue
; branch to the
label if this value is less than
RegLvalue
.
Label
Label to branch to if
RegRvalue
is less than
RegLvalue
.
0 on success, -1 otherwise.
Define a search condition in an interpreted program. Compares the right-hand register value with the left; branch to a label if the RH value is less than or equal to the LH value.
This method, like the other
NdbOperation
branch on comparison
methods, compares the two register values from right to
left.
int branch_lt ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
Register value compared with
RegRvalue
.
RegRvalue
Compare value of this register with
RegLvalue
; branch to the
label if this value is less than or equal to
RegLvalue
.
Label
Label to branch to if
RegRvalue
is less than or
equal to RegLvalue
.
0 on success, -1 otherwise.
Branch to a label in an interpreted program when two register values are equal.
int branch_eq ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
One of two register values to be compared.
RegRvalue
The other register value to be compared.
Label
Branch to this label if the register values are equal.
0 on success, -1 otherwise.
Branch to a label in an interpreted program when two register values are not equal.
int branch_eq ( Uint32RegLvalue
, Uint32RegRvalue
, Uint32Label
)
RegLvalue
One of two register values to be compared.
RegRvalue
The other register value to be compared.
Label
Branch to this label if the register values are not equal.
0 on success, otherwise -1.
Branch to a label in an interpeted program if a register
value is not NULL
.
int branch_ne_null ( Uint32RegLvalue
, Uint32Label
)
RegLvalue
Register to be tested.
Label
Branch to this label if
RegLvalue
is not
NULL
.
On success, returns 0; otherwise, returns -1.
Branch to a label in an interpeted program if a register
value is NULL
.
int branch_ne_null ( Uint32RegLvalue
, Uint32Label
)
RegLvalue
Register to be tested.
Label
Branch to this label if
RegLvalue
is
NULL
.
On success, 0; otherwise, -1.
Jump to a label in an interpeted progam.
int branch_label
(
Uint32 Label
)
Label
The label to branch to.
0 if successful; otherwise, -1.
Call a subroutine in an interpeted program.
int call_sub
(
Uint32 Subroutine
)
Subroutine
The subroutine number.
If successful, returns 0; otherwise, returns -1.
Define a jump label in an interpreted operation. Labels are numbered automatically starting with 0.
int def_label
(
int labelNumber
)
labelNumber
The label number. For easier debugging, this should
match the automatic numbering performed by
NDB
.
labelNumber
on success, -1
otherwise.
Define a subroutine in an interpreted program.
int def_subroutine
(
int SubroutineNumber
)
SubroutineNumber
The subroutine number.
0 on success, -1 otherwise.
This method defines the
NdbOperation
as a
DELETE
operation. When the
NdbTransaction::execute()
method is invoked, the operation deletes a tuple from the
table.
virtual int deleteTuple ( void )
None.
Returns 0
on success,
-1
on failure.
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 is Long*
).
When using insertTuple()
, you may also
define the search key with setValue()
.
See NdbOperation::setValue().
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
, Int32value
) int equal ( const char*name
, Uint32value
) int equal ( const char*name
, Int64value
) int equal ( const char*name
, Uint64value
) int equal ( Uint32id
, const char*value
) int equal ( Uint32id
, Int32value
) int equal ( Uint32id
, Uint32value
) int equal ( Uint32id
, Int64value
) int equal ( Uint32id
, Uint64value
)
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
Returns -1
in the event of an error.
This method is used in place of
getValue()
or
setValue()
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.
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 )
This method takes a single parameter, which can be either one of the following:
The name
of the attribute
The id
of the attribute
Regardless of parameter type used, this method return a
pointer to an instance of
NdbBlob
.
Returns a pointer to the current operation's lock
handle. When used with
NdbRecord
, the lock handle
must first be requested with the
OO_LOCKHANDLE
operation option. For other
operations, this method can be used alone. In any case, the
NdbLockHandle
object returned by this
method cannot be used until the operation has been executed.
const NdbLockHandle* getLockHandle ( void ) const
or
const NdbLockHandle* getLockHandle ( void )
None.
Pointer to an NdbLockHandle
that can be
used by the NdbTransaction
methods
unlock()
and
releaseLockHandle()
.
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 to
LM_Read
or LM_Exclusive
.
Call
NdbOperation::getLockHandle()
during operation definition, or, for
Ndbrecord
, set the
OO_LOCKHANDLE
operation option when calling
NdbTransaction::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 the const 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 (mode LM_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.
This method gets the operation's lock mode.
LockMode getLockMode ( void ) const
None.
A LockMode
value. See
NdbOperation::LockMode.
This method retrieves the method number in which the latest error occurred.
int getNdbErrorLine ( void ) const
None.
The method number (an integer).
This method is used to retrieve the table object associated with the operation.
const NdbDictionary::Table* getTable ( void ) const
None.
A pointer to an instance of
Table
.
This method retrieves the name of the table used for the operation.
const char* getTableName ( void ) const
None.
The name of the table.
Gets the NdbTransaction
object for this operation.
virtual NdbTransaction* getNdbTransaction ( void ) const
None.
A pointer to an
NdbTransaction
object.
This method is used to retrieve the access type for this operation.
Type getType ( void ) const
None.
A Type
value.
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 many
NdbRecAttr
accessor
methods, the exact method to be used depending on the
attribute's data type. (This includes the generic
NdbRecAttr::aRef()
method,
which retrieves the data as char*
,
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 calling
NdbTransaction::execute()
.
If a specific attribute has not changed, the corresponding
NdbRecAttr
has the state
UNDEFINED
. This can be checked by using
NdbRecAttr::isNULL()
, which
in such cases returns -1
.
There are three versions of this method, each having different parameters:
NdbRecAttr* getValue ( const char*name
, char*value
= 0 ) NdbRecAttr* getValue ( Uint32id
, char*value
= 0 ) NdbRecAttr* getValue ( const NdbDictionary::Column*col
, char*value
= 0 )
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 is
NULL
, is it stored only in the
NdbRecAttr
object returned
by this method.
If no value
is specified in the
getValue()
method call, or if 0 is passed
as the value, then the
NdbRecAttr
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 the
NdbRecAttr
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.
A pointer to an NdbRecAttr
object to hold the value of the attribute, or a
NULL
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.
This structure is used to specify an extra value to obtain
as part of an NdbRecord
operation.
The elements making up this structure are shown in the following table:
Table 2.52 GetValueSpec structure member names, types, and descriptions
Name | Type | Description |
---|---|---|
column |
const |
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 the
NdbRecAttr object).Important It is the caller's responsibility to ensure that the following conditions are met:
|
recAttr |
NdbRecAttr * |
After the operation is defined, recAttr
contains a pointer to the
NdbRecAttr object for
receiving the data. |
Blob reads cannot be specified using
GetValueSpec
.
For more information, see Section 2.3.22, “The NdbRecord Interface”.
Interpreted program instruction which adds a value to an attribute. The attribute can be specified by name or by ID. Thus, there are four versions of of this method having slightly different parameters, as shown under Signature.
This instruction uses registers 6 and 7, and overwrites these registers in the course of its operation.
For scans and NdbRecord
operations, use the
NdbInterpretedCode
interface instead.
int incValue ( const char*anAttrName
, Uint32aValue
)
int incValue ( const char*anAttrName
, Uint64aValue
)
int incValue ( Uint32anAttrId
, Uint32aValue
)
int incValue ( Uint32anAttrId
, Uint64aValue
)
anAttrName
Name of the attribute.
anAttrId
The attribute ID.
aValue
The value to be added; this can be a 32-bit or 64-bit integer.
0 on success, -1 otherwise.
This method defines the
NdbOperation
to be an
INSERT
operation. When the
NdbTransaction::execute()
method is called, this operation adds a new tuple to the
table.
virtual int insertTuple ( void )
None.
Returns 0
on success,
-1
on failure.
Terminate the entire transaction.
int interpret_exit_last_row ( void )
none
Returns 0 on success; otherwise, returns -1.
Exit interpreted program with status NOT
OK
and an optional error code (see
Section 2.4.2, “NDB Error Codes: by Type”).
int interpret_exit_nok
(
Uint32 ErrorCode
)
int interpret_exit_nok
(
void
)
ErrorCode
Optional error code, defaults to error
899
. Applications
should use error code
626
or any code in
the 6000-6999 range. Error code 899 is supported for
backwards compatibility, but 626 is recommmended
instead. For other error codes, the behavior is
undefined and may change at any time without prior
notice.
0 on success, -1 otherwise.
Exit interpreted program with status OK
.
int interpret_exit_ok ( void )
none
0 on success, -1 otherwise.
Delete a tuple using an interpreted program.
virtual int interpretedDeleteTuple ( void )
None.
0 on success, -1 otherwise.
Update a tuple using an interpreted program.
virtual int interpretedUpdateTuple ( void )
None.
0 on success, -1 otherwise.
Write a tuple using an interpreted program.
virtual int interpretedWriteTuple ( void )
None.
0 on success, -1 otherwise.
Load a 32-bit constant value into a register.
int load_const_u32 ( Uint32RegDest
, Uint32Constant
)
RegDest
Destination register.
Constant
Value to load into the register.
0 on success, -1 otherwise.
Load a 64-bit constant value into a register.
int load_const_u64 ( Uint64RegDest
, Uint64Constant
)
RegDest
Destination register.
Constant
Value to load into the register.
0 on success, otherwise -1.
Load NULL
into a register.
int load_const_null
(
Uint32 RegDest
)
RegDest
Destination register.
0 on success, -1 otherwise.
This section provides information about the
LockMode
data type.
This type describes the lock mode used when performing a read operation.
Possible values for this type are shown, along with descriptions, in the following table:
Table 2.53 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.
These options are passed to the
NdbRecord
-based primary key
and scan takeover operation methods defined in the
NdbTransaction
and
NdbScanOperation
classes.
Most NdbTransaction::*Tuple()
methods
(see Section 2.3.25, “The NdbTransaction Class”) take a
supplementary sizeOfOptions
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 the OperationOptions
structure. This effect is achieved by passing
sizeof(OperationOptions)
into this
parameter.
Each option type is marked as present by setting the
corresponding bit in
optionsPresent
. (Only the option
types marked in optionsPresent
need have sensible data.) All data is copied out of the
OperationOptions
structure (and any
subtended structures) at operation definition time. If no
options are required, then NULL
may be
passed instead.
The elements making up this structure are shown in the following table:
Table 2.54 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:
|
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 the bits in the
server_id 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”.
Read an attribute identified by name or ID into a register.
int read_attr ( const char*anAttrName
, Uint32RegDest
) int read_attr ( Uint32anAttrId
, Uint32RegDest
)
anAttrName
Attribute name. Use this or the attribute ID.
anAttrId
Attribute ID. Use this or the name of the attribute.
RegDest
Destination register.
On success, 0; otheriwse, -1.
This method defines the
NdbOperation
as a
READ
operation. When the
NdbTransaction::execute()
method is invoked, the operation reads a tuple.
virtual int readTuple
(
LockMode mode
)
mode
specifies the locking mode
used by the read operation. See
NdbOperation::LockMode, for possible
values.
Returns 0
on success,
-1
on failure.
Return from an interpreted program subroutine.
int ret_sub ( void )
none.
0 on success, -1 otherwise.
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 use
equal()
instead.
In addition, it is not necessary when using
insertTuple()
to use
setValue()
on key attributes before other
attributes.
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
, Int32value
) int setValue ( const char*name
, Uint32value
) int setValue ( const char*name
, Int64value
) int setValue ( const char*name
, Uint64value
) int setValue ( const char*name
, floatvalue
) int setValue ( const char*name
, doublevalue
) int setValue ( Uint32id
, const char*value
) int setValue ( Uint32id
, Int32value
) int setValue ( Uint32id
, Uint32value
) int setValue ( Uint32id
, Int64value
) int setValue ( Uint32id
, Uint64value
) int setValue ( Uint32id
, floatvalue
) int setValue ( Uint32id
, doublevalue
)
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.
Returns -1
in the event of failure.
This section provides information about the
SetValueSpec
data structure.
This structure is used to specify an extra value to set as
part of an NdbRecord
operation.
The elements making up this structure are shown in the following table:
Table 2.55 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 to NULL .
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”.
Store difference of two register values in a third register.
int sub_reg ( Uint32RegSource1
, Uint32RegSource2
, Uint32RegDest
)
RegSource1
Register containing value to be subtracted.
RegSource2
Register containing value to be subtracted from.
RegDest
Register in which to store the result.
0 on success, otherwise -1.
Interpreted program instruction which subtracts a value from an attribute in an interpreted operation. The attribute can be specified by name or by ID. Thus, there are four versions of of this method having slightly different parameters, as shown under Signature.
As with
incValue()
,
this instruction uses registers 6 and 7, and overwrites
these registers in the course of its operation.
For scans and NdbRecord
operations, use the
NdbInterpretedCode
interface instead.
int subValue ( const char*anAttrName
, Uint32aValue
)
int subValue ( const char*anAttrName
, Uint64aValue
)
int subValue ( Uint32anAttrId
, Uint32aValue
)
int subValue ( Uint32anAttrId
, Uint64aValue
)
anAttrName
Name of the attribute
anAttrId
The attribute ID
aValue
The value to be subtracted; this can be a 32-bit or 64-bit integer.
0 on success, -1 otherwise.
This section provides information about the
Type
data type.
Type
is used to describe the operation
access type. Each access type is supported by
NdbOperation
or one of its
subclasses, as shown in the following table:
Possible values are shown, along with descriptions, in the following table:
Table 2.56 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 |
This method defines the
NdbOperation
as an
UPDATE
operation. When the
NdbTransaction::execute()
method is invoked, the operation updates a tuple found in
the table.
virtual int updateTuple ( void )
None.
Returns 0
on success,
-1
on failure.
Write an attribute value from a register. The attribute to be written can be specified by name or ID.
int write_attr ( const char*anAttrName
, Uint32RegSource
) int write_attr ( Uint32anAttrId
, Uint32RegSource
)
anAttrName
Attribute name. Use this or the attribute ID.
anAttrId
Attribute ID. Use this or the name of the attribute.
RegSource
Source register.
Returns 0 on success; otherwise, returns -1.
This method defines the
NdbOperation
as a
WRITE
operation. When the
NdbTransaction::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.
virtual int writeTuple ( void )
None.
Returns 0
on success,
-1
on failure.