TSTool / Command / OpenDataStore

Overview
Command Editor
Command Syntax
Examples
Troubleshooting
See Also

Overview

The OpenDataStore command dynamically opens a database datastore. This command is useful for a dynamic database connection that does not need to be open throughout a TSTool session, such as when working with file databases that do not require server software. If a matching open datastore exists, it will by default be closed before the datastore is reopened. See also the CloseDataStore command. This command has been fully enabled for Microsoft Access and SQLite databases. Other datastores should use configuration files that are processed when TSTool starts.

Datastores that are needed throughout a TSTool session should be configured with a datastore configuration file to connect at startup, which allows TSTool to initialize main user interface query filters.

The status of datastores can be shown in TSTool using the View / Datastores menu as shown in the following figure (the Status Message column on the far right, not visible in the figure, provides additional information about the datastore):

Datastore Information from View / Datastores (see full-size image)

Command Editor

The command is available in the following TSTool menu:

Commands / Datastore Processing

The following dialog is used to edit the command and illustrates the syntax of the command. The database engine (database software) dictates which datastore properties are used. Refer to the GenericDatabaseDataStore documentation for information.

OpenDataStore Command Editor using Properties (see full-size image)

OpenDataStore Command Editor using Configuration File (see full-size image)

Command Syntax

The command syntax is as follows:

OpenDataStore(Parameter="Value",...)

Command Parameters

Parameter	Description	Default
`DataStoreName`	The name of the database datastore to open.	None – must be specified.
`DataStoreDescription`	The description of the database datastore to open.	`DataStoreName`
`DataStoreType`	The datastore type, which indicates the software interface to use for the database, currently limited to: `GenericDatabaseDataStore`	`GenericDatabaseDataStore`
`DatabaseEngine`	The database software: `Access` - Microsoft Access `Derby` - Java built-in database `MySQL` `Oracle` `PostgreSQL` `SQLite` `SQLServer`	`SQLite`
`ServerName`	Database server name as recognized name on network or IP address. Additional details for `DatabaseEngine` are: `Access` - not currently used (may be used in the future for remote database access) `SQLite` - specify the relative or absolute path to the existing database file	None - must be specified
`DatabaseName`	Database name. Additional details for `DatabaseEngine` are: `Access` - specify the relative or absolute path to the existing database file `SQLite` - not used
`Login`	Login for account used to connect to the database, may be a shared service account. Additional details for `DatabaseEngine` are: `SQLite` - not used unless database is locked
`Password`	Password for account used to connect to the database, may be a shared service account. Additional details for `DatabaseEngine` are: `SQLite` - not used unless database is locked
`ConnectionProperties`	Connection properties in addition to the above standard properties. This is specified as a string to append to the end of the connection URL, for example: `?property1=value1&property2=value2` Consult the datatabase software's JDBC connection string documentation.
`IfFound`	Action to be taken if an open datastore is found: `Close`- close the datastore before reopening `Warn` - generate a warning message and do not reopen `Fail` - generate a failure message and do not reopen	`Close`

Examples

See the automated tests.

Troubleshooting

See the main TSTool Troubleshooting documentation.

MicroSoft Access Datastore Out of Memory

By default, the UCanAccess driver will read the entire database into memory, which is done to increase performance for relatively small databases. However, this can significantly slow down TSTool startup and may lead to an out of memory error. The OpenDataStore command reopens the datastore each time the commands are run and will be slow each time. To avoid loading the database into memory at the initial connection, use the parameter: ConnectionProperties=;memory=false. If the database is read into memory at startup, initial queries may be slow; however, the speed generally incresaes as more queries occur.

See the UCanAccess documentation for other connection string properties.

If it is desired to load the full database at startup and TSTool runs out of memory, it may be necessary to increase the maximum memory used by TSTool. See the Troubleshooting documentation.