Pervasive logo

Prev Advanced Operations Guide Next

Server Configuration Parameters


Every Pervasive.SQL engine has server configuration options, including the Workgroup engines. This section describes the different configuration options available for Pervasive.SQL engines.

Access

Accept Remote Request (Windows/Linux engines only)
Name
Type
Range
Default
Units
Accept Remote Request
Boolean
On/Off
On
N/A

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.

Active Clients
Name
Type
Range
Default
Units
Active Clients
Numeric
1 - 65535
Dynamic
N/A

This setting is no longer used by the MicroKernel. The client list is allocated dynamically and is limited only by the memory in the computer. Each client requires 308 bytes. By default, this setting is dynamically managed by the database engine. Pervasive recommends that you use the default behavior.

Allow Cache Engine Connections
Name
Type
Range
Default
Units
Allow Cache Engine Connections
Boolean
On, Off
On
N/A

Specifies if the server will support clients that will attempt to connect to the server with the client cache engine. When set to Off, clients will still connect to the Server but will not use the client cache engine.

Allow Client-stored Credentials
Name
Type
Range
Default
Units
Allow Client-stored Credentials
Boolean
On, Off
On
N/A

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 (on Win32 clients only) 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 login 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 5-1 Summary of Login Configuration Behavior

Prompt for Credentials
Allow Client-Stored Credentials
Behavior
Off
Off
Pervasive.SQL 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 Win32 client displays a login dialog to the user, and the Linux 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 Win32 client displays a login dialog to the user, and the Linux client returns a status code for permissions error.

Authentication (Linux engines only)
Name
Type
Range
Default
Units
Authentication
SelectOne
Three options. See below
Emulate Workgroup Engine
N/A

This option specifies which type of authentication to use for access to the server engine. The available options are:

Configuration File (Linux engines only)
Name
Type
Range
Default
Units
Configuration File
String
N/A
/etc/smb.comf
N/A

This setting specifies the location of the smb.conf file used by Linux 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.

The default value is /etc/smb.conf. If you installed the Samba configuration file in a different location, enter the correct path and/or file name.

Load brouter (NetWare engines only)
Name
Type
Range
Default
Units
Load brouter
Boolean
On/Off
Off
N/A

This setting controls whether the Message router (BROUTER.NLM) is loaded during the execution of the BSTART command. The Message Router allows other applications running as NLMs on the server (such as the SQL Interface) to communicate with remote servers on which the MicroKernel is loaded. To access data on a remote server, set this option to On.

Number of Sessions
Name
Type
Range
Default
Units
Number of Sessions
Numeric
Dynamic
Dynamic
N/A

This option is no longer used by the database engine and is no longer displayed in the Configuration utility. The Communications Manager dynamically allocates resources for each connection. The number of sessions allowed is limited by the available user count for the database engine.

Prompt for Client Credentials
Name
Type
Range
Default
Units
Prompt for Client Credentials
Boolean
On, Off
Off
N/A

This setting determines whether the Win32 Pervasive.SQL 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 Win32 client to present a login dialog to the user. This setting only applies when Mixed or Database security is in effect, and does not apply to the Linux 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 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 login 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

Wire Encryption
Name
Type
Range
Default
Units
Wire Encryption
SelectOne
Never, If Needed, Always
If Needed
N/A

This parameter 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 chart summarizes the behavior given each possible combination of client and server values:

 
Table 5-2 Client/Server Results of Wire Encryption 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's 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
Name
Type
Range
Default
Units
Wire Encryption Level
SelectOne
Low, Medium, High
Medium
N/A

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

 
Table 5-3 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.

This setting is ignored if the setting is set to Never.

Communication Buffer Size

Brouter Communication Buffer Size (NetWare only)
Name
Type
Range
Default
Units
Brouter Communication Buffer Size
Numeric
1024 - 65153
16384
bytes

This setting specifies the maximum length of the user data that any local server MicroKernel application can access at a remote server via BROUTER. Specify the length of the user data in bytes. Specifying a value higher than you need does not improve performance and may waste memory.

The actual buffer size may be limited by the amount of memory in the individual machine, because the memory requirement for this option is equal to (buffersize + 355) * 4 bytes.

