3.2.1 Log Event Functions

This section provides information about MGM API functions used for listening to log events.

ndb_mgm_listen_event()

Description

This function is used to listen to log events, which are read from the return file descriptor. Events use a text-based format, the same as in the cluster log.

Signature
int ndb_mgm_listen_event
    (
      NdbMgmHandle handle,
      const int    filter[]
    )
Parameters

This function takes two arguments:

  • An NdbMgmHandle handle.

  • A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a file descriptor. Use 0 for the level to terminate the list.

Return value

The file descriptor from which events are to be read.

ndb_mgm_create_logevent_handle()

Description

This function is used to create a log event handle.

Signature
NdbLogEventHandle ndb_mgm_create_logevent_handle
    (
      NdbMgmHandle handle,
      const int    filter[]
    )
Parameters

This function takes two arguments:

  • An NdbMgmHandle handle.

  • A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a file descriptor. Use 0 for the level to terminate the list.

Return value

A log event handle.

ndb_mgm_destroy_logevent_handle()

Description

Use this function to destroy a log event handle when there is no further need for it.

Signature
void ndb_mgm_destroy_logevent_handle
    (
      NdbLogEventHandle* handle
    )
Parameters

A pointer to a log event handle.

Return value

None.

ndb_logevent_get_fd()

Description

This function retrieves a file descriptor from an NdbMgmLogEventHandle; this descriptor can be used in (for example) an application select() call.

Warning

Do not attempt to read from the file descriptor returned by this function; this can cause the descriptor to become corrupted.

Signature
int ndb_logevent_get_fd
    (
      const NdbLogEventHandle handle
    )
Parameters

A LogEventHandle.

Return value

A file descriptor. In the event of failure, -1 is returned.

ndb_logevent_get_next()

Description

This function is used to retrieve the next log event, using data from the event to fill in the supplied ndb_logevent structure.

Signature
int ndb_logevent_get_next
    (
      const NdbLogEventHandle handle,
      struct ndb_logevent*    logevent,
      unsigned                timeout
    )
Important

Prior to NDB 7.3.2, the log event's ndb_mgm_event_category was cast to an enum type. This behavior, although incorrect, interfered with existing applications and was reinstated in NDB 7.3.7; a new function exhibiting the corrected behavior ndb_logevent_get_next2() was added in these releases.

Parameters

Three parameters are expected by this function:

  • An NdbLogEventHandle

  • A pointer to an ndb_logevent data structure

  • The number of milliseconds to wait for the event before timing out; passing 0 for this parameter causes the function to block until the next log event is received

Return value

The value returned by this function is interpreted as follows: If the return value is less than or equal to zero, then the logevent is not altered or affected in any way.

  • > 0: The event exists, and it data was retrieved into the logevent

  • 0: A timeout occurred while waiting for the event (more than timeout milliseconds elapsed)

  • < 0: An error occurred.

ndb_logevent_get_next2()

Description

This function is used to retrieve the next log event, using data from the event to fill in the supplied ndb_logevent structure.

ndb_logevent_get_next2() was added in NDB 7.3.7. It is intended to serve as a replacement for ndb_logevent_get_next() which corrects that function's handling of the structure's ndb_mgm_event_category, for applications which do not require backward compatibility. It is otherwise identical to ndb_logevent_get_next().

Signature
int ndb_logevent_get_next2
    (
      const NdbLogEventHandle handle,
      struct ndb_logevent*    logevent,
      unsigned                timeout
    )
Parameters

Three parameters are expected by this function:

  • An NdbLogEventHandle

  • A pointer to an ndb_logevent data structure

  • The number of milliseconds to wait for the event before timing out; passing 0 for this parameter causes the function to block until the next log event is received

Return value

The value returned by this function is interpreted as follows: If the return value is less than or equal to zero, then the logevent is not altered or affected in any way.

  • > 0: The event exists, and it data was retrieved into the logevent

  • 0: A timeout occurred while waiting for the event (more than timeout milliseconds elapsed)

  • < 0: An error occurred.

ndb_logevent_get_latest_error()

Description

This function retrieves the error code from the most recent error.

Note

You may prefer to use ndb_logevent_get_latest_error_msg() instead. See ndb_logevent_get_latest_error_msg()

Signature
int ndb_logevent_get_latest_error
    (
      const NdbLogEventHandle handle
    )
Parameters

A log event handle.

Return value

An error code.

ndb_logevent_get_latest_error_msg()

Description

Retrieves the text of the most recent error obtained while trying to read log events.

Signature
const char* ndb_logevent_get_latest_error_msg
    (
      const NdbLogEventHandle handle
    )
Parameters

A log event handle.

Return value

The text of the error message.