2.3.21.2 NdbEventOperation Methods

2.3.21.2.1 NdbEventOperation::clearError()
2.3.21.2.2 NdbEventOperation::execute()
2.3.21.2.3 NdbEventOperation::getBlobHandle()
2.3.21.2.4 NdbEventOperation::getEpoch()
2.3.21.2.5 NdbEventOperation::getEventType()
2.3.21.2.6 NdbEventOperation::getEventType2()
2.3.21.2.7 NdbEventOperation::getGCI()
2.3.21.2.8 NdbEventOperation::getLatestGCI()
2.3.21.2.9 NdbEventOperation::getNdbError()
2.3.21.2.10 NdbEventOperation::getPreBlobHandle()
2.3.21.2.11 NdbEventOperation::getPreValue()
2.3.21.2.12 NdbEventOperation::getState()
2.3.21.2.13 NdbEventOperation::getValue()
2.3.21.2.14 NdbEventOperation::hasError()
2.3.21.2.15 NdbEventOperation::isConsistent()
2.3.21.2.16 NdbEventOperation::isEmptyEpoch()
2.3.21.2.17 NdbEventOperation::isErrorEpoch()
2.3.21.2.18 NdbEventOperation::isOverrun()
2.3.21.2.19 NdbEventOperation::mergeEvents()
2.3.21.2.20 NdbEventOperation::tableFragmentationChanged()
2.3.21.2.21 NdbEventOperation::tableFrmChanged()
2.3.21.2.22 NdbEventOperation::tableNameChanged()
2.3.21.2.23 NdbEventOperation::tableRangeListChanged()

Abstract

This section contains definitions and descriptions of the public methods of the NdbEventOperation class.

2.3.21.2.1 NdbEventOperation::clearError()

Description.  Clears the error most recently associated with this event operation.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release.

Signature. 

void clearError
    (
      void
    )

Parameters.  None.

Return value.  None.

2.3.21.2.2 NdbEventOperation::execute()

Description.  Activates the NdbEventOperation, so that it can begin receiving events. Changed attribute values may be retrieved after Ndb::nextEvent() has returned a value other than NULL.

One of getValue(), getPreValue(), getBlobValue(), or getPreBlobValue() must be called before invoking execute().

Important

Before attempting to use this method, you should have read the explanations provided in Section 2.3.16.1.23, “Ndb::nextEvent()”, and Section 2.3.21.2.13, “NdbEventOperation::getValue()”. Also see Section 2.3.21, “The NdbEventOperation Class”.

Signature. 

int execute
    (
      void
    )

Parameters.  None.

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

2.3.21.2.3 NdbEventOperation::getBlobHandle()

Description.  This method is used in place of getValue() for blob attributes. The blob handle (NdbBlob) returned by this method supports read operations only.

Note

To obtain the previous value for a blob attribute, use getPreBlobHandle().

Signature. 

NdbBlob* getBlobHandle
    (
      const char* name
    )

Parameters.  The name of the blob attribute.

Return value.  A pointer to an NdbBlob object.

2.3.21.2.4 NdbEventOperation::getEpoch()

Description.  Gets the epoch for the latest event data retrieved.

Added in MySQL Cluster NDB 7.4.3, this method supersedes getGCI(), which is now deprecated and subject to removal in a future MySQL Cluster release.

Signature. 

Uint64 getEpoch
  (
    void
  ) const

Parameters.  None.

Return value.  An epoch number (an integer).

2.3.21.2.5 NdbEventOperation::getEventType()

Description.  This method is used to obtain the event's type (TableEvent).

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release. In MySQL Cluster NDB 7.4.3 and later, you should use getEventType2() instead.

Signature. 

NdbDictionary::Event::TableEvent getEventType
    (
      void
    ) const

Parameters.  None.

Return value.  A TableEvent value.

2.3.21.2.6 NdbEventOperation::getEventType2()

Description.  This method is used to obtain the event's type (TableEvent).

Added in MySQL Cluster NDB 7.4.3, this method supersedes getEventType(), which is now deprecated and subject to removal in a future MySQL Cluster release.

Signature. 

NdbDictionary::Event::TableEvent getEventType2
    (
      void
    ) const

Parameters.  None.

Return value.  A TableEvent value.

2.3.21.2.7 NdbEventOperation::getGCI()

