BPS datastore class. More...

#include <bpsdatastore.h>

Inheritance diagram for BpsDatastore:

Signals
void	connected ()
	Signal is emitted after successful connection.

void	disconnected ()
	Signal is emitted after disconnection.

Public Member Functions
QVariant	actorKey () const
	Return the actor's key (c_key in the t_actors table). More...

QString	application () const

	BpsDatastore (QObject *aParent=nullptr)
	Constructor for the BpsDatastore objects. More...

void	checkin (const QString &aTerminalName=QString(), const QString &aApplicationName=QString(), bool aSingleTerminalSession=false)
	Check in the user by creating a record in table t_actors. More...

void	checkout ()
	Check out the user by dropping the record in table t_actors. More...

void	clearKeys (const QVariant &aId)
	Delete a key list from table t_keys. More...

void	commit ()
	Commit an open transaction. More...

void	connect ()
	Connect to database server using the current settings in the properties username, password, driver, database, host and port. More...

QString	connection () const
	Get the connection name. More...

QDateTime	currentTimestamp ()

QString	database () const
	Get database name for PostgreSQL, or TNS service name or SID for Oracle. More...

void	disconnect ()
	Disconnect from database server if currently connected. More...

QString	driver () const
	Get driver name. More...

void	dropConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Drop connection. More...

void	dropKeytable (const QVariant &aTableKey)
	Drops a record from t_keytables. More...

QString	fromDual () const
	Returns " from dual" for oracle, and an empty string otherwise. More...

bool	hasDivisionAccess (const QVariant &aDivisionKey)
	Checks if the current user is authorized for the division. More...

bool	hasPermission (const QString &aPermission)
	Checks if the current user is authorized for the named permission. More...

bool	hasZoneAccess (const QVariant &aZoneKey)
	Checks if the current user is authorized for the zone. More...

QString	host () const
	Get host IP name or address. More...

bool	indexExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain index exists. More...

QString	indexTablespace ()
	Get the tablespace name used for indexes. More...

bool	inTransaction () const

bool	isAdmin () const
	Check if the current user has sufficient database privileges to act as BPS user administrator. More...

bool	isCheckedIn (const QString &aTerminalName=QString(), const QString &aApplicationName=QString(), bool aSingleTerminalSession=false)
	Test if similar actor already checked in. More...

bool	isConnected () const
	Check current connection status. More...

bool	isDBA () const
	Check if the current user has database administrator (Oracle) or superuser (PostgreSQL) privileges respectively. More...

bool	isOracle () const
	Check if current driver is for Oracle. More...

bool	isOwner () const
	Check if the current user is the BPS owner. More...

bool	isPostgres () const
	Check if current driver is for PostgreSQL. More...

QString	joinKeys (const QVariant &aId, const QString &aRef)
	Creates a inner join clause to join a given query to the list of keys in t_keys. More...

QString	joinKeytable (const QVariant &aTableKey, const QString &aRef)
	Creats a inner join clause to join a given query to the list of keys in the table. More...

QSqlDatabase &	link ()
	Get QSqlDatabase object. More...

bool	loadConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalScopes)
	Load connection settings. More...

bool	lockTable (const QString &aTable, int aTimeout)
	Start a transaction with the given table locked in exclusive mode. More...

QVariant	makeKeytable (const QString &aKeyList)
	Creats a record in t_keytables from the given list of values. More...

QVariant	nextIdent (const QString &aSeqenceName)
	Get the next sequence value. More...

QVariant	nextKey (const QString &aTableName)
	Get the next unused key for a table. More...

QString	password () const
	Get database user password. More...

int	port () const
	Get host IP port number. More...

QSqlIndex *	primaryIndex (const QString &aTableName)
	Get the primary index for a certain table. More...

void	purgeActors ()
	Purge actors which are no longer connected. More...

QSqlRecord *	record (const QString &aTableName)
	Get the record info for a certain table. More...

