Zen provides several features and tools that help to address 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 .

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, Zen 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 Zen can help you troubleshoot problems. Messages can be of type status, information, warning, or error, and can originate from any Zen component. Certain messages specific to licensing issues originate only from the license administration components. In either case, Zen 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 the Zen event log. Similarly, any licensing message logged to the operating system event log is also logged to the Zen event log. Note that the operating system event log and Zen 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 Zen 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 need adjusting for proper database operation.

The following table lists some of these situations and the actions you can take.

Zen System Analyzer (ZenSA) is a diagnostic tool. It is included with the database installation to help with the following tasks:

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

You can use the Windows Services control panel.

To verify that Workgroup Engine is running:

Click Start Workgroup Engine in the Start menu or Apps screen.

By default, the MicroKernel allocates resources and is ready to serve local application database requests.

Click Stop Workgroup Engine in the Start menu or Apps screen.

A warning message appears when you try to stop the engine if any of the following are true:

You can the ps utility at a command line to verify that the engine (mkded) is running:

ps -e | egrep 'mkded'

If you need to start the engine service run the following at a command prompt under the root user account:

etc/init.d/actianzen start

You can use Zen 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 Zen 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 Zen utilities. On the Windows platform, use 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 Zen 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.

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

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

For example, the following command returns information for the file dept.mkd in the Demodata sample database included with Zen, located in a default installation in C:\ProgramData\Actian\Zen\Demodata:

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.

Zen 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 Zen 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 Zen User’s Guide.

This topic outlines problems you may encounter during the installation or when first using Workgroup Engine.

When Workgroup Engine 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 or GUI License Administrator as administrator to authorize the license. Another option is to install Workgroup Engine to run as a service. See Running the Workgroup Engine as a Service.

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

When ZenCC 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, 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 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 Zen.

Zen 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\Zen\bin.

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

If you previously installed Zen requesters and then later installed Workgroup Engine, but your application is using only the requesters, you may have an outdated configuration that turns off local access. The Workgroup Engine installation does not overwrite existing settings. To turn on local access, see Using Server and Workgroup Engines Concurrently.

This message appears when the installation program cannot update the Path environment variable because the resulting string would be too long. 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 in a location with a shorter installation directory so that the Path value does not exceed the environment space.

After you uninstall Zen 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 Zen 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.