2.3.6.2 Event Methods

2.3.6.2.1 Event Constructor
2.3.6.2.2 Event::addEventColumn()
2.3.6.2.3 Event::addEventColumns()
2.3.6.2.4 Event::addTableEvent()
2.3.6.2.5 Event::getDurability()
2.3.6.2.6 Event::getEventColumn()
2.3.6.2.7 Event::getName()
2.3.6.2.8 Event::getNoOfEventColumns()
2.3.6.2.9 Event::getObjectStatus()
2.3.6.2.10 Event::getObjectVersion()
2.3.6.2.11 Event::getObjectId()
2.3.6.2.12 Event::getReport()
2.3.6.2.13 Event::getTable()
2.3.6.2.14 Event::getTableEvent()
2.3.6.2.15 Event::getTableName()
2.3.6.2.16 Event::mergeEvents()
2.3.6.2.17 Event::setDurability()
2.3.6.2.18 Event::setReport()
2.3.6.2.19 Event::setName()
2.3.6.2.20 Event::setTable()

This section contains descriptions of the public methods defined by the Event class.

2.3.6.2.1 Event Constructor

Description.  The Event constructor creates a new instance with a given name, and optionally associated with a table.

You should keep in mind that the NDB API does not track allocated event objects, which means that the user must explicitly delete the Event thus created after it is no longer in use.

Signatures.  It is possible to invoke this method in either of two ways, the first of these being by name only, as shown here:

Event
    (
      const char* name
    )

Alternatively, you can use the event name and an associated table, like this:

Event
    (
      const char*                  name,
      const NdbDictionary::Table& table
    )

Parameters.  At a minimum, a name (as a constant character pointer) for the event is required. Optionally, an event may also be associated with a table; this argument, when present, is a reference to a Table object (see Section 2.3.36, “The Table Class”).

Return value.  A new instance of Event.

Destructor.  A destructor for this class is supplied as a virtual method which takes no arguments and whose return type is void.

2.3.6.2.2 Event::addEventColumn()

Description.  This method is used to add a column on which events should be detected. The column may be indicated either by its ID or its name.

Important

You must invoke Dictionary::createEvent() before any errors will be detected. See Section 2.3.4.1.4, “Dictionary::createEvent().

Note

If you know several columns by name, you can enable event detection on all of them at one time by using addEventColumns(). See Section 2.3.6.2.3, “Event::addEventColumns().

Signature.  Identifying the event using its column ID:

void addEventColumn
    (
      unsigned attrId
    )

Identifying the column by name:

void addEventColumn
    (
      const char* columnName
    )

Parameters.  This method takes a single argument, which may be either one of the following:

  • The column ID (attrId), which should be an integer greater than or equal to 0, and less than the value returned by getNoOfEventColumns().

  • The column's name (as a constant character pointer).

Return value.  None.

2.3.6.2.3 Event::addEventColumns()

Description.  This method is used to enable event detection on several columns at the same time. You must use the names of the columns.

Important

As with addEventColumn(), you must invoke Dictionary::createEvent() before any errors will be detected. See Section 2.3.4.1.4, “Dictionary::createEvent().

Signature. 

void addEventColumns
    (
      int          n,
      const char** columnNames
    )

Parameters.  This method requires two arguments, listed here:

  • The number of columns n (an integer).

  • The names of the columns columnNames—this must be passed as a pointer to a character pointer.

Return value.  None.

2.3.6.2.4 Event::addTableEvent()

Description.  This method is used to add types of events that should be detected.

Signature. 

void addTableEvent
    (
      const TableEvent te
    )

Parameters.  This method requires a TableEvent value.

Return value.  None.

2.3.6.2.5 Event::getDurability()

Description.  This method gets the event's lifetime and scope (that is, its EventDurability).

Signature. 

EventDurability getDurability
    (
      void
    ) const

Parameters.  None.

Return value.  An EventDurability value.

2.3.6.2.6 Event::getEventColumn()

Description.  This method is used to obtain a specific column from among those on which an event is defined.

Signature. 

const Column* getEventColumn
    (
      unsigned no
    ) const

Parameters.  The number (no) of the column, as obtained using getNoOfColumns() (see Section 2.3.6.2.8, “Event::getNoOfEventColumns()).

Return value.  A pointer to the Column corresponding to no.

2.3.6.2.7 Event::getName()

Description.  This method obtains the name of the event.

Signature. 

const char* getName
    (
      void
    ) const

Parameters.  None.

Return value.  The name of the event, as a character pointer.

2.3.6.2.8 Event::getNoOfEventColumns()

Description.  This method obtains the number of columns on which an event is defined.

Signature. 

int getNoOfEventColumns
    (
      void
    ) const

Parameters.  None.

Return value.  The number of columns (as an integer), or -1 in the case of an error.

2.3.6.2.9 Event::getObjectStatus()

Description.  This method gets the object status of the event.

Signature. 

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters.  None.

Return value.  The object status of the event. For possible values, see Section 2.3.30.1.3, “The Object::Status Type”.

2.3.6.2.10 Event::getObjectVersion()

Description.  This method gets the event's object version (see Section 8.6, “NDB Schema Object Versions”).

Signature. 

virtual int getObjectVersion
    (
      void
    ) const

Parameters.  None.

Return value.  The object version of the event, as an integer.

2.3.6.2.11 Event::getObjectId()

Description.  This method retrieves an event's object ID.

Signature. 

virtual int getObjectId
    (
      void
    ) const

Parameters.  None.

Return value.  The object ID of the event, as an integer.

2.3.6.2.12 Event::getReport()

