The datastore class is used to access the BPS databases. More...

Public Member Functions
void	checkin ()
	Check in the user by creating a record in table t_actors.
void	checkout ()
	Check out the user by dropping the record in table t_actors.
void	commit ()
	Commit an open transaction.
void	connect ()
	Connect to database server using the current settings in the properties username, password, driver, database, host and port.
void	disconnect ()
	Disconnect from database server if currently connected.
void	dropConnection (Number aScopes=bps::Settings::LocalUserScope)
	Drop connection.
Number	fieldLength (String aTable, String aColumn)
	Get the maximum length of a certain field in the default schema.
Boolean	hasDivisionAccess (Number aDivisionKey)
	Checks if the current user is authorized for the division.
Boolean	hasPermission (String aPermission)
	Checks if the current user is authorized for the named permission.
Boolean	hasZoneAccess (Number aZoneKey)
	Checks if the current user is authorized for the zone.
Boolean	indexExists (String aName, String aSchema="")
	Check if a certain index exists.
Boolean	loadConnection (Number aScopes=bps::Settings::LocalScopes)
	Load connection settings.
Number	nextIdent (String aSeqenceName)
	Get the next sequence value.
Number	nextKey (String aName)
	Get the next unused key for a table.
void	purgeActors ()
	Purge actors which are no longer connected.
String	quote (String aText)
	Quote a literal text in single quotes to include it in a sql statement.
void	renameConnection (QString aConnection, Number aScopes=bps::Settings::LocalUserScope)
	Rename the connection.
bps::Access	reportAccess (Number aReportKey)
	Check access to a certain report.
void	rollback ()
	Roll back an open transaction.
void	saveConnection (Number aScopes=bps::Settings::LocalUserScope)
	Save the connection settings.
Boolean	sequenceExists (String aName, String aSchema="")
	Check if a certain sequence exists.
Boolean	tableExists (String aName, String aSchema="")
	Check if a certain table exists.
void	touchActor ()
	Update the actors timestamp.
void	transaction ()
	Begin a new transaction.
Boolean	viewExists (String aName, String aSchema="")
	Check if a certain view exists.

Properties
Number	actorKey
	Returns the actor's identifier (the primary key c_key in the t_actors table).
Boolean	connected
	Current connection status.
String	connection
	Name of the current connection.
Array	connections
	A list of all connections that have been declared in the BPS configuration program.
Date	currentTimestamp
	The current timestamp from the datastore.
String	database
	Database name for PostgreSQL, or TNS service name or SID for Oracle.
String	driver
	The database driver name as BPSPG for PostgreSQL, or BPSORA for Oracle.
String	host
	Either the database servers host name, or it's numeric IP address.
Boolean	inTransaction
	True when the connection is currently in an uncommitted transaction.
Boolean	oracle
	Current driver is Oracle (BPSORA).
Boolean	owner
	True when current user is the BPS schema owner.
String	password
	The database user's password.
Number	port
	Get host IP port number.
Boolean	postgres
	Current driver is PostgreSQL (BPSPG).
Array	roles
	All database roles.
String	schema
	The BPS schema name.
Number	sessionId
	Returns the session ID (the database internal identifier of the current session).
Array	tablespaces
	All tablespace names.
Array	tnsnames
	List of all Oracle TNS names.
Number	userid
	The userid, or -1 if not available.
Number	userKey
	Returns the user's identifier (the primary key c_key in the t_users table).
String	username
	The database user's name.
Array	users
	All database user names.

Detailed Description

The datastore class is used to access the BPS databases.

It supports connections to PostgreSQL and to Oracle and encapsulates a Qt database connection, adding generic methods for both database types supported by BPS.

Member Function Documentation

void bps::Datastore::checkin ( )

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.

Exceptions

Error thrown when not connected, no valid userid or general sql error.

void bps::Datastore::checkout ( )

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

Exceptions

Error thrown when not connected or general sql error.

void bps::Datastore::commit ( )

Commit an open transaction.

Exceptions

Error thrown when not connected or commit fails.

void bps::Datastore::dropConnection ( Number aScopes = bps::Settings::LocalUserScope )

Drop connection.

The database properties are removed from the settings.

Parameters

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

See Also: saveConnection()

Number bps::Datastore::fieldLength	(	String	aTable,
		String	aColumn
	)

Get the maximum length of a certain field in the default schema.

Parameters

[in]	aTable	Name of the table.
[in]	aColumn	Name of the column.

Returns: The length, or -1 when column or its field length is unknown.

Boolean bps::Datastore::hasDivisionAccess ( Number aDivisionKey )

Checks if the current user is authorized for the division.

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

Parameters

[in] aDivisionKey The key within table t_divisions.

Returns: True if the division access is granted.

Boolean bps::Datastore::hasPermission ( String aPermission )

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

Note: Permissions that were already queried before in the current session are cached in the datastore object for maximum speed. Therefore permission changes may not affect existing sessions witch queried them before the change.; When isOwner() is true, hasPermission() returns always true.

Parameters

[in] aPermission The permission name, for example settings.view

Returns: True if the permission is granted.

Boolean bps::Datastore::hasZoneAccess ( Number aZoneKey )