Description.  This method retrieves the GCI for the most recently retrieved event.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release. In MySQL Cluster NDB 7.4.3 and later, you should use getEpoch() instead.

Signature. 

Uint64 getGCI
    (
      void
    ) const

Parameters.  None.

Return value.  The global checkpoint index of the most recently retrieved event (an integer).

2.3.21.2.8 NdbEventOperation::getLatestGCI()

Description.  This method retrieves the most recent GCI.

Beginning with MySQL Cluster NDB 6.2.5, this method actually returns the latest epoch number, and all references to GCIs in the documentation for this method when using this or a later MySQL Cluster NDB version should be taken to mean epoch numbers instead. This is a consequence of the implementation for micro-CGPs.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release. In MySQL Cluster NDB 7.4.3 and later, you should use Ndb::getHighestQueuedEpoch() instead.

Note

The GCI obtained using this method is not necessarily associated with an event.

Signature. 

Uint64 getLatestGCI
    (
      void
    ) const

Parameters.  None.

Return value.  The index of the latest global checkpoint, an integer.

2.3.21.2.9 NdbEventOperation::getNdbError()

Description.  This method retrieves the most recent error.

Signature. 

const struct NdbError& getNdbError
    (
      void
    ) const

Parameters.  None.

Return value.  A reference to an NdbError structure.

2.3.21.2.10 NdbEventOperation::getPreBlobHandle()

Description.  This function is the same as getBlobHandle(), except that it is used to access the previous value of the blob attribute. See Section 2.3.21.2.3, “NdbEventOperation::getBlobHandle()”.

Signature. 

NdbBlob* getPreBlobHandle
  (
    const char* name
  )

Parameters.  The name of the blob attribute.

Return value.  A pointer to an NdbBlob.

2.3.21.2.11 NdbEventOperation::getPreValue()

Description.  This method performs identically to getValue(), except that it is used to define a retrieval operation of an attribute's previous value rather than the current value. See Section 2.3.21.2.13, “NdbEventOperation::getValue()”, for details.

Signature. 

NdbRecAttr* getPreValue
    (
      const char* name,
      char*       value = 0
    )

Parameters.  This method takes the two parameters listed here:

  • The name of the attribute (as a constant character pointer).

  • A pointer to a value, such that:

    • If the attribute value is not NULL, then the attribute value is returned in this parameter.

    • If the attribute value is NULL, then the attribute value is stored only in the NdbRecAttr object returned by this method.

    See value Buffer Memory Allocation, for more information regarding this parameter.

Return value.  An NdbRecAttr object to hold the value of the attribute, or a NULL pointer indicating that an error has occurred.

2.3.21.2.12 NdbEventOperation::getState()

Description.  This method gets the event operation's current state.

Signature. 

State getState
    (
      void
    )

Parameters.  None.

Return value.  A State value. See Section 2.3.21.1, “The NdbEventOperation::State Type”.

2.3.21.2.13 NdbEventOperation::getValue()

Description.  This method defines the retrieval of an attribute value. The NDB API allocates memory for the NdbRecAttr object that is to hold the returned attribute value.

Important

This method does not fetch the attribute value from the database, and the NdbRecAttr object returned by this method is not readable or printable before calling the execute() method and Ndb::nextEvent() has returned a non-NULL value.

If a specific attribute has not changed, the corresponding NdbRecAttr will be in the state UNDEFINED. This can be checked by using NdbRecAttr::isNULL() which in such cases returns -1.

value Buffer Memory Allocation.  It is the application's responsibility to allocate sufficient memory for the value buffer (if not NULL), and this buffer must be aligned appropriately. The buffer is used directly (thus avoiding a copy penalty) only if it is aligned on a 4-byte boundary and the attribute size in bytes (calculated as NdbRecAttr::get_size_in_bytes()) is a multiple of 4.

Note

getValue() retrieves the current value. Use getPreValue() for retrieving the previous value.

Signature. 

NdbRecAttr* getValue
    (
      const char* name,
      char*       value = 0
    )

Parameters.  This method takes the two parameters listed here:

  • The name of the attribute (as a constant character pointer).

  • A pointer to a value, such that:

    • If the attribute value is not NULL, then the attribute value is returned in this parameter.

    • If the attribute value is NULL, then the attribute value is stored only in the NdbRecAttr object returned by this method.

    See value Buffer Memory Allocation, for more information regarding this parameter.

