MySQL :: MySQL NDB Cluster API Developer Guide :: 2.3.20 The NdbOperation Class

NdbOperation Class Overview

Parent class

None

Child classes

NdbIndexOperation, NdbScanOperation

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 corresponding NdbOperation 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
`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().

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”.

NdbOperation Interpreted Code API

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(ColId, val, len, bool, Label), comparison happens like this, using the second and first arguments passed to the method, in that order:
```
if(val < ColId_value)
  branch_to Label
```
NdbInterpretedCode::branch_col_lt(*val, Uint32, attrId, Label), compares the first argument passed with the third, like this:
```
if(val < attrId_value)
  branch_to Label
```

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.

NdbOperation::AbortOption

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.

NdbOperation::add_reg()

Description

Add contents of two registers; store result in a third register.

Signature

int add_reg
    (
      Uint32 RegSource1, 
      Uint32 RegSource2, 
      Uint32 RegDest
    )

Parameters

RegSource1: Register containing first value to be added.
RegSource2: Register containing second value to be added.
RegDest: Register in which to store the result.

Return value

0 on success, otherwise -1.

NdbOperation::branch_col_eq_null()

Description

Branch to a label in an interpreted program if the specified column is NULL.

Signature

int branch_col_eq_null
    (
      Uint32 ColId, 
      Uint32 Label
    )

Parameters

ColId: ID of the column to check.
parLabelam: Label to jump to if the column is NULL.

Return value

0 on success, otherwise -1.

NdbOperation::branch_col_ne_null()

Description

Branch to a label in an interpreted program if the specified column is not NULL.

Signature

int branch_col_ne_null
    (
      Uint32 ColId, 
      Uint32 Label
    )

Parameters

ColId: ID of the column to check.
parLabelam: Label to jump to if the column is not NULL.

Return value

none

NdbOperation::branch_col_eq()

Description

Branch to a label in an interpreted program if a given value is equal to the value of the specified column.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_eg() compares its second argument with the first, in that order.

Signature

int branch_col_eq
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_col_ne()

Description

Branch to a label in an interpreted program if a given value is not equal to the value of the specified column.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_ne() compares its second argument with the first, in that order.

Signature

int branch_col_ne
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, else -1.

NdbOperation::branch_col_lt()

Description

Branch to a label in an interpreted program if a given value is less than a column value.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_lt() compares its second argument with the first, in that order.

Signature

int branch_col_lt
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, otherwise -1.

NdbOperation::branch_col_le()

Description

Branch to a label in an interpreted program if a given value is less than or equal to a column value.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_le() compares its second argument with the first, in that order.

Signature

int branch_col_le
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

On success, 0; otherwise, -1.

NdbOperation::branch_col_gt()

Description

Branch to a label in an interpreted program if a given value is greater than a column value.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_gt() compares its second argument with the first, in that order.

Signature

int branch_col_gt
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_col_ge()

Description

Branch to a label in an interpreted program if a given value is greater than or equal to a column value.

Note

Like the other NdbOperation::branch_col_*() methods, branch_col_ge() compares its second argument with the first, in that order.

Signature

int branch_col_ge
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 if successful, else -1.

NdbOperation::branch_col_like()

Description

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.

Signature

int branch_col_like
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, otherwise -1.

NdbOperation::branch_col_notlike()

Description

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.

Signature

int branch_col_notlike
    (
      Uint32 ColId, 
      const void* val, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_col_and_mask_eq_mask()

Description

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.

Signature

int branch_col_and_mask_eq_mask
    (
      Uint32 ColId, 
      const void* mask, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_col_and_mask_ne_mask()

Description

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.

Signature

int branch_col_and_mask_ne_mask
    (
      Uint32 ColId, 
      const void* mask, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

On success 0, else -1.

NdbOperation::branch_col_and_mask_eq_zero()

Description

Branch if the value of a column in a logical bitwise AND with a bitmask is equal to 0.

See also Bitwise logical comparisons.

Signature

int branch_col_and_mask_eq_zero
    (
      Uint32 ColId, 
      const void* mask, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_col_and_mask_ne_zero()

Description

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.

Signature

int branch_col_and_mask_ne_zero
    (
      Uint32 ColId, 
      const void* mask, 
      Uint32 len,
      bool,
      Uint32 Label
    )

Parameters

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.

Return value

Returns 0 on success, -1 otherwise.

NdbOperation::branch_ge()

Description

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.

Note

This method, like the other NdbOperation branch on comparison methods, compares the two register values from right to left.

Signature

int branch_ge
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_gt()

Description

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.

Note

This method, like the other NdbOperation branch on comparison methods, compares the two register values from right to left.

Signature

int branch_gt
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_le()

Description

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.

Note

This method, like the other NdbOperation branch on comparison methods, compares the two register values from right to left.

Signature

int branch_le
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_lt()

Description

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.

Note

This method, like the other NdbOperation branch on comparison methods, compares the two register values from right to left.

Signature

int branch_lt
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_eq()

Description

Branch to a label in an interpreted program when two register values are equal.

Signature

int branch_eq
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::branch_ne()

Description

Branch to a label in an interpreted program when two register values are not equal.

Signature

int branch_eq
    (
      Uint32 RegLvalue, 
      Uint32 RegRvalue, 
      Uint32 Label
    )

Parameters

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.

Return value

0 on success, otherwise -1.

NdbOperation::branch_ne_null()

Description

Branch to a label in an interpeted program if a register value is not NULL.

Signature

int branch_ne_null
    (
      Uint32 RegLvalue, 
      Uint32 Label
    )

Parameters

RegLvalue: Register to be tested.
Label: Branch to this label if RegLvalue is not NULL.

Return value

On success, returns 0; otherwise, returns -1.

NdbOperation::branch_eq_null()

Description

Branch to a label in an interpeted program if a register value is NULL.

Signature

int branch_ne_null
    (
      Uint32 RegLvalue, 
      Uint32 Label
    )

Parameters

RegLvalue: Register to be tested.
Label: Branch to this label if RegLvalue is NULL.

Return value

On success, 0; otherwise, -1.

NdbOperation::branch_label()

Description

Jump to a label in an interpeted progam.

Signature

int branch_label
    (
      Uint32 Label
    )

Parameters

Label: The label to branch to.

Return value

0 if successful; otherwise, -1.

NdbOperation::call_sub()

Description

Call a subroutine in an interpeted program.

Signature

int call_sub
    (
      Uint32 Subroutine
    )

Parameters

Subroutine: The subroutine number.

Return value

If successful, returns 0; otherwise, returns -1.

NdbOperation::def_label()

Description

Define a jump label in an interpreted operation. Labels are numbered automatically starting with 0.

Signature

int def_label
    (
      int labelNumber
    )

Parameters

labelNumber: The label number. For easier debugging, this should match the automatic numbering performed by NDB.

Return value

labelNumber on success, -1 otherwise.

NdbOperation::def_subroutine()

Description

Define a subroutine in an interpreted program.

Signature

int def_subroutine
    (
      int SubroutineNumber
    )

Parameters

SubroutineNumber: The subroutine number.

Return value

0 on success, -1 otherwise.

NdbOperation::deleteTuple()

Description

This method defines the NdbOperation as a DELETE operation. When the NdbTransaction::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.

NdbOperation::equal()

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 is Long*).

When using insertTuple(), you may also define the search key with setValue(). 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:
1. The name of the attribute (a string)
2. 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.

NdbOperation::getBlobHandle()

Description

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.

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 attribute
The id of the attribute

Return value

Regardless of parameter type used, this method return a pointer to an instance of NdbBlob.

NdbOperation::getLockHandle

Description

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.

Signature

const NdbLockHandle* getLockHandle
    (
      void
    ) const

or

const NdbLockHandle* getLockHandle
    (
      void
    )

Parameters

None.

Return value

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.

NdbOperation::getLockMode()

Description

This method gets the operation's lock mode.

Signature

LockMode getLockMode
    (
      void
    ) const

Parameters

None.

Return value

A LockMode value. See NdbOperation::LockMode.

NdbOperation::getNdbError()

Description

This method gets the most recent error (an NdbError object).

Signature

const NdbError& getNdbError
    (
      void
    ) const

Parameters

None.

Return value

An NdbError object.

NdbOperation::getNdbErrorLine()

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).

NdbOperation::getTable()

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.

NdbOperation::getTableName()

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.

NdbOperation::getNdbTransaction()

Description

Gets the NdbTransaction object for this operation.

Signature

virtual NdbTransaction* getNdbTransaction
    (
      void
    ) const

Parameters

None.

Return value

A pointer to an NdbTransaction object.

NdbOperation::getType()

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.

NdbOperation::getValue()

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 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.

See NdbTransaction::execute(), and NdbRecAttr::isNULL().

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 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.

Return value

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 */
}

NdbOperation::GetValueSpec

This section provides information about the GetValueSpec data structure.

Parent class

NdbOperation

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 the `NdbRecAttr` object). Important It 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 the `execute()` call returns.
`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”.

