Documentation Home
MySQL NDB Cluster API Developer Guide
Related Documentation Download this Manual
PDF (US Ltr) - 3.6Mb
PDF (A4) - 3.6Mb


2.3.19 The NdbInterpretedCode Class

This section provides information about the NdbInterpretedCode class, which can be used to prepare and execute an NDB API interpreted program.

NdbInterpretedCode Class Overview

Parent class

None.

Child classes

None.

Description

NdbInterpretedCode represents an interpreted program for use in operations created using NdbRecord, or with scans created using the old API. The NdbScanFilter class can also be used to generate an NDB interpreted program using this class.

To create an NdbInterpretedCode object, invoke the constructor, optionally supplying a table for the program to operate on, and a buffer for program storage and finalization. If no table is supplied, then only instructions which do not access table attributes can be used. In NDB 8.0, an instance of Ndbrecord can be used for this purpose, in place of the Table.

Each NDB API operation applies to one table, and so does any NdbInterpretedCode program attached to that operation.

If no buffer is supplied, then an internal buffer is dynamically allocated and extended as necessary. Once the NdbInterpretedCode object is created, you can add instructions and labels to it by calling the appropriate methods as described later in this section. When the program has completed, finalize it by calling the finalise() method, which resolves any remaining internal branches and calls to label and subroutine offsets.

A single finalized NdbInterpretedCode program can be used by more than one operation. It need not be re-prepared for successive operations.

To use the program with NdbRecord operations and scans, pass it at operation definition time using the OperationOptions or ScanOptions parameter. When the program is no longer required, the NdbInterpretedCode object can be deleted, along with any user-supplied buffer.

For additional information and examples, see Section 1.6, “Using NdbInterpretedCode”.

This interface is still under development, and so is subject to change without notice. The NdbScanFilter API is a more stable API for defining scanning and filtering programs.

Methods

The following table lists the public methods of this class and the purpose or use of each method:

Table 2.48 NdbInterpretedCode class methods and descriptions

Name Description
NdbInterpretedCode() Class constructor
add_reg() Add two register values and store the result in a third register
add_val() Add a value to a table column value
branch_col_and_mask_eq_mask() Jump if a column value ANDed with a bitmask is equal to the bitmask
branch_col_and_mask_eq_zero() Jump if a column value ANDed with a bitmask is equal to 0
branch_col_and_mask_ne_mask() Jump if a column value ANDed with a bitmask is not equal to the bitmask
branch_col_and_mask_ne_zero() Jump if a column value ANDed with a bitmask is not equal to 0
branch_col_eq() Jump if a column value is equal to another
branch_col_eq_param() Jump if a column value is equal to a supplied parameter
branch_col_eq_null() Jump if a column value is NULL
branch_col_ge() Jump if a column value is greater than or equal to another
branch_col_ge_param() Jump if a column value is greater than or equal to a supplied parameter
branch_col_gt() Jump if a column value is greater than another
branch_col_gt_param() Jump if a column value is greater than a supplied parameter
branch_col_le() Jump if a column value is less than or equal to another
branch_col_like() Jump if a column value matches a pattern
branch_col_lt() Jump if a column value is less than another
branch_col_ne() Jump if a column value is not equal to another
branch_col_ne_null() Jump if a column value is not NULL
branch_col_ne_param() Jump if a column value is not equal to a supplied parameter
branch_col_notlike() Jump if a column value does not match a pattern
branch_eq() Jump if one register value is equal to another
branch_eq_null() Jump if a register value is NULL
branch_ge() Jump if one register value is greater than or equal to another
branch_gt() Jump if one register value is greater than another
branch_label() Unconditional jump to a label
branch_le() Jump if one register value is less than or equal to another
branch_col_le_param() Jump if a column value is greater than or equal to a supplied parameter
branch_lt() Jump if one register value is less than another
branch_col_lt_param() Jump if a column value is less than a supplied parameter
branch_ne() Jump if one register value is not equal to another
branch_ne_null() Jump if a register value is not NULL
call_sub() Call a subroutine
copy() Make a deep copy of an NdbInterpretedCode object
def_label() Create a label for use within the interpreted program
def_sub() Define a subroutine
finalise() Completes interpreted program and prepares it for use
getNdbError() Gets the most recent error associated with this NdbInterpretedCode object
getTable() Gets the table on which the program is defined
getWordsUsed() Gets the number of words used in the buffer
interpret_exit_last_row() Return a row as part of the result, and do not check any more rows in this fragment
interpret_exit_nok() Do not return a row as part of the result
interpret_exit_ok() Return a row as part of the result
load_const_null() Load a NULL value into a register
load_const_u16() Load a 16-bit numeric value into a register
load_const_u32() Load a 32-bit numeric value into a register
load_const_u64() Load a 64-bit numeric value into a register
read_attr() Read a table column value into a register
reset() Discard program
ret_sub() Return from a subroutine
sub_reg() Subtract two register values and store the result in a third register
sub_val() Subtract a value from a table column value
write_attr() Write a register value into a table column

For reasons of efficiency, methods of this class provide minimal error checking.

See also Section 1.6, “Using NdbInterpretedCode”.

Types

This class defines no public types.

NdbInterpretedCode Constructor

Description

This is the NdbInterpretedCode class constuctor.

Signature
NdbInterpretedCode
    (
      const NdbDictionary::Table* table = 0,
      Uint32* buffer = 0,
      Uint32 buffer_word_size = 0
    )
Alternative constructor (NDB 8.0)
NdbInterpretedCode
    (
      const NdbRecord&,
      Uint32* buffer = 0,
      Uint32 buffer_word_size = 0);
Parameters

The NdbInterpretedCode constructor takes three parameters, as described here:

  • The table against which this program is to be run. Prior to NDB 8.0, this parameter must be supplied if the program is table-specific—that is, if it reads from or writes to columns in a table. In NDB 8.0, the constructor accepts an NdbRecord in place of the Table

  • A pointer to a buffer of 32-bit words used to store the program.

  • buffer_word_size is the length of the buffer passed in. If the program exceeds this length then adding new instructions will fail with error 4518 Too many instructions in interpreted program.

    Alternatively, if no buffer is passed, a buffer will be dynamically allocated internally and extended to cope as instructions are added.

Return value

An instance of NdbInterpretedCode.

NdbInterpretedCode::add_reg()

Description

This method sums the values stored in any two given registers and stores the result in a third register.

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

This method takes three parameters. The first of these is the register in which the result is to be stored (RegDest). The second and third parameters (RegSource1 and RegSource2) are the registers whose values are to be summed.

For storing the result, it is possible to re-use one of the registers whose values are summed; that is, RegDest can be the same as RegSource1 or RegSource2.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::add_val()

Description

This method adds a specified value to the value of a given table column, and places the original and modified column values in registers 6 and 7. It is equivalent to the following series of NdbInterpretedCode method calls, where attrId is the table column' attribute ID and aValue is the value to be added:

read_attr(6, attrId);
load_const_u32(7, aValue);
add_reg(7,6,7);
write_attr(attrId, 7);

aValue can be a 32-bit or 64-bit integer.

Signature

This method can be invoked in either of two ways, depending on whether aValue is 32-bit or 64-bit.

32-bit aValue:

int add_val
    (
      Uint32 attrId,
      Uint32 aValue
    )

64-bit aValue:

int add_val
    (
      Uint32 attrId,
      Uint64 aValue
    )
Parameters

A table column attribute ID and a 32-bit or 64-bit integer value to be added to this column value.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_and_mask_eq_mask()

Description

This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is equal to the bitmask, then execution jumps to a specified label specified in the method call.

Signature
int branch_col_and_mask_eq_mask
    (
      const void* mask,
      Uint32 unused,
      Uint32 attrId,
      Uint32 label
    )
Parameters