void	renameConnection (const QString &aConnection, BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Rename the connection. More...

Bps::Access	reportAccess (const QVariant &aReportKey)
	Check access to a certain report. More...

QStringList	roles ()
	Get a list of all roles. More...

void	rollback ()
	Rollback an open transaction. More...

void	saveConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Save the connection settings. More...

QString	schema () const
	Get BPS datastore schema name. More...

bool	sequenceExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain sequence exists. More...

QVariant	sessionId () const
	Return the current actors session id (the database internal identifier of the current session). More...

void	setConnection (const QString &aConnection)
	Set the connection name. More...

void	setDatabase (const QString &aDatabase)
	Set database name. More...

void	setDriver (const QString &aDriver)
	Set database driver name. More...

void	setHost (const QString &aHost)
	Set DB server's host name or IP address. More...

QVariant	setKeys (const QList< qlonglong > &aKeys)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QVariant	setKeys (const QList< qulonglong > &aKeys)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QVariant	setKeys (const QSet< qlonglong > &aKeys)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QVariant	setKeys (const QSet< qulonglong > &aKeys)
	Insert a key list into table t_keys. More...

QVariant	setKeys (const QVariantList &aKeys)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	setPassword (const QString &aPassword)
	Set database user password. More...

void	setPort (int aPort)
	Set the servers database service IP port number. More...

void	setSchema (const QString &aSchema)
	Set BPS schema. More...

void	setUsername (const QString &aUsername)
	Set database user name. More...

bool	tableExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain table exists. More...

QStringList	tablespaces ()
	Get a list of all tablespaces. More...

QString	tableTablespace ()
	Get the tablespace name used for tables. More...

QString	terminal () const

QString	timestampValue (const QDateTime &aDateTime) const
	Returns a column text representing a constant timestamp without time zone. More...

void	touchActor ()
	Update the actors timestamp. More...

void	transaction ()
	Start a new transaction. More...

BpsTypeLiteral	typeNextval (const QString &aSequence) const
	Get a BpsTypeLiteral representing the next sequence value for use with . More...

void	upsert (const QString &aTable, const QVariantMap &aKeyVals, const QVariantMap &aUpdVals)
	Executes a upsert (insert/update) using MERGE on Oracle or INSERT...ON CONFLICT on PostgreSQL. More...

int	userid () const
	Returns the user id (the numeric bps user identification). More...

QVariant	userKey () const
	Returns the user's key (c_key in the t_users table). More...

QString	username () const
	Get database user name. More...

QStringList	users ()
	Get a list of all database user names. More...

bool	viewExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain view exists. More...

Public Member Functions inherited from QObject
bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo ()

void	dumpObjectInfo () const const

void	dumpObjectTree ()

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_DISABLE_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

	QObject (QObject *parent)

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Static Public Member Functions
static QStringList	connections ()
	Get all defined connections. More...

static QString	quote (const QString &aText)
	Quote a literal text in single quotes to include it in a sql statement. More...

static QString	quote (QChar aChar)
	Quote a char in single quotes to include it in a sql statement. More...

static QStringList	tnsnames ()
	Get a list of all Oracle TNS names. More...

Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Additional Inherited Members
Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Detailed Description

BPS datastore class.

This is the datastore class used throughout the BPS class library. It supports connections to PostgreSQL and to Oracle. The class encapsulates a Qt database connection, adding generic methods for both database types supported by BPS.

#include <bpsexception.h>
#include <bpsdatastore.h>
#include <QCoreApplication>
#include <QDebug>
 
int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
    try {
        qDebug() << "create datastore object";
        BpsDatastore ds;
 
        qDebug() << "connect to database";
        ds.setDriver("BPSORA");       // Oracle driver
        ds.setDatabase("jupiter");    // TNS name
        ds.setUsername("scott");      // user name
        ds.setPassword("tiger");      // user password
        ds.connect();
 
        qDebug() << "list the database users";
        qDebug() << ds.users();
 
        qDebug() << "disconnect from database";
        // Basically this disconnect is obsolete, because when ds gets out
        // of scope at the end of this C++ block, the destructor will
        // do a disconnect
        ds.disconnect();
    } // try
    catch (const BpsException& exc) {
        // in case anything went wrong, show the error messages
        qDebug() << exc.text();
    } // catch
} // main

