#include <transaction_base.hxx>

Inheritance diagram for pqxx::transaction_base:

Collaboration diagram for pqxx::transaction_base:

Public Types
typedef isolation_traits < read_committed >	isolation_tag
	If nothing else is known, our isolation level is at least read_committed. More...

Public Member Functions
virtual	~transaction_base ()=0

void	abort ()
	Abort the transaction. More...

const PGSTD::string &	classname () const throw ()

void	commit ()
	Commit the transaction. More...

connection_base &	conn () const
	Connection this transaction is running in. More...

PGSTD::string	description () const

PGSTD::string	esc (const char str[]) const
	Escape string for use as SQL string literal in this transaction. More...

PGSTD::string	esc (const char str[], size_t maxlen) const
	Escape string for use as SQL string literal in this transaction. More...

PGSTD::string	esc (const PGSTD::string &str) const
	Escape string for use as SQL string literal in this transaction. More...

PGSTD::string	esc_raw (const unsigned char str[], size_t len) const
	Escape binary data for use as SQL string literal in this transaction. More...

PGSTD::string	esc_raw (const PGSTD::string &) const
	Escape binary data for use as SQL string literal in this transaction. More...

result	exec (const PGSTD::string &Query, const PGSTD::string &Desc=PGSTD::string())
	Execute query. More...

result	exec (const PGSTD::stringstream &Query, const PGSTD::string &Desc=PGSTD::string())

PGSTD::string	get_variable (const PGSTD::string &)
	Get currently applicable value of variable. More...

const PGSTD::string &	name () const throw ()

internal::parameterized_invocation	parameterized (const PGSTD::string &query)
	Parameterize a statement. More...

template<typename T >
PGSTD::string	quote (const T &t) const
	Represent object as SQL string, including quoting & escaping. More...

PGSTD::string	quote_name (const PGSTD::string &identifier) const
	Escape an SQL identifier for use in a query. More...

PGSTD::string	quote_raw (const unsigned char str[], size_t len) const
	Binary-escape and quote a binarystring for use as an SQL constant. More...

PGSTD::string	quote_raw (const PGSTD::string &str) const

void	set_variable (const PGSTD::string &Var, const PGSTD::string &Val)
	Set session variable in this connection. More...

Prepared statements
prepare::invocation	prepared (const PGSTD::string &statement=PGSTD::string())
	Execute prepared statement. More...

Error/warning output
void	process_notice (const char Msg[]) const
	Have connection process warning message. More...

void	process_notice (const PGSTD::string &Msg) const
	Have connection process warning message. More...

Protected Member Functions
	transaction_base (connection_base &c, bool direct=true)
	Create a transaction (to be called by implementation classes only) More...

void	Begin ()
	Begin transaction (to be called by implementing class) More...

result	DirectExec (const char C[], int Retries=0)
	Execute query on connection directly. More...

virtual void	do_abort ()=0
	To be implemented by derived implementation class: abort transaction. More...

virtual void	do_begin ()=0
	To be implemented by derived implementation class: start transaction. More...

virtual void	do_commit ()=0
	To be implemented by derived implementation class: commit transaction. More...

virtual result	do_exec (const char Query[])=0
	To be implemented by derived implementation class: perform query. More...

void	End () throw ()
	End transaction. To be called by implementing class' destructor. More...

void	reactivation_avoidance_clear () throw ()
	Forget about any reactivation-blocking resources we tried to allocate. More...

Protected Attributes
internal::reactivation_avoidance_counter	m_reactivation_avoidance
	Resources allocated in this transaction that make reactivation impossible. More...

Private Types
enum	Status { st_nascent, st_active, st_aborted, st_committed, st_in_doubt }

Private Member Functions
	transaction_base ()
	Not allowed. More...

	transaction_base (const transaction_base &)
	Not allowed. More...

void PQXX_PRIVATE	activate ()
	Make sure transaction is opened on backend, if appropriate. More...

