Starting DDF Builder
You can start DDF Builder from the Windows operating system, from within the Pervasive 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 displays.
►
To start DDF Builder from PCC
1
In PCC, click ToolsDDF Builder from the menu bar.
2
The DDF Builder main window displays.
Figure 1 DDF Builder Main Window
Starting DDF Builder from a Command Line
DDF Builder can be started on Windows or Linux by running the executable file from a command line.
Windows
Run the executable file builder.exe to start DDF Builder. See Where are the Pervasive PSQL files installed? in Getting Started With Pervasive PSQL.
Linux
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 on 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.
Table 1
Requirements for Starting DDF Builder on Linux  
Requirement
Discussion
Pervasive PSQL server or client
A compatible Pervasive PSQL server or client must already be installed on the same machine. See Installing Pervasive PSQL Server and Client for Linux in Getting Started With Pervasive PSQL.
X-Server access
The xhost command controls which clients can access X-Windows on the current machine. By default, xhost turns on access control. This means that only the user who starts X-Windows could start DDF Builder.
You may turn off X-Windows client restrictions by typing xhost + at a terminal window.
Java Runtime Environment (JRE)
The JRE components required to run DDF Builder are installed as part of Pervasive PSQL. DDF Builder uses the “local” version of the JRE installed as part of Pervasive PSQL.
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 on 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/lib
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 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 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. SeePervasive PSQL Account Management on Linux in Getting Started With Pervasive 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 Pervasive 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 Pervasive 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 Pervasive DDF Builder and you started Pervasive DDF Builder, proceed to Chapter 2, Using DDF Builder. This chapter provides you with an introduction to the utility’s user interface.