Data Change Notification

Data Structures
struct	db_event_t
	Data change notification event. More...
Functions
db_result_t	db_watch_table (db_t, const db_objname_t *, db_flags_t, uint32_t utid)
db_result_t	db_unwatch_table (db_t, const db_objname_t *)
db_result_t	db_wait (db_t, db_wtime_t, db_event_t *)
db_result_t	db_wait_ex (db_t, db_wtime_t, db_event_t *, db_row_t row, db_row_t aux_row)

---

Detailed Description

---

Function Documentation

db_result_t db_watch_table	(	db_t	hdb,
		const db_objname_t *	table_name,
		db_flags_t	flags,
		uint32_t	utid
	)

Set up a notification handler for a particular table.

Parameters:

hdb	Database handle.
table_name	Name of database table.
flags	Event types and scope, a bitwise combination of flags. The following flags control whether or not an event occurs: DB_WATCH_ROW_INSERTReceive notification when new rows are added to the table. DB_WATCH_ROW_UPDATEReceive notification when an existing row is updated. DB_WATCH_ROW_DELETEReceive notification when an existing row is deleted. The following flags limit the scope of the rows obtained from db_wait_ex:

• DB_WATCH_PRIMARY_KEYInclude a copy of the primary key in the watch row.
• DB_WATCH_MODIFIED_FIELDSInclude a copy of all modified fields in the watch row.
• DB_WATCH_BOUND_FIELDSInclude a copy of all bound fields in the watch row.
• DB_WATCH_ALL_FIELDSInclude a copy of all fields in the watch row.

The following flags control the use of the auxiliary row:

• DB_WATCH_FORMER_VALUESInclude the original values for any updated fields in the watch aux row.

  Parameters:

  utid	User supplied numeric id for the handler.

  Returns:

DB_OK when successful.

• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table name is null, invalid watch flags.

See also:

db_unwatch_table, db_wait,
db_goto_bookmark,
get_db_error, clear_db_error, Error Handling

db_result_t db_unwatch_table	(	db_t	hdb,
		const db_objname_t *	table_name
	)

Remove a notification handler for a particular table.

Parameters:

hdb	Database handle.
table_name	Name of database table.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Casued by: invalid database handle, table name is null.

See also:

db_watch_table, db_wait,
get_db_error, clear_db_error, Error Handling

db_result_t db_wait	(	db_t	hdb,
		db_wtime_t	timeout,
		db_event_t *	event
	)

Wait for a notification message from the database.

Parameters:

hdb	Database handle
timeout	Maximum length of time to wait for a notification 0 - returns right away with DB_FAIL if no notification or DB_OK if there was a notification to report.
event	Event structure containing information about the event. Check event.u.utid

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_ELOCKED When no notification event occurs within the timeout period.
• DB_EINVAL Invalid database handle.

This function does not start or require a transaction, but can be used safely within a transaction.

See also:

db_watch_table, db_unwatch_table,
get_db_error, clear_db_error, Error Handling

Deprecated:

Use db_wait_ex instead.

db_result_t db_wait_ex	(	db_t	hdb,
		db_wtime_t	timeout,
		db_event_t *	event,
		db_row_t	hrow,
		db_row_t	haux_row
	)

Wait for a notification message from the database.

Parameters:

hdb	Database handle
timeout	Maximum length of time to wait for a notification 0 - returns right away with DB_FAIL if no notification or DB_OK if there was a notification to report.
event	Event structure containing information about the event. Check event.u.utid
hrow	Destination for some or all fields of the modified row.
haux_row	For update events only, a destination for the original values.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Invalid database handle.

Precondition:

hrow and haux_row must be allocated, with any size greater than zero, regardless of the number of fields in the event. Existing bindings are replaced, if any.

After the event, hrow and haux_row may contain data, depending on how the notification event was configured in db_watch_table. The fields bound to the row will correspond to the table that originated the event. Only fields included in the event are bound to these rows. For fields that are not included in the event, db_is_null will return -1.

 db_t hdb = ...;
 db_result_t rc;
 db_event_t evt;
 db_row_t hrow = db_alloc_row(NULL, 1);
 do {
   rc = db_wait_ex(hdb, 0, &evt, hrow, NULL);
   ...
 } while (1);

This function does not start or require a transaction, but can be used safely within a transaction.

See also:

db_watch_table, db_unwatch_table,
get_db_error, clear_db_error, Error Handling