Constructor & Destructor Documentation

◆ BpsDatastore()

BpsDatastore::BpsDatastore ( QObject * aParent = nullptr )

Constructor for the BpsDatastore objects.

Parameters

aParent Pointer to an optional parent object.

Member Function Documentation

◆ actorKey()

QVariant BpsDatastore::actorKey ( ) const

Return the actor's key (c_key in the t_actors table).

A valid actorKey is only returned when checked in, otherwise an invalid QVariant is returned.

Returns: QVariant with the actor key.

◆ application()

QString BpsDatastore::application ( ) const

Returns: Application name used at checkin.

◆ checkin()

void BpsDatastore::checkin	(	const QString &	aTerminalName = `QString()`,
		const QString &	aApplicationName = `QString()`,
		bool	aSingleTerminalSession = `false`
	)

Check in the user by creating a record in table t_actors.

Checking in is required for active users, because all permanent locks will be referencing the entry in t_actors. In case the current connection was already checked in, it will be checked out before attempting to do the new check in.

Parameters

aTerminalName	The terminal name for the session. Pass an empty string to use bps->terminalName().
aApplicationName	The name of the application. For C++ applications the file path of the executable, for standalone scripts the file path of the script. Pass an empty string to use QCoreApplication::applicationFilePath().
aSingleTerminalSession	When true (typically MDE applications) other existing actors with the same terminal are checked out. When false (the default) other existing actors with same user, terminal and application get checked out.

Exceptions

BpsException When not connected, no valid userid or general sql error.

◆ checkout()

void BpsDatastore::checkout ( )

Check out the user by dropping the record in table t_actors.

Exceptions

BpsException When not connected or general sql error.

◆ clearKeys()

void BpsDatastore::clearKeys ( const QVariant & aId )

Delete a key list from table t_keys.

Parameters

aId	The ID of the list.

◆ commit()

void BpsDatastore::commit ( )

Commit an open transaction.

Exceptions

BpsException When not connected or commit fails.

◆ connect()

void BpsDatastore::connect ( )

Connect to database server using the current settings in the properties username, password, driver, database, host and port.

Exceptions

BpsException When driver cannot be loaded or connect fails.

◆ connection()

QString BpsDatastore::connection ( ) const

Get the connection name.

The default connection name is empty. The connection name serves to store the database connection parameters host name, port, database and schema in a convenient way so only the connection needs to be selected to set all four parameters in one go.

Returns: Connection name.

◆ connections()

static QStringList BpsDatastore::connections ( )

static

Get all defined connections.

Returns: A list of all connections that have been declared in the BPS configuration program.

◆ currentTimestamp()

QDateTime BpsDatastore::currentTimestamp ( )

Returns: The current timestamp from the datastore.

◆ database()

QString BpsDatastore::database ( ) const

Get database name for PostgreSQL, or TNS service name or SID for Oracle.

Note: For Oracle the database name either refers to the TNS name or to the SID. In case a non-empty host name is given, the database is assumed to be the SID, when the host name is empty it is treated as the TNS name.

Returns: Database name for PostgreSQL, TNS service name or SID for Oracle.

◆ disconnect()

void BpsDatastore::disconnect ( )

Disconnect from database server if currently connected.

Returns: Database object reference.

◆ driver()

QString BpsDatastore::driver ( ) const

Get driver name.

Returns: "BPSPG" for PostgreSQL, "BPSORA" for Oracle.

◆ dropConnection()

void BpsDatastore::dropConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalUserScope )

Drop connection.

The database properties are removed from the settings.

Parameters

aScopes Scopes at which the settings are removed. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

See also: saveConnection()

◆ dropKeytable()

void BpsDatastore::dropKeytable ( const QVariant & aTableKey )

Drops a record from t_keytables.

Parameters

aTableKey Key of the record.

◆ fromDual()

QString BpsDatastore::fromDual ( ) const

Returns " from dual" for oracle, and an empty string otherwise.

Returns

◆ hasDivisionAccess()

bool BpsDatastore::hasDivisionAccess ( const QVariant & aDivisionKey )