void PQXX_PRIVATE	BeginCopyRead (const PGSTD::string &, const PGSTD::string &)

void PQXX_PRIVATE	BeginCopyWrite (const PGSTD::string &Table, const PGSTD::string &Columns)

void PQXX_PRIVATE	CheckPendingError ()

void	EndCopyWrite ()

transaction_base &	operator= (const transaction_base &)
	Not allowed. More...

template<typename T >
bool	parm_is_null (T *p) const throw ()

template<typename T >
bool	parm_is_null (T) const throw ()

bool	ReadCopyLine (PGSTD::string &)

void PQXX_PRIVATE	RegisterFocus (internal::transactionfocus *)

void PQXX_PRIVATE	RegisterPendingError (const PGSTD::string &) throw ()

void PQXX_PRIVATE	UnregisterFocus (internal::transactionfocus *) throw ()

void	WriteCopyLine (const PGSTD::string &)

Private Attributes
connection_base &	m_Conn

internal::unique < internal::transactionfocus >	m_Focus

PGSTD::string	m_PendingError

bool	m_Registered

Status	m_Status

PGSTD::map< PGSTD::string, PGSTD::string >	m_Vars

Friends
class	pqxx::internal::gate::transaction_subtransaction

class	pqxx::internal::gate::transaction_tablereader

class	pqxx::internal::gate::transaction_tablewriter

class	pqxx::internal::gate::transaction_transactionfocus

Member Typedef Documentation

typedef isolation_traits<read_committed> pqxx::transaction_base::isolation_tag

If nothing else is known, our isolation level is at least read_committed.

Member Enumeration Documentation

enum pqxx::transaction_base::Status

private

Enumerator
st_nascent
st_active
st_aborted
st_committed
st_in_doubt

Constructor & Destructor Documentation

virtual pqxx::transaction_base::~transaction_base ( )

pure virtual

pqxx::transaction_base::transaction_base	(	connection_base &	c,
		bool	direct = `true`
	)

explicitprotected

Create a transaction (to be called by implementation classes only)

The optional name, if nonempty, must begin with a letter and may contain letters and digits only.

Parameters

c	The connection that this transaction is to act on.
direct	Running directly in connection context (i.e. not nested)?

pqxx::transaction_base::transaction_base ( )

private

Not allowed.

pqxx::transaction_base::transaction_base ( const transaction_base & )

private

Not allowed.

Member Function Documentation

void pqxx::transaction_base::abort ( )

Abort the transaction.

No special effort is required to call this function; it will be called implicitly when the transaction is destructed.

void PQXX_PRIVATE pqxx::transaction_base::activate ( )

private

Make sure transaction is opened on backend, if appropriate.

void pqxx::transaction_base::Begin ( )

protected

Begin transaction (to be called by implementing class)

Will typically be called from implementing class' constructor.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::transaction().

Here is the caller graph for this function:

void PQXX_PRIVATE pqxx::transaction_base::BeginCopyRead	(	const PGSTD::string &	,
		const PGSTD::string &
	)

private

void PQXX_PRIVATE pqxx::transaction_base::BeginCopyWrite	(	const PGSTD::string &	Table,
		const PGSTD::string &	Columns
	)

private

void PQXX_PRIVATE pqxx::transaction_base::CheckPendingError ( )

private

const PGSTD::string& pqxx::internal::namedclass::classname ( ) const throw ()

inlineinherited

void pqxx::transaction_base::commit ( )

Commit the transaction.

Unless this function is called explicitly, the transaction will not be committed (actually the nontransaction implementation breaks this rule, hence the name).

Once this function returns, the whole transaction will typically be irrevocably completed in the database. There is also, however, a minute risk that the connection to the database may be lost at just the wrong moment. In that case, libpqxx may be unable to determine whether the transaction was completed or aborted and an in_doubt_error will be thrown to make this fact known to the caller. The robusttransaction implementation takes some special precautions to reduce this risk.

