Advanced Reference : Advanced Operations Guide : Configuration Reference
 
Configuration Reference
Configuration Methods and Property Settings in Zen
The following topics cover various ways to configure your database server engines and clients:
Configuration Overview
Configuration Using ZenCC
Configuration Using Bcfg
Service Configuration Properties
Server Configuration Properties on All Platforms
Windows Client Configuration Properties
Linux, macOS, and Raspbian Client Configuration Properties
Reporting Engine Configuration Properties
Configuration Overview
Zen is configured using settings in its database engines and clients. You can set configuration properties in Zen Control Center (ZenCC) or at a command prompt.
In ZenCC, the configuration settings are properties of the engine or client. See To set the properties in ZenCC for an engine and To set the properties in ZenCC for a local client.
Configuring any components is optional. If you do not configure them, each component loads with default configuration settings. For best results, you should use only the version of ZenCC that is the same version as your client and engine components.
You can use configuration for the following reasons:
Your system or your Zen application requires you to adjust the settings. See your application documentation for recommended values. If you are running multiple applications concurrently, add the recommended values together. If you are running multiple applications sequentially, use the highest recommended value.
You want to optimize the settings so that Zen provides the services you need without using more memory than necessary.
The configuration settings themselves are discussed in Configuration Reference.
Ensuring Configuration Changes Take Effect
Some engine configuration settings require that you restart the database engines after the setting is changed. Restarting the engines ensures that the setting takes effect. Each setting in this chapter lists whether a database engine restart is required. Also, ZenCC informs you with a message if a changed setting requires an engine restart.
The CLI tool also informs you that you changed the setting from the command line rather by using an input file. Use of an input file always requires that you restart the engines. See Configuration Using Bcfg.
To stop and start a server database engine from the command line, see the following topics in Zen User’s Guide:
Starting and Stopping the Enterprise Server Engine on a Windows Server
Starting and Stopping the Database Engine on Linux, macOS, and Raspbian
To stop and start a Workgroup engine, see Starting and Stopping the Workgroup Engine on Windows in Zen User’s Guide.
In addition, changing client properties often requires the client to be restarted. To reload the client, simply exit all applications that depend on Zen and restart them.
Connecting to Different Machines
You can configure both local and remote engines as well as local client components; however, each engine must be configured separately. See Configuration Using ZenCC and Configuration Using Bcfg.
When you are connected to a remote machine with ZenCC, you can view and change only engine components. Client components, such as on workgroup and workstation engines and client machines, can be configured only locally on each machine.
Configuration Using ZenCC
In ZenCC, the configuration settings are properties of either an engine or a client. All registered engines appear in Zen Explorer, and you can configure their properties by selecting their nodes, but only the local client is shown. To configure a remote client, locate it in Zen Explorer on the client machine itself.
To configure a remote server, you can open ZenCC on a client to the server or on any server accessible to the network, locate or register the remote server under the Engines node, then configure its properties. This method is useful with operating systems where ZenCC is not supported, such as Windows Nano Server and IoT Core and Raspbian.
The following steps show how to access the properties of an engine and a client.
To set the properties in ZenCC for an engine
1 In Zen Explorer, expand the Engines node.
2 Right-click the database engine for which you want to specify configuration settings.
3 Select Properties.
4 Click a category of properties to display that group of settings.
To open a help topic on a selected setting, you can press F1 or click the question mark icon at lower left. The general documentation for settings is found under Server Configuration Properties on All Platforms.
To set the properties in ZenCC for a local client
1 In Zen Explorer, expand the Local Client node.
2 Right-click MicroKernel Router.
3 Select Properties.
4 Click the desired option category in the tree to display the settings for that category of options.
To open a help topic on a selected setting, you can press F1 or click the question icon at lower left. The general documentation for property settings is found under the following topics:
Windows Client Configuration Properties
Linux, macOS, and Raspbian Client Configuration Properties
Reporting Engine Configuration Properties
You may also set properties from the command line in Windows systems. This method is also normally used on Linux, macOS, and Raspbian systems. See Configuration Using Bcfg.
Configuration Using Bcfg
The bcfg command line tool provides the same settings as property dialogs in ZenCC. The tool runs on Windows, Linux, macOS, and Raspbian platforms supported by Zen. Depending on the platform, its executable program may be bcfg.bat, bcfg.exe, or simply bcfg on Unix-based systems. On systems that support Java, the JRE components needed to run bcfg are installed with Zen. On Windows systems, bcfg is installed in the bin directory of the Zen installation. On Unix systems, it is in /usr/local/actianzen/bin.
If you have difficulty running the tool, the following table gives suggestions for troubleshooting.
Troubleshooting Condition
Discussion
You receive the error: java.lang.UnsatisfiedLinkError
This error occurs if you try to start bcfg by double-clicking the script file icon. Start bcfg at a command prompt.
This error also can result if the LD_LIBRARY_PATH variable is not set. If you run bcfg as user zen-svc, this variable is set in the profile for zen-svc. You may also explicitly set the variable with the following command:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/actianzen/lib64
On macOS, the variable is DYLD_LIBRARY_PATH.
You receive the error:
Unable to connect to database engine. Make sure the target machine is accessible and an engine is running on the target machine.
This error occurs when you attempt to configure the local server.
To configure the local server, you must be a member of the zen-data group or be the root user.
See also Zen Account Management on Linux, macOS, and Raspbian in Getting Started with Zen.
You receive the error:
Interactive input failure detected. Exiting without overwriting file.
When you run the command, add the -F option to suppress the prompt, make no attempt to read from stdin, and always overwrite the file.
Setting a Configuration
You can configure settings one at a time from the command line or by providing one or more settings in an input file.
Tip A convenient way to create an input file is first to create an output file. You can then edit the output file and use it as an input file. See Editing an Input File for the types of permissible edits.
Restarting the Engines
If you use an input file, bcfg prompts you to restart the database engines to ensure that the configuration settings take effect, no matter what settings were included in the file.
If you configure a setting from the command line, bcfg prompts you to restart the database engines only if the setting requires a restart.
See Ensuring Configuration Changes Take Effect for steps to restart the engines.
Example Scenario: Configuring a Single Setting from a Command Prompt
Suppose that you want to turn on a configuration setting having to do with reconnecting a client to the server in the event of a network outage. You are not certain about the name of the configuration setting. The steps in the following example show how to find the setting and configure it at a command prompt.
1 At a command prompt, enter bcfg -H reconnect then press Enter.
The tool reports all settings that contain the string reconnect:
ID               Setting Name
-----------------------------
29               Enable Auto Reconnect
148              Enable Auto Reconnect
149              Auto Reconnect Timeout
Two of the settings, 29 and 148, look like what you want, but which is which?
2 Enter bcfg 29 then press Enter.
The tool reports the following for setting ID 29:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: Off
Options: On    Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
The description tells you that this setting applies to a client and that the setting is currently off.
3 Enter bcfg 29 on then press Enter.
The tool informs you that system setting 29 has been updated.
4 If you want to verify that the setting is now on, enter bcfg 29 then press Enter.
The tool reports the following for setting ID 29, showing that the value is now set to on:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: On
Options: On    Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
Editing an Input File
An input file must contain at least one complete record for one property. If you create an input file from an output file and want to remove properties, be sure that the remaining settings are complete records.
At a minimum, a complete record encompasses an ID and value pair. However, to ensure clarity we recommend that you include all lines from the header through the description. For example, here is a suggested minimal record for Enable Auto Reconnect:
=====================
ENABLE AUTO RECONNECT
=====================
ID: 29
Value: On
Options: On    Off
Default Value: Off
Description: <Client setting> Specifies if the Client will attempt to reconnect to the Server in the event of a network outage. The reconnected Client will continue processing as if no errors were encountered.
The input file can contain all settings or only the ones you need to change. You can make successful configuration changes only by entering valid values on the lines for ID, Value, Options, or Range. Any other changes to entries in the input file may result in errors, failed changes to settings, or other unexpected behavior.
Command Syntax
bcfg -I inputfile [-S server] [-U username]
[-P password] [-E] [-F]
or
bcfg -O outputfile [-S server] [-U username]
[-P password] [-E] [-F]
or
bcfg ID [value] [-S server] [-U username]
[-P password]
or
bcfg -H <keyword | "keyword with spaces"> [-S server]
[-U username] [-P password]
Options
-I
Required if you provide an input file to the tool.
inputfile
A text file that contains one or more configuration setting records for a specified server and the value assigned to each setting.
A convenient way to create an input file is first to create an output file. You can then edit the setting values as required and use the edited version as an input file. See Editing an Input File for the types of edits permissible.
-O
Required if you want the output results of running the tool written to a text file.
outputfile
A text file that contains the current configuration settings for a specified server as a result of running the tool.
ID
A two- or three-digit integer that identifies the configuration setting.
Some configuration settings require that you restart the database engines for the setting to take effect. Bcfg prompts you if a restart is required. See Restarting the Engines.
value
A value assigned to the configuration setting. The valid values are specified in a setting record in Options or Range.
If value is omitted, the tool returns the current setting.
If value is included, the tool changes the setting based on the value.
-H
The help search option for a keyword. The tool searches for configuration settings that contain keyword and returns the ID and setting name, or returns “no matches found.” See also the next item in this list.
keyword
The name of the configuration setting, such as ALLOW CLIENT-STORED CREDENTIALS or SUPPORTED PROTOCOLS.
Note that keyword is case-insensitive. However, if it contains spaces, you must double-quote the string.
The tool can provide help based on partial keywords. For example, if you specify -H client, the tool returns all settings with the word client as part of the setting name. If you specify -H a, the tool returns all settings with an “a” in the name.
-S
Required parameter if the configuration settings apply to a remote server (a server other than the local one).
server
The name or IP address of the remote server that contains the database engine.
-U
Required parameter if a user name is required to access server.
username
User name with which you will connect to server. See also Zen Security.
If server is a local machine, the username and password are not required if the following are true:
You are logged in to the local machine as administrator or a member of the Zen_Admin group.
The local machine is not running Terminal Services.
-P
Required parameter if a password is required to access server.
password
Password used with username to connect to the server. See username. See also Zen Security.
-E
Ignore errors when reading inputfile or writing to outputfile.
-F
Force overwrite of outputfile without prompting.
Without this flag, the combination of a preexisting outputfile and a lack of stdin, such as found in remote PowerShell sessions, causes bcfg to fail with the message "Interactive input failure detected."
Service Configuration Properties
On Windows server environments, Zen servers run as a service. The service is loaded as part of the installation process and is set to be always available if you applied the complete installation.
You can configure the startup policy for the service from within ZenCC.
To use ZenCC to set service startup policy
1 In ZenCC expand the Services node.
2 Right-click Actian Zen Server Engine.
3 Click Properties.
4 For Startup type, select a startup policy.
Policy
Meaning
Manual
The service is not started automatically when the operating system starts. You must manually start the service after the operating system starts or restarts.
Automatic
The service is started automatically when the operating system starts or restarts.
Disabled
The service is rendered inoperative until you reset the startup policy to Manual or Automatic.
5 Click OK.
Server Configuration Properties on All Platforms
Each Zen database engine has its own server configuration. This topic describes the options available for each engine, which are independent of those for other engines.
You can configure Zen servers on Windows, Linux, macOS, and Raspbian platforms using ZenCC or the command line tool bcfg. For ZenCC, open the properties window by right-clicking a database engine node. For the command line, see Configuration Using Bcfg.
The following table lists all server configuration properties and their settings in alphabetical order. The settings are linked to topics with more information.
Table 7 Server Configuration Properties
Configuration Option
Setting Name
Server name (display-only)
Engine version (display-only)
Engine type (display-only)
 
 
 
 
 
 
 
 
 
