pqxx::transaction_base Class Reference

#include <transaction_base.hxx>

Inheritance diagram for pqxx::transaction_base:

Inheritance graph
[legend]
List of all members.

Public Types

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

Public Member Functions

virtual ~transaction_base ()=0
void commit ()
 Commit the transaction.
void abort ()
 Abort the transaction.
PGSTD::string esc (const char str[]) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string esc (const char str[], size_t maxlen) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string esc (const PGSTD::string &) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string esc_raw (const unsigned char str[], size_t len) const
 Escape binary data for use as SQL string literal in this transaction.
PGSTD::string esc_raw (const PGSTD::string &) const
 Escape binary data for use as SQL string literal in this transaction.
result exec (const PGSTD::string &Query, const PGSTD::string &Desc=PGSTD::string())
 Execute query.
result exec (const PGSTD::stringstream &Query, const PGSTD::string &Desc=PGSTD::string())
connection_baseconn () const
 Connection this transaction is running in.
void set_variable (const PGSTD::string &Var, const PGSTD::string &Val)
 Set session variable in this connection.
PGSTD::string get_variable (const PGSTD::string &)
 Get currently applicable value of variable.
Prepared statements
prepare::invocation prepared (const PGSTD::string &statement)
 Execute prepared statement.
Error/warning output
void process_notice (const char Msg[]) const
 Have connection process warning message.
void process_notice (const PGSTD::string &Msg) const
 Have connection process warning message.

Protected Member Functions

 transaction_base (connection_base &, bool direct=true)
 Create a transaction (to be called by implementation classes only).
void Begin ()
 Begin transaction (to be called by implementing class).
void End () throw ()
 End transaction. To be called by implementing class' destructor.
virtual void do_begin ()=0
 To be implemented by derived implementation class: start transaction.
virtual result do_exec (const char Query[])=0
 To be implemented by derived implementation class: perform query.
virtual void do_commit ()=0
 To be implemented by derived implementation class: commit transaction.
virtual void do_abort ()=0
 To be implemented by derived implementation class: abort transaction.
result DirectExec (const char C[], int Retries=0)
 Execute query on connection directly.
void reactivation_avoidance_clear () throw ()
 Forget about any reactivation-blocking resources we tried to allocate.

Friends

class Cursor
class cursor_base
class internal::transactionfocus
class tablereader
class tablewriter
class pipeline
class prepare::invocation
class subtransaction

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.

Reimplemented in pqxx::basic_robusttransaction, pqxx::robusttransaction< ISOLATIONLEVEL >, and pqxx::transaction< ISOLATIONLEVEL >.


Constructor & Destructor Documentation

pqxx::transaction_base::~transaction_base (  )  [pure virtual]

pqxx::transaction_base::transaction_base ( connection_base ,
bool  direct = true 
) [explicit, protected]

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:
direct running directly in connection context (i.e. not nested)?


Member Function Documentation

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.

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.

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

Execute query.

Perform a query in this transaction.

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() 
)

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

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.

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.

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

Have connection process warning message.

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

Have connection process warning message.

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

Connection this transaction is running in.

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

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.

void pqxx::transaction_base::Begin (  )  [protected]

Begin transaction (to be called by implementing class).

Will typically be called from implementing class' constructor.

void pqxx::transaction_base::End (  )  throw () [protected]

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

virtual void pqxx::transaction_base::do_begin (  )  [protected, pure virtual]

To be implemented by derived implementation class: start transaction.

Implemented in pqxx::dbtransaction.

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

To be implemented by derived implementation class: perform query.

Implemented in pqxx::dbtransaction.

virtual void pqxx::transaction_base::do_commit (  )  [protected, pure virtual]

To be implemented by derived implementation class: commit transaction.

Implemented in pqxx::dbtransaction.

virtual void pqxx::transaction_base::do_abort (  )  [protected, pure virtual]

To be implemented by derived implementation class: abort transaction.

Implemented in pqxx::dbtransaction.

pqxx::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).

void pqxx::transaction_base::reactivation_avoidance_clear (  )  throw () [protected]

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


Friends And Related Function Documentation

friend class Cursor [friend]

friend class cursor_base [friend]

friend class internal::transactionfocus [friend]

friend class tablereader [friend]

friend class tablewriter [friend]

friend class pipeline [friend]

friend class prepare::invocation [friend]

friend class subtransaction [friend]


The documentation for this class was generated from the following files:
Generated on Thu Feb 1 17:12:40 2007 for libpqxx by  doxygen 1.5.1