Windows Client Configuration Parameters

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 PSQL Programmer's Guide available in the Developer Reference.

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 set to 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 a Server or Workgroup 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 PSQL 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.

Application Characteristics

Application Characteristics contains the following configuration settings:

•

•

•


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 PSQL 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. PSQL 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 megabyte to the amount limited by memory (see Note below)	Initialized dynamically at first start-up	megabytes (see Note below)	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.

Speaking very generally, overall performance is usually best when the Cache Allocation Size is a value less than 40% of the physical memory on the system, and the Configuration setting Max cache engine Memory Usage is set to a value greater than 40%. Your exact optimal settings will depend on the size of your data files, the number of other applications running on the system, and the amount of memory installed in the computer.

The database engine initially sets this value the first time it starts and writes the value to the Registry. The initial value is set to 20% of physical memory. After the Registry setting is initialized, whenever the engine starts up, it reads the value from the Registry. The engine never re-calculates the setting. Changing the value using Configuration updates the value in the Registry. If you add or remove memory from the system, you must modify this setting manually to take best advantage of the new amount of memory available.

Note: If you use PSQL Clients prior to PSQL v10, the value for cache allocation size must be specified in bytes, with a minimum of 64 KB (65,536 bytes). The maximum is limited by the amount of memory.

Max MicroKernel Memory Usage


Type	Range	Default	Units	Requires Database Engine Restart
Numeric	0-100	60	Percent	Not applicable

This setting specifies the maximum proportion of total physical memory that the cache engine is allowed to consume. L1, L2, and all miscellaneous memory usage by the cache engine are included. The database engine uses less if the specified proportion is not needed or not available.

If the value zero (0) is specified, then dynamic caching is turned off. In this case, the only cache available is L1, the size of which is specified by Cache Allocation Size.

For more information on tuning performance, please 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 auto-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	See below	All 3 options below	None	Not applicable

This setting specifies the protocols that are used by the client. If more than one protocol is specified, the client attempts to connect using all available protocols. When the first protocol succeeds, that protocol is used for the remainder of the session. The available options are:

•

TCP/IP

•

SPXII

•

NetBIOS

Note: You must have at least one protocol enabled at both the client and the server or they cannot communicate. NetBIOS is valid only for PSQL Workgroup, not PSQL Server. TCP/IP is the only supported protocol for PSQL running on Linux or OS X. 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 “server not found” errors, try a higher setting.

This setting was previously named: TCP/IP Timeout for Communication Requester.

Performance Tuning

Performance Tuning contains the following configuration setting:

•

Use Cache Engine


Type	Range	Default	Units	Requires Database Engine Restart
Boolean	On Off	Off	None	Not applicable

This setting specifies whether the Client Cache engine should be used. The Client Cache engine is a specialized version of the MicroKernel Engine that caches data for reading purposes and runs as a separate process. For simplicity, Client Cache engine is often referred to as the Client cache.

If Use Cache Engine is off, nothing is cached on the Client side. READ requests from an application retrieve data 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. If another READ is issued again for the same record, the request can be satisfied by the Client Cache Engine though the cached data. The READ does not have to access the remote database Engine.

The Client cache is similar in many ways to the Workgroup Engine. By default, it auto-loads into memory when an application first accesses the database, and it unloads a few minutes after that application is stopped.

You may wish to keep the Client cache in memory at all times to avoid the performance cost of re-populating the cache with each usage session. If you want to keep the Client cache loaded, run the following command from a command prompt: file_path\PSQL\bin\w3dbsmgr -btrv.

A tray icon appears after the Client cache starts. The tray icon allows you to control the Client Cache Engine from the Windows task bar. To stop the Client cache, right-click the tray icon then click Stop Engines and Exit.

If the Client is installed as a service, the Client Cache Engine service is set by default to auto-start. However, even though the Client cache service is running, an application does not use the Client cache unless Use Cache Engine is set to on.

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

Security

Security contains the following configuration setting:

•

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.

Note that you may use a fully qualified NDS user name in the format CN=user_name.O=organization,password. The user name may also be a simple Bindery name. The first entry in the Bindery context list must contain the simple name or the NDS login fails. If the NDS login fails for a simple name, a Bindery login is attempted. The Bindery login may cause delays while the login attempt is processing.

SUPERVISOR and ADMIN are not valid user names, even if supplied with the correct password. If the requester cannot find a login user name other than SUPERVISOR or ADMIN, it does not attempt to log in.