The DDF Builder Graphical User Interface

DDF Builder provides a graphical user interface (GUI). The GUI includes various editors, views, and wizards with which you display and work with objects.

The object being edited is represented by a tab on top of the editor. The tab contains the name of the object. Data modified within an editor must be explicitly saved.

Note
Currently, only a single file can be edited at a time. Save any editing changes before attempting to edit or view a different file. Unsaved changes are lost if you change file contexts without first saving.

Views can be opened only one at a time. Actions performed within a view are applied immediately. No explicit save is required.

Wizards contain one or more dialogs and guide you through a task to obtain a specific result.

The following table lists the editors, views, and wizards that DDF Builder provides.

Table 1-1 Editors, Views, and Wizards Within DDF Builder
GUI Component	Editor	View	Wizard	Description
Data Sources Explorer				Data Sources Explorer
Btrieve File Editor				Btrieve File Editor
SQL Table Editor				SQL Table Editor
SQL Editor				"SQL Editor" chapter in Pervasive.SQL User's Guide1
View File Statistics				View File Statistics
Grid				"Grid Window View" in Pervasive.SQL User's Guide1
Text				"Text Window View" in Pervasive.SQL User's Guide1
Outline				"Outline Window View" in Pervasive.SQL User's Guide1
Add Database				Add Database
Add Server				Add Server
Copy SQL Definition				Copy SQL Definition
Export Btrieve Schema				Export Btrieve Schema
Import Btrieve Schema				Import Btrieve Schema
Export Data				Export Data
Import Data				Import Data
1DDF Builder and PCC share common components. Because of this, some editors, views, and wizards are documented in other Pervasive.SQL books and not in DDF Builder User's Guide.

Data Sources Explorer

DDF Builder uses a file explorer-like motif-a tree of objects-referred to as the "Data Sources Explorer." Examples of objects include databases, Btrieve files, and SQL tables. The tree objects are referred to as "nodes."

Figure 1-2 Data Sources Explorer

Nodes can be expanded or collapsed to reveal or conceal subordinate nodes. The expand/collapse icon appears to the left of the node.

Performing Actions Based on Nodes

Most tasks in DDF Builder are initiated by selecting a command relevant to a node in Data Sources Explorer. The following tables direct you to tasks based on what action you want to take. The tables are categorized by areas of interest:

Btrieve Files

Data

Database

Data Sources Explorer

Online Help

Server on Which a Database Engine Is Running

SQL Queries

SQL Tables

Note
You can use DDF Builder with a database that has security enabled, but the utility requires that you log in to the database.

Btrieve Files

If You Want To...	Then...	Notes
Create a new file with an editor	Right-click a data path under the Data Paths node. Click Create Btrieve File.	DDF Builder does not automatically create DDFs for the new file. See Btrieve File Editor .
Export the file structure to a text file	Right-click a Btrieve file name under the Data Paths node. Click Export Btrieve Schema.	The data in the Btrieve file is not exported. See Export Btrieve Schema .
Create a new file based on the structure of another Btrieve file	Right-click a data path under the Data Paths node. Click Import Btrieve Schema.	See Import Btrieve Schema .
Specify a directory where you want a Btrieve file located	Right-click Data Paths or a path listed under Data Paths. Click Create Data File Directory.	Any DDFs that you create for the Btrieve file are located in the original data path for the database. This is because all SQL tables are defined in the same set of DDFs. See Create Data File Directory .
Remove a data path directory from Data Sources Explorer	Right-click a data path under the Data Paths node. Click Delete.	Neither the directory nor any files in it are deleted from physical storage.

Data


If You Want To...	Then...	Notes
Export data from a Btrieve file to a text file	Right-click an SQL table name. Click Export Data.	The names appear under the SQL Tables node, or under a Btrieve file name (Data Paths node) if the Btrieve file has DDFs. See Export Data and Import Data .
Import data from a text file into a Btrieve file	Right-click an SQL table name. Click Import Data.
Specify in Data Sources Explorer a directory where you want data files to reside or where they already reside	Right-click Data Paths or a path listed under the Data Paths node. Click Create Data File Directory.	See Create Data File Directory .
Remove from Data Sources Explorer a directory where data files reside	Right-click Data Paths or a path listed under the Data Paths node. Click Delete.	Neither the directory nor any files in it are deleted from physical storage.

Database