Description.  This method is used to obtain the reporting option in force for this event.

Signature. 

EventReport getReport
    (
      void
    ) const

Parameters.  None.

Return value.  One of the reporting options specified in Section 2.3.6.1.3, “The Event::EventReport Type”.

2.3.6.2.13 Event::getTable()

Description.  This method is used to find the table with which an event is associated. It returns a reference to the corresponding Table object. You may also obtain the name of the table directly using getTableName().

Signature. 

const NdbDictionary::Table* getTable
    (
      void
    ) const

Parameters.  None.

Return value.  The table with which the event is associated—if there is one—as a pointer to a Table object; otherwise, this method returns NULL. (See Section 2.3.36, “The Table Class”.)

2.3.6.2.14 Event::getTableEvent()

Description.  This method is used to check whether a given table event will be detected.

Signature. 

bool getTableEvent
    (
      const TableEvent te
    ) const

Parameters.  This method takes a single parameter, the table event's type—that is, a TableEvent value.

Return value.  This method returns true if events of TableEvent type te will be detected. Otherwise, the return value is false.

2.3.6.2.15 Event::getTableName()

Description.  This method obtains the name of the table with which an event is associated, and can serve as a convenient alternative to getTable(). (See Section 2.3.6.2.13, “Event::getTable().)

Signature. 

const char* getTableName
    (
      void
    ) const

Parameters.  None.

Return value.  The name of the table associated with this event, as a character pointer.

2.3.6.2.16 Event::mergeEvents()

Description.  This method is used to set the merge events flag, which is false by default. Setting it to true implies that events are merged as follows:

  • For a given NdbEventOperation associated with this event, events on the same primary key within the same global checkpoint index (GCI) are merged into a single event.

  • A blob table event is created for each blob attribute, and blob events are handled as part of main table events.

  • Blob post/pre data from blob part events can be read via NdbBlob methods as a single value.

Note

Currently this flag is not inherited by NdbEventOperation, and must be set on NdbEventOperation explicitly. See Section 2.3.20, “The NdbEventOperation Class”.

Signature. 

void mergeEvents
    (
      bool flag
    )

Parameters.  A Boolean flag value.

Return value.  None.

2.3.6.2.17 Event::setDurability()

Description.  This method sets an event's durability—that is, its lifetime and scope.

Signature. 

void setDurability(EventDurability ed)

Parameters.  This method requires a single EventDurability value as a parameter.

Return value.  None.

2.3.6.2.18 Event::setReport()

Description.  This method is used to set a reporting option for an event. Possible option values may be found in Section 2.3.6.1.3, “The Event::EventReport Type”.

Reporting of DDL events.  Prior to MySQL Cluster NDB 6.3.34, 7.0.15, and 7.1.4, it was not necessary to set a specific reporting option in order to receive DDL events from alter table and drop table events. Beginning with MySQL Cluster NDB 6.3.34, 7.0.15, and 7.1.4, this is no longer the case; in these and later versions, you must call setReport() using the new EventReport value ER_DDL (added in the same MySQL Cluster versions).

For example, to enable DDL event reporting in MySQL Cluster NDB 6.3.34, 7.0.15, and 7.1.4, and later on an Event object named myEvent, you must invoke this method as shown here:

myEvent.setReport(NdbDictionary::Event::ER_DDL);
Important

When upgrading to MySQL Cluster NDB 6.3.34, 7.0.15, or 7.1.4 from a version that supports automatic reporting of DDL events where you wish to retain this behavior, you must add the indicated setReport() call or calls, then recompile, following the upgrade. If you merely replace the old version of the libndbclient library with the library included with the new MySQL Cluster version, DDL events are no longer reported by default.

Signature. 

void setReport
    (
      EventReport er
    )

Parameters.  An EventReport option value.

Return value.  None.

2.3.6.2.19 Event::setName()

Description.  This method is used to set the name of an event. The name must be unique among all events visible from the current application (see Section 2.3.6.2.5, “Event::getDurability()).

Note

You can also set the event's name when first creating it. See Section 2.3.6.2.1, “Event Constructor”.

Signature. 

void setName
    (
      const char* name
    )

Parameters.  The name to be given to the event (as a constant character pointer).

Return value.  None.

2.3.6.2.20 Event::setTable()

Description.  This method defines a table on which events are to be detected.

Note

By default, event detection takes place on all columns in the table. Use addEventColumn() to override this behavior. For details, see Section 2.3.6.2.2, “Event::addEventColumn().

Signature. 

void setTable
    (
      const NdbDictionary::Table& table
    )

MySQL Cluster NDB 7.0.40, MySQL Cluster NDB 7.1.29, MySQL Cluster NDB 7.2.14, MySQL Cluster NDB 7.3.3, and later MySQL Cluster releases support the use of a pointer with this method, as shown here:

void setTable
    (
      const NdbDictionary::Table*; table
    )

When so used, this version of setTable() returns -1 if the table pointer is NULL. (Bug #16329082)

Parameters.  This method requires a single parameter, a reference to the table (see Section 2.3.36, “The Table Class”) on which events are to be detected. MySQL Cluster NDB 7.0.40, MySQL Cluster NDB 7.1.29, MySQL Cluster NDB 7.2.14, MySQL Cluster NDB 7.3.3, and later: A reference or a pointer to the table can be used.

Return value.  None. MySQL Cluster NDB 7.0.40, MySQL Cluster NDB 7.1.29, MySQL Cluster NDB 7.2.14, MySQL Cluster NDB 7.3.3, and later: -1, if a null table pointer is used.