class Database

A session’s built-in database or a BDE database alias, which gives access to tables.

Syntax

[<oRef> =] new Database( )

<oRef>

A variable or property—typically of a Form or Report object—in which to store a reference to the newly created Database object.

Properties

The following tables list the properties and methods of the Database class. (No events are associated with this class.) For details on each property, click on the property below.

Property	Default	Description
active	false	Whether the database is open and active or closed
baseClassName	DATABASE	Identifies the object as an instance of the Database class
cacheUpdates	false	Whether to cache changes locally for batch posting later
className	(DATABASE)	Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName
databaseName	Empty string	BDE alias, or empty string for built-in database
driverName	Empty string	Type (table format or server) of database
handle		BDE database handle
isolationLevel	Read committed	Isolation level of transaction
loginDBAlias	Empty string	The currently active database alias, or BDE alias, from which to obtain login credentials (user id and password) to be used in activating an additional connection to a database.
loginString	Empty string	User name and password to automatically try when opening database
name	Empty string	The name of custom object
parent	null	Container form or report
session	Default session	Session to which a database is assigned
share	All	How to share the database connection
Method	Parameters	Description
abandonUpdates( )		Discards all cached changes
applyUpdates( )		Attempts to post cached changes
beginTrans( )		Begins transaction; starts logging changes
close( )		Closes the database connection (called implicitly when active is set to false)
commit( )		Commits changes made during transaction; ends transaction
copyTable( )	<source name expC>, <destination name expC>	Makes a copy of a table in the same database
createIndex( )	<table name expC>, <.dbf index oRef>,	Creates an index in the table
dropIndex( )	<table name expC>, <index name expC>	Deletes index from table
dropTable( )	<table name expC>	Deletes table from database
emptyTable( )	<table name expC>	Deletes all records from a table
executeSQL( )	<expC>	Pass-through SQL statement
getSchema( )	"DATABASES" \|"TABLES" \|"PROCEDURES" \| "VIEWS"	Retrieves information about a database
open( )		Opens the database connection (called implicitly when active is set to true)
packTable( )	<table name expC>	Removes deleted records from DBF or DB table and reconsolidates disk usage
reindex( )	<table name expC>	Rebuilds indexes for DBF or DB table
renameTable( )	<old name expC>, <new name expC>	Renames table in database
rollback( )		Undoes changes made during transaction; ends transaction
tableExists( )	<table name expC>	Whether or not specified table exists in database or on disk

Description

All sessions, including the default session you get when you start dBASE Plus, contain a default database, which can access the Standard table types, DBF (dBASE) and DB (Paradox) tables, without requiring a BDE alias. Whenever you create a Query object, it is initially assigned to the default database in the default session. If you want to use Standard tables in the default session, you don’t have to do anything with that Query object’s database or session properties. If you want to use a Standard table in another session, for example to use DBF or DB table security, assign that session to the Query object’s session property, which causes that session’s default database to be assigned to that Query object. Default databases are always active; their active property has no effect.

You may also set up a BDE alias to access Standard tables. By referring to your Standard tables through a database alias, you can move the tables to a different drive or directory without having to change any paths in your code. All you would have to do is change the path specification for that alias in the BDE Administrator. When using a BDE alias with Standard tables, you must explicitly give the directory path when opening a table in a different directory. You cannot use relative pathing from the directory specified by the alias. For example, if your alias is set to:

C:\MyTables

and you want to use a table somewhere else on the hard drive, such as:

C:\MyTables\TestDir

you must specify the full path without the alias:

C:\MyTables\TestDir or C:\TestDir

For all non-Standard table types, you will need to set up a BDE alias for the database if you haven’t done so already. After creating a new Database object, you may assign it to another session if desired; otherwise it is assigned to the default session. Then you need to do the following:

Assign the BDE alias to the databaseName property.

If you need to log in to that database, either set the loginString property if you already know the user name and password; or let the login dialog appear.

Set the active property to true. This attempts to open the named database. If it’s successful, you now have access to the tables in the database. Methods associated with a Database object will not function properly when the database is not active.

Each database, including any default databases, is able to independently support either transaction logging or cached updates. Transaction logging allows changes to be made to tables as usual, but keeps track of those changes. Those changes can then be undone through a rollback( ), or OK’d with a commit( ). In contrast, cached updates are not written to the table as they happen, but are cached locally instead. You can then either abandon all the updates or attempt to apply them as a group. If any of the changes fail to post—for a variety of reasons, like locked records or hardware failures—any changes that did take are immediately undone, and the updates remain cached. You can then attempt to solve the problem and reapply the update, or abandon the changes. You may also want to use cached updates to reduce network traffic.

Each non-Standard database is responsible for its own transaction processing, up to whatever isolation level it supports. For Standard tables opened through the default database, if you want simultaneous multiple transactions, you need to create multiple sessions, because each database object can support only one active transaction or update cache, and there is only one default database per session.

All Database objects opened by the Navigator are listed in the databases array property of the _app object. The default database of the default session is _app.databases[1].

A Database object also encapsulates a number of table maintenance methods. These methods occur in the context of the specified Database object. For example, the copyTable( ) method makes a copy of a table in the same database. To use these methods on Standard tables, call the methods through the default database of the default session; for example,

_app.databases[ 1 ].copyTable( "Stuff", "CopyOfStuff" )