Return value.  An NdbRecAttr object to hold the value of the attribute, or a NULL pointer indicating that an error has occurred.

2.3.21.2.14 NdbEventOperation::hasError()

Description.  This method is used to determine whether there is an error associated with this event operation.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release. In MySQL Cluster NDB 7.4.3 and later, you should instead use getEventType2() to determine the event type. See Section 2.3.6.1.1, “The Event::TableEvent Type”.

Signature. 

int hasError
    (
      void
    ) const

Parameters.  None.

Return value.  If event loss has taken place, then this method returns 0; otherwise, it returns 1.

2.3.21.2.15 NdbEventOperation::isConsistent()

Description.  This method is used to determine whether event loss has taken place following the failure of a node.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is subject to removal in a future release. In MySQL Cluster NDB 7.4.3 and later, you should instead use getEventType2() to determine whether the event is of type TE_INCONSISTENT. See Section 2.3.6.1.1, “The Event::TableEvent Type”.

Signature. 

bool isConsistent
    (
      void
    ) const

Parameters.  None.

Return value.  If event loss has taken place, then this method returns false; otherwise, it returns true.

2.3.21.2.16 NdbEventOperation::isEmptyEpoch()

Description.  This method is used to determine whether consumed event data marks an empty epoch.

This method was added in MySQL Cluster NDB 7.4.3.

Signature. 

bool isEmptyEpoch
    (
      void
    )

Parameters.  None.

Return value.  If this epoch is empty, the method returns true; otherwise, it returns false.

2.3.21.2.17 NdbEventOperation::isErrorEpoch()

Description.  This method is used to determine whether consumed event data marks an empty epoch.

This method was added in MySQL Cluster NDB 7.4.3.

Signature. 

bool isErrorEpoch
  (
    NdbDictionary::Event::TableEvent* error_type = 0
  )

Parameters.  If this is an error epoch, error_type contains the TableEvent value corresponding to the error.

Return value.  If this epoch is in error, the method returns true; otherwise, it returns false.

2.3.21.2.18 NdbEventOperation::isOverrun()

Description.  This method is used to determine whether event loss has taken place due to a buffer overrun.

Signature. 

bool isOverrun
    (
      void
    ) const

Parameters.  None.

Return value.  If the event buffer has been overrun, then this method returns true, otherwise, it returns false.

2.3.21.2.19 NdbEventOperation::mergeEvents()

Description.  This method is used to set the merge events flag. For information about event merging, see Section 2.3.6.2.16, “Event::mergeEvents()”.

Note

The merge events flag is false by default.

Signature. 

void mergeEvents
    (
      bool flag
    )

Parameters.  A Boolean flag.

Return value.  None.

2.3.21.2.20 NdbEventOperation::tableFragmentationChanged()

Description.  This method is used to test whether a table's fragmentation has changed in connection with a TE_ALTER event. (See Section 2.3.6.1.1, “The Event::TableEvent Type”.)

Signature. 

bool tableFragmentationChanged
    (
      void
    ) const

Note

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

Parameters.  None.

Return value.  Returns true if the table's fragmentation has changed; otherwise, the method returns false.

2.3.21.2.21 NdbEventOperation::tableFrmChanged()

Description.  Use this method to determine whether a table .FRM file has changed in connection with a TE_ALTER event. (See Section 2.3.6.1.1, “The Event::TableEvent Type”.)

Signature. 

bool tableFrmChanged
    (
      void
    ) const

Note

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

Parameters.  None.

Return value.  Returns true if the table .FRM file has changed; otherwise, the method returns false.

2.3.21.2.22 NdbEventOperation::tableNameChanged()

Description.  This method tests whether a table name has changed as the result of a TE_ALTER table event. (See Section 2.3.6.1.1, “The Event::TableEvent Type”.)

Signature. 

bool tableNameChanged
    (
      void
    ) const

Note

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

Parameters.  None.

Return value.  Returns true if the name of the table has changed; otherwise, the method returns false.

2.3.21.2.23 NdbEventOperation::tableRangeListChanged()

Description.  Use this method to check whether a table range partition list name has changed in connection with a TE_ALTER event.

Signature. 

bool tableRangeListChanged
    (
      void
    ) const

Note

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

Parameters.  None.

Return value.  This method returns true if range or list partition name has changed; otherwise it returns false.