MySQL :: MySQL NDB Cluster API Developer Guide :: 1.6 Using NdbInterpretedCode

NdbInterpretedCode Methods for Loading Values into Registers

The methods described in this section are used to load constant values into NdbInterpretedCode program registers. The space required by each of these methods is shown in the following table:

Table 1.1 NdbInterpretedCode methods used to load constant values into NdbInterpretedCode program registers, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`load_const_null()`	1	1
`load_const_u16()`	1	1
`load_const_u32()`	2	2
`load_const_u64()`	3	3

NdbInterpretedCode Methods for Copying Values Between Registers and Table Columns

NdbInterpretedCode provides two methods for copying values between a column in the current table row and a program register. The read_attr() method is used to copy a table column value into a program register; write_attr() is used to copy a value from a program register into a table column. Both of these methods require that the table being operated on was specified when creating the NdbInterpretedCode object for which they are called.

The space required by each of these methods is shown in the following table:

Table 1.2 NdbInterpretedCode methods used to copy values between registers and table columns, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`read_attr()`	1	1
`write_attr()`	1	1

For more information, see NdbInterpretedCode::read_attr(), and NdbInterpretedCode::write_attr().

NdbInterpretedCode Register Arithmetic Methods

NdbInterpretedCode provides two methods for performing arithmetic operations on registers. Using add_reg(), you can load the sum of two registers into another register; sub_reg() lets you load the difference of two registers into another register.

The space required by each of these methods is shown in the following table:

Table 1.3 NdbInterpretedCode methods used to perform arithmetic operations on registers, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`add_reg()`	1	1
`sub_reg()`	1	1

For mroe information, see NdbInterpretedCode::add_reg(), and NdbInterpretedCode::sub_reg().

NdbInterpretedCode: Labels and Branching

The NdbInterpretedCode class lets you define labels within interpreted programs and provides a number of methods for performing jumps to these labels based on any of the following types of conditions:

Comparison between two register values
Comparison between a column value and a given constant
Whether or not a column value matches a given pattern

To define a label, use the def_label() method.

To perform an unconditional jump to a label, use the branch_label() method.

To perform a jump to a given label based on a comparison of register values, use one of the branch_*() methods (branch_ge(), branch_gt(), branch_le(), branch_lt(), branch_eq(), branch_ne(), branch_ne_null(), or branch_eq_null()). See Register-Based NdbInterpretedCode Branch Operations.

To perform a jump to a given label based on a comparison of table column values, use one of the branch_col_*() methods (branch_col_ge(), branch_col_gt(), branch_col_le(), branch_col_lt(), branch_col_eq(), branch_col_ne(), branch_col_ne_null(), or branch_col_eq_null()). See Column-Based NdbInterpretedCode Branch Operations.

To perform a jump based on pattern-matching of a table column value, use one of the methods branch_col_like() or branch_col_notlike(). See Pattern-Based NdbInterpretedCode Branch Operations.

Register-Based NdbInterpretedCode Branch Operations

Most of these are used to branch based on the results of register-to-register comparisons. There are also two methods used to compare a register value with NULL. All of these methods require as a parameter a label defined using the def_label() method.

These methods can be thought of as performing the following logic:

if(register_value1 condition register_value2)
  goto Label

The space required by each of these methods is shown in the following table:

Table 1.4 Register-based NdbInterpretedCode branch methods, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`branch_ge()`	1	1
`branch_gt()`	1	1
`branch_le()`	1	1
`branch_lt()`	1	1
`branch_eq()`	1	1
`branch_ne()`	1	1
`branch_ne_null()`	1	1
`branch_eq_null()`	1	1

Column-Based NdbInterpretedCode Branch Operations

The methods described in this section are used to perform branching based on a comparison between a table column value and a given constant value. Each of these methods expects the attribute ID of the column whose value is to be tested rather than a reference to a Column object.

These methods, with the exception of branch_col_eq_null() and branch_col_ne_null(), can be thought of as performing the following logic:

if(constant_value condition column_value)
  goto Label

In each case (once again excepting branch_col_eq_null() and branch_col_ne_null()), the arbitrary constant is the first parameter passed to the method.

The space requirements for each of these methods is shown in the following table, where L represents the length of the constant value:

Table 1.5 Column-based NdbInterpretedCode branch methods, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`branch_col_eq_null()`	2	2
`branch_col_ne_null()`	2	2
`branch_col_eq()`	2	2 + `CEIL(L / 8)`
`branch_col_ne()`	2	2 + `CEIL(L / 8)`
`branch_col_lt()`	2	2 + `CEIL(L / 8)`
`branch_col_le()`	2	2 + `CEIL(L / 8)`
`branch_col_gt()`	2	2 + `CEIL(L / 8)`
`branch_col_ge()`	2	2 + `CEIL(L / 8)`

