Using the all-Java DataStore Explorer, you can:
There are three ways to launch the DataStore Explorer:
DataStore Explorer requires the following JARs:
The main class for the DataStore Explorer is com.borland.dbtools.dsx.DataStoreExplorer, and it takes one command-line argument for the location of the online help. The command line for starting the server (after setting the classpath) is:
java com.borland.dbtools.dsx.DataStoreExplorer -h=<onlineHelpDir>
Most DataStore operations in the DataStore Explorer require a DataStore file. You can create a new one, or open an existing DataStore file. You may have more than one DataStore file opened at the same time.
To create a new DataStore file:
To open an existing DataStore file:
The DataStore Explorer will keep track of the five most recently opened files. You can open them directly from the File menu.
Transactional DataStore files require a user name. You may also want to open a DataStore file in read-only mode to temporarily bypass transaction support, or to attempt to open a file that has been damaged. These settings are made by selecting View|Options to open the Options dialog box:
If the DataStore file is already marked open--which will happen if the DataStore file was not closed properly--you will get the following dialog box, asking if you want to try and open the DataStore anyway:
javaw
processes):
When a DataStore file is opened, its directory is displayed in a tree control on the left. Each open DataStore file is a node directly off the root node. Information about the DataStore file is displayed in the viewer area on the right:
You can view this information at any time by selecting the node in tree that contains the DataStore file name.
The DataStore directory is displayed in the tree control on the left, using forward slashes ("/") in the stream names to synthesize a hierarchical structure. In addition, known stream types, such as tables and text files, are placed under a corresponding node in the tree. You may use the View|Expand All and View|Collapse All menu items to help manage the directory tree.
When you select a stream in the tree, the stream contents will be displayed if there is an appropriate viewer. There is a built-in viewer for table streams:
The figure shows a DataStore file with an "Accounts" table in the root directory. The View page displays the contents of the table, with navigation controls. You can search, edit, add, and delete data. The Info tab displays information on the columns in the table.
File streams are handled by their file-name extension. DataStore Explorer ships with viewers for the following file types:
For example, here is the text file "demo/explor.txt":
This is the image file "demo/duke.gif":
Use this operation to rename a stream, or move a stream to another directory.
Deleting a stream marks the blocks it used as available. It is possible to undelete a stream, although some of the blocks may have been reclaimed by other streams. See "How DataStore reuses deleted blocks" for more details.
If a deleted stream is visible in the directory tree, it may be undeleted. You cannot undelete a stream if there is another active stream with the same name in the same directory, because you cannot have two streams with the same name.
Undeleting a stream is not guaranteed to recover all the data in the stream. See "How DataStore reuses deleted blocks" for more details.
You may use the DataStore Explorer to copy streams to another DataStore file, much like the DataStoreConnection.copyStreams method. While you cannot use this option to make copies of streams within the same DataStore file, the DataStore Explorer will automatically create a new DataStore file for you.
To verify the structure and contents of the DataStore, select Tools| Verify DataStore or click the Verify DataStore toolbar button.
The entire store is verified and the results are displayed in the Verifier Log window. After you've closed the log window, you view it again by selecting View|Verifier Log.
You can make a non-transactional DataStore transactional with the DataStore Explorer:
To modify transaction settings for a DataStore:
You can check if a DataStore is transactional by checking the TxManager menu. If the Enabled menu option is checked, the DataStore is transactional. If the menu option is disabled, the DataStore is not transactional.
To make a transactional DataStore non-transactional, select
TxManager|Enabled. This immediately removes transaction support.
When you are done with the DataStore file, you should close it to ensure that all changes are written properly. You do not have to close open DataStore files before exiting the DataStore Explorer; this is done automatically.
To close the current DataStore file, select File|Close. To close all open DataStore files, select File|Close all.
When the DataStore is used as a persistent data cache (which means that the data isn't lost when the application is shut down), it's the application's job to contain the logic to manipulate the data. This logic may include code to connect to a server, SQL statements to load data from the server into datasets, and code to save updates back to the server, in addition to whatever presentation and manipulation of the data the application allows.
The DataStore Explorer can take the place of a simple application. Within the Explorer, you can define a connection to a database, define SQL queries against tables in that database, run the queries to produce datasets that are saved in the DataStore, edit the datasets, save your changes back to the database, and rerun queries to get the latest server data--all without writing code.
This same mechanism can be used to simply import data from another database into a DataStore. Because the query and connection information used to import the data is saved, you can easily reimport the data if desired.
This discussion of ways to store and execute queries may bring to mind the distinction between queries that run against a server to produce store datasets and queries against store tables that produce new tables (which may or may not be saved in a DataStore). In the former case, the DataStore provides persistent storage for tables produced by querying a server; in the latter, the DataStore itself functions as a server and, like other servers, is accessed by running SQL queries through a JDBC connection.
Here we introduce a third, complementary use of the DataStore: as a place to store connection information and queries. These queries may be of either type just mentioned; they may get their data either from server tables or from datasets in a DataStore. In either case, the result of running a query through the DataStore Explorer is always another store table.
When using the Explorer to manage queries, it is important to understand the objects involved and how they are related:
The user interface for saving changes and refreshing data reflects this organization, as described in "Saving changes and refreshing data".
The connection information and query SQL statements, which are usually embedded in your application code, are saved in the DataStore in two special tables named "SYS/Connections" and "SYS/Queries".
Keep in mind that although the DataStore Explorer can execute queries and save changes to dataset back to server tables, it has no application-specific logic. Presentation of data is limited to a simple tabular display. Data entry support and data validation that is usually provided by code in a data module won't be performed. If you edit data in the Explorer, you won't see any edit masks or pick lists, won't be prevented from entering values that violate minimum or maximum constraints, and may be able to leave required fields empty or violate referential integrity constraints. (Constraints defined in the server will be enforced, but not until you attempt to save your changes.) The Explorer is useful for working with test data or making small, careful changes to production data, but is not a substitute for a data module written with the specific integrity requirements of its datasets in mind.
To use the DataStore Explorer to manage queries or to import a table from another database, you must have a DataStore open. Then, to define a query, select Tools|Import|Tables. The Import Tables dialog box opens:
The first time you define a query, there won't be any connections to associate it with. The New button next to the Connection combobox lets you define a new connection through the New JDBC Connection dialog box.
Enter the same parameters as you would in the Connection property editor for a database: JDBC Driver Name, URL, Username, and Password. You may also specify extended properties for the connection. When defining queries later, you can choose an existing connection or define a new one.
Once you have a connection to a database, a list of available tables are shown. After selecting the desired tables, you can click Finish to simply import those tables. If you want more control over what is imported, click Next to go to the next page:
This page lists all the tables that will be imported:
Click Finish to import the data and store the queries.
The first time you open the Import Tables dialog box, two empty table streams, named "SYS/Connections" and "SYS/Queries", are created. Queries that you create go into "SYS/Queries", and connections you create go into "SYS/Connections". When you finish defining the first query by clicking OK, each table will have one row.
To maintain connections or queries, select the "Connections" or "Queries" table under the "SYS/DataStore Queries" branch in the Explorer tree. You can:
Right after saving a new query, the DataStore Explorer will attempt to execute that query to fetch its data. You will see the tree pane of the Explorer update to show the newly imported table, using the store name you specified. After that, you can re-execute the query to refresh the data manually. Note that refreshing data will discard any unsaved changes.
To execute a query, select it in the "SYS/Queries" table, click Refresh Table, and respond "Yes" to the warning about unsaved changes.
View a table by selecting it in the Explorer's tree. On the right side of the Explorer, you see the table in a grid. Choose the Info page to see the dataset's column names and their data types. You can edit the table on the View page, but be sure you understand the risk to data integrity first.
After editing, you can save your changes or discard them. You discard changes by refreshing the dataset, and responding "Yes" to the warning about unsaved changes.
You can save changes and refresh data on three different levels:
To refresh or save changes from a single table, select the row in
"SYS/Queries" for the query that creates that table. Buttons labeled Refresh Table and Save Table Changes are available, indicating that only the table provided by that query will be affected.
To refresh or save changes from all the tables for a connection to a database, select that connection's row in the "SYS/Connections" dataset. Buttons labeled Refresh Connection Queries and Save Connection Changes are available, indicating that all tables produced by querying that connection's database will be affected.
To refresh or save changes from all the datasets for which you've defined queries through the DataStore Explorer, select Tools|Refresh DataStore or Tools|Save DataStore Changes. These commands re-execute every query or save changes for every dataset with an associated query, for those queries that have their Enable Refresh on Tools Menu and Enable Save on Tools Menu options enabled. You can change these settings for each query in the "SYS/Queries" table.
In addition importing tables from other databases, the DataStore Explorer makes it easy to import delimited text files as table streams, and arbitrary files as file streams.
The contents of the text file must be in the delimited format that DataExpress exports to, and there must be a SCHEMA file with the same name in the directory to define the structure of the target dataset.
SCHEMA files (which end with a .schema
file-name extension) are created when exporting a dataset to a text file through the com.borland.dx.TextDataFile.save method. It's recommended that you export data from your dataset to generate the SCHEMA file. But to give you an idea of what one looks like, here is one for a simple three-column dataset:
[] FILETYPE = VARYING FILEFORMAT = Encoded ENCODING = Cp1252 DELIMITER = " SEPARATOR = 0x9 FIELD0 = ID,Variant.INT,-1,-1, FIELD1 = Name,Variant.STRING,-1,-1, FIELD2 = Update,Variant.TIMESTAMP,-1,-1,
This SCHEMA file defines the double quote as the string delimiter, and the tab character as the field separator. There are three columns, an integer, a string, and a timestamp.
Once you have a SCHEMA file to accompany the text file, to import the text file as a table:
To import a file as a file stream,
You may execute arbitrary SQL statements with the currently selected DataStore file as the database. This requires that the DataStore file is transactional, or that it is opened in read-only mode. To execute SQL, select Tools|SQL or click the SQL toolbar button, which opens the SQL dialog box:
You may type in SQL statements directly, or execute files containing SQL. Statements that you type are recorded, and you may scroll through them with the Previous and Next buttons to modify and reexecute recorded statements. Result sets returned by SQL statements are displayed in the lower half of the dialog box.
The DataStore Explorer also provides a few functions that do not have a direct analogue in the DataStore API.
Packing the DataStore file renames the existing file (by prepending "BackupX_of_", where X is an auto-incrementing number), and copies all the streams from the old file to the new copy of the current file.
To pack the DataStore, select Tools| Pack DataStore.
The DataStore Explorer will open older versions of the DataStore file format. The only available operation is to upgrade the file to the current version. Upgrading the DataStore file renames the existing file (by prepending "BackupX_of_", where X is an auto-incrementing number), and copies all the streams from the old file to a new version of the current file.
To upgrade the DataStore, select Tools |Upgrade DataStore. When the current DataStore is the current version, this menu option is disabled.
You can use the DataStore Explorer to delete a DataStore file, and its transaction log files. To use this feature, you must open the DataStore file to delete. Then select Tools| Delete DataStore. You will get a confirmation dialog box. Click Yes to delete the DataStore file(s).
pubsweb@borland.com
Copyright © 1999, Inprise Corporation. All rights reserved.