Template Class for doing transactions. More...

#include "rdm_db_transaction.h"

Public Member Functions
RDM_RETCODE	init (RDM_DB db)
	Initialize this object. More...

RDM_RETCODE	begin (void)
	Start a transaction. More...

RDM_RETCODE	end (void)
	End a transaction. More...

RDM_RETCODE	rollback (void)
	Roll back a transaction. More...

void	reset (void)
	Reset this object. More...

RDM_RETCODE	flush_value (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Flush this object. More...

RDM_RETCODE	flush_stats (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Flush this object. More...

RDM_RETCODE	flush_range (uint32_t threshold=1, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Flush this object. More...

template<class SOURCE_VALUE_T >
RDM_RETCODE	put_value (SOURCE_VALUE_T *source_value, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Template method for receiving a data value. More...

template<class SOURCE_STATS_T >
RDM_RETCODE	put_stats (SOURCE_STATS_T *source_stats, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Template method for receiving statistics. More...

template<class SOURCE_RANGE_T >
RDM_RETCODE	put_range (SOURCE_RANGE_T *source_range, TRANSACTIONAL_T transactional=NOT_TRANSACTIONAL)
	Template method for receiving ranges. More...

Data Fields
NEXT	next

Detailed Description

template<class NEXT>
class RDM::DB::transaction< NEXT >

Template Class for doing transactions.

Template class for doing transactions of data values, ranges, or statistics. What is received by this class will be forwarded to the next class. start() must be called before data can received. Call end() when done. Alternatively, rollback() can be called to roll back the transaction. Rolling back the transaction will also rewind the state of the time series classes back to the state when the transaction was started.

Template Parameters

NEXT	The next class in the chain of classes to receive data, ranges, or statistics.

Examples: cpp70Example_main.cpp, and time_series_fft.cpp.

Member Function Documentation

begin()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::begin ( void )

inline

Start a transaction.

Before doing any put or flush operations, a transaction must be started by calling this method. Call end() or rollback() when done.

For the correct operation, none of the RDM transaction operations, such as rdm_dbStartUpdate(), rdm_dbStartRead(), and rdm_dbEnd(), should be called until end() has been called.

Return values

sOKAY	Normal, successful return.
eTRACTIVE	Transaction is active.

 {
RDM_RETCODE rc;

if (transaction_active)
 {
 rc = eTRACTIVE;
 }
else
 {
if (RDM_LEN (tables_to_write_lock) > 1)
 {
 rc = rdm_dbStartUpdate (db, tables_to_write_lock, RDM_LEN (tables_to_write_lock) - 1, tables_to_read_lock, RDM_LEN (tables_to_read_lock) - 1, &trans);
 }
else
 {
 rc = rdm_dbStartRead (db, tables_to_read_lock, RDM_LEN (tables_to_read_lock) - 1, &trans);
 }
if (rc == sOKAY)
 {
 transaction_active = true;
 next_backup_state = next;
 }
 }

return rc;
 }

References eTRACTIVE, RDM::DB::transaction< NEXT >::next, rdm_dbStartRead(), rdm_dbStartUpdate(), RDM_LEN, and sOKAY.

Here is the call graph for this function:

end()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::end ( void )

inline

End a transaction.

Call this method to end a transaction started with begin(). Any changes made using the put or flush methods will be applied.

Return values

sOKAY	Normal, successful return.
eTRNOTACT	Transaction not active.

 {
RDM_RETCODE rc;

if (transaction_active)
 {
 rc = rdm_transEnd (trans);
if (rc == sOKAY)
 {
 transaction_active = false;
 }
 }
else
 {
 rc = eTRNOTACT;
 }

return rc;
 }

References eTRNOTACT, rdm_transEnd(), and sOKAY.

Here is the call graph for this function:

flush_range()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::flush_range	(	uint32_t	threshold = `1`,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Flush this object.

Call this method to flush what has been collected so far. A threshold can also be provided. All the data collected for those ranges will be kept as is. The same is the case when the threshold has not been reached.

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

threshold	[IN] Only flush objects where at least this many elements have been collected
transactional	[IN] Is the flush required to be transactional

 {
RDM_RETCODE rc = next.flush_range (threshold, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

flush_stats()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::flush_stats	(	uint32_t	threshold = `1`,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Flush this object.

Call this method to flush what has been collected so far. A threshold can also be provided. All the data collected for those statistics will be kept as is. The same is the case when the threshold has not been reached.

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

threshold	[IN] Only flush objects where at least this many elements have been collected
transactional	[IN] Is the flush required to be transactional

 {
RDM_RETCODE rc = next.flush_stats (threshold, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

flush_value()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::flush_value	(	uint32_t	threshold = `1`,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Flush this object.

Call this method to flush what has been collected so far. A threshold can also be provided. All the data collected for those values will be kept as is. The same is the case when the threshold has not been reached.

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

threshold	[IN] Only flush objects where at least this many elements have been collected
transactional	[IN] Is the flush required to be transactional

 {
RDM_RETCODE rc = next.flush_value (threshold, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

init()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::init ( RDM_DB db )

inline

Initialize this object.

Call this method before sending it any data values, ranges, or statistics.

Return values

sOKAY	Normal, successful return.
eINVARG	Invalid argument.
eDBNOTOPEN	Database not open.
eCURSORDB	Cursor is associated with a different database.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

db	[IN] Use this database for chained classes that need to insert rows

 {
RDM_RETCODE rc = next.init (db);

if (rc == sOKAY)
 {
 transaction::db = db;
 transaction_active = false;
 }

 (void) next.init_tables_to_read_lock (tables_to_read_lock);
 (void) next.init_tables_to_write_lock (tables_to_write_lock);

return rc;
 }

References RDM::DB::transaction< NEXT >::next, and sOKAY.

put_range()

template<class NEXT >

template<class SOURCE_RANGE_T >

RDM_RETCODE RDM::DB::transaction< NEXT >::put_range	(	SOURCE_RANGE_T *	source_range,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Template method for receiving ranges.

Receive one range and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_first', 'time_stamp_last', and 'value_range' with appropriate types. The column 'value_range' must be an array that is able to hold a static number of elements. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE range
(
 value_range DOUBLE ARRAY [32] NOT NULL,
 time_stamp_first UINT64 NOT NULL,
 time_stamp_last UINT64 PRIMARY KEY
);

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Template Parameters

SOURCE_RANGE_T The actual type of the range received.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

[in]	source_range	The source range sent to this class
	transactional	[IN] Is the put required to be transactional

 {
RDM_RETCODE rc = next.put_range (source_range, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

put_stats()

template<class NEXT >

template<class SOURCE_STATS_T >

RDM_RETCODE RDM::DB::transaction< NEXT >::put_stats	(	SOURCE_STATS_T *	source_stats,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Template method for receiving statistics.

Receive one statistic and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_first', 'time_stamp_last', 'n', 'value_sum', and 'value_sum2' with appropriate types. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE stats
(
 time_stamp_first UINT64 NOT NULL,
 time_stamp_last UINT64 PRIMARY KEY,
 n UINT64 NOT NULL,
 value_sum DOUBLE NOT NULL,
 value_sum2 DOUBLE NOT NULL
);

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Template Parameters

SOURCE_STAT_T The actual type of the statistic received.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

[in]	source_stats	The source statistics sent to this class
	transactional	[IN] Is the put required to be transactional

 {
RDM_RETCODE rc = next.put_stats (source_stats, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

put_value()

template<class NEXT >

template<class SOURCE_VALUE_T >

RDM_RETCODE RDM::DB::transaction< NEXT >::put_value	(	SOURCE_VALUE_T *	source_value,
		TRANSACTIONAL_T	transactional = `NOT_TRANSACTIONAL`
	)

inline

Template method for receiving a data value.

Receive one data value and process it accordingly.

The type for the value provided is required to have columns for 'time_stamp_current' and 'value_current' with appropriate types. Such a type can be generated using rdm-compile with a schema including a table similar to this:

CREATE TABLE measurement
(
 time_stamp_current UINT64 PRIMARY KEY,
 value_current DOUBLE NOT NULL
);

This operation can be specified as being transactional. However, if the caller always rolls back the transaction in the case of a failure, there is no need to specify single operations to be transactional.

Template Parameters

SOURCE_VALUE_T The actual type of the source values received

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.
eINVARG	Invalid argument.

Parameters

[in]	source_value	The source value sent to this class
	transactional	[IN] Is the put required to be transactional

 {
RDM_RETCODE rc = next.put_value (source_value, transactional);

return rc;
 }

References RDM::DB::transaction< NEXT >::next.

reset()

template<class NEXT >

void RDM::DB::transaction< NEXT >::reset ( void )

inline

Reset this object.

Call this method to discard all internally kept data values, ranges, and statistics that have not yet been persisted and start over from scratch.

 {
next.reset ();
 }

References RDM::DB::transaction< NEXT >::next.

rollback()

template<class NEXT >

RDM_RETCODE RDM::DB::transaction< NEXT >::rollback ( void )

inline

Roll back a transaction.

Call this method to roll back a transaction started with begin(). Any changes made using the put or flush methods will be rolled back.

Return values

sOKAY	Normal, successful return.
eTRNOTACT	Transaction not active.

 {
RDM_RETCODE rc;

if (transaction_active)
 {
 rc = rdm_transEndRollback (trans);
if (rc == sOKAY)
 {
 transaction_active = false;
next = next_backup_state;
 }
 }
else
 {
 rc = eTRNOTACT;
 }

return rc;
 }