Access
Right-click a server and select Properties > Access to see the following configuration settings:
Accept Remote Request
Allow Cache Engine Connections
Allow Client-Stored Credentials
Authentication (Linux-Based Engines Only)
Configuration File (Linux, macOS, and Raspbian Engines Only)
Prompt for Client Credentials
Wire Encryption
Wire Encryption Level
Accept Remote Request
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Yes
This setting specifies whether the Communications Manager accepts requests from remote servers and client workstations. If you turn this option to On, the Communications Manager advertises its presence on the network.
Allow Cache Engine Connections
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Yes
Specifies if the server will support clients that will attempt to connect to the server with the Cache engine. When set to Off, clients will still connect to the server but will not use the Cache engine.
Allow Client-Stored Credentials
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
No
When this setting is On, the database engine accepts user credentials stored on the client. The method and location of storage depends on the operating system of the client:
Windows clients: these credentials are stored in the Windows registry. When the Prompt for Client Credentials is set to On, then a popup dialog allows you to save the credentials by selecting the Save User name and Password check box. Alternatively, you can use the pvnetpass command line tool to manage stored credentials.
Linux, macOS, and Raspbian clients: Credentials are stored in the Zen registry by pvnetpass.
When this setting is Off, the database engine forces the client to omit stored credentials from any database operation that requires credentials. Such credentials must be supplied by the application or through the login dialog. The login dialog still writes client-stored credentials if specified using the login dialog, even if this setting is Off. However, they will not be accepted.
When client-stored credentials are allowed, anyone can sit at that particular client computer and log in to the database using the stored credentials without knowing those credentials. This behavior can be convenient for environments in which strict authentication of individual users is not a concern, such as a physically secured work area where all users have the same level of access permissions. On the other hand, in environments where unauthorized personnel are present or authorized users have varying levels of access permissions, this setting must be Off.
See also Prompt for Client Credentials.
Summary Chart of Login Behavior
 
