An Overview of PSQL Control Center

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

PCC uses a file explorer motif – a tree of objects – referred to as the 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 PSQL Explorer is the tree view on the left.

Figure 17 PSQL Control Center on Windows Platforms

Figure 18 PSQL Control Center on Linux Platforms

Depending on the Linux distribution or if you are using OS X, the appearance of PCC may differ, but functionality is the same.

Installing PCC

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

On Linux and OS X, PCC is included in the full installation. See Full and Client Installations in Getting Started with 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

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

PSQL server or client

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

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

You may turn off X Window System 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 PSQL. PCC uses the local version of the JRE installed as part of 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 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/lib64

You receive the error "SWT no more handles" when trying to run PCC as user psql or root.

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 the X server denying a connection to a client. Before switching to user psql or root, open a console window and enter 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

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 in the console window:
export GTK_IM_MODULE=scim-bridge

Starting PCC on OS X

On OS X, only the user logged in to the Desktop can start PCC. Open Finder and then Applications > Actian PSQL > PSQL Control Center.

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 interact with PCC. Otherwise, the installed or upgraded product does not appear in PSQL Explorer. For example, if you were to install or upgrade DataExchange, 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 (select File > Exit).

Open a command prompt.

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

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

Enter the following command:

pcc -clean

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

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

Editors and Views Within PCC

The PCC main window offers various editors and views:

•

•

•

•

•

•

You can display and work with objects through the different editors and views. Multiple editors of the same type, such as 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 PSQL Explorer, can be opened only one at a time. Your actions within a view are applied immediately, without your having to save them.

Editor and View Characteristics

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

Table 7

Characteristics of PCC Window Views

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

PSQL Explorer

This view displays a tree of objects of various types and enables you to do many tasks.

•

Objects and Their Properties

•

Right-click Tasks

Objects and Their Properties

The tree of objects includes a root node named 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 PSQL Explorer can be expanded to reveal more detail. Click the expand icon to the left of an object to see objects under it. The expand icon may be a plus sign “+”, a triangle “”, or some other similar symbol. The collapse icon appears after you click an expand icon. Click the collapse icon to hide subordinate objects.

If properties (configurable settings) apply to an object, you can access them by right-clicking 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 PSQL Explorer

Right-click Tasks

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

Table 8

Right-click Tasks for Objects in PSQL Explorer

View or set object configuration properties

Any object and select Properties

System

Register a server to work with a remote database engine
(The local engine is automatically registered to PCC when you install PSQL)

The PSQL node

You can right-click any object subordinate to the PSQL root to work with a remote engine

To register a remote server engine

Work with PSQL services on Windows machines

The Services node (if applicable to the installation)

To start or stop services

To set services startup policy

A database engine under Engines node

To log in to a database engine

To log out from a database engine

Monitor concurrent sessions and data usage

A database engine under Engines node

To access Capacity Usage Viewer in Advanced Operations Guide

Monitor certain activities and attributes

A database engine under Engines node

To access Monitor for a database engine in Advanced Operations Guide

Delete a remote database engine

A database engine under Engines node

To delete a remote database engine

Databases

Create

The Databases node

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

To create a new database

Delete

A database under Databases node

To delete a database

A database under Databases node

To log out from and log in to a database

See also Groups, Users, and Security

Associate table(s) with a new database
(repair database name in tables bound to an original database name)

A database under Databases node

To repair a database name and associate copied tables with a new database

Schemas,
Tables

Export database schema

A database under Databases node

To export all table schemas at once

Export table schema

A table under Tables node

To export a table schema for a particular table

Add table
(performs a SELECT * from table_name query)

A database under Databases node, or
a table under Tables node

To start Table Editor for a new table

Open table

A table under Tables node

To open a table

Edit table

A table under Tables node

To start Table Editor for an existing table

Import table

A table under Tables node

To import data into a database table

Export table

A table under Tables node

To export data from a database table

Delete table

A table under Tables node

To delete a table

Users,
Groups

Add user

A database under Databases node or
a user

To create a new user using PSQL Explorer

