GUI Reference
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.
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.
SQL Editor chapter in PSQL User's Guide1
Grid Window View in PSQL User's Guide1
Text Window View in PSQL User's Guide1
Outline Window View in PSQL User's Guide1
*2
1DDF Builder and PCC share common components. Because of this, some editors, views, and wizards are documented in other PSQL books and not in DDF Builder User’s Guide.
2The Check Database and Check Table action is similar to a wizard except that you make your selection on Data Sources Explorer rather than on a dialog. The result of checking consistency displays in a manner similar to a view, however.
Welcome Page
Each time you start DDF Builder, the Welcome page displays. From this page you can quickly access a variety of information and perform common tasks.
Common tasks you can perform from this page are adding a new server and creating a new database.
A variety of information is also available from this page. The page contains several links which provide quick access to various pieces of information. The information provided in the Welcome page includes the following:
How to Access
If you have closed the Welcome page in DDF Builder, you can view it again at any time. From the DDF Builder menu bar, click HelpWelcome to display the Welcome page.
Figure 2 DDF Builder Welcome Page
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, data paths, Btrieve files, and SQL tables. The tree objects are referred to as nodes.
Figure 3 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 if a subordinate node is available.
Btrieve File Editor
Btrieve File Editor creates the file and key specification for a new Btrieve file. DDFs are not automatically created for a new Btrieve file. You must add them separately, if you want them (see SQL Tables).
*Tip: To create a Btrieve file and its DDFs, use the SQL Editor in the PSQL Control Center.
How To Access
In Data Sources Explorer, right-click on a data path under the Data Paths node, then click Create Btrieve File.
Figure 4 Btrieve File Editor
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 FileSave 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 Specifications tab.
As stated in What You Need to Know, 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.
 