Checks if the current user is authorized for the division.

Note: When isOwner() is true, hasDivisionAccess() returns always true.

Parameters

aDivisionKey The key within table t_divisions.

Returns: True if the division access is granted.

◆ hasPermission()

bool BpsDatastore::hasPermission ( const QString & aPermission )

Checks if the current user is authorized for the named permission.

Note: When isOwner() is true, hasPermission() returns always true.

Parameters

aPermission The permission name, for example settings.view

Returns: True if the permission is granted.

◆ hasZoneAccess()

bool BpsDatastore::hasZoneAccess ( const QVariant & aZoneKey )

Checks if the current user is authorized for the zone.

Note: When isOwner() is true, hasZoneAccess() returns always true.

Parameters

aZoneKey The key within table t_zones.

Returns: True if the zone access is granted.

◆ host()

QString BpsDatastore::host ( ) const

Get host IP name or address.

Note: For Oracle, when using a TNS service name the host name must stay empty. If a host name or IP is set for Oracle, then a ad-hoc connection will be made using host name and port, and using the database property as SID.

Returns: Host IP name or address.

◆ indexExists()

bool BpsDatastore::indexExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain index exists.

Parameters

aName	Name of the index.
aSchema	Schema name. Default schema is used when omitted.

Exceptions

BpsException When the query fails.

Returns: True if the index exists, false otherwise.

◆ indexTablespace()

QString BpsDatastore::indexTablespace ( )

Get the tablespace name used for indexes.

Note that this is only working for a existing BPS schema because it queries table t_users to get the information.

Returns: Name of the tablespace for BPS indexes.

◆ inTransaction()

bool BpsDatastore::inTransaction ( ) const

Returns: True if in uncommitted transaction, false if not.

◆ isAdmin()

bool BpsDatastore::isAdmin ( ) const

Check if the current user has sufficient database privileges to act as BPS user administrator.

Returns: True if having the required database privileges.

◆ isCheckedIn()

bool BpsDatastore::isCheckedIn	(	const QString &	aTerminalName = `QString()`,
		const QString &	aApplicationName = `QString()`,
		bool	aSingleTerminalSession = `false`
	)

Test if similar actor already checked in.

Call this before checkin() with the same parameters to find out if a similar actor already exists.

Parameters

aTerminalName	The terminal name for the session. Pass an empty string to use bps->terminalName().
aApplicationName	The name of the application. For C++ applications the file path of the executable, for standalone scripts the file path of the script. Pass an empty string to use QCoreApplication::applicationFilePath().
aSingleTerminalSession	When true (typically MDE applications) other existing actors with the same terminal are checked. When false (the default) other existing actors with same user, terminal and application are checked.

Exceptions

BpsException When not connected, no valid userid or general sql error.

Returns: True if a actor already exists that would get thrown out by a subsequent checkin() call.

◆ isConnected()

bool BpsDatastore::isConnected ( ) const

Check current connection status.

Returns: True if currently connected, false otherwise.

◆ isDBA()

bool BpsDatastore::isDBA ( ) const

Check if the current user has database administrator (Oracle) or superuser (PostgreSQL) privileges respectively.

Returns: True if having DBA/superuser privileges.

◆ isOracle()

bool BpsDatastore::isOracle ( ) const

Check if current driver is for Oracle.

Returns: True if current driver is BPSORA, false otherwise.

◆ isOwner()

bool BpsDatastore::isOwner ( ) const

Check if the current user is the BPS owner.

The schema must not be empty and be equal to the username. Compare of username and schema are done case insensitive.

Returns: True if the BPS owner, false otherwise.

◆ isPostgres()

bool BpsDatastore::isPostgres ( ) const

Check if current driver is for PostgreSQL.

Returns: True if current driver is BPSPG or BPSPG, false otherwise.

◆ joinKeys()

QString BpsDatastore::joinKeys	(	const QVariant &	aId,
		const QString &	aRef
	)

Creates a inner join clause to join a given query to the list of keys in t_keys.

Parameters

