The following topics cover various ways to configure your database server engines and clients:

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:

The configuration settings themselves are discussed in Configuration Reference.

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:

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.

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.

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

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.

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.

You can configure settings one at a time from the command line or by providing one or more settings in an input file.

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.

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.

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:

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.

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.

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.

Right-click a server and select Properties > Access to see the following configuration settings:

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.

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.

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:

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.

The following options set which type of authentication to use for access to the server engine:

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.

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.

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.

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:

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.

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:

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

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.

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.

This setting specifies the strength of the encryption key that should be used for encrypted communications. The following table shows the levels available.

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 contains the following configuration settings:

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.

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.

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.

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.

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.

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.

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 contains the following configuration settings:

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.

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:

Even if a file has a unique key, you may want to include system data, because users can drop indexes.

Data Integrity contains the following configuration settings:

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.

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.

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

See more information on similar and related settings under Transaction Logging.

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.

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.

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 provides the following benefits if a lock conflict occurs:

Wait lock timeouts apply to only two kinds of applications:

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:

On receiving a page or lock conflict error, the application may determine how to handle the conflict by retrying, waiting, or other options.

The MicroKernel Engine API provides controls to handle record lock situations. In brief, here are the control mechanisms:

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 contains the following configuration settings:

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

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

The Selected list displays the available Btrieve API operation codes that are traced. Select from the list the desired operations to trace.

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.

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.

Directories contains the following configuration settings:

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.

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.

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.

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.

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.

If you do not want the configuration file in the default location, enter a valid path.

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 lists the following display-only items:

Memory Usage contains the following configuration settings:

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.

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.

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

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.

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 involves the following configuration settings:

This setting turns automatic defragmentation on or off. When it is on, the feature works as follows:

For more information about defragmenting data, see Monitoring Data File Fragmentation.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

For more information on tuning performance, see Tuning Performance.

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.

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.

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.

Access contains the following configuration settings:

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.

This setting specifies the number of times the MicroKernel Router attempts to connect to the target engine.

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.

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.

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.

See Wire Encryption.

See Wire Encryption Level.

Application Characteristics includes the following configuration settings:

This option instructs the MicroKernel Engine to allow embedded spaces in file names for MicroKernel Engine operations.

This setting controls whether or not the MicroKernel Engine splash screen displays. The splash screen displays the first time a client requester loads.

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.

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:

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.

This setting displays only if the Workgroup engine is running.

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.

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.

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.

This setting displays only if the Workgroup engine is running.

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

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:

Communication Protocols contains the following configuration settings:

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.

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.

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.

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 contains the following configuration property:

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.

The following operations are not stored in the Client cache:

See also the discussion of Client cache for the Cache Allocation Size property.

Security contains the following configuration setting:

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.

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.

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.

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.

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.

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.

Access contains the following configuration settings:

See Use Local MicroKernel Engine.

See Use Remote MicroKernel Engine.

For UNC paths to work properly from a client, the following steps must be performed:

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

See Use IDS.

See Wire Encryption.

See Wire Encryption Level.

Communication protocols contains the following configuration setting:

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.

Application characteristics include the following configuration settings:

See Embedded Spaces.

See Verify Key Length.

You can configure a Client Reporting Engine using Zen Control Center or the command line tool bcfg.