Table 8 Summary of Login Configuration Behavior
Prompt for Credentials
Allow Client-Stored Credentials
Behavior
Off
Off
Zen client does not prompt the user or use stored credentials, thus credentials must be supplied by the client application during a Btrieve operation.
Off
On
If credentials are not supplied by the client application during the Btrieve operation, the client uses credentials stored by the login dialog or by pvnetpass, if such credentials are available. If no credentials are supplied by either method, the connection attempt fails. No login dialog is displayed.
On
Off
If credentials are not supplied by the client application during the Btrieve operation, the client displays a login dialog to the user, and the Linux, macOS, or Raspbian client returns a status code for permissions error. Credentials stored by the login dialog or by pvnetpass are not used.
On
On
If credentials are not supplied by the client application during the Btrieve operation, stored credentials are used. If no stored credentials are available, then the client displays a login dialog to the user, and the Linux, macOS, or Raspbian client returns a status code for permissions error.
Authentication (Linux-Based Engines Only)
Type
Range
Default
Units
Requires Engine Restart
SelectOne
Three options. See below
Emulate Workgroup Engine
None
Yes
The following options set which type of authentication to use for access to the server engine:
Emulate Workgroup Engine. Use this value when Samba is used to authenticate user access on the system. If you want to bypass security provided by the operating system and do not want to store RTSS passwords in the registry, use Emulate Workgroup Engine.
Proprietary Authentication (using btpasswd). Use this value when not using Samba for Linux or SMB for macOS to authenticate and the user has no account on the server. This option allows you to maintain a separate password file for connecting to the Linux, macOS, or Raspbian system.
If you are using BTPASSWD authentication on your server, user names and passwords must be set from clients connecting to this server. Use Zen Control Center or pvnetpass at a command prompt. See Groups, Users, and Security and pvnetpass, both topics in Zen User’s Guide.
Use Proprietary Authentication if stronger security is needed for the server and you want user names and passwords to be different from any user authentication scheme employed on the server.
Standard Linux Authentication. Use this value when not using Samba to authenticate but users have accounts on the Linux, macOS, or Raspbian system.
Standard Linux authentication is used with PAM. Use PAM if you want to use existing user names and passwords on the Linux, macOS, or Raspbian server. You can specify user names and passwords from the client using pvnetpass. PAM is also very flexible and offers many custom modules for Linux, macOS, and Raspbian. Check the PAM home page on the Web for more information.
If the Zen installation detects PAM, the installation completes its configuration so that PAM can be used. If you install PAM after installing Zen and want to use standard authentication with PAM, you must reinstall Zen. The reason is that the PAM installation copies files, creates configuration files, sets permissions, and creates links. Zen needs to be reinstalled to detect PAM and correctly complete its PAM configuration.
You reinstall Zen by uninstalling and then installing again. See Installing Zen for Linux-based Systems in Getting Started with Zen for the steps to do this.
Samba and Authentication Using PVPIPE$ (Linux Only)
You may use Samba, if available, in addition to any of the three authentication methods described above. If PVPIPE$ is shared as described under Configuration File (Linux, macOS, and Raspbian Engines Only), the Zen engine creates the FIFO in $ACTIANZEN_ROOT/etc/pipe/mkde.pip. PVPIPE$ is supported only on Linux.
Note The trailing dollar sign ($) means this share will be hidden. The Zen client components automatically take care of accessing this pipe as \\<server>\PVPIPE$\mkde.pip (case-insensitive). You do not need to perform any explicit actions or modify your application to access this pipe. The only exception to this is if you are troubleshooting your Samba or Zen configurations.
When a client connects to the remote engine and discovers the engine returns Unix in the version block, it first looks in the registry (RTSS setting) for authentication information. If it finds no user name and password there, the client connects to the above pipe and receives client authentication information from the server, which will be validated later.
To be authenticated, you must be able to connect to the share and read the pipe. This is one way of specifying who can use the engine and who cannot. The easiest way to do this is to set the valid users value in the smb.conf configuration file. If the client is unable to get authentication, status 3119 is returned.
Caution By allowing a client read access to PVPIPE$, that client is authorized to access the engine remotely.
A simple way to ensure the client gets authentication is to enter \\<yourserver>\pvpipe$\mkde.pip at a command prompt. You should see a lot of question marks (unprintable symbols), occasional printable characters, and hear beeps. If you do not, check your Samba configuration file to be sure you have rights to read this pipe. If you do but still see error 94 or 3119, validate your RTSS setting using the engine configuration properties in Zen Control Center or with pvnetpass.
To learn more about access to files shared through Samba, read the Samba documentation.
Configuration File (Linux, macOS, and Raspbian Engines Only)
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
/etc/smb.conf
None
Yes
This setting gives the location of the smb.conf file used to export local file systems to Windows clients. The engine requires this file to translate UNC paths on remote systems into local calls to the correct database file. Note that on macOS and Raspbian systems where native SMB file sharing is used instead of a third-party Samba package, this setting does not apply.
The default value is /etc/smb.conf. If you installed the Samba configuration file in a different location, enter the correct path name.
Zen checks for the smb.conf configuration file in the following locations, in this order:
/etc/samba/smb.conf
/etc/smb.conf
/usr/local/samba/lib/smb.conf
/usr/local/lib/smb.conf
/lib/smb.conf
/etc/samba.d/smb.conf
/opt/samba/lib/smb.conf
/usr/share/samba/smb.conf
/usr/local/share/samba/smb.conf
/home/samba/lib/smb.conf
/opt/local/etc/samba3/smb.conf
The first smb.conf found is the one used. If no smb.conf is found, Zen logs an entry in the system log file, and no Samba sharing is enabled.
On Linux, if you want to use the PVPIPE$ FIFO share, and it is not already present in the smb.conf file, you must be set in the file as follows. Note that Zen server installation creates the zen-svc user and zen-data group.
[PVPIPE\$]
comment = Zen pipes
path = /usr/local/actianzen/etc/pipe
# only members of group zen-data will have access
valid users = @zen-data
# Absolutely necessary - prevents caching
oplocks = no
level2 oplocks = no
read only = yes
browseable = no
To enable the user named zen-svc to access this share, you must use the smbpasswd command with certain parameters. See the Samba documentation for information about the -n option. When you are ready to enable access, do the following on the system where Zen Enterprise Server or Cloud Server is installed:
1 Log in as root.
2 Run the following command to add user zen-svc to the local smbpasswd file:
smbpasswd -a -n zen-svc
3 Restart smbd for the changes to take effect.
Prompt for Client Credentials
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
No
This setting determines whether the Windows Zen client prompts the user for login credentials if no other credentials are available during a database operation that requires user authentication.
When this setting is On, in the absence of other authentication credentials, the engine requires the Windows client to present a login dialog to the user. This setting applies only when Mixed or Database security is in effect and does not apply to a Linux, macOS, or Raspbian client under any circumstances. If valid credentials are supplied via another method (for example, explicit Btrieve Login (78) operation or credentials stored on the client), the login dialog does not appear.
If no database context is specified to the engine within the operation requiring user credentials, the engine assumes the user is attempting to log in to the current database.
When this setting is Off and one of the new security models is in use, user credentials must be provided programmatically (credentials stored on the client or provided with a Btrieve Login (78), Open (0), or Create (14) operation), or else the login attempt fails with an authentication error.
See Also
Allow Client-Stored Credentials
Storage Server
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
blank
None
Yes
This property gives the name of the Zen server that the Client Reporting Engine is supporting. It is set on the system where the Client Reporting Engine is installed. On Windows, the string is not case-sensitive. This setting is provided in Zen only for Client Reporting Engine.
Wire Encryption
Type
Range
Default
Units
Requires Engine Restart
Single select
Never
If Needed
Always
If Needed
None
Yes
This property specifies whether the given client or server should use encryption for its network communications. The default value of If Needed means that the client or server only uses encryption if the other end of the communication stream requires it. For example, assume that Server A has its Wire Encryption value set to Always. Server B has its value set to Never. Your client has its value set to If Needed. In this case, the client will use encryption when communicating with Server A, but it will not use encryption when communicating with Server B.
The following table summarizes behavior for each combination of client and server values.
Table 9 Client-Server Results of Wire Encryption Setting Combinations
Client Setting
Server Setting “Never”
Server Setting “Always”
Server Setting “If Needed”
Never
Encryption not used
Status Code 5001
Encryption not used
Always
Status Code 5000
Encryption used. Level determined by highest Wire Encryption Level setting between client and server
Encryption used. Level determined by client Wire Encryption Level setting.
If Needed
Encryption not used
Encryption used. Level determined by server’s Wire Encryption Level setting
Encryption not used
Wire Encryption Level
Type
Range
Default
Units
Requires Engine Restart
Single select
Low
Medium
High
Medium
None
Yes
This setting specifies the strength of the encryption key that should be used for encrypted communications. The following table shows the levels available.
Table 10 Meaning of Encryption Level Values
Value
Meaning
Low
40-bit encryption key used
Medium
56-bit encryption key used
High
128-bit encryption key used
Encryption using a key 128 bits long is generally accepted as strong encryption. The other settings provide progressively less protection but higher performance, in the event that you require some level of encryption but are willing to accept a lower level of deterrence to gain better performance.
When a client and a server both require encryption and one specifies a stronger encryption level than the other, the two entities use the stronger level to communicate.
Communication Protocols
Communication Protocols contains the following configuration settings:
Auto Reconnect Timeout
Enable Auto Reconnect (Windows only)
Listen IP Address
Supported Protocols
TCP/IP Multihomed
TCP/IP Port
Auto Reconnect Timeout
Type
Range
Default
Units
Requires Engine Restart
Numeric
45 - 65535
180
seconds
Yes
This setting specifies how long the client will attempt to connect to the server before giving up. When an Auto Reconnect-enabled client first connects to a Auto Reconnect-enabled server, the server communicates this value to the client so that both components know how long to attempt to reconnect in the event of a network interruption.
Enable Auto Reconnect (Windows only)
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Yes
This setting specifies whether you want the server to support clients attempting to automatically reconnect during a network outage. A setting of On means Auto Reconnect is enabled.
Auto Reconnect is not in effect for a given client connection unless this setting is also enabled in that client’s configuration.
To specify how long a client will attempt to reconnect to the server before giving up, see Auto Reconnect Timeout, above.
Listen IP Address
Type
Range
Default
Units
Requires Engine Restart
String
Valid IP address or multiple addresses separated by a comma between each address
0.0.0.0
None
Yes
This option specifies the IP address or addresses the database engine listens on when TCP/IP Multihomed is Off. This option is ignored when TCP/IP Multihomed is On.
Multiple IP addresses may be specified but must be separated by a comma between each address. The string can be a combination of IPv4 and IPv6 addresses. Any of the IPv6 address formats supported by Zen can be used. See Drive-based Formats in Getting Started with Zen.
Supported Protocols
Type
Range
Default
Units
Requires Engine Restart
Multiple select
One or more
TCP/IP
None
Yes
This setting specifies the protocols by which the database engine listens for client connections. If more than one protocol is selected, the engine begins the session by listening on all of them. The first protocol that succeeds is used for the remainder of the session. You must have at least one protocol enabled on both the client and the server or they cannot communicate.
Note The default is TCP/IP, which is the only option currently supported.
Linux, macOS, and Raspbian
TCP/IP is the only supported protocol for Zen on Linux, macOS, and Raspbian. Therefore, the Supported Protocols setting is not available for those environments.
TCP/IP Multihomed
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Yes
This option specifies whether the database engine should listen for client connections on all network interfaces. If it is set to On, the database engine listens on all network interfaces, and the IP addresses listed in the Listen IP Address option is ignored. If this setting is Off, you must specify in Listen IP Address which addresses) for the database engine to use for client communications.
TCP/IP Port
Type
Range
Default
Units
Requires Engine Restart
Numeric
256 to 65535
1583
None
Yes
This setting configures the port number used by the Relational Engine.
This port number must be the same as that defined in any Client DSNs pointing to this server. For information on how to change the port number in a Client DSN, see Advanced Connection Attributes in ODBC Guide.
For additional information on ports, see Changing the Default Communication Ports in Getting Started with Zen.
Compatibility
Compatibility contains the following configuration settings:
Create File Version
System Data
Create File Version
Type
Range
Default
Units
Requires Engine Restart
SelectOne
6.x - 8.x, 9.0, 9.5, 13.0
9.5
None
No
This setting specifies the format used to create new files, but it does not affect files already created. All files from version 6.x onward can be read from and written to without changing their file format. So 8.x files are kept in 8.x file format, 7.x files in 7.x format, and 6.x files in 6.x format. The exception is 5.x files and earlier, which can be read but cannot be written without first rebuilding them to convert them to a later format.
Choose 6.x, 7.x, or 8.x only if you need backward compatibility with a previous MicroKernel version.
Note Dictionary files (DDFs) must be created with a file format of 6.x or later. The New Database wizard uses the setting for create file version. The data files can be in any of the previous file formats supported. Only the DDFs must use a file format of 6.x or later.
System Data
Type
Range
Default
Units
Requires Engine Restart
Single select
See below
If needed
None
No
System data refers to a hidden unique key in each record. Because the MicroKernel relies on uniquely identifying rows in order to ensure transaction durability, a file must either have a unique key defined or have system data included in the file. The default value is If needed; the available options are:
None. By default, system data is not included on file creation. Application developers using the Create operation can override this setting.
If needed. System data is added to the file on file creation if the file does not have a unique key.
Always. System data is always added on file creation, regardless of whether the file has a unique key.
Note The System Data setting does not affect existing files. This setting only affects how new files are created.

