2.3.16 The NdbEventOperation Class

This section provides information about the NdbEventOperation class, which is used to monitor changes (events) in a database. It provides the core functionality used to implement NDB Cluster Replication.

• NdbEventOperation Class Overview

• NdbEventOperation::clearError() (DEPRECATED)

• NdbEventOperation::execute()

• NdbEventOperation::getBlobHandle()

• NdbEventOperation::getEpoch()

• NdbEventOperation::getEventType() (DEPRECATED)

• NdbEventOperation::getEventType2()

• NdbEventOperation::getGCI() (DEPRECATED)

• NdbEventOperation::getLatestGCI() (DEPRECATED)

• NdbEventOperation::getNdbError()

• NdbEventOperation::getPreBlobHandle()

• NdbEventOperation::getPreValue()

• NdbEventOperation::getState()

• NdbEventOperation::getValue()

• NdbEventOperation::hasError() (DEPRECATED)

• NdbEventOperation::isConsistent() (DEPRECATED)

• NdbEventOperation::isEmptyEpoch()

• NdbEventOperation::isErrorEpoch()

• NdbEventOperation::isOverrun()

• NdbEventOperation::mergeEvents()

• NdbEventOperation::State

• NdbEventOperation::tableFragmentationChanged()

• NdbEventOperation::tableFrmChanged()

• NdbEventOperation::tableNameChanged()

• NdbEventOperation::tableRangeListChanged()

NdbEventOperation Class Overview

Parent class

None

Child classes

None

Description

NdbEventOperation represents a database event.

Methods

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

Table 2.42 NdbEventOperation class methods and descriptions

Name	Description
clearError()	Clears the most recent error. Deprecated in NDB 7.4.
execute()	Activates the NdbEventOperation
getBlobHandle()	Gets a handle for reading blob attributes
getEpoch()	Retrieves the epoch for the event data most recently retrieved. Added in NDB 7.4.
getEventType()	Gets the event type. Deprecated in NDB 7.4.
getEventType2()	Gets the event type. Added in NDB 7.4.
getGCI()	Retrieves the GCI of the most recently retrieved event. Deprecated in NDB 7.4.
getLatestGCI()	Retrieves the most recent GCI (whether or not the corresponding event has been retrieved). Deprecated in NDB 7.4.
getNdbError()	Gets the most recent error
getPreBlobHandle()	Gets a handle for reading the previous blob attribute
getPreValue()	Retrieves an attribute's previous value
getState()	Gets the current state of the event operation
getValue()	Retrieves an attribute value
hasError()	Whether an error has occurred as part of this operation. Deprecated in NDB 7.4.
isConsistent()	Detects event loss caused by node failure. Deprecated in NDB 7.4.
isEmptyEpoch()	Detects an empty epoch. Added in NDB 7.4.
isErrorEpoch()	Detects an error epoch, and retrieves the error if there is one. Added in NDB 7.4.
isOverrun()	Whether event loss has taken place due to a buffer overrun. Deprecated in NDB 7.4.
mergeEvents()	Makes it possible for events to be merged
tableFragmentationChanged()	Checks to see whether the fragmentation for a table has changed
tableFrmChanged()	Checks to see whether a table .FRM file has changed
tableNameChanged()	Checks to see whether the name of a table has changed
tableRangeListChanged()	Checks to see whether a table range partition list name has changed

Types

NdbEventOperation defines one enumerated type, the State type.

Creating an Instance of NdbEventOperation.  This class has no public constructor or destructor. Instead, instances of NdbEventOperation are created as the result of method calls on Ndb and NdbDictionary objects, subject to the following conditions:

1. There must exist an event which was created using Dictionary::createEvent(). This method returns an instance of the Event class.

2. An NdbEventOperation object is instantiated using Ndb::createEventOperation(), which acts on an instance of Event.

An instance of this class is removed by invoking Ndb::dropEventOperation.

Tip

A detailed example demonstrating creation and removal of event operations is provided in Section 2.5.9, “NDB API Event Handling Example”.

Known Issues.  The following issues may be encountered when working with event operations in the NDB API:

• The maximum number of active NdbEventOperation objects is currently fixed at compile time at 2 * MaxNoOfTables.

• Currently, all INSERT, DELETE, and UPDATE events—as well as all attribute changes—are sent to the API, even if only some attributes have been specified. However, these are hidden from the user and only relevant data is shown after calling Ndb::nextEvent().

  Note that false exits from Ndb::pollEvents() may occur, and thus the following nextEvent() call returns zero, since there was no available data. In such cases, simply call pollEvents() again.

  See Ndb::pollEvents(), and Ndb::nextEvent() (DEPRECATED).

• Event code does not check the table schema version. When a table is dropped, make sure that you drop any associated events.

• If you have received a complete epoch, events from this epoch are not re-sent, even in the event of a node failure. However, if a node failure has occurred, subsequent epochs may contain duplicate events, which can be identified by duplicated primary keys.

  In the NDB Cluster replication code, duplicate primary keys on INSERT operations are normally handled by treating such inserts as REPLACE operations.

