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:
•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 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.
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 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.
Why Not Use ZenCC?
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.
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 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.
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 Zen books if you need to further your understanding before attempting to use DDF Builder. Note that, by default, the Zen developer documentation is installed with the Zen 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 learn more about transactional access:
•Zen 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)
•Zen User’s Guide (General Reference)
•Zen 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 Zen security models enabled, you should take the database offline and disable all security before opening the files in DDF Builder.
Components of DDF Builder
In addition to the utility, DDF Builder includes the following components:
Log File
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:
DDF Builder User’s Guide is part of the Zen user documentation.
Tutorial Files
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.
You can start DDF Builder from the Windows operating system, from within the Zen Control Center (ZenCC), or from a command line.
►To start DDF Builder from the Windows Operating System
1 Access DDF Builder from the Start menu or Apps screen.
The DDF Builder main window opens.
►To start DDF Builder from ZenCC
1 In ZenCC, click Tools > DDF Builder from the menu bar.
2 The DDF Builder main window opens.
Figure 1 DDF Builder Main Window
Starting DDF Builder 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.
Windows
Run the executable file builder.exe to start DDF Builder. See Where are the files installed? in Getting Started with Zen.
Linux and macOS
Run the executable script file builderto 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.
Table 1 Requirements for Starting DDF Builder on Linux or macOS
Requirement
Discussion
Zen server or client
A compatible Zen server or client must already be installed on the same machine. See Installing Zen for Linux-based Systems in Getting Started with Zen.
X server access
The xhost command controls which clients can access X Window System on the current machine. By default, xhost turns on access control. This means that only the user who starts X Window System could start DDF Builder.
You may turn off X Window System client restrictions by running xhost+ in a terminal window.
Java Runtime Environment (JRE)
The JRE components required to run DDF Builder are installed as part of Zen. DDF Builder uses the “local” version of the JRE installed as part of Zen.
Desktop ownership (macOS only)
Only the user logged in to the Desktop can start DDF Builder.
If you have met the requirements to run DDF Builder and still are having difficulty running the utility, refer to the following troubleshooting guide.
Table 2 Troubleshooting Guide for Running DDF Builder
Troubleshooting Condition
Discussion
You receive the error “java.lang.UnsatisfiedLinkError."
This error typically occurs if you try to start DDF Builder by double-clicking the script file using a file browser application. Start DDF Builder from a command prompt.
This error can result if the LD_LIBRARY_PATH variable is not set. The builder script sets this variable for you. You may also explicitly set the variable with the following command:
You receive the error "SWT no more handles" when trying to run DDF Builder as root or as user zen-svc.
You are not required to log in as user zen-svc or root to run DDF Builder. However, if you are neither of these users, you must be a member of group zen-data.
The "SWT no more handles" error is caused by the X server denying a connection to a client. Before switching to user zen-svc or root, open a console window and type xhost+ to allow other clients to connect to the X server.
Now you can switch to user zen-svc or root.
Also, sometimes the display environment variables needs to be set. As user zen-svc or root, type the following command at a console window:
export DISPLAY=:0.0
or
export DISPLAY=localhost:0.0
You want to view the error log file for DDF Builder or redirect the errors to the console window.
The log file of DDF Builder errors is located under the user’s home directory. For troubleshooting, you may find it more convenient to redirect the errors to the console window.
To redirect errors to the console window, use the ‑consoleLog option when starting DDF Builder:
builder -consoleLog
You receive the following error message: “Unable to connect to database engine. Make sure the target machine is accessible and an engine is running on the target machine.”
The context of this error occurs if you attempt to administer the local server.
You receive the error: “GTK IM Module SCIM: Cannot connect to Panel!” then trying to run DDF Builder as a user other than root.
On some Linux operating systems, it is necessary to specify the environment variable GTK_IM_MODULE.
To resolve this problem, before starting DDF Builder, run the following command at the console window:
export GTK_IM_MODULE=scim-bridge
Clearing the DDF Builder Cache
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.
Note Clearing the cache when starting DDF Builder provides no advantage under normal usage. For normal usage, start the utility as discussed in Starting DDF Builder.
►To clear DDF Builder cache
1 Exit DDF Builder if it is running.
2 Open a command prompt.
3 Change directory to the Zen\bin\ folder in the Zen installation directory.
4 Enter builder -clean and press Enter.
This clears the cache and starts DDF Builder.
Where to Go From Here
Now that you have a general understanding of DDF Builder, see Using DDF Builder for an introduction to the user interface.
