3.2.1 Log Event Functions

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

• ndb_mgm_listen_event()

• ndb_mgm_create_logevent_handle()

• ndb_mgm_destroy_logevent_handle()

• ndb_logevent_get_fd()

• ndb_logevent_get_next()

• ndb_logevent_get_next2()

• ndb_logevent_get_latest_error()

• ndb_logevent_get_latest_error_msg()

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.

ndb_mgm_listen_event() does not support TLS. You can use ndb_mgm_create_logevent_handle(), which does.

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

The log event's ndb_mgm_event_category is cast to an enum type. For an equivalent function that does not perform this cast, use ndb_logevent_get_next2() instead.

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() corrects the ndb_logevent_get_next() 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.