An Overview of Pervasive PSQL Control Center

Pervasive PSQL Control Center (PCC) is an integrated framework in which users can connect to Pervasive PSQL engines, set up and modify databases and tables, query and update data, tune engine performance, and access the Pervasive PSQL documentation library.

PCC uses a file explorer-like motif—a tree of objects—referred to as the Pervasive PSQL Explorer. This tree of objects can be opened or expanded to reveal more detail. Examples of objects include engines, databases, tables, and users. The following figures illustrate PCC with several window views displayed. The Pervasive PSQL Explorer is the tree view on the left.

Figure 17 Pervasive PSQL Control Center on Windows Platforms

Figure 18 Pervasive PSQL Control Center on Linux Platforms

Note that the PCC graphical user interface (GUI) may look cosmetically different depending on your distribution of Linux.

Installing PCC

On Windows platforms, PCC is installed by default when you install a database engine or a client. See Pervasive PSQL Optional Features in Getting Started With Pervasive PSQL.

On Linux, PCC is included in the full install. See Full Installations in Getting Started With Pervasive PSQL.

Starting PCC on Windows

Access Control Center from the operating system Start menu or Apps screen. You may also run the executable file pcc.exe.

Starting PCC On Linux

You start PCC by running the executable script file pcc from a command prompt. The script file is located, by default installation, in the usr/local/psql/bin directory.

We recommend that you start PCC from a command prompt and not by double-clicking on the script file using a file browser application. See Table 6, Troubleshooting Guide for Running PCC.

The following requirements must be met to start PCC on Linux.

Table 5

Requirements for Starting PCC on Linux

Requirement

Discussion

Pervasive PSQL server or client

A compatible Pervasive PSQL server or client must already be installed on the same machine.

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

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 PCC are installed as part of Pervasive PSQL. PCC uses the “local” version of the JRE installed as part of Pervasive PSQL.

If you have met the requirements to run PCC and still are having difficulty running the utility, refer to the following troubleshooting guide.

Table 6

Troubleshooting Guide for Running PCC

Troubleshooting Condition

Discussion

You receive the error “java.lang.UnsatisfiedLinkError."

This error typically occurs if you try to start PCC by double-clicking on the script file using a file browser application. Start PCC from a command prompt.

This error can result if the LD_LIBRARY_PATH variable is not set. The PCC 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 PCC as root or as user psql.

You are not required to log in as user psql or root to run PCC. 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

export DISPLAY=localhost:0.0

You want to view the error log file for PCC or redirect the errors to the console window.