aId	The ID of the list.
aRef	Text to insert as referenced column or placeholder.

Returns: The inner join clause.
// Example when aRef = "?":

"inner join t_keys kid6 on kid6.c_id=6 and kid6.c_key=?"

// Example when aRef = "ab.c_orderrow":

"inner join t_keys kid234 on kid234.c_id=234 and kid234.c_key=ab.c_orderrow"

◆ joinKeytable()

QString BpsDatastore::joinKeytable	(	const QVariant &	aTableKey,
		const QString &	aRef
	)

Creats a inner join clause to join a given query to the list of keys in the table.

Parameters

aTableKey	The key of the record in t_keytables.
aRef	Text to insert as referenced column or placeholder.

Returns: The inner join clause.
// Example for Oracle when aRef = "?":

"inner join table(select c_table from t_keytables where c_key=6) ktbl6 on ktbl6.column_value=?"

// Example for Oracle when aRef = "ab.c_orderrow":

"inner join table(select c_table from t_keytables where c_key=6) ktbl6 on ktbl6.column_value=ab.c_orderrow"

// Example for PostgreSQL when aRef = "a.c_key":

"inner join t_keytables ktbl16 on ktbl16.c_key=16 and a.c_key=any(ktbl16.c_table)"

◆ link()

QSqlDatabase& BpsDatastore::link ( )

Get QSqlDatabase object.

Returns: Qt database object used by the BPS datastore class for direct usage of Qt functions.

◆ loadConnection()

bool BpsDatastore::loadConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalScopes )

Load connection settings.

When loading a connection that has been previously saved, the properties for node, schema, database, driver, host and port are searched and loaded from the locations defined in aScopes.

Parameters

aScopes Scopes at which the settings are searched. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

Returns: True if the connection settings were found and loaded.

◆ lockTable()

bool BpsDatastore::lockTable	(	const QString &	aTable,
		int	aTimeout
	)

Start a transaction with the given table locked in exclusive mode.

Commit or rollback the transaction to release the lock.

Parameters

aTable	Name of the table to lock.
aTimeout	Time out in seconds while waiting for lock. Special values: 0 = no wait, -1 = wait endless.

Returns: True if the lock was successful, false if not.

◆ makeKeytable()

QVariant BpsDatastore::makeKeytable ( const QString & aKeyList )

Creats a record in t_keytables from the given list of values.

The use of keytables is required when running queries against a large number of keys. The SQL clause "IN (...)" will not work then, because of the DB restrictions for query sizes. However with keytables the number of keys is only restricted by the maximum size of a CLOB.

// Some examples:
QString mCsvList = bStr("1,12,765,13,25");
 
QVariant kt = mDatastore->makeKeytable(mCsvList);
BpsQuery q(mDatastore);
 
q.execute(
  bStr(
    "insert into t_samples (c_key, c_time) "
    "select kt.c_key, localtimestamp from %1 kt"
  ).arg(mDatastore->keytable(kt))
);
 