If you want to use transaction durability with a file that was not created with System Data turned on and does not have a unique key, you must recreate the file after setting System Data to Yes or If needed.

The Relational Engine always creates files with System Data. This information applies to files created through SQL, OLE DB, JDBC, or any method other than the Btrieve API.
Even if a file has a unique key, you may want to include system data, because users can drop indexes.
Data Integrity
Data Integrity contains the following configuration settings:
Archival Logging Selected Files
Initiation Time Limit
Operation Bundle Limit
Transaction Durability
Transaction Logging
Wait Lock Timeout
Archival Logging Selected Files
Type
Range
Default
Units
Requires Engine Restart
Boolean
On, Off
Off
None
Yes
This setting controls whether the MicroKernel performs archival logging, which can facilitate your file backup activities. If a system failure occurs, you can use the archival log files and the butil -rollfwd command to recover changes made to a file between the time of the last backup and a system failure.
To direct the MicroKernel to perform archival logging, you must specify the files for which the MicroKernel is to perform archival logging by adding entries to an archival log configuration file that you create on the volume that contains the files. For more information about archival logging, refer to Understanding Archival Logging and Continuous Operations.
Initiation Time Limit
Type
Range
Default
Units
Requires Engine Restart
Numeric
1 - 1800000
10000
milliseconds
No
This setting specifies the time limit that triggers a system transaction. The MicroKernel initiates a system transaction when it reaches the Operation Bundle Limit or the time limit, whichever comes first, or when it needs to reuse cache.
Operation Bundle Limit
Type
Range
Default
Units
Requires Engine Restart
Numeric
1 to 65535
65535
None
No
This option specifies the maximum number of operations (performed on any one file) required to trigger a system transaction. The MicroKernel initiates a system transaction when it reaches the bundle limit or the Initiation Time Limit, whichever comes first, or when it needs to reuse cache.
The MicroKernel Database Engine treats each user transaction (starting with Begin Transaction until End Transaction or Abort Transaction) as one operation. For example, if there are 100 Btrieve operations between the Begin Transaction and the End Transaction operation, then all the 102 Btrieve operations together are treated as a single operation.
Transaction Durability
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Yes
Transaction Durability is the same as Transaction Logging except that Transaction Durability guarantees that all successfully completed transactions are committed to the data files in the event of a system crash.
For a full discussion of transaction logging and durability, see Transaction Logging and Durability.
Note When you turn Transaction Durability on, some files may not be able to support the feature. A file must contain at least one unique key, or when it was created, the configuration setting System Data must have been set to “Yes” or “If Needed.” Otherwise, any changes to the file are not written to the transaction log. For more information about transaction durability and system data, see Zen Programmer’s Guide.

Because System Data does not affect existing files, you may need to recreate files that do not have a unique key and were not created with System Data turned on. Be sure to turn on System Data before recreating these files.
Caution Gateway locator files allow different engines to manage files in different directories on the same file server. If your database contains data files in different directories, you must be sure that the same database engine manages all the data files in the database. If you have more than one database engine managing files within the same database, database integrity and transaction atomicity are not guaranteed. For more information on how to avoid this potential problem, see Redirecting Locator Files.
Related Settings
See more information on similar and related settings under Transaction Logging.
Transaction Logging
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Yes
This setting controls whether the MicroKernel ensures atomicity of transactions by logging all operations that affect the data files.
If the related setting, Transaction Durability, is turned on, then logging takes place automatically, and the Transaction Logging setting is ignored.
For a full discussion of transaction logging and durability, see Transaction Logging and Durability.
Note When you turn Transaction Logging on, some files may not be able to support the feature. A file must contain at least one unique key, or when it was created, the configuration setting System Data must have been set to “Yes” or “If Needed.” Otherwise, any changes to the file are not written to the transaction log. For more information about transaction durability and system data, see Zen Programmer’s Guide.
Because System Data does not affect existing files, you may need to recreate files that do not have a unique key and were not created with System Data turned on. Be sure to turn on System Data before recreating these files.
Caution Do not turn off Transaction Logging unless your database does not require transaction atomicity among data files. Database integrity for multifile databases cannot be guaranteed if Transaction Logging is turned off.

Do not turn off Transaction Logging unless doing so is supported by your application vendor.
Related Settings
The server configuration setting Transaction Durability is similar to Transaction Logging, but provides a higher level of data safety along with a lower level of performance. The server configuration settings Log Buffer Size and Transaction Log Size are related to Transaction Logging. Log Buffer Size allows you to configure the balance between transaction recoverability and performance. The larger the log buffer, the fewer times it is written to disk, and thus the greater the performance. However, database changes that are in the log buffer are not durable through a system failure.
Transaction Log Size controls how large each log file segment gets before a new segment is started.
Note that all of these settings are ignored if Btrieve or SQL transactions are not being used.
Wait Lock Timeout
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 - 2147483647
30000
milliseconds
Yes
The database engine and its clients use a coordinated retry mechanism when a record lock conflict occurs. If the engine cannot obtain a lock on every requested record within the duration for wait lock timeout, the engine returns control to the application with an appropriate status code.
Wait Lock Timeout Benefits
Wait lock timeout provides the following benefits if a lock conflict occurs:
Allows the database engine to continue processing requests while waiting for the lock to release.
Improves thread queuing if multiple threads are waiting for the locked resource.
Improves network performance by reducing network traffic.
When Wait Lock Timeouts Apply
Wait lock timeouts apply to only two kinds of applications:
Any application that uses the Relational Engine
Btrieve applications performing a change operation that does not need to be retried. Such applications receive a lock error within either one second or the wait lock timeout value, whichever is less.
Wait lock timeouts do not usually apply to Btrieve applications that use the MicroKernel Engine through a Zen client on Windows, Linux, macOS, or Raspbian. Instead, such applications do one of the following:
Receive a page or lock conflict error immediately for read operations with “no wait” lock bias (200, 400) or a write operation to which a “no write wait” lock bias (500) has been applied.
Receive a page or lock conflict error within the lesser of either 1 second or the wait lock timeout value for nontransactional write operations where a “no write wait” lock bias (500) has not been applied.
Wait indefinitely if the operation involved is a read operation with a “wait” lock bias (100, 300).
Wait indefinitely if the operation involved is a write operation inside of a transaction and a “no write wait” lock bias (500) has not been applied to either the operation or the transaction.
On receiving a page or lock conflict error, the application may determine how to handle the conflict by retrying, waiting, or other options.
Handling of Page Locks
The MicroKernel Engine API provides controls to handle record lock situations. In brief, here are the control mechanisms:
Explicit record locks – You can add lock biases (100, 200, 300, or 400) to read operations when reading records to specify whether to wait. You may also apply these biases to the Begin Transaction operation.
Implicit page locks during a transaction – Most page lock conflicts are avoided because of row-level locking, but you can add lock bias 500 to your transactions to avoid waiting when a page lock occurs.
Exclusive file locks – Use concurrent transactions to avoid explicit file locks. If a file cannot be opened exclusively, the request always returns immediately.
For more information about transaction locking, see Zen Programmer’s Guide, as well as lock bias steps for various operations in Btrieve API Guide.
Debugging
Debugging contains the following configuration settings:
Number of Bytes from Data Buffer
Number of Bytes from Key Buffer
Select Operations
Trace File Location
Trace Operation
Number of Bytes from Data Buffer
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 - 65535
128
bytes
No
This setting specifies the size of the data buffer that the MicroKernel writes to the trace file. The Trace Operation setting must be set to On to use this setting. The size you specify depends on the nature of your tracing needs (whether you need to see the entire data buffer contents or just enough of the buffer contents to identify a record).
Number of Bytes from Key Buffer
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 - 255
128
bytes
No
This setting specifies the size of the key buffer that the MicroKernel writes to the trace file. The Trace Operation setting must be set to On to use this setting. The size you specify depends on the nature of your tracing needs (whether you need to see the entire key buffer contents or just enough of the buffer contents to identify a key).
Select Operations
Type
Range
Default
Units
Requires Engine Restart
Multiselect
See below
All
None
No
The Selected list displays the available Btrieve API operation codes that are traced. Select from the list the desired operations to trace.
Abort Transaction (21)
Get Position (22)
Begin Transaction (19)
Get Previous (7)
Clear Owner (30)
Get Previous Extended (37)
Close (1)
Insert (2)
Create (14)
Insert Extended (40)
Create Index (31)
Open (0)
Delete (4)
Reset (28)
Drop Index (32)
Set Directory (17)
End Transaction (20)
Set Owner (29)
Extend(16)
Stat (15)
Find Percent (45)
Step First (33)
Get By Percent (44)
Step Last (34)
Get Direct/Chunk (23)
Step Next (24)
Get Directory (18)
Step Next Extended (38)
Get Equal (5)
Step Previous
Get First (12)
Stop (25)
Get Greater (8)
Step Previous Extended (39)
Get Greater or Equal (9)
Unlock (27)
Get Last (13)
Update (3)
Get Less or Equal (11)
Update Chunk (53)
Get Less Than (10)
Version (26)
Get Next (6)
 