By default, the log file of PCC errors is located in a subdirectory of the user’s home directory (the subdirectory is dir_pcc/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 PCC:

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

You receive the error: “GTK IM Module SCIM: Cannot connect to Panel!” then trying to run PCC 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 PCC, run the following command at the console window:

export GTK_IM_MODULE=scim-bridge

Situations Requiring That You Clear PCC Cache

PCC caches certain information to improve efficiency. The cache must be cleared after you install or upgrade any other products that “plug in” to PCC. Otherwise, the installed or upgraded product does not appear in the Pervasive PSQL Explorer. For example, if you were to install or upgrade Pervasive Data Exchange, you would then need to clear the PCC cache.

The cache can be cleared only by starting PCC with a parameter from the command line.

►

To clear PCC cache

Exit PCC if it is running (click File  Exit).

Open a command prompt, or terminal window, at the operating system.

Change directory to the PSQL\bin\ folder in the Pervasive PSQL installation directory.

For default locations of Pervasive PSQL files, see Where are the Pervasive PSQL files installed? in Getting Started With Pervasive PSQL.

Type pcc -clean and press Enter.

This starts PCC and clears the cache. The newly installed or upgraded products should then appear in the Pervasive PSQL Explorer.

Note: Use of the -clean parameter when starting PCC provides no advantage under normal usage. The parameter is required only if you install or upgrade a plug-in product.

Editors and Views Within PCC

The PCC main window comprises editors and views:

•

Pervasive PSQL Explorer

•

•

•

•

•

You can display and work with objects through the different editors and views. Multiple editors of the same type (for example, SQL Editor) can be open at the same time. Each object being edited is represented by a tab on top of the editor. The tab contains the name of the object. Data modified within an editor must be explicitly saved (for example, with File  Save).

Views, such as Pervasive PSQL Explorer, can be opened only one at a time. Actions performed within a view are applied immediately. No explicit save is required.

Editor and View Characteristics

The following table summarizes the characteristics of the editors and views.

Table 7

Characteristics of PCC Window Views

Characteristic

Pervasive PSQL Explorer

Contains icons specific to that view

Can be closed

Can be minimized

Can be maximized

Can be restored to previous size

Can be opened in new window

Can be rearranged within PCC main window

Can be "pulled" from PCC and placed on desktop

Pervasive PSQL Explorer

This view displays a tree of objects and subordinate objects and provides access to the following:

•

Objects and Their Properties

•

Right-click Tasks

Objects and Their Properties

The tree of objects includes a root node named Pervasive PSQL. The root node contains objects such as clients, services (if applicable), database engines, databases, tables, views, stored procedures, user-defined functions, triggers, groups, users, and system objects (such as system tables).

Most objects in Pervasive PSQL Explorer can be expanded to reveal more detail. Click the expand icon to the left of an object to reveal subordinate objects. The expand icon may be a “+” symbol, a “” symbol, or some other similar symbol. Click the collapse icon to hide subordinate objects. (The collapse icon appears after you click an expand icon.)

If properties (configurable settings) apply to an object, you can access them by right-clicking on an object and selecting Properties. You can also click an object then press Alt+Enter to display properties. (See also Configuration Reference in Advanced Operations Guide.)

Figure 19 Example Objects Shown in Pervasive PSQL Explorer

Right-click Tasks

In addition to accessing properties, numerous other tasks can be invoked from Pervasive PSQL Explorer by right-clicking on an object. The follow table summarizes the tasks.

Table 8

Right-click Tasks for Objects in Pervasive PSQL Explorer

View or set configuration properties

Right-click on the object then click Properties.

Pervasive PSQL node

Work with a remote database engine (add a new server).

The local engine is automatically registered to PCC when you install Pervasive PSQL.

(This task can also be performed from any object subordinate to the Pervasive PSQL root.)

To register a remote server engine

Services node (if applicable to the product installed)

Work with Pervasive PSQL services on Windows machines

To start or stop services

To set services startup policy

A database engine under Engines node

Create a new database

(This task can also be performed from any object subordinate to the Engines node.)

To create a new database

To log in to a database engine

To log out from a database engine

Monitor concurrent sessions and data usage

To access Capacity Usage Viewer

Monitor certain activities and attributes

To access Monitor for a database engine

Delete a remote database engine

To delete a remote database engine

Databases node

Create a new database

To create a new database

A database under Databases node

Add a new table (using Table Editor)

(This task can also be performed from any object subordinate to the Databases node.)

To start Table Editor for a new table

Create a user defined function, stored procedure, trigger, or view (using SQL Editor)

(This task can also be performed from any object subordinate to the Databases node.)

To create a common SQL object

Export the schemas for all tables in the database

To export all table schemas at once

Associate the tables copied from an existing database with a new database

To repair a database name

To log out from and log in to a database

See also Groups, Users, and Security

Add users or groups

(This task can also be performed from any object subordinate to the Databases node.)

To create a new user using Pervasive PSQL Explorer

To create a new group using Pervasive PSQL Explorer

Delete a database

To delete a database

A table under Tables node

Add a new table

To start Table Editor for a new table

Open a table (performs a SELECT * from table_name query)

To open a table

Edit a table (using Table Editor)

To start Table Editor for an existing table

Export the schema

To export a table schema for a particular table

Import or export data

To import data from a database table

To export data from a database table

Delete a table

To delete a table

A user defined function, stored procedure, trigger, or view

Create a user defined function, stored procedure, trigger, or view (using SQL Editor)

To create a common SQL object

Edit or delete a user defined function, stored procedure, trigger, or view

To modify a common SQL object

To delete a common SQL object

User or group

Add users or groups

To create a new user using Pervasive PSQL Explorer

To create a new group using Pervasive PSQL Explorer

To assign a user to a group using Pervasive PSQL Explorer

Delete users or groups

To delete a group or user using Pervasive PSQL Explorer

SQL Editor

SQL Editor allows you to run Structured Query Language (SQL) statements against a Pervasive PSQL database. See SQL Editor for a detailed discussion.

Grid

The Grid window view shows in a matrix format, like a spreadsheet, the result of running SQL statements. Each field is represented as a column and the data appears in cells within the columns. You can change data directly in the Grid cells as well as add additional rows to the Grid.

Both Table Editor and SQL Editor use the Grid. See To view table data and Grid Window View for further details.

Text

The Text window view shows in a text format the result of running SQL statements. The text is display only. You cannot change data values by changing the text, but you can copy text. See Text Window View for a detailed discussion.

Outline

The Outline window view allows you to view the SQL statements in a tree structure. The root node of the tree is the same name as the name of the SQL Editor window view. See Outline Window View for a detailed discussion.

Note that the editor must support an outline or the Outline window view is not available. Currently, only SQL Editor supports an outline view.

Table Editor

Table Editor allows you to add, delete, or change the characteristics of columns within a table. The table may be one newly created or an existing table that you want to edit. See Table Editor for a detailed discussion.

Preferences

You can set general preferences for your experience in PCC. You can also set preferences for the window views in PCC or for the external tools.

►

To set general preferences for Grid

On the PCC Window menu, click Preferences. Expand the Pervasive node if it is not already expanded.

Click General.

The following are the options that can be set in the General Preferences:

•

Always remove associated DSN entries (see Deleting DSNs)

•

Do not prompt for new database each time a SQL document is opened (see To set database context for an SQL query.

Select Always remove associated DSN entries to have all DSN entries for any database automatically deleted along with the database without prompting.

Deselect Do not prompt for new database each time a SQL document is opened to be prompted to select a database each time you open a SQL document in the SQL Editor. If this option is deselected, select it to use the most recently selected database when you open a SQL document. The selected database is not maintained across PCC sessions. If you close and reopen PCC, you will have to select a new default database context.

Preferences for PCC Window Views

You can set preferences for the following PCC window views:

•

•

•

•

•

►

To set preferences for PCC Window Views

On the PCC Window menu, click Preferences. Expand the Pervasive node if it is not already expanded.

Perform one of the following actions:

To set preferences for Data Grid, click Data Grid.

To set preferences for Monitor, click Monitor.

To set preferences for SQL Editor, click SQL Editor.

To set preferences for Table Editor, click Table Editor.

To set preferences for Text Output, click Text Output.

Additional Utilities

Some utilities have not yet been tightly integrated within the PCC framework. However, they may still be started from within PCC by selecting them through the Tools menu:

•

Function Executor (see Testing Btrieve Operations in Advanced Operations Guide)

•

Monitor (see Monitoring Database Resources in Advanced Operations Guide)

•

Maintenance (see Manipulating Btrieve Data Files with Maintenance in Advanced Operations Guide)

•

DDF Builder (see Getting Started with DDF Builder in DDF Builder User’s Guide)

•

License Administrator (see License Administration)

•

Rebuild (see Converting Data Files in Advanced Operations Guide)

•

ODBC Administrator—separate choices for 32-bit Administrator and 64-bit Administrator on 64-bit operating systems (see DSNs and ODBC Administrator in SQL Engine Reference). Note that Windows uses whichever ODBC Administrator is open if you try to invoke the other one. That is, if the 32-bit ODBC Administrator is open and you attempt to start the 64-bit one, Windows displays the 32-bit version (and vice versa). In other words, only one version of ODBC Administrator runs at a time. This is a limitation of Windows, not Pervasive PSQL.

•

Pervasive System Analyzer (see Pervasive System Analyzer (PSA))

•

Query Plan Viewer (see Query Plan Viewer in SQL Engine Reference)

•

Gateway Locator (if PCC installed with Pervasive PSQL Workgroup) (see Gateway Configuration in Getting Started With Pervasive PSQL)

Note: These utilities appear in the Tools menu only on Windows platforms. For both Windows and Linux platforms, you can add your own custom tools to the Tools menu. Refer to the next section.

External Tools

You can add your own software programs to the PCC Tools menu. This provides a convenient way to start the programs from PCC.

►

To add external tools

On the PCC Window menu, click Preferences. Expand the Pervasive node if it is not already expanded.