NdbOperation::incValue()

Description

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.

Signature

int incValue
    (
      const char* anAttrName, 
      Uint32 aValue
    )

int incValue
    (
      const char* anAttrName, 
      Uint64 aValue
    )

int incValue
    (
      Uint32 anAttrId, 
      Uint32 aValue
    )

int incValue
    (
      Uint32 anAttrId, 
      Uint64 aValue
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::insertTuple()

Description

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.

Signature

virtual int insertTuple
    (
      void
    )

Parameters

None.

Return value

Returns 0 on success, -1 on failure.

NdbOperation::interpret_exit_last_row()

Description

Terminate the entire transaction.

Signature

int interpret_exit_last_row
    (
      void
    )

Parameters

none

Return value

Returns 0 on success; otherwise, returns -1.

NdbOperation::interpret_exit_nok()

Description

Exit interpreted program with status NOT OK and an optional error code (see Section 2.4.2, “NDB Error Codes: by Type”).

Signature

int interpret_exit_nok
    (
      Uint32 ErrorCode
    )

int interpret_exit_nok
    (
      void
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::interpret_exit_ok()

Description

Exit interpreted program with status OK.

Signature

int interpret_exit_ok
    (
      void
    )

Parameters

none

Return value

0 on success, -1 otherwise.

NdbOperation::interpretedDeleteTuple()

Description

Delete a tuple using an interpreted program.

Signature

virtual 
int interpretedDeleteTuple
    (
      void
    )

Parameters

None.

Return value

0 on success, -1 otherwise.

NdbOperation::interpretedUpdateTuple()

Description

Update a tuple using an interpreted program.

Signature

virtual
int interpretedUpdateTuple
    (
      void
    )

Parameters

None.

Return value

0 on success, -1 otherwise.

NdbOperation::interpretedWriteTuple()

Description

Write a tuple using an interpreted program.

Signature

virtual
int interpretedWriteTuple
    (
      void
    )

Parameters

None.

Return value

0 on success, -1 otherwise.

NdbOperation::load_const_u32()

Description

Load a 32-bit constant value into a register.

Signature

int load_const_u32
    (
      Uint32 RegDest, 
      Uint32 Constant
    )

Parameters

RegDest: Destination register.
Constant: Value to load into the register.

Return value

0 on success, -1 otherwise.

NdbOperation::load_const_u64()

Description

Load a 64-bit constant value into a register.

Signature

int load_const_u64
    (
      Uint64 RegDest, 
      Uint64 Constant
    )

Parameters

RegDest: Destination register.
Constant: Value to load into the register.

Return value

0 on success, otherwise -1.

NdbOperation::load_const_null()

Description

Load NULL into a register.

Signature

int load_const_null
    (
      Uint32 RegDest
    )

Parameters

RegDest: Destination register.

Return value

0 on success, -1 otherwise.

NdbOperation::LockMode

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.

NdbOperation::OperationOptions

This section provides information about the OperationOptions data structure.

Parent class

NdbOperation

Description

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.

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 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”.

NdbOperation::read_attr()

Description

Read an attribute identified by name or ID into a register.

Signature

int read_attr
    (
      const char* anAttrName, 
      Uint32 RegDest
    )

int read_attr
    (
      Uint32 anAttrId, 
      Uint32 RegDest
    )

Parameters

anAttrName: Attribute name. Use this or the attribute ID.
anAttrId: Attribute ID. Use this or the name of the attribute.
RegDest: Destination register.

Return value

On success, 0; otheriwse, -1.

NdbOperation::readTuple()

Description

This method defines the NdbOperation as a READ operation. When the NdbTransaction::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.

NdbOperation::ret_sub()

Description

Return from an interpreted program subroutine.

Signature

int ret_sub
    (
      void
    )

Parameters

none.

Return value

0 on success, -1 otherwise.

NdbOperation::setValue()

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 use equal() instead.

In addition, it is not necessary when using insertTuple() to use setValue() 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:
1. The attribute name (a string)
2. 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:
1. String (const char*)
2. 32-bit integer
3. Unsigned 32-bit integer
4. 64-bit integer
5. Unsigned 64-bit integer
6. Double
7. Float
See NdbOperation::equal(), for important information regarding the value's format and length.

Return value

Returns -1 in the event of failure.

NdbOperation::SetValueSpec

This section provides information about the SetValueSpec data structure.

Parent class

NdbOperation

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 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”.

NdbOperation::sub_reg()

Description

Store difference of two register values in a third register.

Signature

int sub_reg
    (
      Uint32 RegSource1, 
      Uint32 RegSource2, 
      Uint32 RegDest
    )

Parameters

param

RegSource1: Register containing value to be subtracted.
RegSource2: Register containing value to be subtracted from.
RegDest: Register in which to store the result.

Return value

0 on success, otherwise -1.

NdbOperation::subValue()

Description

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.

Signature

int subValue
    (
      const char* anAttrName, 
      Uint32 aValue
    )

int subValue
    (
      const char* anAttrName, 
      Uint64 aValue
    )

int subValue
    (
      Uint32 anAttrId, 
      Uint32 aValue
    )

int subValue
    (
      Uint32 anAttrId, 
      Uint64 aValue
    )

Parameters

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.

Return value

0 on success, -1 otherwise.

NdbOperation::Type

This section provides information about the Type data type.

Description

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:

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`

NdbOperation::updateTuple()

Description

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.

Signature

virtual int updateTuple
    (
      void
    )

Parameters

None.

Return value

Returns 0 on success, -1 on failure.

NdbOperation::write_attr()

Description

Write an attribute value from a register. The attribute to be written can be specified by name or ID.

Signature

int write_attr
    (
      const char* anAttrName, 
      Uint32 RegSource
    )

int write_attr
    (
      Uint32 anAttrId, 
      Uint32 RegSource
    )

Parameters

anAttrName: Attribute name. Use this or the attribute ID.
anAttrId: Attribute ID. Use this or the name of the attribute.
RegSource: Source register.

Return value

Returns 0 on success; otherwise, returns -1.

NdbOperation::writeTuple()

Description

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.

Signature

virtual int writeTuple
    (
      void
    )

Parameters

None.

Return value

Returns 0 on success, -1 on failure.