To assign a user to a group using PSQL Explorer

Add group

A database under Databases node or
a group

To create a new group using PSQL Explorer

Delete user or group

A user or group

To delete a group or user using PSQL Explorer

Triggers,
Stored Procedures,
User-defined Functions,
Views

Create

A database under Databases node, or
a trigger,
stored procedure,
user-defined function, or
view

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

To create a common SQL object

Edit

A database under Databases node, or
a trigger,
stored procedure,
user-defined function, or
view

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

To modify a common SQL object

Delete

A database under Databases node, or
a trigger,
stored procedure,
user-defined function, or
view

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

To delete a common SQL object

SQL Editor

SQL Editor allows you to run Structured Query Language (SQL) statements against a 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 PSQL 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.

Clear 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

In the PCC Window menu, click Preferences, and expand the PSQL node if needed.

Perform one of the following actions:

•

To set preferences for Data Grid, click Data Grid.

•

To set preferences for Defragmenter, click Defragmenter.

•

To set preferences for Monitor, click Server 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.

File Encoding Preferences

The preference setting for File Encoding allows you to work more easily with files containing wide character data. This setting provides the following features:

•

An option to use the PCC dialogs for File Open and File Save.

•

A list of encodings from which to select the default to be used for the following PCC actions:

•

•

•

•

•

►

To set a preference to use PCC dialogs for File Open and File Save

In PCC, select Window > Preferences > PSQL > File Encoding.

Make sure that the option Do not prompt for encoding during File Open and File Save is not selected. By default, the option is not selected.

Click OK.

►

To set a preference for default encoding

In PCC, select Window > Preferences > PSQL > File Encoding.

Select an encoding from the Default encoding list and click OK.

Table 9

Default Encoding Choices

Encoding

Discussion

(system code page)

The default is the system code page currently in use. For example, on Windows platforms in English you commonly see “windows-1252.”

Big5

Big5 is a Chinese character encoding method used for traditional Chinese characters.

EUC_JP

Extended Unix Code (EUC)_JP is a variable-width encoding used to represent the elements of three Japanese character set standards: JIS X 0208, JIS X 0212, and JIS X 0201.

Shift_JIS

Shift_JIS (Japanese Industrial Standards) is a character encoding for the Japanese language.

UTF-8

UTF (Universal Character Set Transformation Format)-8 is an 8-bit variable-width encoding that can represent every character in the Unicode character set. It was designed for backward compatibility with ASCII and to avoid the complications of endianness and byte order marks (BOM).

UTF-8 with BOM

Same as UTF-8 except with a byte order mark (BOM)—which is a Unicode character used to signal the endianness (byte order)—written to the file during the save action.

UTF-16BE

A UTF encoding in 16-bit with byte order of big endian (BE).

UTF-16BE with BOM

Same as UTF-16BE except with a BOM written to the file during the save action.

UTF-16LE

A UTF encoding in 16-bit with byte order of little endian (LE).

UTF-16LE with BOM

Same as UTF-16LE except with a BOM written to the file during the save action.

Notes:

By default, PCC remembers the encoding of a file that has been opened. If you modify the file and save your changes, the changes are saved in the original encoding. However, if you use the PCC File Save As dialog to save your changes, the changes are saved to the encoding specified on the dialog.

PCC automatically detects the encoding of a file if the file contains a BOM and displays that encoding in the PCC File Open dialog. If the file does has no BOM and byte order is important, you need to select the proper encoding for the save action.

Note: You can also access the File Encoding preference setting from the dialogs for File Open, Save File, Import Data, Export Data, and Export Schema. Click Change default encoding in the dialog.

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:

•

ODBC Administrator – Separate choices for 32-bit Administrator and 64-bit Administrator on 64-bit operating systems (see DSN Setup and Connection Strings in ODBC Guide). 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 rather than PSQL.

•

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

•

Defragmenter (see Monitoring Data File Fragmentation in Advanced Operations Guide)

•

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

•

License Administrator (see License Administration)

•

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

•

Monitor (see Monitoring in Advanced Operations Guide)