q.execute(
  bStr("select * from t_samples s %1")
    .arg(mDatastore->joinKeytable(kt,bStr("s.c_key"))
);
while (q.next()) ...
 
mDatastore->dropKeytable(kt);

Parameters

aKeyList A list of keyvalues in CSV format.

Returns: Key of the record in t_keytables.

◆ nextIdent()

QVariant BpsDatastore::nextIdent ( const QString & aSeqenceName )

Get the next sequence value.

Parameters

aSeqenceName The name of the sequence.

Returns: Next identifier as QVariant.

◆ nextKey()

QVariant BpsDatastore::nextKey ( const QString & aTableName )

Get the next unused key for a table.

Parameters

aTableName The base name of the sequence and table, where the prefix s_ and t_ is added. Example: aName = users, sequence = s_users and table = t_users.

Returns: Next key as QVariant.

◆ password()

QString BpsDatastore::password ( ) const

Get database user password.

Returns: Database user password.

◆ port()

int BpsDatastore::port ( ) const

Get host IP port number.

The default is -1 which will assume 5432 for PostgreSQL and 1531 for Oracle (in case not using TNS).

Returns: Host IP port number.

◆ primaryIndex()

QSqlIndex* BpsDatastore::primaryIndex ( const QString & aTableName )

Get the primary index for a certain table.

If no primary index exists an empty QSqlIndex is returned.

Parameters

aTableName The name of the table.

Returns: The primary index.

◆ purgeActors()

void BpsDatastore::purgeActors ( )

Purge actors which are no longer connected.

Such records can be present in case of crashed sessions. Removing them will release all permanent locks that still may be held.

Exceptions

BpsException When not connected or general sql error.

◆ quote() [1/2]

static QString BpsDatastore::quote ( const QString & aText )

static

Quote a literal text in single quotes to include it in a sql statement.

Takes care of any single quotes within the literal.

Parameters

aText Literal text to be quoted.

Returns: Quoted literal text.

◆ quote() [2/2]

static QString BpsDatastore::quote ( QChar aChar )

static

Quote a char in single quotes to include it in a sql statement.

Takes care of char being a single quote itself.

Parameters

aChar Char to be quoted.

Returns: Quoted char.

◆ record()

QSqlRecord* BpsDatastore::record ( const QString & aTableName )

Get the record info for a certain table.

Parameters

aTableName The name of the table.

Returns: The record of the found table, or an empty record if no such table found.

◆ renameConnection()

void BpsDatastore::renameConnection	(	const QString &	aConnection,
		BpsSettings::Scopes	aScopes = `BpsSettings::LocalUserScope`
	)

Rename the connection.

Parameters

aConnection	New name of the connection.
aScopes	Scopes at which the settings are renamed. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

◆ reportAccess()

Bps::Access BpsDatastore::reportAccess ( const QVariant & aReportKey )

Check access to a certain report.

The connection must be established and checked in.

Parameters

aReportKey The key within table t_reports.

Returns: Access for current user.

◆ roles()

QStringList BpsDatastore::roles ( )

Get a list of all roles.

Exceptions

BpsException When the query fails.

Returns: List of all roles in lowercase.

◆ rollback()

void BpsDatastore::rollback ( )

Rollback an open transaction.

Exceptions

BpsException When not connected or rollback fails.

◆ saveConnection()

void BpsDatastore::saveConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalUserScope )

Save the connection settings.

The database properties are saved for subsequent availability by setConnection().

Parameters

aScopes Scopes at which the settings are saved. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

See also: dropConnection()

◆ schema()

QString BpsDatastore::schema ( ) const

Get BPS datastore schema name.

Returns: BPS datastore schema name.

◆ sequenceExists()

bool BpsDatastore::sequenceExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain sequence exists.

Parameters

aName	Name of the sequence.
aSchema	Schema name. Default schema is used when omitted.

Exceptions

BpsException When the query fails.

Returns: True if the sequence exists, false otherwise.

◆ sessionId()

QVariant BpsDatastore::sessionId ( ) const

Return the current actors session id (the database internal identifier of the current session).

A valid sessionId is only returned when connected, otherwise an invalid QVariant is returned.

Returns: QVariant with the session id.

◆ setConnection()

void BpsDatastore::setConnection ( const QString & aConnection )

Set the connection name.

The database connection name is used to identify a certain connection within the application.

Parameters

aConnection Name of the connection.

See also: connection()

◆ setDatabase()

void BpsDatastore::setDatabase ( const QString & aDatabase )

Set database name.

Parameters

aDatabase Database name for PostgreSQL, TNS name or SID for Oracle.

See also: database() const

◆ setDriver()

void BpsDatastore::setDriver ( const QString & aDriver )

Set database driver name.

The database driver name as "BPSPG" for PostgreSQL, or "BPSORA" for Oracle.

Parameters

aDriver Database driver name as "BPSPG" for PostgreSQL, or "BPSORA" for Oracle.

◆ setHost()

void BpsDatastore::setHost ( const QString & aHost )

Set DB server's host name or IP address.

Either the database servers host name, or it's numeric IP address.

Parameters

aHost Database server's host name or IP address.

See also: host()

◆ setKeys()