Get Next Extended (36)
 
Trace File Location
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
file_path\Zen\bin\mkde.tra
None
No
This setting specifies the trace file to which the MicroKernel writes trace information. The file name must include a drive or volume specification and path or use a UNC path. If you do not want the trace file in the default location, enter a different path or file name.
For default locations of Zen files, see Where are the files installed? in Getting Started with Zen.
Note Do not use the same trace file name for ODBC tracing and MicroKernel tracing.
Trace Operation
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
No
This setting enables or disables the trace feature, which allows you to trace each Btrieve API call and save the results to a file. Developers can use tracing to debug applications. The MicroKernel writes to the trace file using forced write mode, which ensures that data gets written to the file even if the MicroKernel unloads abnormally. The MicroKernel’s performance can be severely impacted, depending on the frequency of incoming requests. If you enable this option, you must specify a Trace File.
Note You do not need to restart the engine in order to start and stop tracing. You can turn tracing on or off during runtime and apply the changes directly to the engine. If you receive a message from Configuration indicating that you must restart the engine for changes to take effect, you may safely ignore the message for this setting.
Directories
Directories contains the following configuration settings:
Temporary File Location
Transaction Log Directory
Working Directory
DBNames Configuration Location
TEMPDB Directory (Client Reporting Engine only)
Temporary File Location
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
Varies
None
No
This property sets the directory where Zen can write a temporary file while processing a query. For more information, see Temporary Files in SQL Engine Reference.
Transaction Log Directory
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
Varies
None
Yes
This setting specifies the location the MicroKernel uses to store the transaction log. It must be a valid path and include a drive or volume specification or UNC path. Default varies with the operating system.
The engine ignores this setting unless Transaction Durability or Transaction Logging is turned on.
Caution Do not use the same directory for multiple database engines. For example, it may seem convenient to set a remote server directory as the transaction log directory for more than one engine. However, the engines will be unable to determine which transaction log segments belong to which engine if it becomes necessary to do a log roll forward
If your database engine sees heavy use, you should configure your system to maintain the transaction logs on a separate physical volume from the volume where the data files are located. Under heavy load, performance is typically better when the log writes and data file writes are split across different drives instead of competing for I/O bandwidth on a single drive. For a full discussion of transaction logging, see Transaction Logging and Durability.
Working Directory
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
Same directory as data file
None
Yes
This setting specifies the location of the MicroKernel working directory, which is used to store temporary files in operations such as building large indexes. If disk space is limited on certain volumes, you can use this option to specify a working directory on a volume with adequate space.
There is no default value specified, but if you do not set a working directory, then the default is the location of the data file. To specify a fixed working directory, enter a path in the Value text box. The path must include a drive or volume specification or a UNC path.
DBNames Configuration Location
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
Varies
None
Yes
This value sets the path to an alternate location for the DBNames configuration file.
For Zen server engines, this is a local file path, not a directory path. For Workgroup engines, it can be a remote path accessible to the Workgroup MicroKernel. The default value varies by operating system.
Windows platforms: application_data_directory\
Linux, macOS, or Raspbian server: /usr/local/actianzen/etc
If you do not want the configuration file in the default location, enter a valid path.
TEMPDB Directory (Client Reporting Engine only)
Type
Range
Default
Units
Requires Engine Restart
String
not applicable
Varies
None
Yes
This property sets the location where Client Reporting Engine creates a temporary database to cache data from its storage server. It must be a valid path and include a drive or volume specification or UNC path. Default varies with the operating system. This setting is provided only for Client Reporting Engine.
Information
Information lists the following display-only items:
Display-only Item
Discussion
Server name
The name of the machine on which the database engine is running
Engine version
The release version of the database engine
Engine type
The product category of the database engine
Memory Usage
Memory Usage contains the following configuration settings:
Allocate Resources at Startup
Back to Minimal State if Inactive
Minimal State Delay
Sort Buffer Size
System Cache
Allocate Resources at Startup
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Yes
This setting instructs the MicroKernel to allocate resources, including threads and memory buffers, when the MicroKernel is started. The resources allocated at startup includes the background threads in addition to the L1 cache. Zen components automatically allocate resources as needed. Therefore, in most cases, this setting can be off, which is the default.
With the setting off, the MicroKernel does not allocate any resources until the first operation request. If your server system supports a large number of users, you may prefer to have this setting turned on.
When first set to on, the setting may not produce any noticeable difference in the memory allocated because of how Windows behaves. When the MicroKernel allocates its L1 cache, the Windows operating system reserves pages of memory but does not commit them to the MicroKernel. Later, when the MicroKernel actually accesses cache memory, Windows then commits physical pages and memory usage of Zen components increases.
If you look at the VM Size column in Windows Task Manager, you can see the memory value change as L1 cache is accessed. You should also be able to see the number of threads change when background threads are accessed.
Back to Minimal State if Inactive
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Yes
This setting causes the MicroKernel to free considerable memory and thread resources to the system and return to a minimal state after a certain amount of time without any active clients. The time interval is specified by the value of Minimal State Delay. The MicroKernel reallocates resources when another client becomes active.
Minimal State Delay
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 - 2147483647
300
milliseconds
Yes
This value sets how long the MicroKernel waits during a period of inactivity before returning to a minimal state, the initial state in which the MicroKernel begins. By returning to this state, the MicroKernel frees memory and thread resources to the system. In some cases, you may not want the MicroKernel to return to a minimal state. For example, you may be running a batch file that uses the MicroKernel repeatedly. The MicroKernel reallocates resources when another client becomes active.
This setting is ignored if the value of Back to Minimal State if Inactive is set to Off (the default).
Sort Buffer Size
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 - limited by memory
0
bytes
Yes
This setting specifies the maximum amount of memory (in kilobytes) that the MicroKernel dynamically allocates and releases for sorting purposes during run-time creation of indexes.
If the memory required for sorting exceeds the size specified or is greater than 60 percent of the available process memory, the MicroKernel creates a temporary file. The amount of available memory for a process is a dynamic value and varies according to system configuration and load. If you specify zero kilobytes, the MicroKernel allocates as much memory as needed, up to 60 percent of the available memory.
System Cache
Type
Range
Default
Units
Requires Engine Restart
Boolean
On, Off
Off (Server)
On (Workgroup)
None
Yes
This option specifies whether the MicroKernel should use the system cache in addition to the MicroKernel’s own database cache, as set using the configuration parameter Cache Allocation Size.
If you are using the L2 cache, you should set System Cache to Off. Check the setting of Max MicroKernel Memory Usage. When Max MicroKernel Memory Usage is set to a value greater than zero, you are using L2 cache.
If you are not using L2 cache, performance can be enhanced by turning on System Cache. The MicroKernel relies on the system cache to organize and group pages to be written. It delays a flush long enough to allow the system cache to write the pages to disk in a more efficient manner. However, if your server has an advanced self-cached disk array, you might achieve better performance by setting System Cache to Off.
For Windows Server only, you can use the Paging File and Process objects in the Windows Performance Monitor tool to determine whether the Windows system cache is being used effectively. For the zenengnsvc.exe instance, monitor the % Usage and % Usage Peak in the Page File object and the Page Faults/Second and Page File Bytes in the Process object.
Performance Tuning
Performance tuning involves the following configuration settings:
Automatic Defragmentation
Cache Allocation Size
Communications Threads
File Growth Factor
Index Balancing
Limit Segment Size to 2 GB
Log Buffer Size
Max MicroKernel Memory Usage
Number of Input/Output Threads
Transaction Log Size
Automatic Defragmentation
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
No
This setting turns automatic defragmentation on or off. When it is on, the feature works as follows:
One hour after the setting is turned on, the engine begins discovery of files to defragment.
The engine first identifies files active since the last engine restart.
The engine then tests those files for any of the following criteria.
 