Communication Buffer Size
Name
Type
Range
Default
Units
Communication Buffer Size
Numeric
Linux: 1024 - 65149
NetWare: 1024 - 65116
Win32: 1024 - 65153
65149
65116
64512
bytes

This setting specifies the size of the buffer that the Btrieve communications layer allocates for database requests from remote clients. This value should be at least as large as your largest data record plus an allowance of 200 bytes for overhead. Unless you have very small fixed-length records in a highly memory-constrained environment, Pervasive recommends using the default value (the maximum value). Each Communications Thread uses one of these buffers. See Communications Threads for more information.

Any value entered is rounded up to the least multiple of 1024 bytes that is greater than or equal to the entered value. The rounded value is not displayed until the database engine is restarted.

MKDE Communication Buffer Size
Name
Type
Range
Default
Units
MKDE Communication Buffer Size
Numeric
Linux: 1024 - 65149
NetWare, Win32: 1024 - 65153
65149
64512
bytes

This setting specifies the length in bytes of the buffer that the MicroKernel uses to contain requests from both remote and local clients. Each worker thread allocates a memory buffer large enough to accommodate this maximum length of data. (A request is a unit of related data that the MicroKernel or the application passes over the network.) Unless you have very small fixed-length records in a highly memory-constrained environment, Pervasive recommends using the default value (the maximum value).

Any value entered is rounded up to the least multiple of 1024 bytes that is greater than or equal to the entered value. The rounded value is not displayed until the database engine is restarted.


Note
System Administrators: Refer to the documentation for your Pervasive.SQL application to get an appropriate value for this option. If you use multiple applications, use the largest value.

Read Buffer Size (Windows/Linux engines only)
Name
Type
Range
Default
Units
Read Buffer Size
Numeric
4096 - 65536
4096
bytes

This setting specifies the size of the buffer that the Btrieve communications layer uses to read data from the network. Any value you enter is rounded up to the nearest multiple of the system page size (4096 bytes on Intel platforms) at the time that the engine allocates the buffer. The rounded value is not displayed until the database engine is restarted.

For Workgroup engine on Windows 98/ME when NetBIOS is used as the protocol, this buffer is automatically set to 65535 bytes. Each client connection uses one of these buffers.

Receive Packet Size (NetWare engines only)
Name
Type
Range
Default
Units
Receive Packet Size
Numeric
523 - 4096
1500
bytes

This setting only applies to the SPX protocol and specifies the size of the individual network packets this component receives. For the approximate memory required, the number of receive packets can grow dynamically during execution, but starts with the number indicated.

To determine the proper value for your system, use the following formula:

Number of receive packets * Receive packet size
where Number of receive packets = (Communications Buffer Size / Receive packets) + 1, or 45, whichever is greater

The default Receive Packet Size varies depending on your network card and hardware capabilities. If you are using the Win32 client Requester on an Ethernet topology, use the default value for this option. If you are on a Token Ring topology, set this value to 4,096 bytes. Setting the value too low may result in workstation hangs or a Status Code 95, "The session is no longer valid."

Communication Protocols

Auto Reconnect Timeout
Name
Type
Range
Default
Units
Auto Reconnect Timeout
Numeric
45 - 65535
180
seconds

This setting specifies how long the client will attempt to connect to the server before giving up. When a AutoReconnect-enabled client first connects to a AutoReconnect-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/NetWare only)
Name
Type
Range
Default
Units
Enable Auto Reconnect
Boolean
On/Off
Off
N/A

This setting specifies whether you want the server to support clients attempting to auto-reconnect during a network outage. A setting of "On" means AutoReconnect 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
Name
Type
Range
Default
Units
Listen IP Address
String
Any valid IP address
0.0.0.0
N/A

This option specifies the IP address the database engine listens on when TCP/IP Multihomed is Off, and two or more Network Interface Cards (NICs) are installed. This option is ignored when TCP/IP Multihomed is On, or when only one NIC is installed.

NetBIOS Port (Workgroup engines only)
Name
Type
Range
Default
Units
NetBIOS Port
Numeric
33 - 254
66
N/A

This option specifies the NetBIOS port the MicroKernel listens on. The Server engine does not support NetBIOS.