QVariant BpsDatastore::setKeys ( const QSet< qulonglong > & aKeys )

Insert a key list into table t_keys.

Only unique keys are inserted, duplicates are silently ignored.

The list will get automatically deleted on disconnect. However it is good practice to purge no longer used lists with method clearKeys().

Note: Keytables are much faster when a large number of keys need to be sent to the database.; See BpsDatastore::makeKeytable

Select example:

QVariant kid = mDatastore->setKeys(myKeyList);
BpsQuery q(mDatastore);
q.prepare(
  bStr("select * from t_sometable t %1")
    .arg(mDatastore->joinKeys(kid, bStr("t.c_key"))
);
q.execute(kid);
mDatastore->clearKeys(kid);

Update example:

QVariant kid = mDatastore->setKeys(myKeyList);
BpsQuery q(mDatastore);
q.prepare(bStr(
    "update t_sometable ... "
    "where c_key in (select c_key from t_keys where c_id=?)"
));
q.bind(kid);
q.execute();
mDatastore->clearKeys(kid);

Parameters

aKeys The list of keys to insert.

Returns: ID referencing the key list.

◆ setPassword()

void BpsDatastore::setPassword ( const QString & aPassword )

Set database user password.

Set the password before connecting to the database.

Parameters

aPassword Password of the database user.

◆ setPort()

void BpsDatastore::setPort ( int aPort )

Set the servers database service IP port number.

Parameters

aPort Database service port number on server.

See also: port() const

◆ setSchema()

void BpsDatastore::setSchema ( const QString & aSchema )

Set BPS schema.

Parameters

aSchema BPS schema name.

◆ setUsername()

void BpsDatastore::setUsername ( const QString & aUsername )

Set database user name.

Set the username before connection to the database.

Parameters

aUsername Name of the database user.

◆ tableExists()

bool BpsDatastore::tableExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain table exists.

Parameters

aName	Name of the table.
aSchema	Schema name. Default schema is used when omitted.

Exceptions

BpsException When the query fails.

Returns: True if the table exists, false otherwise.

◆ tablespaces()

QStringList BpsDatastore::tablespaces ( )

Get a list of all tablespaces.

Exceptions

BpsException When the query fails.

Returns: List of all tablespaces in lowercase.

◆ tableTablespace()

QString BpsDatastore::tableTablespace ( )

Get the tablespace name used for tables.

Note that this is only working for a existing BPS schema because it queries table t_users to get the information.

Returns: Name of the tablespace for BPS tables.

◆ terminal()

QString BpsDatastore::terminal ( ) const

Returns: Terminal name used at checkin.

◆ timestampValue()

QString BpsDatastore::timestampValue ( const QDateTime & aDateTime ) const

Returns a column text representing a constant timestamp without time zone.

Oracle example: to_timestamp('2012.01.15 13:15:21.000','YYYY.MM.DD HH24:MI:SS.FF')

PostgreSQL example: '2012-01-15 13:15:21.000'::timestamp

Parameters

aDateTime The date/time to convert

Returns: Column text for timestamp constant

◆ tnsnames()

static QStringList BpsDatastore::tnsnames ( )

static

Get a list of all Oracle TNS names.

Returns: List of all TNS names found.

Note: Because Oracle has never provided an API or discloses any information how the TNS names can be found, you cannot rely that all TNS names are found by this function. So you should allow your software to also use TNS names not returned in this list.

◆ touchActor()

void BpsDatastore::touchActor ( )

Update the actors timestamp.

Will usually be called by license check routines.

◆ transaction()

void BpsDatastore::transaction ( )

Start a new transaction.

The transaction will be closed either by a call to commit, or a call to rollback.

Exceptions

BpsException When not connected or transaction cannot be started.

◆ typeNextval()

BpsTypeLiteral BpsDatastore::typeNextval ( const QString & aSequence ) const

Get a BpsTypeLiteral representing the next sequence value for use with .

Returns: The variable holding either "sequence.nextval" for Oracle or "nextval('sequence')" for PgSQL

◆ upsert()

void BpsDatastore::upsert	(	const QString &	aTable,
		const QVariantMap &	aKeyVals,
		const QVariantMap &	aUpdVals
	)

Executes a upsert (insert/update) using MERGE on Oracle or INSERT...ON CONFLICT on PostgreSQL.

Takes care of possible conflict on the primary key, when more than one client does the same exactly simultaneously, by retrying the query until success or 10 times failed.

// Example
QVariantMap keyVals, updVals;
keyVals[bStr("c_grai")] = bStr("7613264.00381.100000103035");
updVals[bStr("c_usedate")] = BpsTypeLocaltimestamp();
mDatastore->upsert(bStr("t_graiuses"), keyVals, updVals);
 
// SQL executed for Oracle:
merge into t_graiuses d
using (select ? as c_grai, localtimestamp as c_usedate from dual) s on (d.c_grai=s.c_grai)
when matched then update set d.c_usedate=s.c_usedate
when not matched then insert (c_grai, c_usedate) values (s.c_grai, s.c_usedate)
 
// SQL executed for PostgreSQL:
insert into t_graiuses (c_grai, c_usedate) values (?, localtimestamp)
on conflict on constraint t_graiuses_pkey do update set c_usedate=excluded.c_usedate

Parameters

aTable	The name of the table to upsert.
aKeyVals	The key values together forming the primary key of the table.
aUpdVals	The update (non-key) values.

◆ userid()

int BpsDatastore::userid ( ) const

Returns the user id (the numeric bps user identification).

No valid userid is returned when the username is not made up by {schema}{userid}. The userid of the BPS owner is 0.

Returns: The userid, or -1 if the userid is invalid.

◆ userKey()

QVariant BpsDatastore::userKey ( ) const

Returns the user's key (c_key in the t_users table).

A valid userKey is only returned when checked in, otherwise an invalid QVariant is returned.

Returns: QVariant with the user key.

◆ username()

QString BpsDatastore::username ( ) const

Get database user name.

Returns: Database user name.

◆ users()

QStringList BpsDatastore::users ( )

Get a list of all database user names.

Exceptions

BpsException When the query fails.

Returns: List of all database user names in lowercase.

◆ viewExists()

bool BpsDatastore::viewExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain view exists.

Parameters

aName	Name of the view.
aSchema	Schema name. Default schema is used when omitted.

Exceptions

BpsException When the query fails.

Returns: True if the view exists, false otherwise.

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

bpsdatastore.h

Signals

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BpsDatastore()

Member Function Documentation

◆ actorKey()

◆ application()

◆ checkin()

◆ checkout()

◆ clearKeys()

◆ commit()

◆ connect()

◆ connection()

◆ connections()

◆ currentTimestamp()

◆ database()

◆ disconnect()

◆ driver()

◆ dropConnection()

◆ dropKeytable()

◆ fromDual()

◆ hasDivisionAccess()

◆ hasPermission()

◆ hasZoneAccess()

◆ host()

◆ indexExists()

◆ indexTablespace()

◆ inTransaction()

◆ isAdmin()

◆ isCheckedIn()

◆ isConnected()

◆ isDBA()

◆ isOracle()

◆ isOwner()

◆ isPostgres()

◆ joinKeys()

◆ joinKeytable()

◆ link()

◆ loadConnection()

◆ lockTable()

◆ makeKeytable()

◆ nextIdent()

◆ nextKey()

◆ password()

◆ port()

◆ primaryIndex()

◆ purgeActors()

◆ quote() [1/2]

◆ quote() [2/2]

◆ record()

◆ renameConnection()

◆ reportAccess()

◆ roles()

◆ rollback()

◆ saveConnection()

◆ schema()

◆ sequenceExists()

◆ sessionId()

◆ setConnection()

◆ setDatabase()

◆ setDriver()

◆ setHost()

◆ setKeys()

◆ setPassword()

◆ setPort()

◆ setSchema()

◆ setUsername()

◆ tableExists()

◆ tablespaces()

◆ tableTablespace()

◆ terminal()

◆ timestampValue()

◆ tnsnames()

◆ touchActor()

◆ transaction()

◆ typeNextval()

◆ upsert()