The following topics prepare you to use DDF Builder for relational access to Btrieve files:

DDF Builder is a Java utility that allows you to view, create, and change Zen data dictionary files (DDFs) without making modifications to the underlying data file, called a Btrieve file. Although DDF Builder provides a variety of functions, the utility’s primary purpose supports the following:

Other functionality in DDF Builder includes, but is not limited to, the following:

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.

Some previous versions of the Table Designer in the Zen 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.

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 Zen Control Center and other Zen 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 Zen Control Center when working with keys. DDF Builder is intended to create and modify DDFs.

Zen Control Center is intended to manipulate the physical data files and the data dictionary files at the same time, or in linked mode. Using ZenCC to alter only DDFs is not recommended.

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.

It is also helpful if you have a general understanding of the two primary methods in which data is accessed from Zen 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.

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 learn more about transactional 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:

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.)

If you are working with a database that has any of the Zen security models enabled, you should take the database offline and disable all security before opening the files in DDF Builder.

In addition to the utility, DDF Builder includes the following components:

The .log file is where DDF Builder enters reports of any problematic conditions. In a default installation, the log file is installed in the following directory:

C:\ProgramData\Actian\Zen\rcp\workspace-builder\.metadata

DDF Builder User’s Guide is part of the Zen user documentation.

DDF Builder installs a set of files for use with the tutorials included in DDF Builder User’s Guide. The tutorial files are installed by default in C:\ProgramData\Actian\Zen\DDFBuilder\tutorials. For documentation, see DDF Builder Tutorials.

For a list of default installation locations, see Where are the files installed? in Getting Started with Zen.

You can start DDF Builder from the Windows operating system, from within the Zen Control Center (ZenCC), or from a command line.

DDF Builder can be started on Windows, Linux, or macOS by running the executable file from a command line. See the following topics for details.

Run the executable file builder.exe to start DDF Builder. See Where are the files installed? in Getting Started with Zen.

Run the executable script file builder to start DDF Builder. The script file is located, by default installation, in the usr/local/actianzen/bin directory.

We recommend that you start DDF Builder from a command prompt and not by double-clicking the script file using a file browser application. See Troubleshooting Guide for Running DDF Builder.

The following requirements must be met to start DDF Builder on Linux or macOS:

If you have met the requirements to run DDF Builder and still are having difficulty running the utility, refer to the following guidelines:

DDF Builder caches certain information to improve efficiency. On occasion, you may need to clear the cache for troubleshooting purposes as directed by technical support or to ensure that all files are reloaded. The cache can be cleared only by starting DDF Builder with a parameter from the command line.

Now that you have a general understanding of DDF Builder, see Using DDF Builder for an introduction to the user interface.