Skip navigation links
2.3.10 The NdbDictionary Class »
Section Navigation      [Toggle]

2.3.9.2. NdbBlob Methods

[+/-]

2.3.9.2.1. NdbBlob::getState()
2.3.9.2.2. NdbBlob::getValue()
2.3.9.2.3. NdbBlob::setValue()
2.3.9.2.4. NdbBlob::setActiveHook()
2.3.9.2.5. NdbBlob::getVersion()
2.3.9.2.6. NdbBlob::getNull()
2.3.9.2.7. NdbBlob::setNull()
2.3.9.2.8. NdbBlob::getLength()
2.3.9.2.9. NdbBlob::truncate()
2.3.9.2.10. NdbBlob::getPos()
2.3.9.2.11. NdbBlob::setPos()
2.3.9.2.12. NdbBlob::readData()
2.3.9.2.13. NdbBlob::writeData()
2.3.9.2.14. NdbBlob::getColumn()
2.3.9.2.15. NdbBlob::getNdbError()
2.3.9.2.16. NdbBlob::blobsFirstBlob()
2.3.9.2.17. NdbBlob::blobsNextBlob()
2.3.9.2.18. NdbBlob::getBlobEventName()
2.3.9.2.19. NdbBlob::getBlobTableName()
2.3.9.2.20. NdbBlob::getNdbOperation()

Abstract

This section discusses the public methods available in the NdbBlob class.

Important

This class has no public constructor. You can obtain a blob handle using NdbEventOperation::getBlobHandle().

2.3.9.2.1. NdbBlob::getState()

Description.  This method gets the current state of the NdbBlob object for which it is invoked. Possible states are described in Section 2.3.9.1.2, “The NdbBlob::State Type”.

Signature.  

State getState
    (
      void
    )

Parameters.  None.

Return value.  A State value. For possible values, see Section 2.3.9.1.2, “The NdbBlob::State Type”.

2.3.9.2.2. NdbBlob::getValue()

Description.  Use this method to prepare to read a blob value; the value is available following invocation. Use getNull() to check for a NULL value; use getLength() to get the actual length of the blob, and to check for truncation. getValue() sets the current read/write position to the point following the end of the data which was read.

Signature.  

int getValue
    (
      void*  data,
      Uint32 bytes
    )

Parameters.  This method takes two parameters — a pointer to the data to be read, and the number of bytes to be read.

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

2.3.9.2.3. NdbBlob::setValue()

Description.  This method is used to prepare for inserting or updating a blob value. Any existing blob data that is longer than the new data is truncated. The data buffer must remain valid until the operation has been executed. setValue() sets the current read/write position to the point following the end of the data. You can set data to a null pointer (0) in order to create a NULL value.

Signature.  

int setValue
    (
      const void*  data,
      Uint32       bytes
    )

Parameters.  This method takes two parameters:

  • The data that is to be inserted or used to overwrite the blob value.

  • The number of bytes — that is, the length — of the data.

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

2.3.9.2.4. NdbBlob::setActiveHook()

Description.  This method defines a callback for blob handle activation. The queue of prepared operations will be executed in no-commit mode up to this point; then, the callback is invoked. For additional information, see Section 2.3.9.1.1, “The NdbBlob::ActiveHook Type”.

Signature.  

int setActiveHook
    (
      ActiveHook*  activeHook,
      void*        arg
    )

Parameters.  This method requires two parameters:

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

2.3.9.2.5. NdbBlob::getVersion()

Description.  This method is used to distinguish whether a blob operation is statement-based or event-based.

Signature.  

void getVersion
    (
      int& version
    )

Parameters.  This method takes a single parameter, an integer reference to the blob version (operation type).

Return value.  One of the following three values:

  • -1: This is a “normal” (statement-based) blob.

  • 0: This is an event-operation based blob, following a change in its data.

  • 1: This is an event-operation based blob, prior to any change in its data.

Note

getVersion() is always successful, assuming that it is invoked as a method of a valid NdbBlob instance.

2.3.9.2.6. NdbBlob::getNull()

Description.  This method checks whether the blob's value is NULL.

Signature.  

int getNull
    (
      int& isNull
    )

Parameters.  A reference to an integer isNull. Following invocation, this parameter has one of the following values, interpreted as shown here:

  • -1: The blob is undefined. If this is a nonevent blob, this result causes a state error.

  • 0: The blob has a nonnull value.

  • 1: The blob's value is NULL.

Return value.  None.

2.3.9.2.7. NdbBlob::setNull()

Description.  This method sets the value of a blob to NULL.

Signature.  

int setNull
    (
      void
    )

Parameters.  None.

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

2.3.9.2.8. NdbBlob::getLength()

Description.  This method gets the blob's current length in bytes.

Signature.  

int getLength
    (
      Uint64& length
    )

Parameters.  A reference to the length.

Return value.  The blob's length in bytes. For a NULL blob, this method returns 0. to distinguish between a blob whose length is 0 blob and one which is NULL, use the getNull() method.