If You Want To...	Then...	Notes
Create a new database	Right-click Database node. Click Create New Database.	See Add Database .
Remove a database from Data Sources Explorer	Right-click Database node. Click Delete.	The database is not deleted from physical storage

Data Sources Explorer


If You Want To...	Then...	Notes
Update the tree to show additions to or deletions from a node(s)	Right-click on any node except for the name of an SQL table. Click Refresh.	The context of the Refresh command applies to the node from which you invoke it. If you want to refresh all nodes in Data Sources Explorer, execute the command from the Engines node (the "top" of the tree).

Online Help


If You Want To...	Then...	Notes
Access the JavaHelp	Press F1 within an editor, view, or wizard (or click Help 4 Help Contents).	See the Note in How Do You Access the Documentation? .

Server on Which a Database Engine Is Running


If You Want To...	Then...	Notes
Add a server to Data Sources Explorer	Right-click Engines node (or right-click a server name under the Engines node). Click Add Server.	You identify a server by its network name or by its IP address. Optionally, you may specify the type of encoding. See Add Server .
Remove a server from Data Sources Explorer	Right-click a server name under the Engines node. Click Delete.

SQL Queries


If You Want To...	Then...	Notes
Execute a SELECT statement for all records in an SQL table (SELECT * FROM) or Access an editor in which you can type SQL statements to execute against an SQL table	Double-click an SQL table name or right-click the table name then click SQL Editor.	By default, SQL Editor executes a SELECT * FROM statement when it opens. SQL table names display as subordinate nodes under SQL Tables and under the Btrieve file name (provided the Btrieve file has DDFs). See SQL Editor .
Execute SQL statements in SQL Editor or in Outline View	See "Execution Tasks" in Pervasive.SQL User's Guide.	You can perform numerous tasks with SQL Editor. See "SQL Editor Tasks" in Pervasive.SQL User's Guide for a complete list.

SQL Tables

If You Want To...	Then...	Notes
Create a new table with an editor	Right-click a Btrieve file name under the Data Paths node. Click Create Table Definition.	You can create one or more SQL tables for a Btrieve file. Each SQL table appears as a subordinate node under the Btrieve file name. See SQL Table Editor .
Create a new table based on the schema of another SQL table	Right-click an SQL table name. Click Copy SQL Definition.	The table names appear under the SQL Tables node, or under a Btrieve file name (Data Paths node) if the Btrieve file has DDFs. See Copy SQL Definition .
Modify a table	Right-click an SQL table name. Click Edit Table Definition.	The names appear under the SQL Tables node, or under a Btrieve file name (Data Paths node) if the Btrieve file has DDFs. See SQL Table Editor .
Remove a table from Data Sources Explorer	Right-click an SQL table name. Click Delete.	The table is not deleted from physical storage. The table names appear under the SQL Tables node, or under a Btrieve file name (Data Paths node) if the Btrieve file has DDFs.
View statistics for the Btrieve file with which the SQL table is associated	Right-click an SQL table name or a Btrieve file name. Click View File Statistics.	The table names appear under the SQL Tables node, or under Data Paths node. See View File Statistics .

Btrieve File Editor

Btrieve File Editor creates the file and key specification for a new Btrieve file. DDFs are not automatically created for the new file. You must add them separately, if you want them (see SQL Tables ).

How To Access

In Data Sources Explorer, right-click on a data path under the Data Paths node, then click Create Btrieve File.

A Btrieve file must be located on physical storage, which is why the editor is invoked from a data path.

Features

Btrieve File Editor contains two tabs: one for specifying the characteristics of the file and one for specifying characteristics of the keys. The Apply button on each tab saves the specifications for that tab. Click File 4 Save to save the editing changes for both tabs.

At a minimum, you must supply a file name and a record length to create a Btrieve file. You specify these on the File Specification tab.

As stated in What Do You Need To Know Before Using DDF Builder? , this book assumes that you thoroughly understand the transactional access method and relational concepts. This section does not attempt to explain the controls on the Btrieve File Editor tabs. The following table provides links to related documentation if you need to further your understanding of Btrieve files.

Table 1-2 Related Documentation for Creating Btrieve Files
Tab	Database Engine Documentation	Software Development Kit (SDK) Documentation1
File Specifications	In Advanced Operations Guide: "File Size" "Owner Names and Security" "System Data" "File Information Editor"	In Pervasive.SQL Programmer's Guide: "Btrieve Fundamentals" chapter "Designing the Database" chapter
Key Specifications	In Advanced Operations Guide: "Methods for Handling Duplicate Keys"	In Pervasive.SQL Programmer's Guide: "Btrieve Fundamentals" chapter "Designing the Database" chapter "Working with Records" chapter "Creating a Database" chapter
1By default, the SDK JavaHelp is installed with the database engine product. Refer to the Readme file provided with the database engine for how to access the SDK documentation.