Note

The expression CEIL(L / 8) is the number of whole 8-byte words required to hold the constant value to be compared.

Pattern-Based NdbInterpretedCode Branch Operations

The NdbInterpretedCode class provides two methods which can be used to branch based on a comparison between a column containing character data (that is, a CHAR, VARCHAR, BINARY, or VARBINARY column) and a regular expression pattern.

The pattern syntax supported by the regular expression is the same as that supported by the MySQL Server's LIKE and NOT LIKE operators, including the _ and % metacharacters. For more information about these, see String Comparison Functions and Operators.

Note

This is the same regular expression pattern syntax that is supported by NdbScanFilter; see NdbScanFilter::cmp(), for more information.

The table being operated upon must be supplied when the NdbInterpretedCode object is instantiated. The regular expression pattern should be in plain CHAR format, even if the column is actually a VARCHAR (in other words, there should be no leading length bytes).

These functions behave as shown here:

if (column_value [NOT] LIKE pattern)
  goto Label;

The space requirements for these methods are shown in the following table, where L represents the length of the constant value:

Table 1.6 Pattern-based NdbInterpretedCode branch methods, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`branch_col_like()`	2	2 + `CEIL(L / 8)`
`branch_col_notlike()`	2	2 + `CEIL(L / 8)`

Note

The expression CEIL(L / 8) is the number of whole 8-byte words required to hold the constant value to be compared.

NdbInterpretedCode Bitwise Comparison Operations

These instructions are used to branch based on the result of a logical AND comparison between a BIT column value and a bitmask pattern.

Use of these methods requires that the table being operated upon was supplied when the NdbInterpretedCode object was constructed. The mask value should be the same size as the bit column being compared. BIT values are passed into and out of the NDB API as 32-bit words with bits set in order from the least significant bit to the most significant bit. The endianness of the platform on which the instructions are executed controls which byte contains the least significant bits. On x86, this is the first byte (byte 0); on SPARC and PPC, it is the last byte.

The buffer length and the request length for each of the methods listed here each requires an amount of space equal to 2 words plus the column width rounded (up) to the nearest whole word:

NdbInterpretedCode Result Handling Methods

The methods described in this section are used to tell the interpreter that processing of the current row is complete, and—in the case of scans—whether or not to include this row in the results of the scan.

The space requirements for these methods are shown in the following table, where L represents the length of the constant value:

Table 1.7 NdbInterpretedCode result handling methods, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`interpret_exit_ok()`	1	1
`interpret_exit_nok()`	1	1
`interpret_exit_last_row()`	1	1

NdbInterpretedCode Convenience Methods

The methods described in this section can be used to insert multiple instructions (using specific registers) into an interpreted program.

Important

In addition to updating the table column, these methods use interpreter registers 6 and 7, replacing any existing contents of register 6 with the original column value and any existing contents of register 7 with the modified column value. The table itself must be previously defined when instantiating the NdbInterpretedCode object for which the method is invoked.

The space requirements for these methods are shown in the following table, where L represents the length of the constant value:

Table 1.8 NdbInterpretedCode convenience methods, with required buffer and request message space.

Method	Buffer (words)	Request message (words)
`add_val()`	4	1; if the supplied value >= 2¹⁶: 2; if >= 2³²: 3
`sub_val()`	4	1; if the supplied value >= 2¹⁶: 2; if >= 2³²: 3

Using Subroutines with NdbInterpretedCode

NdbInterpretedCode supports subroutines which can be invoked from within interpreted programs, with each subroutine being identified by a unique number. Subroutines can be defined only following all main program instructions.

Important

Numbers used to identify subroutines must be contiguous; however, they do not have to be in any particular order.

The beginning of a subroutine is indicated by invoking the def_sub() method;
ret_sub() terminates the subroutine; all instructions following the call to def_sub() belong to the subroutine until it is terminated using this method.
A subroutine is called using the call_sub() method.

Once the subroutine has completed, the program resumes execution with the instruction immediately following the one which invoked the subroutine. Subroutines can also be invoked from other subroutines; currently, the maximum subroutine stack depth is 32.

NdbInterpretedCode Utility Methods

Some additional utility methods supplied by NdbInterpretedCode are listed here:

copy(): Copies an existing interpreted program by performing a deep copy on the associated NdbInterpretedCode object.
finalise(): Prepares an interpreted program by resolving all branching instructions and subroutine calls.
getTable(): Get a reference to the table for which the NdbInterpretedCode object was defined.
getNdbError(): Get the most recent error associated with this NdbInterpretedCode object.
getWordsUsed(): Obtain the number of words used from the buffer.