On Windows, the database engine may use standard Named Pipes or NetBIOS communications over TCP/IP, depending on your type of engine and protocol selection. By default, Named Pipes and NetBIOS communications use port numbers 137, 138, and 139.

ODBC Connection Mgr Supported Protocol
(Server engines only)
Name
Type
Range
Default
Units
ODBC Connection Mgr Supported Protocol
SelectOne
TCP, SPX
TCP
N/A

This option is no longer used by the database engine and is no longer displayed in the Configuration utility. The SRDE uses the protocol(s) specified in the Supported Protocols setting.

Supported Protocols
Name
Type
Range
Default
Units
Supported Protocols
Multiselect
See below
Varies
N/A

This setting specifies the protocols on which the database engine listens for client connections. If more than one protocol is specified, the database engine listens on all specified protocols. The default value varies depending upon the platform; the available options are:

 
Table 5-4 Supported Protocols

  • Microsoft TCP/IP
  • Novell IPX
  • Microsoft SPXII
  • Novell SPXII
  • Microsoft NetBIOS


Note
You must have at least one specific protocol that is enabled at both the client and the server, or else they cannot communicate. NetBIOS is only valid for Workgroup engine, not Server engine.

TCP/IP Multihomed
Name
Type
Range
Default
Units
TCP/IP Multihomed
Boolean
On/Off
On
N/A

This option specifies whether the Communications Manager should listen for client connections on all Network Interface Cards (NICs). If it is set to On, the database engine listens on all NICs, and the IP address listed in the Listen IP Address option is ignored. If this option is set to Off, and more than one NIC is installed, then you must specify in Listen IP Address which NIC the server should use.

TCP/IP Port (Server engines only)
Name
Type
Range
Default
Units
TCP/IP Port
Numeric
256 - 65535
1583
N/A

This setting configures the port number that the SRDE listens on.

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 Client DSN Options .

The Btrieve interface port is 3351, and is not configurable within Configuration.

On Windows, the database engine may use standard Named Pipes or NetBIOS communications over TCP/IP, depending on your type of engine and protocol selection. Named Pipes and NetBIOS communications use port numbers 137, 138, and 139.

Use SAP (NetWare only)
Name
Type
Range
Default
Units
Use SAP
Boolean
On/Off
Off
N/A

This setting specifies whether the Btrieve Communications Manager should use the Service Advertising Protocol (SAP). This setting applies to SPX communications only.

Compatibility

Create File Version
Name
Type
Range
Default
Units
Create File Version
SelectOne
5.x - 8.x
8.x
N/A

This setting specifies the format in which all new files are created. The 8.x MicroKernel can read files created in 5.x, 6.x, and 7.x versions of the MicroKernel. In addition, the 8.x version can write to files using the existing file format. In other words, it writes to 5.x files using the 5.x file format, writes to 6.x files using the 6.x file format, and so forth.

Specify 5.x, 6.x, or 7.x only if you need backward compatibility with a previous version of the MicroKernel. Specifying a previous file version does not affect any existing 8.x files.


Note
Dictionary files (DDFs) must be created with a file format of 6.x or later. The PCC 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
Name
Type
Range
Default
Units
System Data
SelectOne
See below
If needed
N/A

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:


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 re-create the file after setting System Data to Yes or If needed.

The SRDE 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

Archival Logging Selected Files
Name
Type
Range
Default
Units
Archival Logging Selected Files
Boolean
On/Off
Off
N/A

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
Name
Type
Range
Default
Units
Initiation Time Limit
Numeric
1 - 1800000
10000
milliseconds

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
Name
Type
Range
Default
Units
Operation Bundle Limit
Numeric
1 - 65535
65535
N/A

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
Name
Type
Range
Default
Units
Transaction Durability
Boolean
On/Off
Off
N/A

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 Compatibility | 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, refer to Pervasive.SQL Programmer's Guide available with the SDK.

Because System Data does not affect existing files, you may need to re-create 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 re-creating 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 Re-directing Locator Files .

Related Settings

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

Transaction Logging
Name
Type
Range
Default
Units
Transaction Logging
Boolean
On/Off
On
N/A

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 Compatibility | 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, refer to Pervasive.SQL Programmer's Guide available with the SDK.