Restrictions

Only one Btrieve file can be created at a time. On the Key Specification tab, click Apply after adding or changing each segment of a segmented key. This saves the changes to each segment before you create or edit the next segment.

See tracking numbers 52009 and 52284 in the "Known Issues" section of the readme file.

SQL Table Editor

SQL Table Editor creates or changes the schema for SQL metadata. Note that SQL Table Editor is conceptually similar to Table Editor in Pervasive Control Center (PCC). See "Table Editor" chapter in Pervasive.SQL User's Guide.

How To Access

Perform one of the following actions in Data Sources Explorer:

Right-click a Btrieve file name then click Create Table Definition.

Right-click an SQL table name then click Edit Table Definition.

Features

SQL Table Editor provides three different views of the metadata as explained in the following table.


Metadata View	Description
Hex and ASCII	Simultaneously shows the Hex and ASCII values of data records. You access the Hex and ASCII views on the Table tab of the editor. See callouts 1, 4, and 5 in Figure 1-3. Note that if you click on a cell in the Field Definition View (Figure 1-4), the Hex/ASCII display (callout 1) highlights the bytes for that field. The green highlighted values indicate where each field within the record begins. You navigate among data records with the buttons to the right of the Hex/ASCII display. See callout 2 in Figure 1-3. "File Position" shows which record out of the total number of records is being displayed. For example, "1/1315" indicates that record one is displayed out of a total of 1,315 records. If the total record length still has unassigned space for columns, you can create a column with the "Create" button to the right of the Hex/ASCII display (see callout 3 in Figure 1-3). The new column is added to the bottom of the fields displayed in the Field Definition View. See Figure 1-4.
Definitions	Shows the schema structure of the fields and the index. You access the fields structure on the Table tab of the editor and the index structure on the Index tab. See Figure 1-4 and Figure 1-5. Note that you must check mark the "Incl" (Include) column for each field that you want to include in the SQL table definition. Note that the Indexes tab is read-only. You cannot change information on that tab. Index additions or changes to an SQL table must be made with Pervasive Control Center. See "Table Editor" chapter in Pervasive.SQL User's Guide.
Formatted data	Shows the data in a human-readable layout. You navigate among the data records with the buttons on the tab. See Figure 1-6. Note that the tab shows how many records are being displayed out of the total number of records. For example, "0-24/1315" indicates that the first 25 records are displayed out of a total of 1,315 records.

Figure 1-3 Hex and ASCII Views in SQL Table Editor

Figure 1-4 Field Definition View in SQL Table Editor

Figure 1-5 Index Definition View in SQL Table Editor

Figure 1-6 Formatted Data View in SQL Table Editor

Restrictions

You cannot change the size, offset, or data type for a column if the column has keys defined for it in the Btrieve file. DDF Builder does not permit changing the layout structure of an existing Btrieve file.

The Indexes tab is read-only. You cannot change information on that tab. Index additions or changes to an SQL table must be made with Pervasive Control Center. See "Table Editor" chapter in Pervasive.SQL User's Guide. See tracking number 52287 in the "Known Issues" section of the readme file.

SQL Editor

SQL Editor allows you to run Structured Query Language (SQL) statements against a Pervasive.SQL database, provided the database contains SQL tables. This editor is shared with Pervasive Control Center (PCC). See "SQL Editor" chapter in Pervasive.SQL User's Guide.

View File Statistics

View File Statistics displays the file and key specifications for a Btrieve file. The information is read-only; you cannot change it in the view.

How To Access

In Data Sources Explorer, right-click a Btrieve file name or an SQL table name, then click View File Statistics.

Features

View File Statistics provides a convenient way to look at the structural characteristics of a Btrieve file. This is particularly useful if you are considering exporting the file schema but are unfamiliar with the file and key specifications.

Restrictions

Currently, only a single file can be viewed at a time. Also, if you are editing a file and want to view another file, save any editing changes before attempting to view the other file. Unsaved changes are lost if you change file contexts without first saving.

See tracking number 52009 in the "Known Issues" section of the readme file.

Add Database