Analysis
Greater Than or Equal to
Fragmented
15%
Unused
15%
Out of Order
5%
These criteria are the same as the ones defined under the Watch List topic. The advantage of automatic defragmentation is that you do not have to manually select files, add them to the Watch List, and then manually check and defragment them.
Defragmentation begins immediately on the first file that meets any of the criteria.
The engine defragments one file at a time. When it finishes with a file, it waits one minute before starting to defragment the next one.
For efficiency, files matching the following criteria are ignored:
Already defragmented in the last 24 hours
Smaller than 10 MB
If you want to defragment such files, add them to the Watch List for manual monitoring or use the dbdefrag command line tool.
When all files meeting automatic defragmentation criteria are done, the engine waits 60 minutes before beginning the next round of file discovery.
Messages in zen.log state whether a file was defragmented automatically or manually.
Note If an active file is closed and its pages flushed from cache, the engine no longer considers it a candidate for automatic defragmenting. When the file is next opened, the engine discovers it again.
For more information about defragmenting data, see Monitoring Data File Fragmentation.
Cache Allocation Size
Type
Range
Default
Units
Requires Engine Restart
Numeric
1 MB to the amount limited by memory
Server value calculated on first startup, 64 MB for other editions
MB
Yes
This property sets the size of the Level 1 cache that the MicroKernel allocates. The MicroKernel uses this cache when accessing data files.
Generally speaking, overall performance is best when the cache allocation size is a value less than 40% of the physical memory on the system, and the configuration property Max MicroKernel Memory Usage is set to a value greater than 40%. Your optimal settings depend on the size of your data files, the number of other applications running on the system, and the amount of physical memory.
Setting for a Server Engine
The initial setting is 20% of physical memory. The database engine calculates this value the first time it starts and writes it to the registry. From then on, whenever the engine starts, it reads the value in the registry. The engine never recalculates the value. Changing it manually updates the registry.
Setting for Workgroup, Client Cache, and Client Reporting Engines
For Zen installations other than servers, cache allocation size is set to a default value of 64 MB. As for servers, changing it manually updates the registry.
Note If you use Zen clients before PSQL v10, the value for Fcache allocation size must be specified in bytes, with a minimum of 64 KB (65,536 bytes).
Using Cache Allocation Size to Optimize Performance
To optimize performance, set a larger cache allocation size. The value should be no larger than the sum of the sizes of the files that the engine is using. Setting a higher value provides no benefit and may waste memory needed by the system for other tasks. Taking all available memory, especially if the system is running other applications, may lead to undesirable behavior.
If you add or remove memory from the system, you also should reset this property to take account of the new amount of memory.
Communications Threads
Type
Range
Default
Units
Requires Engine Restart
Numeric
num_cores to 256
num_cores, where num_cores is the number of processors in the machine on which the database engine is running
None
Yes
This setting specifies how many threads the MicroKernel initially spawns to handle requests from remote clients. Communication threads are the elements that actually perform Btrieve operations on behalf of the requesting remote client process. In this way they are very similar to worker threads. Communications threads increase dynamically as needed up the maximum range allowed. The maximum is 256.
The Communications Threads setting can help improve scaling under certain conditions. For example, if you have many clients performing operations (typically writes) on one file, a lower setting should improve scalability. The lower number of threads prevents context switching on system resources. Another condition that this setting may improve is a slowdown caused by thrashing among large numbers of worker threads. Worker threads are dynamically created only if all the existing threads are waiting on record or file locks.
File Growth Factor
Type
Range
Default
Units
Requires Engine Restart
Numeric
0-100
15
Percent
Yes
This value specifies the approximate percentage of free pages to maintain in version 8.x and later format data files. The setting does not apply to any previous file format versions. The MicroKernel uses this value to decide whether to extend a file or use free pages first. The database engine has the ability to write multiple contiguous file pages on disk. The goal is to improve the performance of disk writes as the number of free pages increases within a file. However, because disk write performance is a trade-off against file size, allowing too many free pages in a file can reduce overall performance.
To maintain a certain amount of contiguous free pages in a data file, the database engine must periodically expand the file. Keep in mind that the file size effects of this setting are exponential. For example, if you start with a file that has no free pages and you set a File Growth Factor value of 50%, then the file will eventually double in size. If you set a File Growth Factor value of 75%, the file will quadruple in size. A value of 90% will allow the file size to grow by as much as 10 times.
Note that only completely unused pages are counted as empty, so 15% empty pages does not mean that 15% of the file is unused, since even mostly unused pages are not counted as empty.
Depending on how heavily a given file is being updated, the actual percentage of empty pages may be much less at any given moment.
This setting is not applicable to pre-8.x format files. These older files also have empty pages, but the percentage of empty pages varies with the activity on the file.
Index Balancing
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Yes
This setting controls whether the MicroKernel performs index balancing. Index balancing increases performance on read operations. However, when you enable this option, the MicroKernel requires extra time and may require more disk I/O during insert, update, and delete operations. For more information about index balancing, see Zen Programmer’s Guide.
Limit Segment Size to 2 GB
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Yes
This setting specifies that a data file is to be automatically broken into 2GB operating system file segments as its size passes that boundary. If set to On, this setting specifies that you want data files divided into 2GB segments. If set to Off, this setting specifies that data files will remain a single, nonsegmented file. The advantage of using a larger nonsegmented file is more efficient disk I/O. Therefore, you can expect increased performance.
Any nonsegmented files are subject to the limit on file size specified by your operating system. If a previously created file is already segmented, that segmentation remains on the file.
See also Automatic Upgrade of File Version for related information.
Note This setting does not affect 13.0 format files, which are never segmented.
Log Buffer Size
Type
Range
Default
Units
Requires Engine Restart
Numeric
262144 - limited by memory
The smaller value of the following:
(physical memory in MB / 256)
or 8 MB
bytes
Yes
This setting specifies the size of both the transaction log buffer and the archival log buffer that the MicroKernel uses. You can enhance performance by increasing the log buffer size, because the MicroKernel writes the log information to disk less frequently.
Note If you set Log Buffer Size to a value greater than that of Transaction Log Size, then the MicroKernel automatically increments Transaction Log Size to the value you specified for Log Buffer Size.
Max MicroKernel Memory Usage
Type
Range
Default
Units
Requires Engine Restart
Numeric
0-100
60
Percent
No
This property dynamically controls the size of the secondary (L2) cache so that all data caching (L1 + L2), plus additional internal memory usage needed by the MicroKernel Engine, does not exceed the proportion of total physical memory specified. The engine uses less than the specified proportion if it is not needed or not available. It may use additional memory for internal processing beyond the limit specified by this configuration if necessary to handle certain scenarios, such as massive data insert, update, and delete operations in transactions. Note that memory for the Relational Engine is not included in this discussion.
Entering a value of zero turns off dynamic caching. In this case, the only cache available is L1, the size of which is specified by Cache Allocation Size. Also in this case, the maximum amount of memory used will not be limited, and additional memory for the MicroKernel will be allocated and released as needed.
If you have a dedicated database server machine, then you should set Max MicroKernel Memory Usage to the maximum value, or whatever proportion of memory is not occupied by the operating system. If you run other applications on your database server and you need to balance performance among all of these, then you should set this value lower so that the database cache does not compete as much with the other applications when using available memory.
Note If Cache Allocation Size is set to a higher amount of physical memory than Max MicroKernel Memory Usage, then Cache Allocation Size takes precedence. For example, a machine has 1 GB of physical memory and you set Cache Allocation Size to 600 MB and Max MicroKernel Memory Usage to 40%. The L1 cache is allocated 600 MB of memory. Since Cache Allocation Size is higher, it takes precedence and the amount of memory allocated to the L1 cache exceeds the value specified for Max MicroKernel Memory Usage.
Use the following equation to determine the approximate value for Max MicroKernel Memory Usage.
(L1_cache_size + internal_allocations + L2_cache_size / size_of_physical_memory) * 100
where:
L1_cache_size is the Cache Allocation Size
internal_allocations is approximately 25% of the size of the L1 cache
L2_cache_size is the amount of memory that expands and contracts based on memory load of the system
size_of_physical_memory is the amount of memory installed in the machine
For more information on tuning performance, see Tuning Performance.
Number of Input/Output Threads
Type
Range
Default
Units
Requires Engine Restart
Numeric
1 to 1024
32
None
Yes
This setting specifies how many background I/O threads the MicroKernel spawns. These threads are responsible for writing all pages from the MicroKernel cache to the file on disk in an atomic and consistent manner. They also are responsible for initially opening a file and reading the File Control Record. Most of the other reads are done by local worker threads and communication threads. When the MicroKernel updates or writes to data files, it assigns each file to a particular I/O thread sequentially. When it reaches the last thread, the MicroKernel starts over until all data files have been assigned to a background thread. Because the MicroKernel does not spawn additional I/O threads as needed, specify the maximum number of I/O threads you anticipate needing.
For best performance, set this value based on the average number of open files. Monitor shows the current and peak number of files open. If your database has an average of 256 files open, then the default of 32 I/O threads makes each thread responsible for 8 files. A good rule of thumb is to have about 8 files per I/O thread. For example, if your average number of open files is 400, you should use about 50 I/O threads. Specifying a value higher than 64 may degrade performance, but that depends on the capabilities of the system.
Note No accurate way is available to calculate the appropriate number of I/O threads because this setting depends on the machine’s characteristics, OS configuration, and the database engine’s planned work load.
Transaction Log Size
Type
Range
Default
Units
Requires Engine Restart
Numeric
65536 - limited by disk space
2 times the Log Buffer Size
bytes
Yes
This setting specifies the maximum size of a transaction log segment. When the log file reaches its size limit, the MicroKernel closes the old log segment file and starts a new one. You might want to limit the size of your transaction log segments, because this reduces the disk space that the MicroKernel uses temporarily. However, limiting the size of the transaction log segments does require more processing by the MicroKernel and can decrease performance, because it has to close and create log segments more frequently.
Note If you set the value for this option less than the value you specified for Log Buffer Size, the Database Engine automatically adjusts Transaction Log Size by setting it to the value of Log Buffer Size.
Windows Client Configuration Properties
All Zen editions can be configured as clients. The client properties must be set independently for each client, including servers acting as clients. You can configure a client on Windows platforms using Zen Control Center or the command line tool bcfg. For ZenCC, open the properties window by right-clicking MicroKernel Router node in Zen Explorer. For bcfg, see Configuration Using Bcfg.
The following table lists all client properties and their settings in alphabetical order. The settings are linked to topics with more information.
Table 11 Client Configuration Properties
Configuration Option
Parameter Name
The settings available under Cache Engine Debugging perform the same functions for the client cache as similar settings for a server. See the related server settings for Debugging.
Access
Access contains the following configuration settings:
Gateway Durability
Number of Load Retries
Use IDS
Use Local MicroKernel Engine
Use Remote MicroKernel Engine
Gateway Durability
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Not applicable
This option specifies whether the MicroKernel Router should store in the registry a list of computers that do not have Zen running on them. This decreases the time it takes to find a gateway engine. You must set this option to Off when new engines are added to the workgroup.
Number of Load Retries
Type
Range
Default
Units
Requires Engine Restart
Numeric
0 to 65536
5
None
Not applicable
This setting specifies the number of times the MicroKernel Router attempts to connect to the target engine.
Use IDS
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting is primarily for use with legacy applications that used Zen (IDS). IDS functionality is now integrated into the core product and IDS is no longer available as separately installed components. The integration of IDS requires that you reconfigure your client-server environment.
Typically, an application provides its own file location information. As an alternative, IDS provided file location mapping based on information in a text file, idshosts.
If your applications do not use the mapping feature through idshosts, set Use IDS to Off to improve performance.
If your applications already use idshosts, or if you prefer to use this alternative method to map file locations, set Use IDS to On. See Using the idshosts File.
Note PSQL 8.5 or later is required if you set Use IDS to On or if your legacy applications pass file location information in the format of a PIDS URL. The requester uses database URIs to represent the IDS information. Database URIs were added with PSQL 8.5. See Database URIs in Zen Programmer’s Guide.
Use Local MicroKernel Engine
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Not applicable
This setting determines whether a local application tries to connect to a local engine. If turned off, no attempt is made to connect to a local engine.
Use Remote MicroKernel Engine
Type
Range
Default
Units
Requires Engine Restart
Boolean
On, Off
On
None
Not applicable
This setting specifies whether the MicroKernel Router allows access to an engine running on a remote server. If this value is set to On, and Use Local MicroKernel Engine is set to On, the remote server is tried first.
Wire Encryption
See Wire Encryption.
Note Client-side wire encryption settings are not used by the Zen JDBC and ADO.NET access methods. For them, encryption can be specified using the connection string. See Connection String Overview in JDBC Driver Guide and Defining Basic Connection Strings in Data Provider for .NET Guide.
Wire Encryption Level
See Wire Encryption Level.
Note Client-side wire encryption settings are not used by the Zen JDBC and ADO.NET access methods. For them, encryption can be specified using the connection string. See Connection String Overview in JDBC Driver Guide and Defining Basic Connection Strings in Data Provider for .NET Guide.
Application Characteristics
Application Characteristics includes the following configuration settings:
Embedded Spaces
Splash Screen
Verify Key Length
Embedded Spaces
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Not applicable
This option instructs the MicroKernel Engine to allow embedded spaces in file names for MicroKernel Engine operations.
Splash Screen
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting controls whether or not the MicroKernel Engine splash screen displays. The splash screen displays the first time a client requester loads.
Verify Key Length
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
On
None
Not applicable
This option can be used for legacy Btrieve applications to prevent the requester from verifying that the index key length passed to the client requester is large enough to hold the key. Setting this option to off may allow such applications to avoid status 21 errors.
Caution If set to off, this option disables the check by the Zen requester to prevent memory overwrites. A memory overwrite can cause a general protection fault (GPF) among other undesirable conditions.
Cache Engine
These settings apply only when the cache engine is running. The Workgroup engine doubles as a cache engine. Note, however, that the cache engine is not used if a database server engine is running.
Cache Engine contains the following configuration settings:
Allocate Resources at Startup
Back to Minimal State if Inactive
Cache Allocation Size
Max MicroKernel Memory Usage
Minimal State Delay
Allocate Resources at Startup
Type
Range
Default
Units
Requires Database Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting instructs the cache engine to allocate resources, including threads and memory buffers, when the cache engine is started.
If you turn this option off, the cache engine does not allocate any resources until the first operation request. Zen components automatically allocate resources as needed. Therefore, in most cases you do not need to do so explicitly.
Back to Minimal State if Inactive
This setting displays only if the Workgroup engine is running.
Type
Range
Default
Units
Requires Database Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting causes the cache engine to free considerable memory and thread resources to the system and return to a minimal state after a certain amount of time without any active clients. The time interval is specified by the value of Minimal State Delay. The cache engine reallocates resources when another client becomes active.
Cache Allocation Size
Type
Range
Default
Units
Requires Database Engine Restart
Numeric
1 MB to the amount limited by memory
Initialized dynamically at first startup
MB
Not applicable
This setting specifies the size of the Level 1 cache that the MicroKernel allocates; the MicroKernel uses this cache when accessing any data files.
Generally speaking, overall performance is best when the Cache Allocation Size is a value less than 40% of the physical memory on the system, and the configuration property Max MicroKernel Memory Usage is set to a value greater than 40 percent. Your optimal settings depend on the size of your data files, the number of other applications running on the system, and the amount of physical memory.
The database engine sets this value the first time it starts and writes it to the registry. The initial value is 20% of physical memory. From then on whenever the engine starts, it reads the value in the registry. Changing the value of this property updates it in the registry. If you add or remove memory from the system, you should reset this property to take best advantage of the new amount of memory.
Note If you use Zen Clients earlier than PSQL v10, the value for cache allocation size must be specified in bytes, with a minimum of 64 KB (65,536 bytes).
Max MicroKernel Memory Usage
Type
Range
Default
Units
Requires Database Engine Restart
Numeric
0-100
60
Percent
Not applicable
This setting specifies the maximum percentage of total physical memory that the cache engine is allowed to consume. The percentage applies to L1, L2, and all miscellaneous memory used by the cache engine. The database engine uses less if the memory is not needed or not available.
If a value of zero (0) is entered, then dynamic caching is turned off. In this case, the only cache available is L1, the available amount for which is set by Cache Allocation Size.
For more information on tuning performance, see Tuning Performance.
Minimal State Delay
This setting displays only if the Workgroup engine is running.
Type
Range
Default
Units
Requires Database Engine Restart
Numeric
0 - 2147483647
300
milliseconds
Not applicable
This setting specifies how long the cache engine waits during a period of inactivity before returning to a minimal state. (This is the initial state in which the cache engine begins.) By returning to a minimal state, the cache engine frees considerable memory and thread resources to the system. In some cases, you may not want the cache engine to return to a minimal state. For example, you may be running a batch file that uses the cache engine repeatedly. The cache engine reallocates resources when another client becomes active.
This setting is ignored if the value of Back to Minimal State if Inactive is set to Off (the default).
Cache Engine Debugging
These settings apply only when the cache engine is running. The Workgroup engine doubles as a cache engine. Note, however, that the cache engine is not used if a database engine is running.
The settings available under Cache Engine Debugging perform the same functions for the Client cache as similar settings under Server Debugging perform for the main database engine. For more information about each setting, see the related server setting:
Number of Bytes from Data Buffer
Number of Bytes from Key Buffer
Select Operations
Trace File Location
Trace Operation
Communication Protocols
Communication Protocols contains the following configuration settings:
Enable Auto Reconnect
Supported Protocols
Connection Timeout
Enable Auto Reconnect
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting specifies whether you want the client to attempt to automatically reconnect during a network outage. A setting of On means Auto Reconnect is enabled.
Auto Reconnect is not in effect unless this setting is also enabled in the server configuration.
Supported Protocols
Type
Range
Default
Units
Requires Engine Restart
Multiple select
One or more
TCP/IP
None
Yes
This setting specifies the protocols by which the database engine listens for client connections. If more than one protocol is selected, the engine begins the session by listening on all of them. The first protocol that succeeds is used for the remainder of the session. You must have at least one protocol enabled on both the client and the server or they cannot communicate.
Note The default is TCP/IP, which is the only option currently supported.
Linux, macOS, and Raspbian
TCP/IP is the only supported protocol for Zen on Linux, macOS, and Raspbian. Therefore, the Supported Protocols setting is not available for those environments.
Connection Timeout
Type
Range
Default
Units
Requires Engine Restart
Numeric
1 to 2147483647
15
seconds
Not applicable
The value of this setting specifies how long the client waits while searching for or connecting to a remote database engine. If this value is set too low, the client may return spurious “server not found” errors, because it is timing out before it has a chance to complete the connection. If the value is set too high, when the client attempts to connect to a server that is not reachable, you may encounter lengthy delays before receiving an error. Generally speaking, a value between 15 and 30 seconds is adequate for most networks. If you receive many errors of server not found, try a higher setting.
This setting was previously named: TCP/IP Timeout for Communication Requester.
Performance Tuning
Performance Tuning contains the following configuration property:
Use Cache Engine
Use Cache Engine
Type
Range
Default
Units
Requires Database Engine Restart
Boolean
On
Off
Off
None
Not applicable
This property sets whether to use the Client cache engine. This engine is a subset of the MicroKernel engine that caches data only for reading and runs as a separate process. The Client cache engine is also referred to as the Client cache or cache engine.
If Use Cache Engine is off, nothing is cached on the Client side. Read requests from an application retrieve data directly from the remote database engine.
If Use Cache Engine is on, the Client cache engine acts as an intermediary between the Client and the remote database Engine to cache data. The first time an application issues a read request, the Client cache engine caches the data. It then answers additional read requests for the same record using the cached data. The read operation does not have to access the remote database engine.
The Client cache is similar to the Workgroup Engine. By default, it automatically loads in memory when an application first accesses the database, and it unloads shortly after that application exits.
You may wish to keep the Client cache in memory to avoid the performance cost of repopulating it with each usage session. To keep the Client cache loaded, run the following from a command prompt: install_path\Zen\bin\zenengnapp
After the Client cache starts, an icon appears to the far right of the taskbar in the notification area. The icon allows you to control the Client cache engine. To stop the Client cache, right-click the icon and select Stop Engines and Exit.
If the Client is installed as a service, the Client cache engine is set by default to start automatically. However, even though the Client cache service is running, an application does not use the Client cache unless Use Cache Engine is turned on.
Note Zen synchronizes the Client cache with the database engine cache and other Client cache locations. This behavior is fully automatic and entirely transparent. However, there is a maximum delay of 5 seconds between any database change happening in the database engine cache and it being reflected in all Client cache locations. If the possibility of such stale pages existing in the cache for a maximum of 5 seconds is unacceptable in your system, do not use the Client cache.
The following operations are not stored in the Client cache:
Everything inside a transaction
Operations with a lock bias
Write operations such as INSERT, UPDATE, and DELETE
Open and close operations
See also the discussion of Client cache for the Cache Allocation Size property.
Security
Security contains the following configuration setting:
Runtime Server Support
Runtime Server Support
Type
Range
Default
Units
Requires Engine Restart
String
Yes
No
user_name,password
Yes
None
Not applicable
This setting controls runtime server support. If enabled with the value Yes, the current user name and password for the drive on which you are presently running are used. To enable RTSS with a different user name, enter user_name,password.
SUPERVISOR and ADMIN are not valid user names, even if supplied with the correct password. If the requester cannot find a user name other than SUPERVISOR or ADMIN, it does not attempt to log in.
Linux, macOS, and Raspbian Client Configuration Properties
You can configure Zen clients using Zen Control Center or the command line tool bcfg. For ZenCC, open the properties window by right-clicking a MicroKernel Router node in Zen Control Center. For bcfg, see Configuration Using Bcfg.
Note For Raspbian, where the ZenCC GUI is not supported, you can open ZenCC in another Zen installation and add the client remotely, then access its configuration properties. You can also use bcfg in a remote session, such as PowerShell.
Case of Configuration Values
When checking or editing the values of settings, the Linux, macOS, and Raspbian clients perform a case-insensitive comparison. For example, entering Yes or yes for a setting value is interpreted identically by the client.
Client Performance Affected by Local Setting
When the Linux, macOS, and Raspbian client interface is first invoked, it populates its default settings in the Zen registry. The Zen Client does not have knowledge on whether its installation includes a server engine or not. Therefore, it sets the Local setting to yes. This can have an impact on the performance of your client.
If the machine on which you are using the client does not have a server engine, you should set the local setting to no. See Use Local MicroKernel Engine.
File Names with Embedded Spaces
By default, the Linux, macOS, and Raspbian client interface supports file names that contain embedded spaces.
For example:
/mymount/usr/gary/file with spaces.mkd
If you want to use file names without embedded spaces, you need to change the Embedded Spaces setting. See Embedded Spaces.
Configuration Reference
The following table lists the configuration options for Linux, macOS, and Raspbian clients in alphabetical order. The settings are linked to topics with more information.
Table 12 Client Configuration Settings
Configuration Option
Parameter Name
Access
Access contains the following configuration settings:
Use Local MicroKernel Engine
Use Remote MicroKernel Engine
Use IDS
Wire Encryption
Wire Encryption Level
Use Local MicroKernel Engine
See Use Local MicroKernel Engine.
Use Remote MicroKernel Engine
See Use Remote MicroKernel Engine.
Remote Engine and UNC Paths
For UNC paths to work properly from a client, the following steps must be performed:
You must be running an engine on the same computer as the file that you are trying to access
You must set Use Remote MicroKernel Engine to on.
Note You cannot use a UNC path that points to the local Linux, macOS, or Raspbian system. However, you can use a path that is in the UNC style, such as
//localhost/usr/local/actianzen/data/samples/sample.btr
If you do not want an engine on your file server (that is, you want to use the client's local engine), then you can mount the remote file system on the client and modify the path so that it is a "native format" path rather than UNC format. For example, the following path is a native format on Linux, macOS, and Raspbian:
/mnt/myremotedata/sample.btr
Use IDS
See Use IDS.
Wire Encryption
See Wire Encryption.
Note Client-side wire encryption settings are not used by the Zen JDBC and ADO.NET access methods. For them, encryption can be specified using the connection string. See Connection String Overview in JDBC Driver Guide and Defining Basic Connection Strings in Data Provider for .NET Guide.
Wire Encryption Level
See Wire Encryption Level.
Note Client-side wire encryption settings are not used by the Zen JDBC and ADO.NET access methods. For them, encryption can be specified using the connection string. See Connection String Overview in JDBC Driver Guide and Defining Basic Connection Strings in Data Provider for .NET Guide.
Communication Protocols
Communication protocols contains the following configuration setting:
Enable Auto Reconnect
Enable Auto Reconnect
Type
Range
Default
Units
Requires Engine Restart
Boolean
On
Off
Off
None
Not applicable
This setting specifies whether you want the client to attempt to automatically reconnect during a network outage. A setting of on means Auto Reconnect is enabled.
Auto Reconnect is not in effect unless this setting is also enabled in the server configuration.
Note The Zen Linux, macOS, and Raspbian client supports this feature, but currently the server on those operating systems does not. You can use Auto Reconnect only from those clients connecting to a Windows server.
Application Characteristics
Application characteristics include the following configuration settings:
Embedded Spaces
Verify Key Length
Embedded Spaces
See Embedded Spaces.
Verify Key Length
See Verify Key Length.
Reporting Engine Configuration Properties
You can configure a Client Reporting Engine using Zen Control Center or the command line tool bcfg.
For ZenCC, open the properties window by right-clicking the Client Reporting Engine node in Zen Explorer.
For bcfg, see Configuration Using Bcfg.