Getting Started with DDF Builder
 
Getting Started with DDF Builder
Providing Relational Access to Btrieve Files
• DDF Builder Overview
• Starting DDF Builder
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 learn more about 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
DDF Builder User’s Guide is part of the PSQL user documentation. The documentation is installed by default in C:\Program Files (x86)\Actian\PSQL\bin\plugins and is included in an Eclipse Help file:
com.pervasive.help.docs.psql.enus_1.0.0.jar
For a list of default installation locations, see Where are the PSQL files installed? in Getting Started with PSQL.
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\PSQL\DDFBuilder\tutorials.
For a list of default installation locations, see Where are the PSQL files installed? in Getting Started with PSQL.
Starting DDF Builder
You can start DDF Builder from the Windows operating system, from within the PSQL Control Center (PCC), 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 PCC
1 In PCC, 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 PSQL files installed? in Getting Started with PSQL.
Linux and macOS
Run the executable script file builder to start DDF Builder. The script file is located, by default installation, in the usr/local/psql/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
PSQL server or client
A compatible PSQL server or client must already be installed on the same machine. See Installing PSQL Server, Vx Server, and Client for Linux-based Systems in Getting Started with PSQL.
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 PSQL. DDF Builder uses the “local” version of the JRE installed as part of PSQL.
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:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/psql/lib64
On macOS, the variable is DYLD_LIBRARY_PATH.
You receive the error "SWT no more handles" when trying to run DDF Builder as root or as user psql.
You are not required to log in as user psql or root to run DDF Builder. However, if you are neither of these users, you must be a member of group pvsw.
The "SWT no more handles" error is caused by the X server denying a connection to a client. Before switching to user psql 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 psql or root.
Also, sometimes the display environment variables needs to be set. As user psql 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.
By default, the log file of DDF Builder errors is located in a subdirectory of the user’s home directory (the subdirectory is dir_builder/workspace/.metadata). 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.
To administer the local server, you must be a member of the pvsw group or be the root user. See PSQL Account Management on Linux, macOS, and Raspbian in Getting Started with PSQL.
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 PSQL 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 (click File > Exit).
2 Open a command prompt, or terminal window, at the operating system.
3 Change directory to the PSQL\bin\ folder in the PSQL installation directory.
4 Type builder -clean and press Enter.
This starts DDF Builder and clears the cache.
Where to Go From Here
Now that you have a general understanding about DDF Builder and you started DDF Builder, proceed to Using DDF Builder. This topic provides you with an introduction to the utility’s user interface.