Checks if the current user is authorized for the zone.

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

Parameters

[in] aZoneKey The key within table t_zones.

Returns: True if the zone access is granted.

Boolean bps::Datastore::indexExists	(	String	aName,
		String	aSchema = `""`
	)

Check if a certain index exists.

Parameters

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

Exceptions

Error thrown when the query fails.

Returns: True if the index exists, false otherwise.

Boolean bps::Datastore::loadConnection ( Number aScopes = bps::Settings::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

[in] 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.

Number bps::Datastore::nextIdent ( String aSeqenceName )

Get the next sequence value.

Parameters

[in] aSeqenceName The name of the sequence.

Returns: Next identifier.

Number bps::Datastore::nextKey ( String aName )

Get the next unused key for a table.

Parameters

[in] aName 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.

void bps::Datastore::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

Error thrown when not connected or general sql error.

String bps::Datastore::quote ( String aText )

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

Takes care of any single quotes within the literal.

Parameters

[in] aText Literal text to be quoted.

Returns: Quoted literal text.

void bps::Datastore::renameConnection	(	QString	aConnection,
		Number	aScopes = `bps::Settings::LocalUserScope`
	)

Rename the connection.

Parameters

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

bps::Access bps::Datastore::reportAccess ( Number 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.

void bps::Datastore::rollback ( )

Roll back an open transaction.

Exceptions

Error thrown when not connected or rollback fails.

void bps::Datastore::saveConnection ( Number aScopes = bps::Settings::LocalUserScope )

Save the connection settings.

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

Parameters

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

See Also: dropConnection()

Boolean bps::Datastore::sequenceExists	(	String	aName,
		String	aSchema = `""`
	)

Check if a certain sequence exists.

Parameters

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

Exceptions

Error thrown when the query fails.

Returns: True if the sequence exists, false otherwise.

Boolean bps::Datastore::tableExists	(	String	aName,
		String	aSchema = `""`
	)

Check if a certain table exists.

Parameters

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

Exceptions

Error thrown when the query fails.

Returns: True if the table exists, false otherwise.

void bps::Datastore::touchActor ( )

Update the actors timestamp.

Will usually be called by license check routines.

Exceptions

Error thrown when not connected, actor token lost or invalid, or general sql error.

void bps::Datastore::transaction ( )

Begin a new transaction.

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

Exceptions

Error thrown when not connected or transaction cannot be started.

Boolean bps::Datastore::viewExists	(	String	aName,
		String	aSchema = `""`
	)

Check if a certain view exists.

Parameters

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

Exceptions

Error thrown when the query fails.

Returns: True if the view exists, false otherwise.

Property Documentation

Number bps::Datastore::actorKey

read

Returns the actor's identifier (the primary key c_key in the t_actors table).

A valid actorKey is only returned when checked in, otherwise Undefined is returned.

Boolean bps::Datastore::connected

read

Current connection status.

String bps::Datastore::connection

readwrite

Name of the current connection.

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

Array bps::Datastore::connections

read

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

Note: This property is static, e.g. must be accessed as bps.Datastore.connections instead of dbobj.connections

String bps::Datastore::database

readwrite

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.

String bps::Datastore::host

readwrite

Either the database servers host name, or it's numeric IP 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.

Boolean bps::Datastore::inTransaction

read

True when the connection is currently in an uncommitted transaction.

Boolean bps::Datastore::oracle

read

Current driver is Oracle (BPSORA).

Boolean bps::Datastore::owner

read

True when current user is the BPS schema owner.

String bps::Datastore::password

readwrite

The database user's password.

Number bps::Datastore::port

readwrite

Get host IP port number.

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

Boolean bps::Datastore::postgres

read

Current driver is PostgreSQL (BPSPG).

Array bps::Datastore::roles

read

All database roles.

Only available when connected as user with sufficient privileges (for example DBA or Superuser) to query the respective objects, otherwise nothing may be returned or an Error thrown.

String bps::Datastore::schema

readwrite

The BPS schema name.

Number bps::Datastore::sessionId

read

Returns the session ID (the database internal identifier of the current session).

A valid session ID is only returned when connected, otherwise Undefined is returned.

Array bps::Datastore::tablespaces

read

All tablespace names.

Only available when connected as user with sufficient privileges (for example DBA or Superuser) to query the respective objects, otherwise nothing may be returned or an Error thrown.

Array bps::Datastore::tnsnames

read

List of all Oracle TNS names.

Note: This property is static, e.g. must be accessed as bps.Datastore.tnsnames instead of dbobj.tnsnames; 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.

Number bps::Datastore::userid

read

The userid, or -1 if not available.

A valid userid is only present when the username is made up by {schema {userid}. The userid of the BPS owner is 0.

Number bps::Datastore::userKey

read

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

A valid userKey is only returned when checked in, otherwise Undefined is returned.

String bps::Datastore::username

readwrite

The database user's name.

Array bps::Datastore::users

read

All database user names.

Only available when connected as user with sufficient privileges (for example DBA or Superuser) to query the respective objects, otherwise nothing may be returned or an Error thrown.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

Property Documentation