 | Advanced Operations Guide (v10) |  |
|
Each Pervasive PSQL database engine has its own server configuration options. This section describes the different configuration options available for the engines.
You can configure Pervasive PSQL Servers on Windows and Linux platforms using the graphical utility Pervasive PSQL Control Center. On the Windows and Linux platforms, you can also use the command-line interface utility bcfg. For PCC, see Using Pervasive PSQL Control Center in Pervasive PSQL User's Guide. For bcfg, see Configuration Through CLI Utility .
The following table lists the Server configuration options and their settings.
Access contains 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:
pvnetpass command-line utility to manage stored credentials.pvnetpass utility.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 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 .
|
Name
|
Type
|
Range
|
Default
|
Units
|
|---|---|---|---|---|
|
Authentication
|
SelectOne
|
Three options. See below
|
Emulate Workgroup Engine
|
none
|
The following options specify which type of authentication to use for access to the server engine. The available options are:
If you are using BTPASSWD authentication on your Linux server, user names and passwords must be set from clients connecting to this server. Use Pervasive PSQL Control Center or the pvnetpass utility. See Groups, Users, and Security and pvnetpass , both topics in the Pervasive PSQL User's Guide.
Use Proprietary Authentication if stronger security is needed for the server and you want user names and passwords different from any user authentication scheme employed on the Linux server.
Standard Linux authentication is used with PAM. Use PAM if you want to use existing user names and passwords on the Linux server. You can specify user names and passwords from the client using the pvnetpass utility. PAM is also very flexible and offers many custom modules for Linux. Check the PAM home page http://www.us.kernel.org/pub/linux/libs/pam/ for more information.
For PAM authentication, you must create a link from the PAM library to the psql/lib folder. For example, on the RedHat Linux distribution, change directory to /usr/local/psql/lib, then issue the following command: ln -s /lib/libpam.so.0 libpam.so. This assumes that both Pervasive PSQL and PAM have been installed to their default locations. (You can view the PAM library in the psql/lib folder by issuing a ls /usr/local/psql/libpam* command.)
You may use Samba in addition to any of the three authentication methods described above. The server creates a well-known FIFO share via Samba. FIFO is created in $PVSW_ROOT/etc/pipe/mkde.pip. $PVSW_ROOT/etc/pipe should be shared by Samba as PVPIPE$.
Note
The trailing $ means this share will be hidden. The Pervasive PSQL client components automatically take care of accessing this pipe as \\<server>\PVPIPE$\mkde.pip (case-insensitive); you do not need to perform any explicit actions or modify your application to access this pipe. The only exception to this is if you are troubleshooting your Samba or Pervasive PSQL configurations (see section on Troubleshooting below).
When a client connects to the remote engine and discovers the engine returns UNIX in the version block, it will first look in the registry (RTSS) setting) for authentication information. If the user name and password are not found 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 utilize the Samba "valid users" setting in smb.conf (Samba configuration file). If the client is unable to get authentication, status 3106 (The Pervasive Network Services layer encountered a connection failure) will be returned.
The installation program sets up the Samba share (if Samba is installed on the server). For reference, here is an example of setting up the Pervasive pipe.
################################################### [PVPIPE$] comment = Pervasive pipes path = /usr/local/psql/etc/pipe force group = pvsw # force group pvsw when accessing pipe - will be # useful if primary group for this user is not pvsw valid users = @pvsw # only members of group pvsw will have access oplocks = False # Absolutely necessary - prevents caching on the client ###################################################
To configure access to files shared through Samba, read the Samba documentation.
By allowing a client read access to PVPIPE$, that client is authorized to access the engine remotely.
A simple way to ensure the client gets proper authentication is to enter \\<yourserver>\pvpipe$\mkde.pip at the 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 to be sure you have rights to read this pipe. If you do but still get error 94, validate your RTSS setting using the engine configuration properties in Pervasive PSQL Control Center or with pvnetpass.
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.
This setting determines whether the Windows Pervasive PSQL 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 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 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
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:
|
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
|
This setting specifies the strength of the encryption key that should be used for encrypted communications. The following levels are available:
|
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.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 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.
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.
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.
This option specifies the NetBIOS port the MicroKernel listens on. The Server engine does not support NetBIOS.
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 is TCP/IP. The available options are:
You must have at least one protocol enabled at both the client and the server or they cannot communicate.
NetBIOS is valid only for Pervasive PSQL Workgroup, not Pervasive PSQL Server.
TCP/IP is the only supported protocol for Pervasive PSQL running on a Linux platform. Therefore, the Supported Protocols setting is not available on Linux.
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.
This setting configures the port number used by the relational interface.
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 .
For additional information on ports, see Changing the Default Communication Ports in Getting Started With Pervasive PSQL.
Compatibility contains the following configuration settings:
This setting specifies the format in which all new files are created. The 10.x database engine can write to files using the existing file format. In other words, it writes to 7.x files using the 7.x file format, writes to 8.x files using the 8.x file format, and so forth. (The 10.x database engine can read files created with 5.x, 6.x, 7.x, 8.x, and 9.x versions of the database engine.)
Specify 6.x, 7.x, or 8.x only if you need backward compatibility with a previous version of the MicroKernel. Specifying a previous file version does not affect any existing 9.x files.
Dictionary files (DDFs) must be created with a file format of 6.x or later. The New Database wizard uses the setting for create file version. The data files can be in any of the previous file formats supported. Only the DDFs must use a file format of 6.x or later.
System data 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:
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 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 .
When you turn Transaction Durability on, some files may not be able to support the feature. A file must contain at least one unique key, or when it was created, the configuration setting System Data must have been set to "Yes" or "If Needed." Otherwise, any changes to the file are not written to the transaction log. For more information about transaction durability and system data, refer to Pervasive PSQL 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 .
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 .
When you turn Transaction Logging on, some files may not be able to support the feature. A file must contain at least one unique key, or when it was created, the configuration setting System Data must have been set to "Yes" or "If Needed." Otherwise, any changes to the file are not written to the transaction log. For more information about transaction durability and system data, refer to Pervasive PSQL 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.
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.
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 timeout applies only to the following situations:
Wait lock timeout does not apply to applications that use the transactional interface through a Pervasive client on Windows or Linux. Such applications either receive a lock conflict error immediately after a lock conflict is detected or the lock conflict waits indefinitely for the lock to be released. The application then determines how to handle the conflict (retry, wait, and so forth).
The transactional interface API provides controls to handle record lock situations. Refer to API Programmer's Reference in the Pervasive PSQL software development kit (SKD) documentation for a complete discussion. In brief, here are the control mechanisms:
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 Interface operation codes that are traced. Select from the list the desired operations to trace.
|
Name
|
Type
|
Range
|
Default
|
Units
|
|---|---|---|---|---|
|
Trace File Location
|
String
|
not applicable
|
file_path\PSQL\bin\mkde.tra
|
none
|
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.
For default locations of Pervasive PSQL files, see Where are the Pervasive PSQL v10 files installed? in Getting Started With Pervasive PSQL.
Do not use the same trace file name for ODBC tracing and MicroKernel tracing.
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.
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 contains the following configuration settings:
This setting specifies the path to an alternate location for the DBNames 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.
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.
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 .
|
Name
|
Type
|
Range
|
Default
|
Units
|
|---|---|---|---|---|
|
Working Directory
|
String
|
not applicable
|
Same directory as data file
|
none
|
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.
Information contains the following configuration setting:
Information also lists the following display-only items:
The Pervasive JDBC driver supports character encoding. Encoding allows you to interpret data through a specified code page so that it is formatted and sorted correctly. The code page interprets the string data stored in the database.
Note that PCC passes the encoding setting to the JDBC driver. The JDBC driver, in turn, uses the encoding setting to connect to the database. No conversion of the data already existing in the database takes place because of the encoding setting. The encoding setting in PCC has no effect on any other utilities or interfaces within Pervasive PSQL.
The encoding varies by operating system and language. By default, PCC sets the encoding to that used by the machine. For example, the encoding is 1252 for English on a Windows machine.
You can set encoding at the server level or at the database level. At the server level, the encoding applies to all new databases created on that server. See To register a remote server engine in Pervasive PSQL User's Guide.
At the database level, the encoding applies only to that specific database and overrides the encoding setting for the server. You can change the encoding for the current database (the database for which you are logged in). For the encoding change to take effect, however, you must log out from the database then log in again.
For additional information on encoding when using the Pervasive PSQL JDBC driver, see Using Character Encoding in JDBC Driver Guide, which is part of the Pervasive PSQL software developer kit (SDK).
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.
If you turn this option off, the MicroKernel does not allocate any resources until the first operation request. Pervasive PSQL components automatically allocate resources as needed. Therefore, in most cases you do not need to do so explicitly.
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 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 is set to Off (the default).
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.
|
Name
|
Type
|
Range
|
Default
|
Units
|
|---|---|---|---|---|
|
System Cache
|
Boolean
|
On, Off
|
Off (Server engine)
On (Workgroup engine) |
none
|
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 (page 4-48). 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 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 contains the following configuration settings:
|
Name
|
Type
|
Range
|
Default
|
Units
|
|---|---|---|---|---|
|
Cache Allocation Size
|
Numeric
|
65536 bytes to the amount limited by memory
|
Initialized dynamically at first start-up
|
bytes or megabytes
|
This setting specifies the size of the Level 1 cache 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.
The value required and returned for the cache allocation size varies depending on the combination of Pervasive PSQL server and clients, as show in the following table.