This method can accept four parameters, of which three are actually used. These are described in the following list:

  • A pointer to a constant mask to compare the column value to

  • A Uint32 value which is currently unused.

  • The attrId of the column to be compared.

  • A program label to jump to if the condition is true.

    Prior to NDB 8.0.30, this argument was not handled correctly for nonzero values. ( Bug #33888962)

Return value

This method returns 0 on success and -1 on failure.

NdbInterpretedCode::branch_col_and_mask_eq_zero()

Description

This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is equal to 0, then execution jumps to a specified label specified in the method call.

Signature
int branch_col_and_mask_eq_zero
    (
      const void* mask,
      Uint32 unused,
      Uint32 attrId,
      Uint32 label
    )
Parameters

This method can accept the following four parameters, of which three are actually used:

  • A pointer to a constant mask to compare the column value to.

  • A Uint32 value which is currently unused.

  • The attrId of the column to be compared.

  • A program label to jump to if the condition is true.

    Prior to NDB 8.0.30, this argument was not handled correctly for nonzero values. ( Bug #33888962)

Return value

This method returns 0 on success and -1 on failure.

NdbInterpretedCode::branch_col_and_mask_ne_mask()

Description

This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is not equal to the bitmask, then execution jumps to a specified label specified in the method call.

Signature
int branch_col_and_mask_ne_mask
    (
      const void* mask,
      Uint32 unused,
      Uint32 attrId,
      Uint32 label
    )
Parameters

This method accepts four parameters, of which three are actually used. These described in the following list:

  • A pointer to a constant mask to compare the column value to.

  • A Uint32 value which is currently unused.

  • The attrId of the column to be compared.

  • A program label to jump to if the condition is true.

    Prior to NDB 8.0.30, this argument was not handled correctly for nonzero values. ( Bug #33888962)

Return value

This method returns 0 on success and -1 on failure.

NdbInterpretedCode::branch_col_and_mask_ne_zero()

Description

This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is not equal to 0, then execution jumps to a specified label specified in the method call.

Signature
int branch_col_and_mask_ne_zero
    (
      const void* mask,
      Uint32 unused,
      Uint32 attrId,
      Uint32 label
    )
Parameters

This method accepts the following four parameters, of which three are actually used:

  • A pointer to a constant mask to compare the column value to.

  • A Uint32 value which is currently unused.

  • The attrId of the column to be compared.

  • A program label to jump to if the condition is true.

    Prior to NDB 8.0.30, this argument was not handled correctly for nonzero values. ( Bug #33888962)

Return value

This method returns 0 on success and -1 on failure.

NdbInterpretedCode::branch_col_eq()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the values are equal. In NDB 8.0, it can also be used to compare two columns for equality.

Signature

Compare a column with a value:

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

Compare two columns:

int branch_col_eq
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When comparing a column and a value, this method takes the following four parameters:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A Label (previously defined using def_label()) to jump to if the compared values are equal

When comparing two table column values, the parameters required are shown here:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Location to jump to if the compared columns are the same. Must already have been defined using def_label()

When using this method to compare two columns, the columns must be of exactly the same type.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_eq_null()

Description

This method tests the value of a table column and jumps to the indicated program label if the column value is NULL.

Signature
int branch_col_eq_null
    (
      Uint32 attrId,
      Uint32 Label
    )
Parameters

This method requires the following two parameters:

  • The attribute ID of the table column

  • The program label to jump to if the column value is NULL

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_eq_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if they are equal. Added in NDB 8.0.27.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_eq_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if arguments are equal.

Return value

0 on success.

NdbInterpretedCode::branch_col_ge()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the constant column value. In NDB 8.0, it can also be used to compare two columns, and to perform the jump if the value of the first column is greater than or equal to that of the second.

Signature

Compare value with column:

int branch_col_ge
    (
      const void* val,
      Uint32 len,
      Uint32 attrId,
      Uint32 label
    )

Compare values of two columns:

int branch_col_ge
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When used to compare a value with a column, this method takes the four parameters listed here:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A label (previously defined using def_label()) to jump to if the constant value is greater than or equal to the column value

The method takes the parameters listed here when used to compare two columns:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Jump to this if the first column value is greater than or equal to the second

When comparing two columns, the types of the columns must be exactly the same in all respects.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_ge_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if the attribute value is greater than or equal to that of the parameter. Added in NDB 8.0.27.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_ge_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if column value is not less than parameter value.

Return value

0 on success.

NdbInterpretedCode::branch_col_gt()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the constant is greater than the column value. In NDB 8.0, this method is overloaded such that it can be used to compare two column values, and to make the jump if the first is greater than the second.

Signature

Compare value with column:

int branch_col_ge
    (
      const void* val,
      Uint32 len,
      Uint32 attrId,
      Uint32 label
    )

Compare values of two columns:

int branch_col_ge
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When used to compare a value with a table column, this method takes the following four parameters:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A Label (previously defined using def_label()) to jump to if the constant value is greater than the column value

The method takes the three parameters listed here when used to compare two columns:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Jump to this if the first column value is greater than or equal to the second

When comparing two columns, the types of the columns must be exactly the same in all respects.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_gt_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if the attribute value is greater than that of the parameter. Added in NDB 8.0.27.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_gt_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if column value is greater than parameter value.

Return value

0 on success.

NdbInterpretedCode::branch_col_le()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the constant is less than or equal to the column value. In NDB 8.0, it can also be used to compare two table column values in this fashion.

Signature

Compare a table column value with a constant:

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

Compare values of two table columns:

int branch_col_ge
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When comparing a table column value with a constant, this method takes the four parameters listed here:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A Label (previously defined using def_label()) to jump to if the constant value is less than or equal to the column value

The method takes the three parameters listed here when used to compare two table column values:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Jump to this if the first column value is less than or equal to the second

When comparing two table column values, the types of the column values must be exactly the same in all respects.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_le_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if the attribute value is less than or equal to that of the parameter. Added in NDB 8.0.27.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_le_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if column value is not greater than parameter value.

Return value

0 on success.

NdbInterpretedCode::branch_col_like()

Description

This method tests a table column value against a regular expression pattern and jumps to the indicated program label if they match.

Signature
int branch_col_like
    (
      const void* val,
      Uint32 len,
      Uint32 attrId,
      Uint32 Label
    )
Parameters

This method takes four parameters, which are listed here:

  • A regular expression pattern (val); see Pattern-Based NdbInterpretedCode Branch Operations, for the syntax supported

  • Length of the pattern (in bytes)

  • The attribute ID for the table column being tested

  • The program label to jump to if the table column value matches the pattern

Return value

0 on success, -1 on failure

NdbInterpretedCode::branch_col_lt()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the constant is less than the column value. In NDB 8.0, two table column values can be compared instead.

Signature

Compare a table column value with a constant:

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

Compare two table column values:

int branch_col_lt
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When comparing a table column value with a constant, this method takes the following four parameters:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A Label (previously defined using def_label()) to jump to if the constant value is less than the column value

When used to compare two table column values, branch_col_lt() takes the folowwing three parameters:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Jump to this if the first column value is less than the second

When comparing two table column values, the types of the table column values must be exactly the same. This means that they must have the same length, precision, and scale.

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_col_lt_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if the attribute value is less than that of the parameter. Added in NDB 8.0.27.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_lt_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if column value is less than parameter value.

Return value

0 on success.

NdbInterpretedCode::branch_col_ne()

Description

This method compares a table column value with an arbitrary constant and jumps to the specified program label if the two values are not equal. In NDB 8.0, it can also be used to compare a table column value with another table column value instead.

Signature

Compare a table column value with a constant:

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

Compare two table column values:

int branch_col_ne
    (
      Uint32 attrId1,
      Uint32 attrId2,
      Uint32 label
    )
Parameters

When comparing a table column value with a constant, this method takes the four parameters listed here:

  • A constant value (val)

  • The length of the value (in bytes)

  • The attribute ID of the table column whose value is to be compared with val

  • A Label (previously defined using def_label()) to jump to if the compared values are unequal

When comparing two table column values, the parameters required are shown here:

  • AttrId1: The attribute ID of the first table column whose value is to be compared

  • AttrId2: The attribute ID of the second table column

  • label: Location to jump to if the compared columns are not the same. Must already have been defined using def_label()

When using this method to compare two table column values, the columns must be of exactly the same type.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_ne_null()

Description

This method tests the value of a table column and jumps to the indicated program label if the column value is not NULL.

Signature
int branch_col_ne_null
    (
      Uint32 attrId,
      Uint32 Label
    )
Parameters

This method requires the following two parameters:

  • The attribute ID of the table column

  • The program label to jump to if the column value is not NULL. The label must have been defined previously using def_label().

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::branch_col_ne_param()

Description

Compares a table attribute with a parameter, each specified by ID, and branches to the specified label if they are not equal.

The parameter can be NULL, and is compared according to the NULL handling mode in effect; the default is to treat NULL as less than any other value, and NULL as equal to NULL. You can override this behavior and force NULL handling that complies with the SQL standard instead, by invoking setSqlCmpSemantics().

Signature
int branch_col_ne_param
    (
      Uint32 attrId, 
      Uint32 paramId, 
      Uint32 label
    )
Parameters
attrId

ID of a table attribute.

paramId

Parameter ID.

label

Label to jump to if arguments are not equal.

Return value

0 on success.

NdbInterpretedCode::branch_col_notlike()

Description

This method is similar to branch_col_like() in that it tests a table column value against a regular expression pattern; however it jumps to the indicated program label only if the pattern and the column value do not match.

Signature
int branch_col_notlike
    (
      const void* val,
      Uint32 len,
      Uint32 attrId,
      Uint32 Label
    )
Parameters

This method takes the following four parameters:

  • A regular expression pattern (val); see Pattern-Based NdbInterpretedCode Branch Operations, for the syntax supported

  • Length of the pattern (in bytes)

  • The attribute ID for the table column being tested

  • The program label to jump to if the table column value does not match the pattern. The Label must have been defined previously using def_label().

Return value

Returns 0 on success, -1 on failure

NdbInterpretedCode::branch_eq()

Description

This method compares two register values; if they are equal, then the interpreted program jumps to the specified label.

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

This method takes three parameters, the registers whose values are to be compared—RegLvalue and RegRvalue—and the program Label to jump to if they are equal. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_eq_null()

Description

This method compares a register value with NULL; if the register value is null, then the interpreted program jumps to the specified label.

Signature
int branch_eq_null
    (
      Uint32 RegLvalue,
      Uint32 Label
    )
Parameters

This method takes two parameters, the register whose value is to be compared with NULL (RegLvalue) and the program Label to jump to if RegLvalue is null. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_ge()

Description

This method compares two register values; if the first is greater than or equal to the second, the interpreted program jumps to the specified label.

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

This method takes three parameters, the registers whose values are to be compared—RegLvalue and RegRvalue—and the program Label to jump to if RegLvalue is greater than or equal to RegRvalue. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_gt()

Description

This method compares two register values; if the first is greater than the second, the interpreted program jumps to the specified label.

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

This method takes three parameters, the registers whose values are to be compared—RegLvalue and RegRvalue—and the program Label to jump to if RegLvalue is greater than RegRvalue. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_label()

Description

This method performs an unconditional jump to an interpreted program label (see NdbInterpretedCode::def_label()).

Signature
int branch_label
    (
      Uint32 Label
    )
Parameters

This method takes a single parameter, an interpreted program Label defined using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_le()

Description

This method compares two register values; if the first is less than or equal to the second, the interpreted program jumps to the specified label.

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

This method takes three parameters, the registers whose values are to be compared—RegLvalue and RegRvalue—and the program Label to jump to if RegLvalue is less than or equal to RegRvalue. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_lt()

Description

This method compares two register values; if the first is less than the second, the interpreted program jumps to the specified label.

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

This method takes three parameters, the registers whose values are to be compared—RegLvalue and RegRvalue—and the program Label to jump to if RegLvalue is less than RegRvalue. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_ne()

Description

This method compares two register values; if they are not equal, then the interpreted program jumps to the specified label.

Signature
int branch_ne
    (
      Uint32 RegLvalue,
      Uint32 RegRvalue,
      Uint32 Label
    )
Parameters

This method takes three parameters, the registers whose values are to be compared (RegLvalue and RegRvalue) and the program label to jump to if they are not equal. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::branch_ne_null()

Description

This method compares a register value with NULL; if the value is not null, then the interpreted program jumps to the specified label.

Signature
int branch_ne_null
    (
      Uint32 RegLvalue,
      Uint32 Label
    )
Parameters

This method takes two parameters, the register whose value is to be compared with NULL (RegLvalue) and the program Label to jump to if RegLvalue is not null. Label must have been defined previously using def_label().

Return value

0 on success, -1 on failure.

NdbInterpretedCode::call_sub()

Description

This method is used to call a subroutine.

Signature
int call_sub
    (
      Uint32 SubroutineNumber
    )
Parameters

This method takes a single parameter, the number identifying the subroutine to be called.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::copy()

Description

Makes a deep copy of an NdbInterpretedCode object.

Signature
int copy
    (
      const NdbInterpretedCode& src
    )
Parameters

A reference to the copy.

Return value

0 on success, or an error code.

NdbInterpretedCode::def_label()

Description

This method defines a label to be used as the target of one or more jumps in an interpreted program.

def_label() uses a 2-word buffer and requires no space for request messages.

Signature
int def_label
    (
      int LabelNum
    )
Parameters

This method takes a single parameter LabelNum, an integer whose value must be unique among all values used for labels within the interpreted program.

Return value

0 on success; -1 on failure.

NdbInterpretedCode::def_sub()

Description

This method is used to mark the start of a subroutine. See Using Subroutines with NdbInterpretedCode, for more information.

Signature
int def_sub
    (
      Uint32 SubroutineNumber
    )
Parameters

A single parameter, a number used to identify the subroutine.

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::finalise()

Description

This method prepares an interpreted program, including any subroutines it might have, by resolving all branching instructions and calls to subroutines. It must be called before using the program, and can be invoked only once for any given NdbInterpretedCode object.

If no instructions have been defined, this method attempts to insert a single interpret_exit_ok() method call prior to finalization.

Signature
int finalise
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::getNdbError()

Description

This method returns the most recent error associated with this NdbInterpretedCode object.

Signature
const class NdbError& getNdbError
    (
      void
    ) const
Parameters

None.

Return value

A reference to an NdbError object.

NdbInterpretedCode::getTable()

Description

This method can be used to obtain a reference to the table for which the NdbInterpretedCode object was defined.

Signature
const NdbDictionary::Table* getTable
    (
      void
    ) const
Parameters

None.

Return value

A pointer to a Table object. Returns NULL if no table object was supplied when the NdbInterpretedCode was instantiated.

NdbInterpretedCode::getWordsUsed()

Description

This method returns the number of words from the buffer that have been used, whether the buffer is one that is user-supplied or the internally-provided buffer.

Signature
Uint32 getWordsUsed
    (
      void
    ) const
Parameters

None.

Return value

The 32-bit number of words used from the buffer.

NdbInterpretedCode::interpret_exit_last_row()

Description

For a scanning operation, invoking this method indicates that this row should be returned as part of the scan, and that no more rows in this fragment should be scanned. For other types of operations, the method causes the operation to be aborted.

Signature
int interpret_exit_last_row
    (
      void
    )
Parameters

None.

Return value

Returns 0 if successful, -1 otherwise.

NdbInterpretedCode::interpret_exit_nok()

Description

For scanning operations, this method is used to indicate that the current row should not be returned as part of the scan, and to cause the program should move on to the next row. It causes other types of operations to be aborted.

Signature
int interpret_exit_nok
    (
      Uint32 ErrorCode = 626 //  HA_ERR_KEY_NOT_FOUND
    )
Parameters

This method takes a single (optional) parameter ErrorCode. (For a complete listing of NDB error codes, see Section 2.4.2, “NDB Error Codes: by Type”.) If not supplied, this defaults to 626 (HA_ERR_KEY_NOT_FOUND, Tuple did not exist. Applications should use error code 626 or another code in the range 6000 to 6999 inclusive.

For any values other than those mentioned here, the behavior of this method is undefined, and is subject to change at any time without prior notice.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::interpret_exit_ok()

Description

For a scanning operation, this method indicates that the current row should be returned as part of the results of the scan and that the program should move on to the next row. For other operations, calling this method causes the interpreted program to exit.

Signature
int interpret_exit_ok
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::load_const_null()

Description

This method is used to load a NULL value into a register.

Signature
int load_const_null
    (
      Uint32 RegDest
    )
Parameters

This method takes a single parameter, the register into which to place the NULL.

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::load_const_u16()

Description

This method loads a 16-bit value into the specified interpreter register.

Signature
int load_const_u16
    (
      Uint32 RegDest,
      Uint32 Constant
    )
Parameters

This method takes the following two parameters:

  • RegDest: The register into which the value should be loaded.

  • A Constant value to be loaded

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::load_const_u32()

Description

This method loads a 32-bit value into the specified interpreter register.

Signature
int load_const_u32
    (
      Uint32 RegDest,
      Uint32 Constant
    )
Parameters

This method takes the following two parameters:

  • RegDest: The register into which the value should be loaded.

  • A Constant value to be loaded

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::load_const_u64()

Description

This method loads a 64-bit value into the specified interpreter register.

Signature
int load_const_u64
    (
      Uint32 RegDest,
      Uint64 Constant
    )
Parameters

This method takes the following two parameters:

  • RegDest: The register into which the value should be loaded.

  • A Constant value to be loaded

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::read_attr()

Description

The read_attr() method is used to read a table column value into a program register. The column may be specified either by using its attribute ID or as a pointer to a Column object.

Signature

This method can be called in either of two ways. The first of these is by referencing the column by its attribute ID, as shown here:

int read_attr
    (
      Uint32 RegDest,
      Uint32 attrId
    )

Alternatively, you can reference the column as a Column object, as shown here:

int read_attr
    (
      Uint32 RegDest,
      const NdbDictionary::Column* column
    )
Parameters

This method takes two parameters, as described here:

  • The register to which the column value is to be copied (RegDest).

  • Either of the following references to the table column whose value is to be copied:

    • The table column's attribute ID (attrId)

    • A pointer to a column—that is, a pointer to an Column object referencing the table column

Return value

Returns 0 on success, and -1 on failure.

NdbInterpretedCode::reset()

Description

This method clears any existing program from the NdbInterpretedCode object, which can then be used for constructing a new program.

Signature
int ret_sub
    (
      void
    )
Parameters

None.

Return value

None.

This method was added in NDB 8.0.

NdbInterpretedCode::ret_sub()

Description

This method marks the end of the current subroutine.

Signature
int ret_sub
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, -1 otherwise.

NdbInterpretedCode::sub_reg()

Description

This method gets the difference between the values stored in any two given registers and stores the result in a third register.

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

This method takes three parameters. The first of these is the register in which the result is to be stored (RegDest). The second and third parameters (RegSource1and RegSource2) are the registers whose values are to be subtracted. In other words, the value of register RegDest is calculated as the value of the expression shown here:

(value in register RegSource1) − (value in register RegSource2)

It is possible to re-use one of the registers whose values are subtracted for storing the result; that is, RegDest can be the same as RegSource1 or RegSource2.

Return value

0 on success; -1 on failure.

NdbInterpretedCode::sub_val()

Description

This method subtracts a specified value from the value of a given table column, and places the original and modified column values in registers 6 and 7. It is equivalent to the following series of NdbInterpretedCode method calls, where attrId is the table column' attribute ID and aValue is the value to be subtracted:

read_attr(6, attrId);
load_const_u32(7, aValue);
sub_reg(7,6,7);
write_attr(attrId, 7);

aValue can be a 32-bit or 64-bit integer.

Signature

This method can be invoked in either of two ways, depending on whether aValue is 32-bit or 64-bit.

32-bit aValue:

int sub_val
    (
      Uint32 attrId,
      Uint32 aValue
    )

64-bit aValue:

int sub_val
    (
      Uint32 attrId,
      Uint64 aValue
    )
Parameters

A table column attribute ID and a 32-bit or 64-bit integer value to be subtracted from this column value.

Return value

Returns 0 on success, -1 on failure.

NdbInterpretedCode::write_attr()

Description

This method is used to copy a register value to a table column. The column may be specified either by using its attribute ID or as a pointer to a Column object.

Signature

This method can be invoked in either of two ways. The first of these is requires referencing the column by its attribute ID, as shown here:

int read_attr
    (
      Uint32 attrId,
      Uint32 RegSource
    )

You can also reference the column as a Column object instead, like this:

int read_attr
    (
      const NdbDictionary::Column* column,
      Uint32 RegSource
    )
Parameters

This method takes two parameters as follows:

  • A reference to the table column to which the register value is to be copied. This can be either of the following:

    • The table column's attribute ID (attrId)

    • A pointer to a column—that is, a pointer to an Column object referencing the table column

  • The register whose value is to be copied (RegSource).

Return value

Returns 0 on success; -1 on failure.