Tip

To view the contents of the system table containing created events, you can use the ndb_select_all utility as shown here:

ndb_select_all -d sys 'NDB$EVENTS_0'

NdbEventOperation::clearError() (DEPRECATED)

Description

Clears the error most recently associated with this event operation.

This method is deprecated, and is subject to removal in a future release. Beginning with NDB 8.4.0, it does nothing.

Signature

void clearError
    (
      void
    )

Parameters

None.

Return value

None.

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().

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

Signature

int execute
    (
      void
    )

Parameters

None.

Return value

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

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.

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.

NdbEventOperation::getEpoch()

Description

Gets the epoch for the latest event data retrieved.

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

Signature

Uint64 getEpoch
  (
    void
  ) const

Parameters

None.

Return value

An epoch number (an integer).

NdbEventOperation::getEventType() (DEPRECATED)

Description

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

This method is deprecated in NDB 7.4, and is subject to removal in a future release. In NDB 7.4 and later, use getEventType2() instead.

Signature

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

Parameters

None.

Return value

A TableEvent value.

NdbEventOperation::getEventType2()

Description

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

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

Signature

getEventType2
    (
      void
    ) const

Parameters

None.

Return value

A TableEvent value.

NdbEventOperation::getGCI() (DEPRECATED)

Description

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

This method is deprecated in NDB 7.4, and is subject to removal in a future release. In NDB 7.4 and later, use getEpoch() instead.

Signature

Uint64 getGCI
    (
      void
    ) const

Parameters

None.

Return value

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

NdbEventOperation::getLatestGCI() (DEPRECATED)

Description

This method retrieves the most recent GCI.

This method returns the latest epoch number.

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

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

Signature

Uint64 getLatestGCI
    (
      void
    ) const

Parameters

None.

Return value

The index of the latest global checkpoint, an integer.

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.

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 NdbEventOperation::getBlobHandle().

Signature

NdbBlob* getPreBlobHandle
  (
    const char* name
  )

Parameters

The name of the blob attribute.

Return value

A pointer to an NdbBlob.

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.

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.

NdbEventOperation::getState()

Description

This method gets the event operation's current state.

Signature

State getState
    (
      void
    )

Parameters

None.

Return value

A State value.

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.

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.

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.

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.

NdbEventOperation::hasError() (DEPRECATED)

Description

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

This method is deprecated, and is subject to removal in a future release. In NDB 8.4 and later, it returns a constant. Use getEventType2() to determine the event type instead. See Event::TableEvent.

Signature

int hasError
    (
      void
    ) const

Parameters

None.

Return value

NDB 8.3 and earlier: If event loss has taken place, then this method returns 0; otherwise, it returns 1.

NDB 8.4 and later: Always returns 0.

NdbEventOperation::isConsistent() (DEPRECATED)

Description

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

This method is deprecated in NDB 7.4, and is subject to removal in a future release. In NDB 7.4 and later, use getEventType2() to determine whether the event is of type TE_INCONSISTENT. See Event::TableEvent.

Signature

bool isConsistent
    (
      void
    ) const

Parameters

None.

Return value

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

NdbEventOperation::isEmptyEpoch()

Description

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

This method was added in NDB 7.4.

Signature

bool isEmptyEpoch
    (
      void
    )

Parameters

None.

Return value

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

NdbEventOperation::isErrorEpoch()

Description

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

This method was added in NDB 7.4.

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.

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.

NdbEventOperation::mergeEvents()

Description

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

The merge events flag is false by default.

Signature

void mergeEvents
    (
      bool flag
    )

Parameters

A Boolean flag.

Return value

None.

NdbEventOperation::State

This section provides information about the State data type.

Description

This type describes the event operation's state.

A State value is returned by the getState() method.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.43 NdbEventOperation data type values and descriptions

Name	Description
EO_CREATED	The event operation has been created, but execute() has not yet been called.
EO_EXECUTING	The execute() method has been invoked for this event operation.
EO_DROPPED	The event operation is waiting to be deleted, and is no longer usable.
EO_ERROR	An error has occurred, and the event operation is unusable.

NdbEventOperation::tableFragmentationChanged()

Description

This method is used to test whether a table's fragmentation has changed in connection with a TE_ALTER event. (See Event::TableEvent.)

Signature

bool tableFragmentationChanged
    (
      void
    ) const

Parameters

None.

Return value

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

NdbEventOperation::tableFrmChanged()

Description

Use this method to determine whether a table .FRM file has changed in connection with a TE_ALTER event. (See Event::TableEvent.)

Signature

bool tableFrmChanged
    (
      void
    ) const

Parameters

None.

Return value

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

NdbEventOperation::tableNameChanged()

Description

This method tests whether a table name has changed as the result of a TE_ALTER table event. (See Event::TableEvent.)

Signature

bool tableNameChanged
    (
      void
    ) const

Parameters

None.

Return value

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

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

Parameters

None.

Return value

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