2.3.9.2.9. NdbBlob::truncate()

Description.  This method is used to truncate a blob to a given length.

Signature.  

int truncate
    (
      Uint64 length = 0
    )

Parameters.  truncate() takes a single parameter which specifies the new length to which the blob is to be truncated. This method has no effect if length is greater than the blob's current length (which you can check using getLength()).

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

2.3.9.2.10. NdbBlob::getPos()

Description.  This method gets the current read/write position in a blob.

Signature.  

int getPos
    (
      Uint64& pos
    )

Parameters.  One parameter, a reference to the position.

Return value.  Returns 0 on success, or -1 on failure. (Following a successful invocation, pos will hold the current read/write position within the blob, as a number of bytes from the beginning.)

2.3.9.2.11. NdbBlob::setPos()

Description.  This method sets the position within the blob at which to read or write data.

Signature.  

int setPos
    (
      Uint64 pos
    )

Parameters.  The setPos() method takes a single parameter pos (an unsigned 64-bit integer), which is the position for reading or writing data. The value of pos must be between 0 and the blob's current length.

Important

“Sparse” blobs are not supported in the NDB API; there can be no unused data positions within a blob.

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

2.3.9.2.12. NdbBlob::readData()

Description.  This method is used to read data from a blob.

Signature.  

int readData
    (
      void*     data,
      Uint32&  bytes
    )

Parameters.  readData() accepts a pointer to the data to be read, and a reference to the number of bytes read.

Return value.  0 on success, -1 on failure. Following a successful invocation, data points to the data that was read, and bytes holds the number of bytes read.

2.3.9.2.13. NdbBlob::writeData()

Description.  This method is used to write data to an NdbBlob. After a successful invocation, the read/write position will be at the first byte following the data that was written to the blob.

Note

A write past the current end of the blob data extends the blob automatically.

Signature.  

int writeData
    (
      const void*  data,
      Uint32       bytes
    )

Parameters.  This method takes two parameters, a pointer to the data to be written, and the number of bytes to write.

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

2.3.9.2.14. NdbBlob::getColumn()

Description.  Use this method to get the BLOB column to which the NdbBlob belongs.

Signature.  

const Column* getColumn
    (
      void
    )

Parameters.  None.

Return value.  A Column object. (See Section 2.3.1, “The Column Class”.)

2.3.9.2.15. NdbBlob::getNdbError()

Description.  Use this method to obtain an error object. The error may be blob-specific or may be copied from a failed implicit operation. The error code is copied back to the operation unless the operation already has a nonzero error code.

Signature.  

const NdbError& getNdbError
    (
      void
    ) const

Parameters.  None.

Return value.  An NdbError object. See Section 2.3.31, “The NdbError Structure”.

2.3.9.2.16. NdbBlob::blobsFirstBlob()

Description.  This method initialises a list of blobs belonging to the current operation and returns the first blob in the list.

Signature.  

NdbBlob* blobsFirstBlob
    (
      void
    )

Parameters.  None.

Return value.  A pointer to the desired blob.

2.3.9.2.17. NdbBlob::blobsNextBlob()

Description.  Use the method to obtain the next in a list of blobs that was initialised using blobsFirstBlob(). See Section 2.3.9.2.16, “NdbBlob::blobsFirstBlob()”.

Signature.  

NdbBlob* blobsNextBlob
    (
      void
    )

Parameters.  None.

Return value.  A pointer to the desired blob.

2.3.9.2.18. NdbBlob::getBlobEventName()

Description.  This method gets a blob event name. The blob event is created if the main event monitors the blob column. The name includes the main event name.

Signature.  

static int getBlobEventName
    (
      char*       name,
      Ndb*        ndb,
      const char* event,
      const char* column
    )

Parameters.  This method takes 4 parameters:

  • name: The name of the blob event.

  • ndb: The relevant Ndb object.

  • event: The name of the main event.

  • column: The blob column.

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

2.3.9.2.19. NdbBlob::getBlobTableName()

Description.  This method gets the blob data segment table name.

Note

This method is generally of use only for testing and debugging purposes.

Signature.  

static int getBlobTableName
    (
      char*       name,
      Ndb*        ndb,
      const char* table,
      const char* column
    )

Parameters.  This method takes 4 parameters:

  • name: The name of the blob data segment table.

  • ndb: The relevant Ndb object.

  • table: The name of the main table.

  • column: The blob column.

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

2.3.9.2.20. NdbBlob::getNdbOperation()

Description.  This method can be used to find the operation with which the handle for this NdbBlob is associated.

NdbBlob::getNdbOperation() is available beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19.

Signature.  

const NdbOperation* getNdbOperation
    (
      void
    ) const

Parameters.  None.

Return value.  A pointer to an operation.

Important

The operation referenced by the pointer retruned by this method may be represented by either an NdbOperation or NdbScanOperation object.

See Section 2.3.15, “The NdbOperation Class”, and Section 2.3.18, “The NdbScanOperation Class”, for more information.