DDF Builder Overview
DDF Builder is a Java utility that allows you to view, create, and change PSQL data dictionary files (DDFs) without making modifications to the underlying data file (referred to as a Btrieve file). Although DDF Builder provides a variety of functions, the utility’s primary purpose supports the following:
•
Creating the table definitions required to enable relational access to existing Btrieve data files
•
Modifying existing table definitions to ensure that relational access is enabled correctly for Btrieve data files
*Note: When creating and modifying DDFs with DDF Builder, the Btrieve data file is never modified.
Other functionality in DDF Builder includes, but is not limited to, the following:
•
Creating new Btrieve data files to use with the MicroKernel Engine
•
Exporting Btrieve schema to an XML file
•
Importing Btrieve schema from an XML file
•
Creating SQL statements
Why Use DDF Builder
DDF Builder is a specialized utility that allows you to add relational access to your Btrieve data files without making changes to the Btrieve data files. Typically DDF Builder is not a utility that you would use daily. Instead, DDF Builder should be used as needed to add relational access to an existing Btrieve file by creating table definitions in data dictionary files, or by modifying existing data dictionary files to connect table definitions that were not properly constructed.
*Note: DDFs define the schema for your SQL metadata. DDFs are system tables that allow DDF Builder to represent SQL access as objects, or SQL tables. Rather than modifying DDFs directly, you work with the SQL table objects. DDF Builder modifies the DDFs as you create, change, or delete SQL tables.

All of the SQL tables in a database are defined in the same set of DDFs.
Some previous versions of the Table Designer in the PSQL Control Center provided two modes in which to work—Linked and Unlinked. The linked mode allowed you to make changes to both the table definitions and the data file, and the unlinked mode allowed you to make changes to only the table definitions. DDF Builder uses a similar unlinked mode by using IN DICTIONARY calls to modify the DDFs without making changes to the Btrieve file. DDF Builder never writes to the Btrieve file.
What DDF Builder is Not
DDF Builder is not a means by which you can modify your existing Btrieve data files. If you intend to modify existing Btrieve files and DDFs that provide relational access, DDF Builder is not the utility you need to use. Consider using PSQL Control Center and other PSQL utilities for changing your existing Btrieve files.
Additionally, DDF Builder is not intended to be used to create or modify keys. Use the Table Editor in PSQL Control Center when working with keys. DDF Builder is intended to create and modify DDFs.
Why Not Use PCC?
PSQL Control Center is intended to manipulate the physical data files and the data dictionary files at the same time, or in linked mode. Altering only the DDFs within the confines of PCC is not recommended.
What You Need to Know
A thorough understanding of the structure of your data is the most important thing you need to know when using DDF Builder. Without an understanding of how the data is structured, creating or modifying table definitions with DDF Builder could be difficult, time consuming and counterproductive.
Other Helpful Information
It is also helpful if you have a general understanding of the two primary methods in which data is accessed from PSQL databases—transactional and relational. For much of the functionality in DDF Builder, an understanding of transactional access is beneficial. Other areas of functionality require that you are familiar with relational database concepts in general.
*Note: This book assumes that you understand the transactional access method and relational concepts. No attempt is made to explain them or to define common terms, such as keys, indexes, pages types, schema, and so forth.

Listed below are references to other PSQL books if you need to further your understanding before attempting to use DDF Builder. Note that, by default, the PSQL Developer Reference books are installed with the PSQL database engine.
Transactional Access
With transactional access, an application program navigates up and down along either physical or logical pathways through data records. Using a transactional API, an application program provides direct control and allows a developer to optimize data access based on knowledge of the underlying structure of the data. Using the Btrieve API is an example of transactional access.
Refer to the following books to further your understanding of transactional access:
•
PSQL Programmer's Guide (Developer Reference)
•
Btrieve API Guide (Developer Reference)
•
Advanced Operations Guide (Advanced Reference)
Relational Access
Relational is an access method in which data is represented as collections of tables, rows, and columns. The relational model insulates the developer from the underlying data structure and presents the data in a simple table format. ODBC is an example of a relational access method.
Refer to the following books to further your understanding of relational access:
•
SQL Engine Reference (Advanced Reference)
•
Advanced Operations Guide (Advanced Reference)
•
PSQL User's Guide (General Reference)
•
PSQL Programmer's Guide (Developer Reference)
What To Do Next
Changes made to your table definitions with DDF Builder will alter the structure of your DDFs. As a precaution before using the utility, always back up any of the files (including DDFs) with which you intend to work. (Btrieve files are also referred to as data files because the data is stored within the page structure of the file.)
*Note: DDF Builder does not allow you to modify the record layout structure of existing Btrieve files. You can create new Btrieve files with the utility, if you choose.
Disable Security
If you are working with a database that has any of the PSQL security models enabled, you should take the database offline and disable all security prior to opening the files in DDF Builder.
Components of DDF Builder
In addition to the utility, DDF Builder includes the following components:
Log File
•
Log File–.log
The log file is where DDF Builder reports any problematic conditions. By default, the log file is installed in your system’s Application Data directory under the following child directory:
<Application Data>\rcp\workspace-builder\.metadata
*Tip: See Where are the PSQL files installed? of Getting Started with PSQL for a list of the default installation locations.
User Documentation
The DDF Builder user documentation consists of the DDF Builder User’s Guide, which is included as part of the PSQL v12 user documentation. The documentation is installed by default in your system’s Program Files directory under the following child directory:
<Program Files>\bin\plugins\
The complete PSQL v12 user documentation is contained in the following jar file:
com.pervasive.help.docs.psql.enus_1.0.0.jar
*Tip: See Where are the PSQL files installed? of Getting Started with PSQL for a list of the default installation locations.
Tutorial File Folders
DDF Builder installs a set of files for use with the tutorials included in Chapter 3, DDF Builder Tutorials. The tutorial files are installed by default in your system’s Application Data directory under the following child directory:
<Application Data>\DDFBuilder\tutorials\
*Tip: See Where are the PSQL files installed? of Getting Started with PSQL for a list of the default installation locations.