PSQL provides several features and tools that help to prevent configuration and installation problems.

Some of these utilities are installed and run as part of the installation process and all can be run later to evaluate configuration and registry settings and to troubleshoot problems. They are shown in Table 21.

The following topics cover different aspects of troubleshooting:

The following table describes tools to help you avoid or solve problems.

Typically, your installation process finishes with no problems. However, success depends on a number of factors, including proper network support and operating system configuration. If something does go wrong during installation, PSQL offers some tools and troubleshooting techniques to help diagnose the problem.

The following topics cover procedures that you can use in verifying your installation.

Messages logged by PSQL can help you troubleshoot problems. Messages can be of type status, information, warning, or error, and can originate from any PSQL component. Certain messages specific to licensing issues originate only from the license administration components. In either case, PSQL writes messages to the following logging features:

Any licensing message logged to Notification Viewer is also logged to the operating system event log and to PSQL event log. Similarly, any licensing message logged to the operating system event log is also logged to PSQL event log. Note that the operating system event log and PSQL event log may contain licensing messages not logged to Notification Viewer.

Messages not specific to licensing are logged to the operating system event log and to PSQL event log.

Follow these guidelines for using messages to troubleshoot problems:

For logging details, see Reviewing Message Logs in Advanced Operations Guide. For status code details, see Status Codes in Status Codes and Messages.

This topic covers selected scenarios where the default configuration settings for PSQL need adjusting for proper database operation.

The following table lists some of these situations along with actions you can take.

PSQL System Analyzer is a diagnostic utility included with PSQL. It is integrated into the product installation and available as a stand-alone diagnostic tool to help you with the following tasks:

To verify that the PSQL engine is running, see the procedure for your platform and engine:

You can use the Services function of the Windows control panel.

To verify that the PSQL Workgroup engine is running:

You can verify that the engine (mkded) is running with the ps utility.

Run the following at a command line:

ps -e | egrep 'mkded'

Run the following at the command line under the root user account:

etc/init.d/psql start

You can use PSQL utilities to verify that the client and engines have the version number you expect, or to check the version of a particular file.

You can check the engine and client versions using Function Executor on Windows platforms or using the butil command line utility on all platforms. Function Executor is a utility that simulates Btrieve client operations using the PSQL requesters.

Use Function Executor to determine the version of the client, local and remote engines.

From a command prompt, enter the following:

The requester and engine versions are then displayed. You cannot determine the version of a remote server engine with this tool.

You can determine the file version of a MicroKernel data file using the PSQL utilities. On the Windows platform, use PSQL Explorer, Function Executor, DDF Builder, or Btrieve Maintenance. On any platform, use the butil command line utility. The following topics give information on using some of these methods.

You can use the PSQL Control Center to determine a file version.

If you are unfamiliar with the command line, you can use the GUI-based Btrieve Maintenance tool.

The Function Executor utility can simulate Btrieve operations and can be used to determine the file version by performing a statistics report against the file.

The Function Executor utility is documented in more detail in Advanced Operations Guide.

Use the -stat parameter of butil to query file statistics for the following information:

Type the following at a command prompt:

butil -stat filename

For example, the following command queries statistics for the file dept.mkd of the Demodata database included with PSQL:

butil -stat dept.mkd

The butil utility is documented in more detail in Advanced Operations Guide.

We recommend that you use client requesters that are the same version as the database engine. If you choose, you may use a client requester that is an older version than the database engine with which it interacts. In some situations, depending on the type of SDK access method used by your application, an older version requester will not work with the database engine. Your application will be unable to communicate with the database engine. For those situations, you must use client requesters that are the same version as the database engine.

Client requesters that are a newer version than the database engine may or may not function correctly. Correct functioning of newer versions of client requesters with older versions of the engine cannot be guaranteed. Therefore, we recommend that you avoid the use of newer version client requesters with an older engine.

PSQL licensing components may determine that the product key for the database engine has become invalid. If so, the state of the key changes from Active to Failed Validation. Usually, you discover the invalidation after one of the following actions:

Message logs and other notifications can alert you to a failed validation and possible reasons. The most common reason is a change to the host name of the system where PSQL is running.

After validation failure, the database engine continues to run normally for a set number of days, called a failed validation period. This time period, set within product key itself, allows ample time for you to correct the failure and move the key state from failed back to active.

You have three ways to find out how many days you have to do this:

If you do not correct the causes of the failed validation before the expiration date, the key changes state to Disabled. A disabled key prevents the database engine from accessing data files.

For more information, see Reviewing Message Logs in Advanced Operations Guide and License Administration Concepts in PSQL User's Guide.

This section outlines problems you may encounter during the installation or when first using the Workgroup product.

When the PSQL Workgroup is installed as an application, you may experience this situation. Applications do not automatically inherit the user’s administrative rights. You can stop the engine, run it as administrator, and then run the command line license administrator or GUI License Administrator as administrator to authorize the license. Another alternative is to install Workgroup Engine to run as a service. See Running the Workgroup Engine as a Service.

Try stopping and then restarting the database engine. Whenever you make a change to engine configuration components, you must stop and restart the database engine for the changes to take effect. For information on how to start and stop the database engine, see Verifying Database Engine is Running.

When PCC creates a new database, the new database name is added to dbnames.cfg and an entry is added to the ODBC.INI registry in order to create a corresponding System DSN.

Due to Microsoft operating system constraints on registry access, the Workgroup Engine should be run in an elevated mode, so that the database System DSN can be created.

Once the System DSN is created successfully, any user may start the Workgroup Engine and use the DSN.

Your application has lost its session with the database engine. This can happen if you make changes to your configuration settings and must restart the database engine, as in the troubleshooting example given above. At the moment the database engine is stopped, any application that is running loses its session with the database engine. You must stop all those utilities and restart them in order to reestablish communication.

See the Status Codes and Messages manual for more cases in which this status code can be returned.

If the latest DLLs have been overwritten, it is possible to restore the overwritten DLLs using a backup directory that is automatically created when you install PSQL.

PSQL provides the command line utility butil.exe for verifying that your DOS components are functioning properly. In a default installation, it is located in C:\Program Files (x86)\Actian\PSQL\bin.

Database engine components may remain in memory if the engine is interrupted improperly.

If you previously installed PSQL requesters and then installed a later Workgroup engine, but your application is using only the requesters, you may have an outdated configuration that sets Local Access to Off. The Workgroup engine installation does not overwrite existing settings. To reset Local Access to On, see Using the Server and Workgroup Engines Concurrently.

This message appears when the installation program cannot update the Path environment variable because the resulting Path definition would be too long (exceeds the environment space). For information on how to increase the environment space defined in config.sys, see Microsoft knowledge base articles.

If you get this error message, then a REM statement (a comment) has been added to your autoexec.bat file. The REM statement contains the Path value that would have been entered. You can change the Path statement manually.

The best approach, if possible, is to install the product at a location with a shorter installation directory so that the value of Path does not exceed the environment space.

After you uninstall PSQL using Programs and Features in Windows, you should not have any database engine files left on your system. However, certain actions such as restoring archived components can cause a significant number of files to remain. This is a side-effect of how the installation process works with the Windows operating system.

In the situations described previously, the files are left because Windows has them marked with usage counts that indicate that they are being used by more than one program, and therefore the uninstallation program does not remove them. This is expected behavior, but it may lead to a false appearance that the PSQL installer is not functioning correctly.

If you encounter problems during or after the installation that are not covered in the user documentation, please contact technical support.