In Advanced Operations Guide:
In PSQL Programmer's Guide:
In Advanced Operations Guide:
In PSQL Programmer's Guide:
Restrictions
Only one Btrieve file can be created at a time. On the Key Specifications 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.
Table Definition Editor
The Table Definition Editor creates new or changes existing schemas for SQL metadata. Note that Table Definition Editor is conceptually similar to the Table Editor in PSQL Control Center (PCC). See “Table Editor” chapter in PSQL User's Guide.
How To Access
Perform one of the following actions in Data Sources Explorer:
Figure 5 Table Definition Editor
Features
The Table Definition Editor, like the Table Editor in PSQL Control Center (PCC), uses tabs or pages to display different views of table definition information. Some of the pages contain read-only information, while others provide the work area in which you will create and modify your table definitions.
Restrictions
You cannot change the size, offset, or data type for a column if the column is used in a key in the Btrieve file. DDF Builder does not change nor permit changing the layout structure of an existing Btrieve file.
Table Page
The Table Page in the Table Definition Editor provides two primary views of the metadata—raw data view and grid data view. These two views, respectively, display the table definition information as it is in the Btrieve file and the SQL table.
How To Access
Select the Table page by clicking the Table tab at the bottom of the Table Definition Editor.
Figure 6 Table Definition Editor Table Page Tab
Raw Data View
The raw data view simultaneously shows the Hex and ASCII values of data records. This view also displays the record length as well as offset and size for selected bytes. Offset and size are adjusted accordingly as bytes are selected from within this view.
Field, column, null and unknown indicators display at the top of the raw data view. Field indicators show where each field within the record begins. Null indicators show where the null indicator byte is located. Unknown fields and bytes are also illustrated in the raw data view.
Figure 7 Raw Data View in Table Definition Editor
The following lists the attributes displayed in the raw data view:
Grid Data View
The grid data view shows the schema structure of the fields in a table-like grid. Each field is represented in a row on the grid. Each row contains cells that show the attributes for each field.
Figure 8 Grid Data View in Table Definition Editor
The following lists the attributes displayed in the grid data view:
How the Two Views Work Together
Selecting a cell in the grid data view displays the corresponding bytes for that field in the raw data view, just as selecting individual bytes in the raw data view, selects the corresponding element(s) in the grid data view.
Figure 9 Selecting Bytes in the Table Definition Editor
If you try to select past the field definition, an error message displays, and both rows in the grid data view are selected. Both error and warning messages display in this are of the raw data view.
Figure 10 Table Definition Editor Error Message
Figure 11 Table Definition Editor Caution/Warning Message
Indexes Page
The Indexes tab is read-only, with the exception of changing the SQL Index name. You cannot change the structure of any of the indexes on this tab. Index additions or changes to an SQL table must be made with PSQL Control Center. See “Table Editor” chapter in PSQL User's Guide.
How To Access
Select the Indexes page by clicking the Indexes tab at the bottom of the Table Definition Editor.
Figure 12 Indexes Page in Table Definition Editor
Features
Name changes made on the Tables page to columns specified as indexes are updated and shown immediately on the Indexes page.
Restrictions
Only the SQL Index name may be edited from the Indexes page.
When working with Btrieve files that use alternate collating sequence (ACS) files, the ACS file must reside in the same directory as the Btrieve file and must have an .ALT extension (for example, UPPER.ALT).
Preview Page
The Preview page shows the data from the file in a readable layout.
How To Access
Select the Preview page by clicking the Preview tab at the bottom of the Table Definition Editor.
Figure 13 Preview Page in Table Definition Editor
Features
You navigate among data records with the buttons at the bottom center of the page. The file position displays to the right of these buttons. The file position shows how many records are being displayed out of the total number of records. For example, “100-199/1314” indicates that the page displays records 100 through 199 out of a total of 1,314 records.
Changes made on the Tables page to any of the column definitions are reflected immediately on the Preview page.
Information on this page is read-only and cannot be modified.
Statistics Page
The Statistics page 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
Select the Statistics page by clicking the Statistics tab at the bottom of the Table Definition Editor.
Figure 14 Statistics Page in Table Definition Editor
Features
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.
See also Export Btrieve Schema.
*Note: The statistics information is based solely on information in the physical Btrieve file; it does not show any metadata information.
SQL View Page
The SQL View page displays the contents of the Structured Query Language (SQL) statement necessary to create the current table definition.
How To Access
Select the SQL View page by clicking the SQL View tab at the bottom of the Table Definition Editor.
Figure 15 SQL View Page in Table Definition Editor
Features
Most SQL statements created here can be copied and reused in the PSQL Control Center for creating new schemas based on the ones you created with DDF Builder. SQL statements that you use in the PSQL Control Center can also be saved for future use.
Restrictions
Although the SQL statements created here can be copied and reused, they are not saved, nor is a means for automatically saving them currently offered in DDF Builder. To save the statement, you must copy from this window and save the statement in a text editor.
*Caution: Do not reuse any statement that contains a reference to any of the PSQL dictionary system objects. These objects are easily identified by their X$<tablename> and include a proprietary comment prohibiting reuse.
Add Database
The Add Database Wizard creates a new database. This wizard is shared with PSQL Control Center (PCC). See Databases and New Database GUI Reference in PSQL User's Guide.
Check Table Consistency
DDF Builder provides an action with which you check the consistency of a table. A consistency check uses a set of validation rules to compare the physical data file against its metadata (the table against the data dictionary files).
Consistency check validates conditions such as the following:
You can check the consistency of all tables at once or of tables selected individually. The check reports a count of the validation messages, errors, and warnings by object. An object is the database, a table, or a data dictionary file (DDF).
The validation messages are grouped under the heading “PASSED” because they list the checks that passed consistency. Errors are grouped under “ERROR” and warnings under “WARNING.”
Error messages, if any, are always displayed. If an object has both errors and warnings, the warnings are also listed under the “ERROR” grouping.
Optionally, you can display or hide the validation messages and the warnings.
Icons on the results view identify the different types of messages:
An error indicates a problem in the table definition that will, in most cases, cause a failure or incorrect data to be returned when the data file is accessed. For example, an index defined in the DDFs but not in the data file results in an error. An SQL query that causes the engine to optimize on that particular index generates a failure because no such index actually exists in the data file.
Warnings are indicative of possible problems, but the problem may not cause any failures. For example, an index defined in a data file without a corresponding DDF entry results in a warning. SQL access does not know about the index and will not try to use it. The result may be a slow query, but the query eventually returns the correct results.
How To Access
In Data Sources Explorer, right-click the name of a database then click Check Database, or right-click an SQL table name under either the Data Paths or SQL Tables node, then click Check Tables. (You can select multiple tables by holding down the Shift or Control key then clicking the desired table names.)
Figure 16 DBCheck (consistency check results) View
Features
The DBCheck pane can be undocked and moved to any other area in DDF Builder. The pane can be minimized and maximized.
In addition, the pane provides icons with which you can save the consistency check results to a text file, and filter (hide) validation check messages and warnings.
Error Message Tips
A tip displays if you click on an error message. The tip provides comments about the message and may include a suggested corrective action. The tips are also written to the text file if you save the DBCheck results to a file.
Copy SQL Definition
The Copy SQL Definition Wizard creates a new SQL table based on the schema of an existing, or source, SQL 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 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 Importing Data with Import Data Wizard and Exporting Data with Export Data Wizard in PSQL User's Guide.
The wizard requires that you specify the following:
Export Btrieve Schema
The Export Btrieve Schema Wizard creates an XML file 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 Exporting Data with Export Data Wizard in PSQL User's Guide.
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.
Data from the source file is not imported. If you want to import data, see Importing Data with Import Data Wizard in PSQL User's Guide.
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 the 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.
Add Data Path
Data paths are added to the Data Sources Explorer by using Add Data Path. A data path represents a location on physical storage where the Btrieve file resides. Each PSQL 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 the Data Paths node, then click Add Data Path.
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.
Change Associated Data File
DDF Builder allows you to change the data file associated with a selected table definition (SQL Table).
How To Access
In Data Sources Explorer, right-click the SQL Table which you want to change the associated data file, then click Change Associated Data File. You may enter or browse to select the full path name for the data file you want associated.
Features
When changing the data file associated with a particular SQL table, you may enter the filename or use the browse button to select a file, based on the location.
Btrieve Types
DDF Builder provides a separate view for displaying the Btrieve data types and sizes, along with the corresponding SQL data types to which they map.
The Btrieve Types view can be used to analyze your data. Highlight bytes in the raw data view and the Btrieve Types displays how the data would appear for different types compatible with the size. When a particular column is selected in the Table Definition Editor, the Btrieve Types view also displays a preview of the formatted data.
How To Access
The Btrieve Types tab is located in the left pane of the DDF Builder window, next to the Data Sources Explorer tab. Click the Btrieve Types tab to display the view.
Figure 17 Btrieve Types View
Features
The Btrieve Types pane can be undocked and moved to any other area in DDF Builder. Moving the Btrieve Types pane allows you the flexibility to position the viewer so that you can easily resolve data type and size conflicts.
A preview column is also provided, showing how the selected data would appear as that particular data type. Previewing the data in each column can also be used to determine the size of a data type. Using the Btrieve Types pane to compare and preview the data is extremely useful when trying to resolve incorrect data type and size issues.
Definition Errors
Anytime that DDF Builder detects problems and alters your existing table definition, the Definition Errors window automatically displays. You may close this window and revisit the changes later by opening the Definition Errors view.
How To Access
From the menu bar in DDF Builder, click WindowView Definition Errors.
Figure 18 Definition Errors in Table Definition Editor
Features
The issues listed in the Definition Errors window contains specific information regarding the problems addressed by DDF Builder. The original table definition is also provided in a read-only mode in the Original Definitions window. This window may be moved so that comparisons to the updated table definition may be viewed.
Definition Errors List
The following table lists the possible table definition errors that can be detected by DDF Builder in your existing definitions. A general description of what caused the error and how DDF Builder has modified the table definitions as a result are also provided.
Original Definition
Anytime that DDF Builder detects problems and alters your existing table definition, your original table definition is retained until you save your changes. If you are making changes to an existing table definition, the original definition is also retained until your changes are saved. Until you save your changes, your original table definition can be viewed at any time by opening the Original Definition view.
How To Access
From the menu bar in DDF Builder, click WindowView Original Definition.
Figure 19 Original Definition in Table Definition Editor
Features
The original table definition is provided in a read-only mode in this tab. This window may be moved so that comparisons to the updated table definition may be viewed.
You can always retain the original table definition by saving either the modified or the original definition with a different name. To do this, click FileSave As and enter a different name.