connection_base& pqxx::transaction_base::conn ( ) const

inline

Connection this transaction is running in.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::~transaction().

Here is the caller graph for this function:

PGSTD::string pqxx::internal::namedclass::description ( ) const

inherited

result pqxx::transaction_base::DirectExec	(	const char	C[],
		int	Retries = `0`
	)

protected

Execute query on connection directly.

Parameters

C	Query or command to execute
Retries	Number of times to retry the query if it fails. Be extremely careful with this option; if you retry in the middle of a transaction, you may be setting up a new connection transparently and executing the latter part of the transaction without a backend transaction being active (and with the former part aborted).

virtual void pqxx::transaction_base::do_abort ( )

protectedpure virtual

To be implemented by derived implementation class: abort transaction.

Implemented in pqxx::dbtransaction, pqxx::subtransaction, pqxx::nontransaction, and pqxx::basic_robusttransaction.

virtual void pqxx::transaction_base::do_begin ( )

protectedpure virtual

To be implemented by derived implementation class: start transaction.

Implemented in pqxx::subtransaction, pqxx::dbtransaction, pqxx::nontransaction, and pqxx::basic_robusttransaction.

virtual void pqxx::transaction_base::do_commit ( )

protectedpure virtual

To be implemented by derived implementation class: commit transaction.

Implemented in pqxx::subtransaction, pqxx::dbtransaction, pqxx::nontransaction, pqxx::basic_robusttransaction, and pqxx::basic_transaction.

virtual result pqxx::transaction_base::do_exec ( const char Query[] )

protectedpure virtual

To be implemented by derived implementation class: perform query.

Implemented in pqxx::dbtransaction, and pqxx::nontransaction.

void pqxx::transaction_base::End ( ) throw ()

protected

End transaction. To be called by implementing class' destructor.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::~transaction().

Here is the caller graph for this function:

void pqxx::transaction_base::EndCopyWrite ( )

private

result pqxx::transaction_base::exec	(	const PGSTD::string &	Query,
		const PGSTD::string &	Desc = `PGSTD::string()`
	)

Execute query.

Perform a query in this transaction.

This is one of the most important functions in libpqxx.

Most libpqxx exceptions can be thrown from here, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions will be derived from std::exception, however, and all libpqxx-specific exception types are derived from pqxx::pqxx_exception.

Parameters

Query	Query or command to execute
Desc	Optional identifier for query, to help pinpoint SQL errors

Returns: A result set describing the query's or command's result

result pqxx::transaction_base::exec	(	const PGSTD::stringstream &	Query,
		const PGSTD::string &	Desc = `PGSTD::string()`
	)

inline

References exec().

Referenced by exec().

Here is the call graph for this function:

Here is the caller graph for this function:

PGSTD::string pqxx::transaction_base::get_variable ( const PGSTD::string & )

Get currently applicable value of variable.

First consults an internal cache of variables that have been set (whether in the ongoing transaction or in the connection) using the set_variable functions. If it is not found there, the database is queried.

Warning: Do not mix the set_variable with raw "SET" queries, and do not try to set or get variables while a pipeline or table stream is active.; This function used to be declared as const but isn't anymore.

const PGSTD::string& pqxx::internal::namedclass::name ( ) const throw ()

inlineinherited

transaction_base& pqxx::transaction_base::operator= ( const transaction_base & )

private

Not allowed.

internal::parameterized_invocation pqxx::transaction_base::parameterized ( const PGSTD::string & query )

Parameterize a statement.

template<typename T >

bool pqxx::transaction_base::parm_is_null ( T * p ) const throw ()

inlineprivate

template<typename T >

bool pqxx::transaction_base::parm_is_null ( T ) const throw ()

inlineprivate

prepare::invocation pqxx::transaction_base::prepared ( const PGSTD::string & statement = PGSTD::string() )

Execute prepared statement.