Because System Data does not affect existing files, you may need to re-create 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 re-creating these files.



Caution
Do not turn off Transaction Logging unless your database does not require transaction atomicity among data files. Database integrity for multi-file 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 Data Integrity | 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 Performance Tuning | Log Buffer Size and Performance tuning | 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
Name
Type
Range
Default
Units
Wait Lock Timeout
Numeric
0 - 4294697
15
seconds

This setting specifies the wait lock timeout for the MicroKernel. When you fetch records with a wait lock, the MicroKernel does not return control until it has obtained the lock on every record you requested. If another application has locked one of the records you requested, the MicroKernel waits until that application releases the record before proceeding with the lock request. If the wait lock timeout has been reached and the MicroKernel could not lock the record, the MicroKernel returns control to its caller with the appropriate status code.

The purpose of this option is to significantly reduce network traffic, therefore improving network performance in case of a conflict caused by locking. With one exception (as stated in the following note), this configuration option does not have any effect on your application if there is a requester (such as W3BIFxyy.DLL) between your application and the MicroKernel. In this case, even if the wait lock timeout is reached, the requester retries the operation (except for Win16 applications) without notifying your application. The control is returned to your code only if the lock has been granted or a deadlock has been detected.


Note
If you have Win16 applications working with Pervasive.SQL, you may want to set this option to a value lower than the default (such as 1 second). For more information on how the MicroKernel handles wait locks with Win16 applications running on Windows 3.x, Windows 95/98, or Windows NT, refer to the Pervasive.SQL Programmer's Guide.

Debugging

Number of Bytes from Data Buffer
Name
Type
Range
Default
Units
Number of Bytes from Data Buffer
Numeric
0 - 65535
128
bytes

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
Name
Type
Range
Default
Units
Number of Bytes from Key Buffer
Numeric
0 - 255
128
bytes

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
Name
Type
Range
Default
Units
Select Operations
Multiselect
See below
All
N/A

The Selected list displays the available Btrieve Interface operation codes that are traced.

Trace File Location
Name
Type
Range
Default
Units
Trace File Location
String
N/A
C:\pvsw\bin\mkde.tra
N/A

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 and/or file name.


Note
Do not use the same trace file name for ODBC tracing and MicroKernel tracing.

Trace Operation
Name
Type
Range
Default
Units
Trace Operation
Bool
On/Off
Off
N/A

This setting enables or disables the trace feature, which allows you to trace each Btrieve Interface 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

DBNames Configuration Location
Name
Type
Range
Default
Units
DBNames Configuration Location
String
N/A
Varies
N/A

This setting specifies the path to an alternate location for the DBName configuration file.

For Server engines, this is a local file path, not a directory path. For Workgroup engines this could be a remote path that is accessible to the Workgroup MicroKernel. The defaults vary depending upon your particular engine platform:

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

Transaction Log Directory
Name
Type
Range
Default
Units
Transaction Log Directory
String
N/A
Varies
N/A

This setting specifies the location the MicroKernel uses to store the transaction log. The path must be a valid path and include a drive or volume specification or UNC path. The defaults vary depending upon your 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, specifying a remote server directory as the Transaction Log Directory for more than one Workgroup engine). Under these circumstances, the engines cannot determine which transaction log segments are used by each engine in the event a log roll forward is necessary.


Tip   If your database engine is highly utilized, 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
Name
Type
Range
Default
Units
Working Directory
String
N/A
Same directory as data file
N/A

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; however, if you do not specify a working directory, the default will be 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.

Memory Usage

Allocate Resources at Startup (Windows/Linux engines only)
Name
Type
Range
Default
Units
Allocate Resources at Startup
Boolean
On/Off
Off
N/A

This setting instructs the MicroKernel to allocate resources, including threads and memory buffers, when the MicroKernel is started.

If you turn this option off, the MicroKernel does not allocate any resources until the first operation request. Pervasive.SQL components automatically allocate resources as needed. Therefore, in most cases you do not need to do so explicitly.

Back to Minimal State if Inactive (Windows/Linux engines only)
Name
Type
Range
Default
Units
Back to Minimal State if Inactive
Boolean
On/Off
Off (Server)
On (Workgroup and client cache)
N/A

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 (Windows/Linux engines only). The MicroKernel reallocates resources when another client becomes active.

Minimal State Delay (Windows/Linux engines only)
Name
Type
Range
Default
Units
Minimal State Delay
Numeric
0 - 4294967
300
seconds

This setting specifies how long the MicroKernel waits during a period of inactivity before returning to a minimal state. (This is the initial state in which the MicroKernel begins.) By returning to a minimal state, the MicroKernel frees considerable 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 (Windows/Linux engines only) is set to Off.

Sort Buffer Size
Name
Type
Range
Default
Units
Sort Buffer Size
Numeric
0 - limited by memory
0
bytes

This setting specifies the maximum amount of memory (in kilobytes) that the MicroKernel dynamically allocates and de-allocates 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 0 kilobytes, the MicroKernel allocates as much memory as needed, up to 60 percent of the available memory.

System Cache (Windows/Linux engines only)
Name
Type
Range
Default
Units
System Cache
Boolean
On/Off
Off (Server)
On (WG)
N/A

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.

In 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 NT/2000 Performance Monitor utility to determine whether the Windows system cache is being used effectively. For the NTDBSMGR 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

Cache Allocation Size
Name
Type
Range
Default
Units
Cache Allocation Size
Numeric
65536 - limited by memory
Initialized dynamically at first start-up
bytes

This setting specifies the size of the Level 1 cache (in bytes) that the MicroKernel allocates; the MicroKernel uses this cache when accessing any data files. The MicroKernel uses values that are multiples of 16 KB or 16,384 bytes. If you specify a number that is not a multiple of 16 KB, the MicroKernel rounds that number down to the nearest multiple of 16 KB and allocates the cache to exactly that size.

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

Server Engine

On Windows, this setting is initially set to 20% of physical memory by the database engine the very first time it starts up, and it writes that value to the Registry. After that, whenever the engine starts up, it reads the value from the Registry. 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 to take best advantage of the new amount of memory available.

On NetWare, Novell sets the value to 1,024 bytes which is far too small in most cases, so you must increase the setting as advised here.

To optimize your performance, allocate a cache size no larger than the sum of the sizes of the files you are using. However, be careful not to take all available memory, especially when the server is running other applications. You cannot improve performance-and may waste memory-by specifying a value higher than you need.

Workgroup Engine and Client Cache

The database engine initially sets this value the very first time it starts up, and it writes the value to the Registry. The value is set to 20% of physical memory, up to a maximum of 32 MB. 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.

This information also applies to the client software (client cache) if the Configuration setting Client | Performance Tuning | Use Cache Engine is turned on.

Communications Threads
Name
Type
Range
Default
Units
Communications Threads
Numeric
1 - 1024
1-200 (NetWare)
16
N/A

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. The difference is that communications threads are not spawned dynamically. They reside in a fixed pool in a sleep state until a request comes in.

On NetWare, each supported protocol spawns the specified number of communications threads. For example, if you set this to 3 threads, you will have 3 SPX and 3 TCP/IP threads, making a total of 6 threads. On this platform, the maximum value is 200.

This setting may need to be increased for large servers. Although it may be optimal to have one thread for each remote session, this is not feasible in most multi-user environments. Use Monitor to watch the peak communication thread usage and the peak number of sessions. Set the value of Communication Threads in between the two. It does not need to be larger than the peak number of sessions because those sessions do not all issue a request at exactly the same time. A good rule of thumb is to set this to the number of remote clients, up to about 32, then use Monitor to determine whether you need to set this number any higher. If the peak number of communication threads is within two (2) of the maximum, you may want to raise the Communications Threads value higher.

File Growth Factor
Name
Type
Range
Default
Units
File Growth Factor
Numeric
0-100
15
Percent

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 performance of disk writes using the feature Turbo Write Accelerator can be expected to improve as the number of free pages within the file increases, due to the ability to write multiple contiguous file pages on disk. Thus, disk write performance is a trade-off against file size. However, maintaining too many free pages in a file can actually 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 specify a File Growth Factor value of 50%, the file will eventually double in size. If you specify a File Growth Factor value of 75%, the file will quadruple in size. A value of 90% will cause the file 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, as some pages may not be completely full.

This value is only a hint to the MicroKernel; depending on how heavily a given file is being updated, the actual percentage of empty space 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 and the percentage of empty pages varies with the activity on the file.

Index Balancing
Name
Type
Range
Default
Units
Index Balancing
Boolean
On/Off
Off
N/A

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, refer to Pervasive.SQL Programmer's Guide available with the SDK.

Largest Compressed Record Size
Name
Type
Range
Default
Units
Largest Compressed Record Size
Numeric
0 - 65536
Dynamic
bytes

This setting is no longer configurable.

Log Buffer Size
Name
Type
Range
Default
Units
Log Buffer Size
Numeric
262144 - limited by memory
262144
bytes

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
Name
Type
Range
Default
Units
Max MicroKernel Memory Usage
Numeric
0-100
Server: 90 (NetWare 60)
Workgroup and client cache: 60
Percent

This setting specifies the maximum proportion of total physical memory that the MicroKernel is allowed to consume. L1, L2, and all miscellaneous memory usage by the MicroKernel are included (SRDE is not 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. 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 between 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.

On the Workgroup engine, setting this value to zero causes the System Cache (Windows/Linux engines only) setting to be enabled. This is to protect against performance degradation.

For more information on tuning performance, please see Tuning Performance .

Number of Input/Output Threads
Name
Type
Range
Default
Units
Number of Input/Output Threads
Numeric
1 - 1024
4
N/A

This setting specifies how many background I/O threads the MicroKernel spawns. These threads are responsible for writing all pages from the MicroKernel's 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 100 files open, then the default of 4 I/O threads makes each thread responsible for 25 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 100, you should use about 12 I/O threads. Specifying a value higher than 64 may degrade performance, but that depends on the capabilities of the system.


Note
Application Developers: There is no accurate way to calculate the appropriate number of I/O threads because this setting depends on the machine's characteristics, OS configuration, and the MicroKernel Database Engine's planned work load.

Transaction Log Size
Name
Type
Range
Default
Units
Transaction Log Size
Numeric
65536 - limited by disk space
524288
bytes

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.

NetWare RTSS (NetWare only)

Runtime Server Support
Name
Type
Range
Default
Units
Runtime Server Support
SelectOne
See below
Complete
N/A

This setting specifies the level of Runtime Server Support provided by the MicroKernel. The available options are Complete, Disabled, or Pre-Authorized.

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, there is no valid name to pass. For more information about Runtime Server Support, see your Novell documentation.

Configuration Mapping

The following table is a mapping of all the available Server configuration options and their settings.

 
Table 5-5 Server Configuration Mapping

Configuration Option
Setting Name
Access
Accept Remote Request1
Authentication2
Configuration File2
Load brouter3
Number of Sessions
Communication Buffer Size
Brouter Communication Buffer Size3
Communication Buffer Size
MKDE Communication Buffer Size
Read Buffer Size2
Receive Packet Size3
Communication Protocol
Listen IP Address
NetBIOS Port4
ODBC Connection Mgr Supported Protocol4
Supported Protocols
TCP/IP Multihomed
TCP/IP Port5
Use SAP3
Compatibility
Create File Version
System Data
Data Integrity
Archival Logging Selected Files
Initiation Time Limit
Operation Bundle Limit
Transaction Durability
Transaction Logging
Wait Lock Timeout
Debugging
Number of Bytes from Data Buffer
Number of Bytes from Key Buffer
Select Operations
Trace File Location
Trace Operation
Directories
DBNames Configuration Location
Transaction Log Directory
Working Directory
Memory Usage
Allocate Resource at Startup1
Back to Minimal State if Inactive1
Minimal State of Delay1
Sort Buffer Size
System Cache 1
Performance Tuning
Cache Allocation Size
Communications Threads
File Growth Factor
Index Balancing
Log Buffer Size
Max MicroKernel Memory Usage
Number of Input/Output Threads
Transaction Log Size
NetWare RTSS
Runtime Server Support3
1
Windows engines only.

2
Linux engines only.

3
NetWare engines only.

4
Server engines only.


Prev
Configuration Reference
Contents
Up
Check for Revisions
Next
Win32 Client Configuration Parameters