The Add Database Wizard creates a new database. This wizard is shared with Pervasive Control Center (PCC). See "Pervasive.SQL Databases" chapter in Advanced Operations Guide, particularly "New Database GUI Reference."

Add Server

The Add Server Wizard permits DDF Builder to identify and interact with machines on which a Pervasive.SQL database engine is running. This wizard is shared with Pervasive Control Center (PCC). See "Database Engines" in Pervasive.SQL User's Guide.

Copy SQL Definition

The Copy SQL Definition Wizard creates a new SQL table based on the schema of an existing SQL table. The existing SQL table is called the "source" table. The wizard also creates a Btrieve file with which the new SQL table is associated.

How To Access

In Data Sources Explorer, right-click an SQL file name, then click Copy SQL Definition.

Features

If the source table contains data, the wizard provides a preview of the formatted data. Note, however, that the wizard does not include the data in the new table. You can, if you want, export the data from the source table and import it into the new table. See Export Data and Import Data .

The wizard requires that you specify the following:

Which columns of data you want to include in the new table.

Server on which the database engine is running.

Database in which you want to include the new table.

Name of the new table (which, by default, becomes the name of the associated Btrieve file).

Export Btrieve Schema

The Export Btrieve Schema Wizard creates a file of XML content that specifies the schema of a source Btrieve file. You can use the XML file to create a new Btrieve file based on the structure of an existing Btrieve file. See Import Btrieve Schema .

Data from the source file is not exported. If you want to export data, see Export Data .

How To Access

In Data Sources Explorer, right-click a Btrieve file name under the Data Paths node, then click Export Btrieve Schema.

Features

By default, the wizard uses the source file name for the exported XML file name. The wizard adds a file extension of "xml" and locates the output file in the same directory as the source file. You can change the name and location of the XML output file if you choose.

The wizard also provides a preview of the XML content before you export it.

Import Btrieve Schema

The Import Btrieve Schema Wizard creates a Btrieve file based on the structure of another Btrieve file. The structure must be a schema of the source file in XML format. See Import Btrieve Schema .

How To Access

In Data Sources Explorer, right-click on a data path under the Data Paths node, then click Import Btrieve Schema.

A Btrieve file must be located on physical storage, which is why the wizard is invoked from a data path.

Features

Since the wizard is invoked from the context of a known data path, you do not specify a path for "Target File," only a file name. The file name length must be less than or equal to 255 bytes. The file name cannot contain spaces unless the Embedded Spaces client configuration option is enabled. The option is enabled by default. See "Embedded Spaces" section in the "Configuration Reference" chapter in Advanced Operations Guide.

Export Data

The Export Data Wizard exports data from a Btrieve file to a text file. A combination of carriage return and line feed delimits records.

How To Access

In Data Sources Explorer, right-click a Btrieve file name under the Data Paths node, then click Export Data.

Features

The wizard provides a preview of the formatted data before you export it. In addition, you can specify the following:

Which columns of data you want to export.

File name that contains the exported data. If you include a path with the file name, the directory or directories in the path must already exist.

Field delimiter.

Import Data

The Import Data Wizard reads delimited data from a text file and adds the data to a Btrieve file. The data must use a field delimiter of the comma, colon, or tab character. A combination of carriage return and line feed must delimit records.

How To Access

In Data Sources Explorer, right-click an SQL table name then click Import Data.

Data resides within the pages of a Btrieve file. The reason that you invoke the Wizard from the name of an SQL table has to do with presenting the data in a readable format in the DDF Builder interface. For example, double-clicking an SQL table name in Data Sources Explorer displays the data through SQL Editor.

Features

The wizard allows you to specify the following:

Text file that contains the data to import.

Which columns of data you want to import.

Field delimiter.

Server on which the database engine is running.

Database in which the table to receive the data resides.

Table to receive the imported data. The table must already exist.

Create Data File Directory

Create Data File Directory adds a data path to Data Sources Explorer. A data path represents a location on physical storage where Btrieve files reside. Each Pervasive.SQL database must have at least one data path identified for it.

Any DDFs that you create for Btrieve files are located in the original data path for the database. This is because all SQL tables for an entire database are defined in the same set of DDFs.

How To Access

In Data Sources Explorer, right-click Data Paths or a database name under Data Paths, then click Create Data File Directory.

Features

The existing directory can be empty or contain files.

Use the Delete command to remove a data path from Data Sources Explorer (right-click Data Paths or a database name, then click Delete). The directory is not deleted from physical storage.