Prepared statements are defined using the connection classes' prepare() function, and continue to live on in the ongoing session regardless of the context they were defined in (unless explicitly dropped using the connection's unprepare() function). Their execution however, like other forms of query execution, requires a transaction object.

Just like param_declaration is a helper class that lets you tag parameter declarations onto the statement declaration, the invocation class returned here lets you tag parameter values onto the call:

result run_mystatement(transaction_base &T)
{
  return T.prepared("mystatement")("param1")(2)()(4).exec();
}

Here, parameter 1 (written as "<tt>$1</tt>" in the statement's body) is a string that receives the value "param1"; the second parameter is an integer with the value 2; the third receives a null, making its type irrelevant; and number 4 again is an integer. The ultimate invocation of exec() is essential; if you forget this, nothing happens.

To see whether any prepared statement has been defined under a given name, use:

T.prepared("mystatement").exists()

Warning: Do not try to execute a prepared statement manually through direct SQL statements. This is likely not to work, and even if it does, is likely to be slower than using the proper libpqxx functions. Also, libpqxx knows how to emulate prepared statements if some part of the infrastructure does not support them.; Actual definition of the prepared statement on the backend may be deferred until its first use, which means that any errors in the prepared statement may not show up until it is executed–and perhaps abort the ongoing transaction in the process.

If you leave out the statement name, the call refers to the nameless statement instead.

void pqxx::transaction_base::process_notice ( const char Msg[] ) const

inline

Have connection process warning message.

void pqxx::transaction_base::process_notice ( const PGSTD::string & Msg ) const

inline

Have connection process warning message.

void pqxx::transaction_base::reactivation_avoidance_clear ( ) throw ()

inlineprotected

Forget about any reactivation-blocking resources we tried to allocate.

References pqxx::result::clear().

Here is the call graph for this function:

bool pqxx::transaction_base::ReadCopyLine ( PGSTD::string & )

private

void PQXX_PRIVATE pqxx::transaction_base::RegisterFocus ( internal::transactionfocus * )

private

void PQXX_PRIVATE pqxx::transaction_base::RegisterPendingError ( const PGSTD::string & ) throw ()

private

void pqxx::transaction_base::set_variable	(	const PGSTD::string &	Var,
		const PGSTD::string &	Val
	)

Set session variable in this connection.

The new value is typically forgotten if the transaction aborts. Known exceptions to this rule are nontransaction, and PostgreSQL versions prior to 7.3. In the case of nontransaction, the set value will be kept regardless; but in that case, if the connection ever needs to be recovered, the set value will not be restored.

Parameters

Var	The variable to set
Val	The new value to store in the variable

void PQXX_PRIVATE pqxx::transaction_base::UnregisterFocus ( internal::transactionfocus * ) throw ()

private

void pqxx::transaction_base::WriteCopyLine ( const PGSTD::string & )

private

Friends And Related Function Documentation

friend class pqxx::internal::gate::transaction_subtransaction

friend

friend class pqxx::internal::gate::transaction_tablereader

friend

friend class pqxx::internal::gate::transaction_tablewriter

friend

friend class pqxx::internal::gate::transaction_transactionfocus

friend

Member Data Documentation

connection_base& pqxx::transaction_base::m_Conn

private

internal::unique<internal::transactionfocus> pqxx::transaction_base::m_Focus

private

PGSTD::string pqxx::transaction_base::m_PendingError

private

internal::reactivation_avoidance_counter pqxx::transaction_base::m_reactivation_avoidance

protected

Resources allocated in this transaction that make reactivation impossible.

This number may be negative!

bool pqxx::transaction_base::m_Registered

private

Status pqxx::transaction_base::m_Status

private

PGSTD::map<PGSTD::string, PGSTD::string> pqxx::transaction_base::m_Vars

private

The documentation for this class was generated from the following file:

/usr/include/pqxx/transaction_base.hxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Types

Private Member Functions

Private Attributes

Friends

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation