How to Proceed When You Encounter Errors After Installation
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 19.
The following topics cover different aspects of troubleshooting:
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.
Note If the installation fails, look for the installation log file in the Windows %Temp% directory.
Checklist for Problems
Did you see any error messages displayed during installation?
Does the Network function correctly?
Do you have the appropriate administrator-level privileges?
Is the Engine running?
Is the Client software correctly functioning?
Are there errors in the zen.log file (Windows) or in syslog (Linux, macOS, or Raspbian)?
Troubleshoot 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:
•Notification Viewer
•Operating system event log
•Zen event log (zen.log) (Windows only)
Any licensing message logged to Notification Viewer is also logged to the operating system event log and to Zen event log. Similarly, any licensing message logged to the operating system event log is also logged to 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:
•If you suspect a problem related to licensing, first check Notification Viewer, then check the operating system event log and Zen event log.
•If you suspect a problem not related to licensing, check the operating system event log and Zen event log.
For logging details, see Reviewing Message Logs in Advanced Operations Guide. For status code details, see Status Codes in Status Codes and Messages.
Configuration for Special Installation Situations
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.
►To check Actian Zen Enterprise Server Engine Service on Windows servers using the Control Panel
1 At the operating system, open Services under Administrative Tools.
2 In the list of services, find the Actian Zen engine service.
This service must be started for Zen to run. The Status column shows whether the service is running. The Startup column shows whether the service is set to start automatically or start manually.
3 If a service is not started, right-click it, then click Start.
Zen Workgroup on Windows
To verify that Workgroup Engine is running:
►To start Workgroup Engine
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.
►To stop Workgroup Engine
Click Stop Workgroup Enginein the Start menu or Apps screen.
A warning message appears when you try to stop the engine if any of the following are true:
•The engine has one or more active clients.
•No activity has taken place since the engine loaded.
•Less than 10 seconds has passed since the last operation took place.
Zen Servers on Linux-based Systems
You can the ps utility at a command line to verify that the engine (mkded) is running:
ps -e | egrep 'mkded'
►To start the Zen service
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
Obtaining File, Client, and Engine Version Number
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.
Determining Client and Engine Version
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.
►To Determine the Engine Version using Function Executor
1 Access Function Executor from the operating system Start menu or Apps screen.
2 Do one of the following:
•Click View > Btrieve Version from the File menu.
•Select the Btrieve Version Info toolbar button, as shown in Figure 2.
Figure 2 Selecting the Btrieve Version Info button
3 A dialog box displays the version of the client requesters and the local engine. If a file is open, the remote MicroKernel version is included.
Figure 3 Btrieve Version Info Display
Using the butil Utility
From a command prompt, enter the following:
butil -ver
The requester and engine versions are then displayed. You cannot determine the version of a remote server engine with this tool.
Determining a File Version
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.
►To Determine the File Version of a Table Using Zen Control Center
1 Access ZenCC from the operating system Start menu or Apps screen.
2 Find the database by expanding its name in Explorer on the left.
3 Do one of the following:
•Click a table name to choose it and select File > Properties from the File menu.
•Right-click the table name and select Properties.
4 The table properties are displayed, which include the file version of the underlying MicroKernel data file.
Figure 4 Table Properties Page
Using Btrieve Maintenance
If you are unfamiliar with the command line, you can use the GUI-based Btrieve Maintenance tool.
►To Determine the File Version of a Table Using Btrieve Maintenance Utility
1 Open Maintenance.
2 Select Options > Show Information Editor.
3 In File Information Editor, select Load Information.
4 Enter the path or browse for a file and click Open.
The version appears at upper right under Data File Info.
Using Function Executor
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.
►To Determine the File Version of a Table Using Function Executor
1 Open Function Executor.
2 Select File > Open.
3 In the Open Btrieve File dialog, enter the path or browse for a file.
4 With the file open in Function Executor, select View > File Statistics or press Ctrl-S to see the file version in the File Statistics window.
Figure 5 File Statistics in Function Executor
Function Executor is documented in more detail in Advanced Operations Guide.
Using the butil Utility
Use the -stat parameter of butil to see file statistics for information about the following:
•File version
•Owner name protection if used, including encryption level
•Page size, preallocation, and other characteristics
•Records
•Keys
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.
Engine and Client Version Conflicts
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:
•You manually run the command line utility clilcadm with the -t option to validate the key.
•You restart the Zen service, automatically prompting key validation.
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:
•In License Administrator, the product key shows a state of Failed Validation and an expiration date for the last day of the grace period.
•Zen Notification Viewer gives a history that includes licensing events. It lists any key validation failure, the number of days left until expiration, and gives steps you can take for correction.
•The file zen.log lists an entry for the validation failure that includes the expiration date.
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.
This topic outlines problems you may encounter during the installation or when first using Workgroup Engine.
I receive Status 7224 or my license is no longer listed in the License Administrator utility.
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.
I fail to see the effects of my configuration changes.
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.
Why do I receive Status 7012 when trying to create a new database with Workgroup Engine using ZenCC on Windows?
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.
Note In Windows, standard users may create User DSNs without this restriction.
Why do I (now) receive Status 95, after running my application successfully?
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.
Installing a Zen application has rendered another application unusable.
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.
How do I verify that my DOS components are functioning properly?
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.
Why can’t I restart my application after an improper program exit?
Database engine components may remain in memory if the engine is interrupted improperly.
►If you cannot restart your program after improperly aborting the application by using Ctrl-C or stopping the process
1 Shut down and restart your system.
2 Avoid terminating applications in an abnormal manner.
Why isn’t my application using Workgroup Engine?
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.
How Do I Access the Documentation?
►To access the online documentation
1 Access Control Center& Documentation from the Start menu or Apps screen.
2 Click the desired manual on the ZenCC Welcome tab. If the Welcome tab has been closed, click Help > Welcome.
I received an error message during installation that begins: “Setup did not update the PATH statement in autoexec.bat because the new path would be too long for Windows.”
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.
Issues After Uninstalling Zen on Windows
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.
How to Get Additional Help
If you encounter problems during or after the installation that are not covered in the user documentation, please contact technical support.
Did you see any error messages displayed during installation?
