Skip navigation links
2.3.16 The NdbRecAttr Class »
Section Navigation      [Toggle]

2.3.15.2. NdbOperation Methods

[+/-]

2.3.15.2.1. NdbOperation::getValue()
2.3.15.2.2. NdbOperation::getBlobHandle()
2.3.15.2.3. NdbOperation::getTableName()
2.3.15.2.4. NdbOperation::getTable()
2.3.15.2.5. NdbOperation::getNdbError()
2.3.15.2.6. NdbOperation::getNdbErrorLine()
2.3.15.2.7. NdbOperation::getType()
2.3.15.2.8. NdbOperation::getLockMode()
2.3.15.2.9. NdbOperation::getNdbTransaction()
2.3.15.2.10. NdbOperation::equal()
2.3.15.2.11. NdbOperation::setValue()
2.3.15.2.12. NdbOperation::insertTuple()
2.3.15.2.13. NdbOperation::readTuple()
2.3.15.2.14. NdbOperation::writeTuple()
2.3.15.2.15. NdbOperation::updateTuple()
2.3.15.2.16. NdbOperation::deleteTuple()

Abstract

This section lists and describes the public methods of the NdbOperation class.

Note

This class has no public constructor. To create an instance of NdbOperation, you must use NdbTransaction::getNdbOperation(). See Section 2.3.19.2.1, “NdbTransaction::getNdbOperation()”, for more information.

2.3.15.2.1. 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() which retrieves the data as char*, regardless of its actual type. However, this is not type-safe, and requires a cast from the user.) See Section 2.3.16, “The NdbRecAttr Class”, and Section 2.3.16.1.19, “NdbRecAttr::aRef()”, for more information.

Important

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 Section 2.3.19.2.5, “NdbTransaction::execute()”, and Section 2.3.16.1.4, “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 with regard to the type of the first parameter, which can be any one of the following:

  • The attribute name

  • The attribute id

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

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 Section 2.3.16.1.19, “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 */
}

2.3.15.2.2. 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. See Section 2.3.9, “The NdbBlob Class”, for details.

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.

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

2.3.15.2.4. 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.  An instance of Table. For more information, see Section 2.3.21, “The Table Class”.

2.3.15.2.5. 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. See Section 2.3.31, “The NdbError Structure”.

2.3.15.2.6. NdbOperation::getNdbErrorLine()

Description.  This method retrieves the method number in which the latest error occurred.

Signature.  Beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19, this method can (and should) be used as shown here: 

int getNdbErrorLine
    (
      void
    ) const

The non-const version of this method, shown here, was removed in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.28, and MySQL Cluster NDB 7.0.9. (Bug#47798) 

int getNdbErrorLine
    (
      void
    )

Parameters.  None.

Return value.  The method number (an integer).

2.3.15.2.7. NdbOperation::getType()

Description.  This method is used to retrieve the access type for this operation.

Signature.  

Type getType
    (
      void
    ) const

Parameters.  None.

Note

Prior to MySQL Cluster NDB 7.1.0, this method used const Type as its return type. (Bug#44840)

Return value.  A Type value. See Section 2.3.15.1.2, “The NdbOperation::Type Type”.

2.3.15.2.8. NdbOperation::getLockMode()

Description.  This method gets the operation's lock mode.

Signature.  

LockMode getLockMode
    (
      void
    ) const

Parameters.  None.

Return value.  A LockMode value. See Section 2.3.15.1.3, “The NdbOperation::LockMode Type”.

2.3.15.2.9. NdbOperation::getNdbTransaction()

Description.  Gets the NdbTransaction object for this operation. Available beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19.

Signature.  

virtual NdbTransaction* getNdbTransaction
    (
      void
    ) const

Parameters.  None.

Return value.  A pointer to an NdbTransaction object. See Section 2.3.19, “The NdbTransaction Class”.

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

Important

If the attribute is of a fixed size, its value must include all bytes. In particular a Char value must be native-blank 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*).

Note

When using insertTuple(), you may also define the search key with setValue(). See Section 2.3.15.2.11, “NdbOperation::setValue()”.

Signature.  There are 10 versions of equal(), each having slightly different parameters. All of these are listed here: 

int  equal
    (
      const char* name,
      const char* value
    )

int  equal
    (
      const char* name,
      Int32       value
    )

int  equal
    (
      const char* name,
      Uint32      value
    )

int  equal
    (
      const char* name,
      Int64       value
    )

int  equal
    (
      const char* name,
      Uint64      value
    )

int  equal
    (
      Uint32      id,
      const char* value
    )

int  equal
    (
      Uint32 id,
      Int32  value
    )

int  equal
    (
      Uint32 id,
      Uint32 value
    )

int  equal
    (
      Uint32 id,
      Int64  value
    )

int  equal
    (
      Uint32 id,
      Uint64 value
    )

Parameters.  This method requires two parameters:

  • The first parameter can be either of the following:

    • The name of the attribute (a string)

    • The id of the attribute (an unsigned 32-bit integer)

  • The second parameter is the attribute value to be tested; it 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.

2.3.15.2.11. NdbOperation::setValue()

Description.  This method defines an attribute to be set or updated.

Important

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.

However, 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 datatype 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.

Tip

To set a NULL value, use the following construct: 

setValue("ATTR_NAME", (char*)NULL);

Note

When you use insertTuple(), the NDB API will automatically detect 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 (and summarised in the Parameters section following): 

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 two parameters:

  • The first parameter identified the attribute to be set, and may be either one of:

    • The attribute name (a string)

    • The attribute id (an unsigned 32-bit integer)

  • The second parameter is the value to which the attribute is to be set; its type may be any one of the following 7 types:

    • String (const char*)

    • 32-bit integer

    • Unsigned 32-bit integer

    • 64-bit integer

    • Unsigned 64-bit integer

    • Double

    • Float

See Section 2.3.15.2.10, “NdbOperation::equal()”, for important information regarding the value's format and length.

Return value.  Returns -1 in the event of failure.

2.3.15.2.12. 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. See Section 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.  

virtual int insertTuple
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.15.2.13. NdbOperation::readTuple()

Description.  This method define the NdbOperation as a READ operation. When the NdbTransaction::execute() method is invoked, the operation reads a tuple. See Section 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.  

virtual int readTuple
    (
      LockMode mode
    )

Parameters.  mode specifies the locking mode used by the read operation. See Section 2.3.15.1.3, “The NdbOperation::LockMode Type”, for possible values.

Return value.  0 on success, -1 on failure.

2.3.15.2.14. 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. See Section 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.  

virtual int writeTuple
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.15.2.15. 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. See Section 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.  

virtual int updateTuple
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.15.2.16. 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. See Section 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.  

virtual int deleteTuple
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.