About This Manual

This manual describes advanced procedures and provides technical information of use to the advanced user.

Some of the information in this manual may not apply to you. For example, the chapter on Gateway engine configuration does not apply to Server engines. Such information is clearly marked throughout the manual.

Pervasive Software would appreciate your comments and suggestions about this manual. As a user of our documentation, you are in a unique position to provide ideas that can have a direct impact on future releases of this and other manuals. If you have comments or suggestions for the product documentation, post your request at http://www.pervasive.com/devtalk/ or send E-mail to docs@pervasive.com.

Prev
Check for Revisions 		Next
Who Should Read This Manual


Who Should Read This Manual

This manual is provided for advanced users. Advanced users are considered to have a strong understanding of the underlying operating systems on which you run your Pervasive.SQL-based applications. Advanced users should be comfortable configuring their operating system, and in many cases, must have administrative permissions to configure the database engine. Advanced users may include the following:

  • network administrators of networks where one or more Pervasive.SQL-based applications are installed
  • value-added resellers of Pervasive.SQL-based applications
  • developers of Pervasive.SQL-based applications
Prev
About This Manual 		Up
Check for Revisions 		Next
Manual Organization


Manual Organization

The following list briefly describes each chapter in the manual:

  • Chapter 2—Concepts of Database Maintenance

    This chapter provides a brief introduction to the basic concepts and procedures involved with the job of maintaining a database.

  • Chapter 3—Understanding the Pervasive Component Architecture

    This chapter explains in some detail the major components that make up Pervasive.SQL and some of their unique features.

  • Chapter 4—Changing Your Configuration

    This chapter explains how to use the graphical utility named Configuration and how to tune database engine performance.

  • Chapter 5—Configuration Reference

    This chapter provides detailed information about all of the available configuration options for engines, 32-bit clients, and 16-bit clients.

  • Chapter 1—Pervasive.SQL Databases

    This chapter explains internal database names, public Data Source Names, and the limits on identifiers, such as table names, within a database.

  • Chapter 6—Setting Up Referential Integrity

    This chapter explains how to setup referential integrity rules to enforce the internal consistency of related data.

  • Chapter 7—Pervasive.SQL Security

    This chapter explains Btrieve security and SQL security and how the two schemes interact.

  • Chapter 8—Logging, Backup, and Restore

    This chapter describes how to develop a regular backup procedure to ensure your data is protected, and how to restore from backup if necessary.

  • Chapter 9—Server High-Availability Support

    This chapter describes how Pervasive.SQL works with cluster services and SFT III for NetWare.

  • Chapter 10—Workgroup Engine in Depth

    This chapter provides technical details and advanced procedures regarding the Workgroup engine.

  • Chapter 11—Monitoring Database Resources

    This chapter explains how to use the graphical utility named Monitor to view users connected to a database, file usage information, and resource usage information.

  • Chapter 12—Testing Btrieve Operations

    This chapter explains how to use the utility named Function Executor to perform individual Btrieve operations.

  • Chapter 13—Adding Relational Access to Btrieve Files

    This chapter explains how to create DDFs for existing Btrieve files so that they can be accessed via ODBC.

  • Chapter 14—Manipulating Btrieve Data Files with Maintenance

    This chapter covers the graphical utility named Maintenance and the variety of functions it provides.

  • Chapter 15—Converting Data Files

    This chapter covers the graphical utility named Rebuild and its functions, such as upgrading the file format version of a Btrieve file.

  • Appendix A—Description Files

    This appendix covers how to use description files to archive information about Btrieve data files you have created.

This manual also includes an index.

Prev
Who Should Read This Manual 		Up
Check for Revisions 		Next
Conventions


Conventions

Unless otherwise noted, command syntax, code, and examples use the following conventions:
CASE | Commands and reserved words typically appear in uppercase letters. Unless the manual states otherwise, you can enter these items using uppercase, lowercase, or both. For example, you can type MYPROG, myprog, or MYprog.
Bold | Words appearing in bold include the following: menu names, dialog box names, commands, options, buttons, statements, etc.
Monospaced font | Monospaced font is reserved for words you enter, such as command syntax.
[ ] | Square brackets enclose optional information, as in [log_name]. If information is not enclosed in square brackets, it is required.
| | A vertical bar indicates a choice of information to enter, as in [file name | @file name].
< > | Angle brackets enclose multiple choices for a required item, as in /D=<5|6|7>.
variable | Words appearing in italics are variables that you must replace with appropriate values, as in file name.
. . . | An ellipsis following information indicates you can repeat the information more than one time, as in [parameter . . . ].
::= | The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b.

Prev
Manual Organization 		Up
Check for Revisions 		Next
Pervasive.SQL Databases


Pervasive.SQL Databases

An Exploration of Object Names, Named Databases, and DSNs

This chapter delves into Named Databases and DSNs. It is divided into the following sections:

  • Pervasive.SQL Database Concepts
  • Pervasive.SQL Database GUI Reference
  • Pervasive.SQL Database Tasks
Prev
Conventions
Check for Revisions 		Next
Pervasive.SQL Database Concepts


Pervasive.SQL Database Concepts

  • Named Database
  • Identifiers and Object Names
  • The Default Database and the Current Database
  • ODBC DSN Creation Options
  • ODBC Connection Strings

Named Database

A named database (also referred to as a DBname) is a database that has a logical name that allows users to identify it without knowing its actual location. Pervasive.SQL requires that all databases be named. When you name a database, you associate that name with a particular dictionary directory path and one or more data file paths. Database names are typically used internally by Pervasive.SQL, and most users refer to the database by ODBC Data Source Name (DSN) that points to it.

For ODBC access, you must set up a DSN to refer to the database name. Multiple DSNs may point to the same named database.

Note
To work with named databases, you must log into the computer where the database engine is located, using an operating system user name that has administrator-level privileges or is a member of the Pervasive_Admin security group.

.

Identifiers and Object Names

An identifier is the name of a column, table, procedure, cursor, or other named object within the database. A regular identifier is an identifier that is not surrounded by double quotes. A delimited identifier is an identifier surrounded by double quotes.

Regular and Delimited

A regular identifier must begin with a letter, either upper or lower case. The remainder of the identifier can consist of any combination of upper or lower case letters, digits, and the underscore character ("_"). You cannot use a reserved word as a regular identifier. Regular identifiers are case-insensitive, so that the identifiers Abc, ABC, and abc are identical and can be used interchangeably.

A delimited identifier can consist of any string enclosed in double quotes. While it is not recommended, reserved words can be used as delimited identifiers. For example, INSERT is not permitted as a regular identifier, but "INSERT" is permitted as a delimited identifier. If you need to represent a double-quote within a delimited identifier, use a pair of double quotes without a space between them.

Maximum Length

Almost all identifiers are limited in length. For delimited identifiers, the size limit includes the opening and closing quotations.
Table 1-1 Maximum Length of Identifiers
Type of Identifier | Maximum number of characters allowed
Table | 20
View | 20
Column | 20
Index | 20
Foreign key | 20
User/group name | 30
Password | 8
Database See the following topic in SQL Engine Reference for a list of valid characters: Database Names | 20
Stored procedure | 30
Trigger | 30
Variable | none
Data file path name | 64 (the maximum length of the data file path name is a combination of Xf$Loc path and the data file path)

Identifier Examples

The following identifiers are permitted:

"INSERT"
myInsert
"my Insert"
"3tableA"
Table56
"Table 56 & (*#)"
Long_table_name_1234 [20 characters]
"Long_table_name123" [20 characters including quotes]

The following identifiers are not permitted:

INSERT [reserved word requires quotes]
my Insert [spaces require quotes]
3tableA [regular identifier must start with a letter]
Table56(*#) [regular identifier contains only alpha-numeric characters]
Long_table_name_12345 [21 characters]
"Long_table_name1234" [21 characters including quotes]

Unique Scope

Identifiers generally must be unique within a certain scope. That is, instances of the same type of object using the same name cannot be used within the same arena. Table 1-2 shows the arena, or the scope, within which a given object name must be unique.
Table 1-2 Unique Scope for Common Identifiers
A name for this type of object ... | ... must be unique within this scope:
Database | All databases hosted by a given database engine
Table | Database
Trigger or stored procedure | Database
User or group | Database
Cursor | Stored Procedure
View | Database
Constraint | Database
Column | Table
Index | Table

The Default Database and the Current Database

In order to support existing applications that do not specify a database name when creating or opening Btrieve files, this release maintains the concept of a default database for each transactional database engine. The default database is a pre-defined database named "DefaultDB." To make use of the new security models without having to modify your application code, you can associate your Btrieve data directories with the default database, then set up users and privileges in the default database to control access to the data files in those directories.

This release also introduces the concept of a current database for each client connection. If no database name is specified in a Btrieve Login (78), Create (14), or Open (0) operation, the transactional engine assumes the operation is associated with the current database. For each client, the current database is the database to which the most recent Login (78) operation occurred (explicit login). If the client computer has requested no explicit login operations, the current database is the database to which the most recent Create (14) or Open (0) operation occurred (implicit login). If no explicit or implicit logins have occurred, then the current database is the default database, described in the preceding paragraph. Note that the current database may change at any time when the given client performs an implicit or explicit login, or closes the last file handle, making "DefaultDB" the current database. The current database for each client is independent of other clients' activities.

The simplest way to configure the new security model for existing applications is to associate all Btrieve data directories with the default database, and set up rights for the group PUBLIC within this database. The group PUBLIC is automatically created along with the Master user when you enable security for a database.

File Structure

All Pervasive.SQL databases use a common data format. This commonality allows different access methods, such as transactional and relational, to access the same data. The database management system through which all access methods operate is called the MicroKernel Database Engine (MKDE).

Each Pervasive.SQL database table is a separate file with a default file extension of MKD. Developers, however, can specify any file name extension desired. A MicroKernel file may contain both data and indexes, and is organized into various types of pages. A MicroKernel files contains data in the common data format.

Each Pervasive.SQL database also contains a set of data dictionary files, with a file extension of DDF. The DDF files contain the schema of the database. Each database has, at a minimum, three DDF files: FILE.DDF, FIELD.DDF, and INDEX.DDF.

(The MKDE is completely unconcerned with the schema of the data apart from the key fields. However, the provision for referential integrity or access via SQL requires knowledge of the schema.)

The names and locations of Pervasive.SQL databases are contained in a binary file named dbnames.cfg. On Windows-based systems, this file is located in the %WINSYSDIR% (Windows 98) or %WINDIR% (Windows NT/2000/XP) directory. The file is located at sys:system\ for Netware. On Linux systems, the file is located at
/usr/local/psql/etc/. These locations represent the installation defaults.

All of the files associated with a Pervasive.SQL database can be viewed from the operating system. Table 1-3 summarizes the associated files.
Table 1-3 Files Associated With a Pervasive.SQL Database
Type | Description
Database Names Configuration | The dbnames.cfg file. Contains the names and locations of the Pervasive.SQL databases.
Data (common data format) | Files named, by default, tablename.MKD for relational databases. Each database table has a corresponding MicroKernel file. For transactional data files, the name of each file is specified by the application.
Data Dictionary | Files with an extension of DDF. At a minimum, three always exist for each database: FILE.DDF, FIELD.DDF, and INDEX.DDF.

Access Methods

The two primary methods in which data is accessed from Pervasive.SQL databases are transactional and relational.

With transactional, an application program navigates up and down along either physical or logical pathways through data records. Using a transactional API, an application program provides direct control and allows a developer to optimize data access based on knowledge of the underlying structure of the data. Btrieve is an example of a transactional database engine.

Relational is an access method in which data is represented as collections of tables, rows, and columns. The relational model insulates the developer from the underlying data structure and presents the data in a simple table format. ODBC is an example of a relational access method.

A single application program may include both types of access. For example, an application may use transactional access for adding and changing data, and relational access for querying the data and report writing.

You need to know the access method(s) used by the application programs that rely on your installation of Pervasive.SQL. The access methods may have different configurations. You may need to customize the configuration to optimize a particular access method.

Also, troubleshooting is easier when you are aware of the access method(s) used by a given application program. For example, if an application program uses relational access through ODBC, you may need to troubleshoot a problem at the ODBC level rather than at the database management system.

See Chapters 4 and 5 for the tasks and references pertaining to customizing configurations.

Client/Server Communications

The MKDE supports two types of processing modes, stand-alone (also called Workgroup) and client/server. An application accessing the database in stand-alone mode accesses a local copy of the MKDE. The local MKDE calls upon the operating system of the workstation which performs the I/O on a local or networked hard disk.

Client/server mode uses a client/server MKDE executing on a shared file server. When an application program accesses the database engine in client/server mode, a communication program called a requester is called upon instead of the local MKDE. This requester passes transactional-level requests and data records between the application program and the client/server MKDE using the network protocol supported by the operating system. File I/O functions are completely bypassed in client/server mode and the workstation has no operating system handles allocated to shared data files. Database manipulation is performed by the server-based MKDE on behalf of each workstation.

Note that the processing mode is determined by the configuration of the workstation and not the application program itself. This means that an application is capable of accessing both Workgroup and client/server database engines. The application program does not have to be recompiled to switch the application to client/server mode from Workgroup mode.

Both Workgroup and Server engine can operate in either mode. When an application on the same computer as the database engine accesses the engine, it is operating in local mode. When an application on a different machine access the engine, it is operating in client/server mode.

The client/server configurations may be customized for the Workgroup and Server versions of Pervasive.SQL. A Configuration utility exists in the Pervasive Control Center (PCC) to facilitate the configuration of client/server configurations as well as stand-alone configurations.

See Chapters 4 and 5 for the tasks pertaining to configuring the client/server communications and database engine.

ODBC DSN Creation Options

This section explains in detail the driver options that can be configured for Pervasive.SQL DSNs.

Engine DSN Open Mode Options

The DSN Open Mode options available for Engine DSNs allow you to specify one of several characteristics that go into effect when tables are opened through the specified DSN. These options are mutually exclusive—you are not permitted to select more than one.

These options correspond directly to the Btrieve open modes allowed in the Open (0) operation. By setting an Open Mode for a DSN, you are setting the default behavior for tables (corresponding to Btrieve files) opened through that DSN.
Table 1-4 DSN Open Modes and ODBC Connection Options
This Open Mode ... | ... generates this ODBC connection string ... | ... and this SQLSetConnectOption call:
Normal | OPENMODE=0 | SQLSetConnectOption( pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_WRITE);
Accelerated | OPENMODE=-1 | SQLSetConnectOption is ignored
Read-only | OPENMODE=1 | SQLSetConnectOption( pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_ONLY);
Exclusive | OPENMODE=-4 | SQLSetConnectOption is ignored

Normal

Normal mode is the default. Opening a table in Normal mode allows read/write access according to the permissions defined in the database.

If this mode is selected, the ODBC connection string includes OPENMODE=0, and the following ODBC function call is executed when you connect to the database:

SQLSetConnectOption(pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_WRITE);
Accelerated

Opening a table in Accelerated mode provides increased insert/update performance by disabling database engine logging functions for the current user. Logging is not affected for other users accessing the same table, but please see the warning below.

Caution
The database engine cannot guarantee transaction atomicity, transaction durability, or archival log safety for any client during use of Accelerated mode by any client. The reason for this restriction is that in the event a restore from log is needed, the log may not contain adequate information to complete the restore, because it is only a partial record of operations on a data file.

For example, if a system failure occurs while the same file is being accessed by a client performing inserts using Accelerated mode and a client performing updates using Normal mode, it is possible for the transaction log to contain updates to records that do not yet exist in the data files, because the Accelerated insert operation in memory was never flushed to disk, while the transactional update operation was written to the transaction log.

An attempt to roll forward an archival log containing this combination of operations will fail.

When this mode is selected, the ODBC connection string includes OPENMODE=-1, and the SQLSetConnectOption call is ignored by the ODBC driver. You cannot use SQLSetConnectOption to specify this mode.

Read-only

When a table is opened in read-only mode, operations that modify the database structure or the data in the database are not permitted.

If this mode is selected, the ODBC connection string includes OPENMODE=1, and the following ODBC function call is executed when you connect to the database:

SQLSetConnectOption(pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_ONLY);
Exclusive

When a table is opened in exclusive mode, no other connections to the table are permitted. If other users are currently accessing the given table, it cannot be opened in Exclusive mode. You must try again later.

When this mode is selected, the ODBC connection string includes OPENMODE=-4, and the SQLSetConnectOption call is ignored by the ODBC driver. You cannot use SQLSetConnectOption to specify this mode.

Client DSN Options

In the Pervasive Client DSN Setup window, the following options can be modified if you click Options.

Enable Array Fetch

An array fetch is a memory cache on the client machine for result sets. When array fetch is enabled, data from the latest result set is cached to the client machine's local memory, thereby speeding performance on subsequent queries. We recommend you leave array fetch "On," if you will be doing multiple queries.

The default size of the buffer used to cache array fetches is 8KB. You can set it anywhere between 1 and 64KB.

TCP/IP Port Number

You can use this setting to change the network port number on which Pervasive.SQL transmits ODBC communications. The network layer on the server engine has a similar setting, described in TCP/IP Port (Server engines only) . You must change both settings at the same time, and you must change them both to the same port number, or else your client and server cannot communicate.

Caution
Do not change the client port number unless you also change the corresponding port number on the server. If the server and client are not using the same port number, they cannot communicate.

Generally, the only reason you would need to change this port number is if you have another network service that is already using this port, and it is easier to change the port number for your Pervasive.SQL applications than for the other application.

The Btrieve interface communicates over port 3351. This value is not configurable.

Use OEM/ANSI Conversion

This setting allows applications to store or retrieve character data in any OEM character set using Pervasive.SQL, while allowing the data to be manipulated and displayed using the ANSI Windows character set. The Pervasive ODBC driver translation DLL can perform all necessary translations between the two character sets. This feature can be turned on or off for each DSN.

The Pervasive Control Center (PCC) and the SQL Data Manager (SQLDM) are fully OEM-character aware if you use extended ASCII characters for column or table names. Any character data that is passed to and from the database is correctly translated between the OEM and ANSI character sets.

If your application connects to the data source using SQLDriverConnect, you can also specify the translation DLL using the connection string option TRANSLATIONDLL=path_and_DLL_name. The translation DLL name for Pervasive.SQL is W32BTXLT.DLL.

NOTE: The OEM to ANSI translation option is available only for client or local Engine DSNs. It is not available when setting up a remote Engine DSN.

ODBC Connection Strings

This section describes the ODBC connection strings supported by Pervasive.SQL. This information is provided for two audiences:

  • advanced users using a database access tool that allows connection strings to be specified (such as ODBC Test)
  • developers writing ODBC, ASP, or OLE DB applications to access Pervasive.SQL.

Users of Pervasive.SQL 7 should note that the connection string parameters have changed significantly between Pervasive.SQL 7 and newer versions.

Driver Name

If you wish to connect to a database engine that is running on the same computer as the program that is attempting to connect, use the following driver connection string:

Driver={Pervasive ODBC Engine Interface}

If you wish to connect to a remote database engine using the Pervasive.SQL client, use the following driver connection string:

Driver={Pervasive ODBC Client Interface}

Other Parameters

The tables below shows the other parameters that may be used. Engine connection strings may be used for both connections to a local database engine and to a remote engine. Client connection strings may only be used for connections to a remote Server engine.
Table 1-5 Engine Connection Strings
Connection String | Description
DBQ=[@]db_name | Specify the internal database name (not DSN) to which you wish to connect. Required. The @ character is optional. It has no particular effect and is supported only for backward compatibility.
UID=user_name | If security is enabled for the given database, specify the user name. Optional, depending on security.
PWD=password | If security is enabled for the given database, specify the password. Optional, depending on security.
OPENMODE=-4|-1|0|1 | Specify the default file open mode for files opened with the current connection. Default is 0, "Normal." Can be used only with local connections, not remote client connections. Optional. For more information on file open modes, see Engine DSN Open Mode Options .
TRANSLATIONDLL= path_and_DLL_name | Specify the full path name of the DLL to use for OEM/ANSI translation. For more information, see Use OEM/ANSI Conversion .
Table 1-6 Client Connection Strings
Connection String | Description
ServerName=server[.port] | Specify the machine name or IP address of the computer to which you wish to connect. If you are not using the default port, specify the port number to use. Required.
ServerDSN=dsn_name | Specify the Engine DSN to which you wish to connect. Required, unless DBQ is specified.
TransportHint= <TCP|SPX>[:SPX|TCP] | Specify the transport protocol to use, or which to try first. Default is TCP:SPX. Optional. For example, a value of "TCP" forces the client to try a TCP/IP connection only. A value of "SPX:TCP" forces the client to try an SPX connection first, and if that fails, to try a TCP/IP connection.
TCPPort=port | Specify the TCP/IP port on which to find the server. Default is 1583. Optional.
ArrayFetchOn=1|0 | Specify whether to cache result sets on the client. Default is 1, "On." Optional.
ArrayBufferSize=size | Specify the size of the client cache, in KB. Default is 8 KB. Optional.

Examples

Example A

This example shows how to connect to a database with the internal name "SOMEDATA" on a remote server named "ServerMain" using TCP/IP port 1590, trying TCP/IP first then SPX:

Driver={Pervasive ODBC Client Interface}; ServerName=ServerMain.1590;DBQ=SOMEDATA; TransportHint=TCP:SPX;

Example B

This example shows how to connect to an Engine DSN named "mydata" on a remote server named "MyServer" with database security turned on:

Driver={Pervasive ODBC Client Interface}; ServerName=MyServer;ServerDSN=mydata;UID=ajones;PWD=jones52;

Example C

This example shows how to connect to a local database with the internal name "DATA5":

Driver={Pervasive ODBC Engine Interface};DBQ=DATA5;

See Also

For further information on Engine DSN open modes, see Engine DSN Open Mode Options .

For further information on Client connection string options, see Client DSN Options .

Prev
Pervasive.SQL Databases 		Up
Check for Revisions 		Next
Pervasive.SQL Database GUI Reference


Pervasive.SQL Database GUI Reference

To learn about this dialog, click on an area of the image. To display this page from the Maintain Named Database dialog, press F1.

Table 1-7 Maintain Named Databases Dialog Box Elements
Element | Description | Related Material
Registered DB Names | Lists available named databases. | To create, modify or delete a Pervasive named database
Current database name | Displays currently selected database name. | To create, modify or delete a Pervasive named database
Dictionary Location | Displays the location of the Data Dictionary Files (DDF) for the selected database name. | To create, modify or delete a Pervasive named database
Data File Locations | Displays the locations of data files for the database. | To create, modify or delete a Pervasive named database
Bound | Indicates whether or not the database is bound. Binding a database prevents the DDFs or data files from being used in another database and prevents a data file from having two or more different table definitions within the same database. For more information about bound databases, refer to Bound Database versus Integrity Enforced . | To create a bound database
Integrity Enforced | Specifies whether integrity constraints (security, RI, and triggers) are enforced on the database. These constraints apply to Btrieve access to the data files as well as ODBC/SQL access. | Setting Up Referential Integrity
Btrieve Security Policy | Allows you to specify what the Btrieve security policy for this database should be. | Pervasive.SQL Security

Prev
Pervasive.SQL Database Concepts 		Up
Check for Revisions 		Next
Pervasive.SQL Database Tasks


Pervasive.SQL Database Tasks

The following are the tasks for the Maintain Named Databases dialog:

  • To create, modify or delete a Pervasive named database
  • To create a bound database
  • To modify a named database
  • To delete a named database

For conceptual information on named databases, see Pervasive.SQL Database Concepts

To create, modify or delete a Pervasive named database

  1. In Pervasive Control Center, right-click on Configuration for the database engine that you want to work with.
  2. Choose Maintain named database from the pop-up menu. The Maintain named database dialog box appears.

Figure 1-1 Maintain Named Database Wizard Dialog Box

Table 1-7 describes the elements in the Maintain named database dialog box.

Creating a New Bound Database

To create a bound database

  1. Right-click on the Configuration namespace node of the machine on which the named database is to be created.
  2. Choose Maintain named database from the pop-up menu. The Maintain named database dialog box appears.

Figure 1-2 Maintain Named Databases Dialog Box

  3. Click on the Add database icon in the upper left hand corner of the dialog box. A new named database appears in the Registered DB Names panel with its name highlighted. Type in a name for the new database, making sure not to use any spaces.
  4. Specify the location for the database in the Dictionary Location field. This location must be on the same server to which you are connected (and where the database engine is running). It must be formatted as though you are working directly at the server machine.
    • For NetWare, enter a path in the form vol:\path.
    • For Windows NT, enter a path in the form drive:\path, where drive is a drive letter on the server.
    • For Linux, enter the standard Linux path format from root.

      For example, if you are at a workstation connected to a Windows server where the database engine is running, and you want to create a new database on the C:\ drive of the server in the folder "mydata," you would enter the location as "c:\mydata." You would enter it this way even if you have a local network drive (for example, F:\) mapped to the server's C:\ drive.

  5. Specify the location of the data file(s) in the Data File Locations field. Click on the Add File Location icon just above the directory list or click on the next available blank line in the list.

    If you are specifying paths to data file(s) on this server, specify them in the same manner as in the Dictionary Location field (step 4). If you are entering paths to data files on another server, specify the full UNC path as shown below.

    • For NetWare, enter the path in the form \\server\vol:\path
    • For Windows NT, enter the path in the form \\server\sharename\path
    • For Linux, enter the path in one of two ways:
      \\server\share\path  or
\\server\$PVSW$\path

        You can select a data file path in the list and press the Delete file location icon if you decide not to include a specific data file location.
  6. Select Bound to bind this database, if desired. For more information on this setting, see Interactions Between Btrieve and Relational Constraints .
  7. Select Integrity enforced to enforce integrity constraints (security, referential integrity, and triggers) on this database, if desired. For more information on this setting, see Interactions Between Btrieve and Relational Constraints .
  8. Select Create DDF Files.

Note
The only situation in which you would choose not to create DDF files is when you have an unnamed legacy database for which DDFs already exist, and you are now creating a database name for that database. Under these circumstances, the database engine links the new database name with the pre-existing DDFs.

  9. Click Apply.

Figure 1-3 Create Named Database Dialog Box

Modifying Named Databases

To modify a named database

  1. Click on the database name in the Registered DB Names list.
  2. Add or modify the named database attributes.
  3. Click Apply.

Deleting Named Databases

To delete a named database

  1. Click on the database name in the Registered DB Names list.
  2. Click on the Delete database icon. You can also right-click on the database name and select Delete from the pop-up menu.

Note
Deleting a Named Database without deleting the corresponding DSN(s) results in "orphaned" DSNs. Because the underlying database has been removed, these DSNs do not work. You should always remove any DSNs created for a Named Database if you delete the Named Database.

Prev
Pervasive.SQL Database GUI Reference 		Up
Check for Revisions 		Next
Concepts of Database Maintenance


Concepts of Database Maintenance

An Introduction to Database Maintenance

Pervasive.SQL V8 is a comprehensive database management system built around Pervasive Software's MicroKernel Database Engine. Pervasive.SQL offers easy installation, uncomplicated maintenance, and high levels of performance and reliability. While Pervasive.SQL can run for months or years with practically no maintenance, you can get the most out of it by understanding some of its unique features and learning how to perform useful tasks. This manual describes how to tune, configure, and manage your Pervasive.SQL engine and associated databases.

  • Configurations
  • Database Security
  • Data Archival and Restoration
  • Troubleshooting
  • Summary of Pervasive.SQL Utilities
Prev
Pervasive.SQL Database Tasks
Check for Revisions 		Next
Configurations


Configurations

You can configure separate settings for the server and client aspects of the database engine. The settings allow you to optimize the performance of the engine based on your business requirements.

Figure illustrates the flow from an application program to the database files at the operating system. The database engine resides between the application program and the data files.

Figure 2-1 Conceptual View of Database Engine Configuration

The types of settings that you can configure for server include the following:

  • Access
  • Communications buffer size
  • Communication protocols
  • Compatibility (with previous versions of the MKDE)
  • Data integrity
  • Debugging
  • Directories
  • Memory usage
  • Performance
  • Security (Pervasive.SQL Server on NetWare only)

The types of settings that you can configure for client include the following:

  • Access
  • Communication protocols
  • Performance
  • Security
  • Application characteristics

You configure these settings within the PCC. See Chapters 4 and 5 for the tasks and references pertaining to configuration.

Prev
Concepts of Database Maintenance 		Up
Check for Revisions 		Next
Database Security


Database Security

The access to a Pervasive.SQL database can be protected in several ways. Administrative-level security is set through the operating system. You can control who can administer a Pervasive.SQL database with the security mechanisms native to the operating system.

For transactional-only applications, database security is limited to file passwords called Owner Names. In order to access a specific data file, a user must supply the Owner Name for that file.

Pervasive.SQL also provides relational security at the user and group levels. You can control who can access the data and at what capability. For example, for each table within a Pervasive.SQL database, you can specify whether a user or group can create, select, update, insert into, delete, or alter the table.

You establish security by setting a password for the entire database. At that point, the only user authorized to access the database is a default user named Master. You can then add additional users and groups.

Security can be set within the PCC. Also supported are two Structured Query Language (SQL) statements pertaining to security: GRANT and REVOKE. GRANT and REVOKE also allow you to set security at the column level if you choose.

The GRANT syntax integrates with transactional Owner Names, allowing owner names to be enforced when using relational access.

See Chapter 7 for information pertaining to security, Owner Names, users, and groups.

Prev
Configurations 		Up
Check for Revisions 		Next
Data Archival and Restoration


Data Archival and Restoration

Backing up data is a routine part of protecting your databases and ensuring disaster recovery. You have several ways in which you can back up and restore your Pervasive.SQL databases.

If your business allows you to stop all applications that access a Pervasive.SQL database, you may use any of the operating system utilities, or third-party software, to backup or restore the database files.

Archival logging is another backup method that you can use to supplement operating system utilities. Archival logging allows you to keep a log of all database operations since your last backup. In case of a system failure, you can restore the data files from backup then roll forward the changes from the log file to return the database to the state it was in prior to the system failure.

Continuous operations allows you to backup database files while the database engine is running and users are connected. After starting Continuous Operations, the database engine closes the active data files and stores all changes in temporary data files (called delta files). When the backup is complete, you turn off Continuous Operations. The database engine then reads the delta file and applies all the changes to the original data files.

See Chapters 8 for the tasks pertaining to backing up and restoring databases.

Prev
Database Security 		Up
Check for Revisions 		Next
Troubleshooting


Troubleshooting

The Pervasive.SQL User's Guide and both of the Getting Started With Pervasive.SQL guides (Server and Workgroup) contain troubleshooting information. A good place to start if you have troubleshooting questions is the troubleshooting chapter in those books.

The Getting Started books contain troubleshooting information pertaining to installing the Pervasive.SQL products. The User's Guide contains general troubleshooting information as well as an extensive list of frequently asked questions (FAQs).

The Pervasive System Analyzer is a utility that you may also use for troubleshooting. This utility lets you analyze system and archived components, test network communications, and test the database engines.

Other resources at your disposal for troubleshooting include the Pervasive knowledge base, http://support.pervasive.com/esupport, which contains information based on actual customer solutions and common problems, and Pervasive customer support at http://www.pervasive.com/support.

Note that your purchase of Pervasive products entitles you to 30 days of free technical support for installation and configuration problems.

Prev
Data Archival and Restoration 		Up
Check for Revisions 		Next
Summary of Pervasive.SQL Utilities


Summary of Pervasive.SQL Utilities

Pervasive.SQL comes with a variety of utilities designed to help you control and manage your databases. Most of the utilities run only on 32-bit Windows and allow access to NetWare or Linux database server engines.
Table 2-1 Summary of Pervasive.SQL Utilities
Utility name | Runs on these platforms | Description | Server or Workgroup
Pervasive Control Center | Win32 | Utilities warehouse for Pervasive.SQL V8. Shows list of engines and databases available. | All
Configuration - invoked within PCC | Win32 | Manipulates settings for Pervasive client and server components. | All
Monitor | Win32 | Monitors server engine activity, useful for database administration and programming diagnostics. | All
Function Executor | Win16, Win32 | Executes Btrieve operations, enabling you to learn how the Btrieve interface works or test and debug an application. | All
Pervasive.SQL Maintenance | DOS, Win32 and NetWare | Performs common Pervasive.SQL file and data manipulations, such as importing and exporting data. BUTIL - command line version. | Windows NT and NetWare servers All 32-bit Windows workstations and Linux for command-line version
SQL Data Manager - invoked automatically within PCC | Win32 | Allows you to execute SQL Statements interactively. Creates and maintains Data Dictionary Files (DDFs) and database files. | All
Rebuild | Win16, Win32, and NetWare | Converts previous versions of MicroKernel files into more recent versions. | Windows and NetWare servers Windows 32-bit workstations Command-line version on Linux
License Administrator Utility | Win32, NetWare, and Linux | Manages Pervasive.SQL license keys and user counts. | Windows, NetWare, and Linux servers remotely Workgroup local Command-line version on Windows, NetWare, and Linux
ODBC Administrator | Win32 | Sets up Data Source Names (DSNs) for client and engine interfaces | All Windows engines - local Server - remote
Gateway Locator | Win32 | Used to configure and maintain gateway configuration files for the workgroup engine. | Workgroup engine only
Pervasive System Analyzer | Win32 | Analyzes system components, runs communication tests, and archives or restores database engine files on your system. | All

Prev
Troubleshooting 		Up
Check for Revisions 		Next
Understanding the Pervasive Component Architecture


Understanding the Pervasive Component Architecture

A Detailed Discussion of Smart Components and Related Features

This chapter covers Smart Components and other features designed to offer a trouble-free environment for installing and running critical applications. This chapter is divided into the following sections:

  • Pervasive.SQL Database Engine
  • Relational Architectural Overview
  • Overview of Smart Components
  • Component Identification
  • Unique Component Naming
  • Dynamic Binding
  • Pervasive.SQL Event Logging
  • Error Code Clarification
  • Diagnosing Load Errors
  • Pervasive Auto-Reconnect
Prev
Summary of Pervasive.SQL Utilities
Check for Revisions 		Next
Pervasive.SQL Database Engine


Pervasive.SQL Database Engine

The Pervasive.SQL engine consists of two database sub-engines:

  • MicroKernel Database Engine (MKDE), which provides Btrieve/MicroKernel API support for Pervasive.SQL applications.
  • SQL Relational Database Engine (SRDE), which provides ODBC support for Pervasive.SQL V8 applications.

Common Address Space

Pervasive.SQL uses an optimized memory architecture that provides high performance for both transactional and relational data access methods. On Windows platforms, both the MKDE and the SRDE load and operate in the same process address space, minimizing the CPU time required to communicate between them.

Row Level Locking

Row level locking improves database engine performance in multi-user environments in which many updates and writes occur at the same time, or in which transactions remain open for an extended period of time.

In releases prior to Pervasive.SQL 2000i SP3, the database engine locked data pages containing more than one record in order to update any record on that page. Any other client attempting to update records on that page while the page was still locked had to wait until the first operation released the page lock. This behavior occurred even though the records needed by the second operation were not affected by the first operation.

With the current row level locking architecture, a transaction locks only the rows that it affects directly, not the entire page. One client can update records on a given page at the same time as another client updates different records on the same page. Waiting is necessary only when a second application attempts to modify the exact same records currently locked by the first application. Thus, row level locking decreases overall wait time and improves performance in a multi-user environment.

This feature is completely transparent within the MicroKernel Database Engine. There are no changes to the Btrieve API, data file format, configuration settings, or any external component. This feature is always on and is supported across Server and Workgroup products as well as all supported operating system platforms. This feature is supported for data file format v6.x and later. It is not supported for data file format v5.x or earlier.

In this release, row level locking is implemented for key pages and data pages only, not variable pages. Furthermore, a small percentage of key page changes may cause key entries to move from one page to another. An example is when a key page is split or combined. These changes retain a full page lock until the transaction is completed.

MicroKernel Database Engine

The MicroKernel Database Engine (MKDE) provides Btrieve/MicroKernel API support for Pervasive.SQL applications. Both versions of the engine—Server and Workgroup—support local applications running on the same computer as the engine. The server MKDE supports both local applications and remote (client/server) applications. The workgroup MKDE supports applications running on remote machines as well and can service requests made by another peer workgroup engine on a remote machine.

There are two versions of the MicroKernel engine in this release. The server engine runs on Linux, Windows servers, and NetWare. (The NetWare version runs as an NLM directly on a NetWare server.) The Workgroup engine runs on Windows only and is designed for single-user or small workgroup configurations.

For servers, Btrieve client platforms include DOS and Windows 98/NT/2000/XP. Win16 Btrieve applications running on a Win32 workstation that is executing a Pervasive.SQL engine locally are supported using the existing Btrieve thunk mechanism. Thunking is also the default configuration for remote Pervasive.SQL engine access from a Win16 Btrieve application running on a Win32 workstation. It is possible to build Btrieve applications as NLMs (NetWare Loadable Modules) that access a local MKDE on NetWare. DOS applications running on a Windows 98/ME machine use BTRBox95.

The Workgroup engine is by default configured to start up when you log into Windows. A Workgroup engine can service requests made by another peer engine if the files have already been opened by the engine. It can also serve in a gateway mode by configuring a particular machine and database engine to act as a gateway, thus preventing another Workgroup engine from opening the files.

A "tray icon" is displayed to provide a graphical indication when a Pervasive.SQL Workgroup MKDE is running. No tray icon is displayed when the Workgroup MKDE is not running. The tray icon does not display for the server engine.

The Btrieve and ODBC APIs in Pervasive.SQL support writing distributed database applications that hide the details of connecting to a local or remote database engine from an application. Using this architecture, an application can access data that is co-located with the application (that is, running on the same computer as the application) while also accessing data on a remote computer. Moreover, a SQL database can be distributed by having DDFs (data dictionary files) serviced by a local MicroKernel Database Engine and data files (tables) serviced by a remote MicroKernel Database Engine. Such a SQL database, which is not serviced exclusively by a local MicroKernel Database Engine, is referred to as a "mixed access database."

Mixed-access databases are subject to the following constraints:

  • The following features are not supported: referential integrity (RI), bound databases, triggers, distributed transaction atomicity (requires two-phase commit).
  • The SRDE and the MicroKernel Database Engine must be running on the same computer to access DDFs.
  • Data files for tables that are involved in an RI relationship, or those that have any triggers defined for them, or are in a bound named database, cannot be opened by a remote MicroKernel Database Engine.
  • When opening a file, the SRDE does not verify the version of the MicroKernel Database Engine servicing the request. If an operation that requires v6.30 or higher MicroKernel Database Engine API support (for example, shared locking) is issued to a MicroKernel Database Engine less than v6.30, then an error code is returned. When opening DDFs or when attempting to bind a DDF or data file, the SRDE verifies that the local MicroKernel Database Engine is servicing the request.

Asychronous I/O

The Server MicroKernel engine for Win32 uses asychronous I/O when writing pages to disk. This feature improves performance. The MicroKernel quickly writes pages to the Windows system cache or its own cache. In turn, Windows signals when the pages are on disk, helping the MicroKernel to perform write operations efficiently.

Read performance is also enhanced when there are many concurrent operations being done in the MicroKernel at the same time, especially if you access your data set on a striped set of disk drives. Each read causes a worker thread to wait until the page is available. With asynchronous I/O, the operating system can pool the work of multiple readers to make the read operations more efficient.

SQL Relational Database Engine

The Pervasive.SQL Relational Database Engine (SRDE) provides ODBC support for Pervasive.SQL applications. The SRDE runs as a service on Windows NT, as an NLM on NetWare, and as a daemon on Linux.

ODBC client platforms include Windows 98/NT/2000/XP. Remote ODBC application access to the SRDE requires installation of the ODBC Client, which is a specialized ODBC driver that routes client-side ODBC calls to the ODBC communications server over the network.

Win16 ODBC applications running on a Win32 workstation that is executing a Pervasive.SQL engine locally are supported using the ODBC thunk mechanism. Thunking with the Microsoft-provided ODBC thunk DLLs is required for remote Pervasive.SQL engine access from a Win16 ODBC application running on a Win32 workstation.

Features of the SRDE include:

  • Atomic statements
  • Bidirectional cursors (using the ODBC Cursor Library)
  • Outer join support
  • Updatable views
  • ODBC data type support
  • Multiple variable length columns in a table

The ODBC communications server performs the following functions:

  • supports network communication for ODBC Clients
  • routes ODBC calls to the server-side ODBC Driver Manager (which, in turn, routes ODBC calls to the SRDE)
Prev
Understanding the Pervasive Component Architecture 		Up
Check for Revisions 		Next
Relational Architectural Overview


Relational Architectural Overview

The following diagram illustrates the architectural components of Pervasive.SQL's relational ODBC interface for the server version. The SQL Connection Manager starts and runs as a service on Windows NT (W3SQLMGR.EXE), as an NLM on NetWare, and as a daemon on Unix.

Pervasive.SQL Relational Architecture: Server

On Windows, the SQL Connection Manager consists of one executable and three DLL files:

  • W3SQLMGR.EXE - SQL Connection Manager
  • W3MGRMSG.DLL - Message File
  • W3MGRRES.DLL - Resource DLL
  • W3MGRRSX.DLL

The SQL Connection Manager supports up to 2000 simultaneous connections and uses the ODBC Driver Manager to make calls to the SQL Relational Database Engine (SRDE), which in turn rests on top of the MicroKernel.

Figure 3-1 illustrates the client/server relational architecture of Pervasive.SQL. The client talks to the SQL Connection Manager on the server through TCP/IP or SPX. This architecture applies to the server engine and to the Workgroup engine (in the case where a client DSN is used to connect from the local Workgroup engine to the remote Workgroup engine).

Figure 3-2 illustrates the Workgroup relational architecture when an Engine DSN is used to connect from the local Workgroup engine to the remote database, assuming that a remote Workgroup engine is acting as a Gateway to the remote data.

Figure 3-1 Client/Server Relational Architecture

Figure 3-2 Workgroup Relational Architecture

Prev
Pervasive.SQL Database Engine 		Up
Check for Revisions 		Next
Overview of Smart Components


Overview of Smart Components

Since version 7.0, Pervasive.SQL has offered a component architecture called Smart Components, which improves installation and run-time reliability and makes application troubleshooting easier.

In earlier Pervasive Software releases, some developers experienced one or more of the following problems:

  • Installation of a new application (with old client Requester components) overwrote new Requester components in shared locations, causing old applications to fail the next time they ran.
  • Installation of a new Workgroup engine was incompatible with existing client Requesters. Existing client Requesters loaded the old engine, failing to provide features required by the new application.
  • Difficulty identifying the function, version, and patch level of installed components.
  • Difficulty determining the root cause of run-time operational failures, especially in client/server operation.

The Smart Components architecture is designed to reduce or eliminate these problems by providing the following features and benefits:

  • Component Identification: Component function, major, and minor functional level are easily identified to aid in problem resolution.
  • Unique Component Naming: Each release of a given component has a unique file name, so that updated versions of a component never overwrite previous versions. A Pervasive upgrade will not damage existing Pervasive-based applications.
  • Dynamic Binding: Pervasive.SQL no longer loads a fixed set of program files into memory. Dependent components are loaded only if another component specifically requires its functionality, major, and minor functional level. Incompatible components are never accidentally loaded, reducing or eliminating version-related failures.
  • Pervasive.SQL Event Logging: All components report errors and messages to a central log, easing the burden of troubleshooting.
  • Error Code Clarification: Error conditions from underlying layers are logged through to the Pervasive.SQL Event Log, rather than hidden within an umbrella status code. Because the root causes of certain errors can now be more quickly determined, troubleshooting is much easier.
Prev
Relational Architectural Overview 		Up
Check for Revisions 		Next
Component Identification


Component Identification

Each component contains a unique embedded Component ID. The Component ID is a string containing information such as:

  • Designated operating system
  • Functionality
  • Major functional level
  • Minor functional level
  • Build site
  • Build number
  • Timestamp
  • Checksum

Pervasive Software Customer Support representatives can browse the file image of a component to locate the Component ID and verify that it is the correct component.

Prev
Overview of Smart Components 		Up
Check for Revisions 		Next
Unique Component Naming


Unique Component Naming

Pervasive.SQL components have unique names that reflect the platform, type, and functional level of the component. Each subsequent release of a component (even patches) will have a slightly different name, so that no two releases of the same functional component have the same file name.

This feature both identifies the exact functionality of a file and prevents different versions of a file from overwriting each other during installation of a new version or uninstall to a previous version.

Components are named using a well-defined scheme. All component names adhere to 8.3 notation for compatibility on systems that do not support long file names (such as Windows 3.1). The first two characters of the prefix identify the designated run-time platform. The next three characters identify the component functionality—its type. The sixth character identifies the major functional level (hexadecimal, range 1 to F), and the final two characters identify the minor functional level (hexadecimal, range 00 to FF).

The major functional level defines the version of the component, which began at one (1) with the first release of Pervasive.SQL. The minor functional level begins at zero (0) for each major functional level. Whenever the major functional level increments, the minor functional level is reset to zero. The minor functional level increases with each patch or public release of the component if it contains any changes whatsoever. The following tables show the Platform Codes and a sampling of Component Type Codes.

Table 3-1 Platform Codes
Platform | Code
Windows 3.1, Windows for Workgroups (Win16) | W1
Windows 98/NT/2000/XP (Win32) | W3
NetWare | NW

Table 3-2 Component Type Codes
Component | Type Code
Btrieve Interface DLL | BIF
Network Services Layer | NSL
MicroKernel Interface DLL | MIF

Prev
Component Identification 		Up
Check for Revisions 		Next
Dynamic Binding


Dynamic Binding

Rather than load a hard-coded file name, upstream components that require the functionality of a downstream component now can specify what functionality and what revision they require. An upstream component loads before a downstream component. For example, the application loads the Btrieve interface component, or BIF. The BIF then loads the MicroKernel interface module, or MIF. In this example, the BIF is an upstream component, and the MIF is a downstream component.

Upstream components load their downstream components with the help of a component called the Abstract OS Services DLL (Services DLL). The upstream component provides the Services DLL with a binding rule, specifying the type and minimum functional level of the required downstream component. Based on the binding rule, the Services DLL constructs a file name template and searches for a file that can deliver at least the required functionality. When it finds such a file, it returns the full path to the calling component, which then loads the specified downstream component.

When the engine is first started, the operating system searches the default path for W3BTRV7.DLL and W3SCMV7.DLL. On Windows 98, these DLLs are installed into the system directory.

Once these DLLs are loaded, when looking for additional downstream components, Smart Components first explore the directory specified in the engine's "InstallInfo\InstallDir" registry key. This registry key is written silently during product installation in the Pervasive Software registry pathway based on the target installation directory. If the requested component is not found in the directory specified in the registry, Smart Components then searches on the platform's default path.

The Services DLL employs a best first match search algorithm, meaning that it stops in the first directory where it finds an acceptable match and then returns the highest minor functional level of the specified component that exists in that directory.

For example, if a component requires W1MIF101.DLL or later, the Services DLL searches until it finds an instance of W1MIF1xx.DLL, where xx is 01 or greater. Then, the Services DLL searches that directory for the instance of W1MIF1xx.DLL with the greatest value of xx. This file name is then returned to the calling component. For example, if W1MIF101.DLL and W1MIF102.DLL are present in that directory, W1MIF102.DLL is returned. If there is an instance of W1MIF103.DLL in a different directory later on the search path, it is never reached.

Prev
Unique Component Naming 		Up
Check for Revisions 		Next
Pervasive.SQL Event Logging


Pervasive.SQL Event Logging

With the release of Pervasive.SQL 7 and greater, the MicroKernel message log has been replaced by a new centralized event log. All Pervasive.SQL 7 and later components write status and error messages to the same log file. In addition, if two or more Pervasive-based applications are running on the same machine, they share a single event log.

The event log, called PVSW.LOG (or event.log on Linux), is located in the Windows root directory of each machine that is running a Pervasive-based application (on Linux, it is located in the bin subdirectory of the psql installation directory). This location cannot be changed or customized. In the following table, C: represents the drive letter where your operating system is installed.
Table 3-3 Platform Event Log Locations
Platform | Event log location
Windows 98/ME | C:\WINDOWS
Windows NT/2000/XP | C:\WINNT
NetWare | SYS:SYSTEM
Unix | ~psql/bin

Syntax

The event log consists of ASCII text messages in a format similar to the following syntax description:
Table 3-4 Event Log Fields
Field | Length (in Bytes) | Contents
Date | 10 | Automatic date-stamp in mm/dd/yyyy format.
Time | 8 | Automatic time-stamp in hh:mm:ss format.
Component | 15 | File name of component returning the error (prefix only, no extension).
Process | 8 | Instance ID of the component, which is either the process ID of the component or the thread group ID in NetWare.
Process Name | Up to 15 | Path and name of the component, truncated to the last 15 characters.
Computer Name | Up to 15 | Name assigned to the machine hosting the process, truncated to the first 15 characters.
Type | 1 | A single character: I for Information, W for Warning, or E for Error.
Category | Up to 10 | A component-specific text field. Components are not required to provide a value in this field.
Msg ID | Up to 8 | A numeric message identifier that corresponds to a message string within a resource file associated with the calling component.
Message | Up to 1,024 | The message text which may be either a string retrieved from a resource associated with the calling component or a text string passed directly from the calling component.

An entry may be followed by binary data in standard ASCII hexadecimal format. There is no limit to the length of the binary data.

Sample Entry

The following shows an example of the type of data contained in the event log.
Date | Time | Component | Process | Process Name
11-04-1997 | 14:01:05 | NTMKDE | 000000DD | W3DBSMGR.EXE

Computer Name | Type Category | Msg ID | Message
LABSERVER | I |  | MicroKernel is using default settings.

Prev
Dynamic Binding 		Up
Check for Revisions 		Next
Error Code Clarification


Error Code Clarification

In earlier Btrieve and SQL Interface releases, top-level components occasionally subsumed error codes from underlying components into an umbrella error code returned by the top level component. In some cases, this situation could make troubleshooting difficult because a single error code could have a wide range of possible root causes.

Starting with Pervasive.SQL 7, most top level components were redesigned to pass through error codes from underlying components so that the actual source of the error is clearly identified to the calling application and/or in the log file.

In situations where an error code remains overloaded, specific information in the Pervasive.SQL event log should identify the root cause of the error.

Prev
Pervasive.SQL Event Logging 		Up
Check for Revisions 		Next
Diagnosing Load Errors


Diagnosing Load Errors

Pervasive.SQL provides the following types of information you can use in diagnosing module load errors:

  • Status codes. You can refer to the Status Codes and Messages manual for more information about the specific status code returned.
  • Event log. You can look for the following information in the Pervasive.SQL Event Log to get additional information about a specific module load error:
    Component Name
    The logical or physical name of the module that received the load failure. Logical names used are:
    ServicesIfc—Abstract OS Services
    BtrvIfc—Btrieve
    MKDEIfc—MicroKernel
    PSQLIfc—Pervasive.SQL

    The physical name is logged if the calling module attempted to load a component using a binding rule. For example, a physical name is W3BIF102.
    Type
    The type of load error, as follows:

    E (Error)—The module could not be found or an operating system-specific error occurred while loading the module.

    W (Warning)—A symbol could not be found or was not exported by the module.
    Message
    The message depends on the type of module load error. If the module could not be found, the event log contains the binding rule that specified the downstream component. If an operating system-specific error occurred, the event log contains that operating system error. If a symbol could not be found or was not exported, the event log contains that symbol.
  • On-screen errors. The event log is not functional until the Services DLL loads. Therefore, if a load error occurs while binding to the Services DLL, the event log does not log the error. Instead, Pervasive.SQL can display an on-screen error.

    You must enable the Services DLL to display on-screen module load errors by setting the PVSW_DISP_LOAD_ERRS environment variable. Its format is as follows:

    PVSW_DISP_LOAD_ERRS=AIF

    This environment variable should only be set to diagnose module load errors. In all other cases, it should not be set.

    To diagnose an error, set this variable as specified and perform the operation. The load error is displayed in a message box on your system.

Prev
Error Code Clarification 		Up
Check for Revisions 		Next
Pervasive Auto-Reconnect


Pervasive Auto-Reconnect

Pervasive Auto-Reconnect (PARC) allows client-server or workgroup applications to endure temporary network interruptions without canceling the current database operation. When Pervasive.SQL detects a network interruption, it automatically attempts to reconnect at specific intervals for a configurable amount of time. This feature also preserves the client context so that when communications are re-established, database access continues exactly where it left off when the network interruption occurred.

This feature preserves the application context and attempts to reconnect regardless of whether the client or server was attempting to send data at the moment when the network communications were interrupted.

When a network interruption occurs, the reconnect attempts occur at specific intervals. For all connections, successive attempts are made at 0.5, 1, 2, 4, and 8 seconds, continuing every 8 seconds thereafter until the AutoReconnect Timeout value is reached. If no attempt is successful before the maximum wait time is reached, then the current operation fails and the client connection is reset. The maximum wait time is configurable between 45 seconds and 65,535 seconds.

This feature is disabled by default. For this feature to operate, you must select Enable Auto Reconnect (Windows/NetWare only) for both client and server configurations. You can specify the time-out value using the server setting Auto Reconnect Timeout .

Remarks

This feature is supported for Btrieve, ODBC, and DTI connections. All 16-bit (when thunking to Win32) and 32-bit Windows applications are supported, but not pure DOS applications. DOS using Btrieve DOS box support on 32-bit Windows platforms is supported. This feature is supported on Windows and NetWare.

The Btrieve communication servers may write out *.PAR or *.SAR files to the Transaction Log Directory. These are temporary files that contain the context for the last item that the server tried to send to the client. When a reconnection occurs, the client may ask for data to be re-sent. The server reads these files to obtain the appropriate data. These files are normally deleted by the server after the data is read or later when the connection is finally terminated.

Prev
Diagnosing Load Errors 		Up
Check for Revisions 		Next
Changing Your Configuration


Changing Your Configuration

How to Work with the Configuration Utility within PCC

This chapter covers operating system permissions, network topologies, engine configuration, and client configuration.

  • Configuration Utility Overview
  • Special Notes on the Configuration Utility
  • Configuration Utility Tips
  • Tuning Performance
Prev
Pervasive Auto-Reconnect
Check for Revisions 		Next
Configuration Utility Overview


Configuration Utility Overview

The Pervasive.SQL Configuration utility uses a tree control/results pane GUI design. It supports configuration of any client and engine components, including remote engines, as well as Win16 client components on Win32 operating systems. All client components must be configured at each individual client workstation.

Configuring any components is optional. If you do not configure them, each component loads with default configuration settings. For best results, you should use only the version of Configuration that is the same version as your client and engine components. For example, you should use the Version 8 Configuration utility with Version 8 clients and engines.

You can use the Configuration utility for the following reasons:

  • Your system or your Pervasive.SQL application requires you to adjust the settings. Refer to your application documentation for recommended values. If you are running multiple applications concurrently, add the recommended values together. If you are running multiple applications sequentially, use the highest recommended value.
  • You want to optimize the settings so that Pervasive.SQL provides the services you need without using more memory than necessary. (The stated memory requirements provide guidelines for optimizing your computer's resources.)

Note
For some of your changes to take effect, you must shut down and restart Pervasive.SQL.

The Configuration utility is tightly integrated with the Pervasive Control Center and appears as nodes in the Control Center tree. Figure 4-1 shows the Configuration utility within the PCC.

Figure 4-1 Pervasive.SQL Control Center Screen

Prev
Changing Your Configuration 		Up
Check for Revisions 		Next
Special Notes on the Configuration Utility


Special Notes on the Configuration Utility

This section contains information to help you understand the Configuration utility, which is described in the following sections:

  • Ensuring Configuration Changes Take Effect
  • Connecting to Different Machines
  • Interpreting Parameter Settings

When you start the Configuration utility, it is ready to configure client requesters and the engine on the local machine if one is present.

Ensuring Configuration Changes Take Effect

Most engine Configuration parameters require the database engine to be reloaded after they have been changed. You can re-load the engine in one of two ways:

  • reboot the server machine
  • stop and re-start the engine as described in Chapter 2 of Pervasive.SQL User's Guide.

In addition, changing client parameters often requires the client to be restarted. To re-load the client, simply exit all applications that depend on Pervasive.SQL and restart them.

Connecting to Different Machines

The Configuration utility can configure both local and remote engines as well as local client components; however, each engine must be configured separately. To configure a particular Pervasive.SQL engine:

  1. Open the Pervasive Control Center and double-click Pervasive.SQL Engines.

    If you wish to configure a machine that is not in your engines list, it must first added:

    1. Right click on Pervasive.SQL Engines and select Register New Engine from the pop-up menu.
    2. Type in the server name or use the browse button to search for the desired server. Click OK.
  2. Expand the desired engine and expand the Configuration section beneath that engine.

    If you are not logged into the server, you are prompted to enter your user name and password at this time. You must have full local administrator-level rights on the machine where the database engine is running, or be a member of the Pervasive_Admin group on the machine where the database engine is running, to view or change the engine configuration options.

  3. Expand all available options beneath Configuration. The options available will vary depending on the platform of the engine you are trying to configure.

When you are connected to a remote machine, you can view and change only engine components. Client components (such as on workgroup and workstation engines and client machines) can only be configured locally on each machine.

Note
If you have engines registered that are not running, you may encounter delays in PCC as it periodically attempts to contact these engines. To eliminate the delay, unregister the "dead" engines. You can minimize the delay by performing the following procedure:

In PCC, right-click Pervasive.SQL Engines and choose Properties. Set Poll interval (seconds) to 999. Click OK. You can also disable polling completely by clearing Enable service state polling on the same panel.

Interpreting Parameter Settings

Under each option, there are a number of parameters, which are displayed in the following table:

Table 4-1 Parameter Settings
Name
The name of the parameter.
Type
Defines the value type. The different types are:
  • Numeric
  • Bool(ean)
  • String
  • Multisel(ect) – choose several values from a given list
  • SelectOne – must choose one value from a given list
Value
Shows the current setting.
Units
If the value is numeric, this field explains any specific units of measure, such as KB or seconds, if required.

Note
If you cannot find information about a particular Configuration setting, click on the Find Setting icon on the tool bar. Enter the name of the desired setting and a list of case matches is displayed. You can display the setting information by clicking on the desired setting.

The following table outlines the functionality of the Configuration utility:
Table 4-2 Pervasive.SQL Win16, and Win32 Configuration Utilities
Configuration utility | Components that it configures | Transactional Access: Where Changed | Relational Access: Where Changed
Win32 Configuration utility (Runs on Windows 98/NT/2000/XP client or Workgroup platforms or Windows NT/2000 server platforms.) | Local Win32 components | Windows Registry on local machine | Windows Registry on local machine
 | Local Win16 components | BTI.INI on local machine | ODBC.INI on local machine
 | Windows NT/2000 Server components (local or remote machines) | Windows Registry on Windows server | Windows Registry on Windows server
 | NetWare Server components (remote machines only) | BTI.CFG on NetWare server | ODBC.INI on NetWare server
 | Linux Server components (remote machines only) | bti.ini on Linux server | odbc.ini on Linux server
Win16 Configuration utility (Runs on Windows 3.11, Windows 9x/NT/2000 (using Thunking) – Transactional access only) | Local Win16 components | BTI.INI on local machine | No 16-bit relational access
 | Windows NT/2000 Server components (remote machine only) | Windows Registry on Windows NT server | No 16-bit relational access
 | NetWare Server components (remote machines only) | BTI.CFG on NetWare server | No 16-bit relational access
 | Unix Server components (remote machines only) | bti.ini on the Unix server | No 16-bit relational access

For each parameter appearing in Configuration, you can double-click the parameter to see a window showing the minimum, maximum, default, and current value of the parameter.

Access to Client Configuration Settings

All operating system users have permissions to modify the client configuration parameters.

Prev
Configuration Utility Overview 		Up
Check for Revisions 		Next
Configuration Utility Tips


Configuration Utility Tips

The next chapter describes the configuration options available for Pervasive.SQL V8.

PCC also provides an optional helper pane that provides basic information about each setting. To view the helper pane:

  1. Click any configuration folder beneath the Configuration node of the desired engine or client, and click View on the toolbar.
  2. Make sure Show Helper Pane is checked.

Note
While working with the configuration settings, if you wish to find a particular setting, click on the Find Setting icon on the tool bar. Enter the name of the desired setting and a list of case matches will be displayed. You can display the setting information by clicking on the desired setting.

Prev
Special Notes on the Configuration Utility 		Up
Check for Revisions 		Next
Tuning Performance


Tuning Performance

This section provides some general tips on how to maximize performance on the initial database connection and on runtime operations. While we can offer some general guidelines, the performance of any specific application is dependent on a great number of factors, including but not limited to the following:

  • network bandwidth and utilization
  • coding techniques in the application
  • free disk space
  • available memory
  • processor speed
  • application(s) usage patterns (write-heavy, read-heavy, transactions used/not used, small record size, large record size, complex queries, simple queries, ODBC, Btrieve only, and so on)
  • unrelated applications competing for CPU cycles
  • database engine configuration parameters

As you can see, the engine configuration plays a relatively limited role in the overall performance of any given application. Further, the database engine dynamically manages a variety of resources based on usage patterns. It tunes itself to your environment as needed. The sections provided below are offered only as helpful guidelines and are not a guarantee of any specific level of performance.

SMP Support

Pervasive.SQL fully supports symmetric multi-processing (SMP) and multiple processors because it is fully multi-threaded and thread safe. However, Pervasive.SQL does not take direct advantage of any SMP-specific API calls.

In an SMP environment, the operating system schedules available threads, including Pervasive.SQL's threads, on the available processors. Since Pervasive.SQL is fully multi-threaded and thread safe, this behavior can yield a significant performance boost up to and including at least 4 CPUs. Internal tests, however, have not shown any significant advantage to bypassing the OS scheduling by utilizing SMP specific calls to become SMP aware. The reason is because Pervasive.SQL performance is usually not limited by CPU utilization, but rather by I/O on either the disk or network interfaces.

Novell NetWare poses an exception to the multi-CPU performance gain in some cases because, though it is multiprocessor, it is not true SMP.

Spotting Performance Bottlenecks

You can use Monitor to expose performance bottlenecks related to certain database engine configuration parameters. To start Monitor, choose Start 4 Programs 4 Pervasive.SQL V8 4 Other Utilities 4 Monitor.

Relating Monitor Displays to Configuration Parameters

Two different Monitor menu selections display performance readings related to configuration parameters:

  • MicroKernel 4 Resource Usage
  • MicroKernel 4 Communications

The table below shows which configuration parameters correspond to the readings displayed in the Resource Usage window:
Table 4-3 Monitor Resource Usage Corresponding Configuration Settings
This performance display ... | ... corresponds to this parameter in Configuration:
Files | None. Formerly "Maximum Open Files," now managed dynamically by the database engine.
Handles | None. Formerly "Logical File Handles," now managed dynamically by the database engine.
Clients | None. Formerly Active Clients, now managed dynamically by the database engine.
Worker Threads | None. Formerly "Worker Threads." The MicroKernel now spawns additional worker threads as necessary.

The table below shows which configuration parameters correspond to the readings displayed in the Communications window:
Table 4-4 Monitor Communications Corresponding Configuration Settings
This performance display ... | ... corresponds to this parameter in Configuration:
Communications Threads | Communications Threads .
Total Remote Sessions | None. Formerly Number of Sessions . Now managed dynamically by the database engine.

Interpreting the Displays and Taking Action

You can make use of the information displayed in Monitor. Monitor displays three pieces of information about each type of resource. For example, the Communications Threads display shows:

  • Current. The current number of actual communication threads operating.
  • Peak. The highest number of actual communication threads that have been used since the engine was started.
  • Maximum. The maximum number of communication threads allowed.

If the Peak value for a resource is the same as the Maximum value, then you may want to use Configuration to increase the Maximum value for the resource, thus allowing the database engine to allocate additional instances of that particular resource when it needs to.

Before You Modify Configuration Parameters

The sections below assume the following:

  1. Pervasive Control Center (PCC) is already open.

    If you need assistance with this task, see An Overview of Pervasive Control Center of Pervasive.SQL User's Guide.

  2. You have already registered (if applicable) the engine you wish to configure.

    If you need assistance with this task, see Registering or Removing a Server of Pervasive.SQL User's Guide.

  3. You have already double-clicked on the icon representing the given engine. For the Server configuration settings, you have double-clicked Server or for Client configuration settings, you have double-clicked Client.
  4. You have appropriate operating system privileges to configure the given engine.

    If you need assistance with this task, see Granting Administrative Rights for the Database Engine of Pervasive.SQL User's Guide.

  5. You must re-start the database engine after making Configuration changes to the engine parameters.

Minimizing Initial Connection Time

The theory underlying minimal connection time revolves around three requirements. These requirements are summarized below, and detailed procedures follow:

  • Known communications protocol. You do not want the client or server to spend additional time trying to connect via protocols that are not supported in your environment. By removing client/server support for unavailable protocols, you prevent the networking components from trying to use them.
  • Known location of database engine. You do not want the client to attempt to connect to an engine that does not exist. By specifying Workgroup-only or Server-only support, as appropriate, you prevent the client from timing out while attempting non-existent connections. In environments where you have both unshared and shared databases, you can use Gateway Durability to force the database engine to keep track of machines where no database engine is running, so that it never attempts to connect to an engine on these machines, but uses another method to access the data.
  • Database engine ready to execute. When a sleeping engine receives a new connection request, it takes time to re-allocate resources and return to a runtime state. If connection speed is more important than resource usage on the server, you can prevent the server engine from sleeping when it is not in use.

Client Parameters

You must be at the client machine to change the client parameters. You must change the parameters at each workstation whose settings you wish to change.

To minimize client-side connection delays

  1. In Configuration, click on Client 4 Communication Protocols. Double click Supported Protocols.
  2. In the protocol selection window that appears, select the protocols that you are not using in the box labeled "Selected." Click < to move the protocols into the box labeled "Available."
  3. Click OK. You have now prevented the client from attempting to communicate on protocols that are not supported.
  4. Click on Client 4 Access. If you are using only a remote Server or remote Workgroup engine, double-click Use Local MicroKernel Engine and set it to Off.

    If you are using only a local Workgroup engine, double-click Use Remote MicroKernel Engine and set it to Off.

    If you sometimes use a Workgroup engine and you sometimes connect to a Server engine or a remote Workgroup engine, you must leave both settings On.

    In such a mixed environment with shared and unshared data, you can set Access 4 Gateway Durability to On at each client. This setting forces the client software to keep a list of the names of any machines on which it is unable to connect to a database engine. In order for the client software to determine no engine exists on a given computer, it waits for all of its network protocol requests to time out. If your data is stored on a server that does not have a Pervasive database engine on it, and you have set Access 4 Use Remote MicroKernel Engine to Yes, the client must time out at least once to discover that there is no engine on that machine. Gateway Durability ensures that this time-out only happens the first time your application tries to access that data.

 Note
Using Gateway Durability fixes the network topology. If you later install a Server or Workgroup engine on the remote computer, you must turn off Gateway Durability on each client so that the list of computers without database engines is deleted (thus allowing you to connect to the new database engine). You may turn Gateway Durability back on immediately, but it starts with an empty list.

  5. Click OK. You have now prevented the client from attempting to connect to any database engine types that are not in use.

Server Parameters

To minimize server-side connection delays

  1. In Configuration, click on Server 4 Communication Protocols. Double-click Supported Protocols.
  2. In the protocol selection window that appears, select the protocols that you are not using in the box labeled "Selected." Click < to move the protocols into the box labeled "Available."

Note
Be sure that at least one protocol you have selected in the Server configuration is the same as selected in the Client configuration. Your client and server cannot communicate if they are not using the same protocol.

  3. Click OK. You have now prevented the server from attempting to communicate on protocols that are not supported.
  4. This step does not apply to database engines on NetWare. Click on Server 4 Memory Usage. Double-click Allocate Resources at Startup. Set the value to On.

    You have now specified that the database engine should allocate all necessary memory when it starts up, rather than when the first connection request comes in. Choosing this value requires more memory, but from the client perspective allows the engine to become operational faster.

  5. This step does not apply to database engines on NetWare. Double-click Back to Minimal State if Inactive. Set the value to Off.

    You have now specified that the database engine should not release resources back to the operating system if the engine is inactive. All resources remain allocated and ready for use at the next client connection.

  6. Click OK. You must re-start the Server engine for these changes to take effect.

Maximizing Runtime Throughput

The theory behind maximum throughput relies on too many variables to list here. Several of the most significant factors are:

  • Adequate physical memory. If your host system has too little RAM, the system spends most of its time and CPU cycles swapping memory to disk and back, as different users and processes compete for limited resources.
  • Adequate CPU capacity. If your CPU cannot keep up with the inflow of data processing requests, application performance suffers.
  • Adequate network bandwidth. If your network is slow or suffers from a high collision rate, the database engine may sit idle between data access requests, while each client seems to display poor performance.
  • Minimal disk I/O. Disk I/O is significantly slower than memory
    I/O. You want to avoid accessing the disk as much as possible, by having sufficient cache.
  • Adequate resource allocations. Even with massive physical memory available, database performance may suffer if database engine configuration parameters are set artificially low.

In the end, optimal performance is a balancing act among network bottlenecks, disk I/O bottlenecks, memory bottlenecks, and CPU bottlenecks. This section provides some guidelines on how to reduce memory and disk I/O bottlenecks.

Fast Disk versus Fast CPU

If you want to maximize the effect of your hardware investment for performance gains, you must understand the existing constraints on your performance. If you have a database that is so large that you cannot reasonably buy and install enough memory to cache a significant part of the database, then performance is likely to be constrained by the disk I/O. Under these conditions, you may be better off to invest in a fast RAID disk array to maximize performance of the disk I/O.

In addition, if your application uses the SRDE and forces temporary files to be created frequently, you may want to ensure that the directory where these files are created is located on a fast disk drive. For more information about the location of this directory and the types of queries that generate temporary files, see Temporary Files in SQL Engine Reference.

If your database is small enough to be fully or near-fully cached in memory, then adding a fast disk array is unlikely to provide a significant performance boost. Under these conditions, upgrading the CPU or adding an additional CPU may provide the best performance improvement value.

Ensuring Adequate Physical Memory and Database Cache

Starting with Pervasive.SQL V8, the database engine offers Level 2 dynamic cache in addition to the Level 1 cache specified by the configuration setting, Cache Allocation Size . Assuming you do not turn off the Level 2 dynamic cache by setting Max MicroKernel Memory Usage to zero, the need to manually adjust the Level 1 cache size is much less critical than in previous releases. With that in mind, this section explains how to ensure that you have enough memory available for optimal performance of the database engine.

Ideally, your database engine should be able to allocate enough memory to cache full copies of every database it hosts, thus avoiding as much disk I/O as possible. Obviously, caching one or more entire databases is not practical in some situations, particularly when database size is very large. In addition, such measures as adding RAM to the machine only improve performance if the existing system resources are heavily loaded under normal usage.

The database engine dynamically selects a Level 1 cache size value when it starts up the first time. However, this value is based on available memory and may not be the ideal amount of cache for your environment.

To calculate the ideal size of the database memory cache

  1. Start by adding up the file sizes of all the data files serviced by the database engine.

Note
If you have more than one database serviced by the engine, but they are never used at the same time, add up the file sizes of just the largest database.

For example, assume there are two databases on your server, with the following file sizes, and users access both databases at the same time:
Database A |  | Database B
file1.mkd | 223 MB | Afile.mkd | 675 MB
file2.mkd | 54 MB | Bfile.mkd | 54 MB
file3.mkd | 92 MB | Cfile.mkd | 318 MB
file4.mkd | 14 MB |  |

The sum of all these files is 1,430 MB or 1,499,463,680 bytes.

The number you have now is the maximum amount of memory that the database engine would use if it cached all its hosted data. This number can be referred to as MaxCache.

You would never want to specify a value greater than this for Cache Allocation Size, because you would be allocating memory to the database engine that it would likely never use. In practice, the Level 2 cache adjusts dynamically to store as much data as possible in memory, given the constraints on your system. A reasonable rule of thumb is to set Cache Allocation Size to about 20% to 70% of MaxCache. Lower values in this range are best for read-intensive applications, and higher values are best for write-intensive applications since all write/update operations take place in the Level 1 cache.

 Note File pages are only written to the database cache when they are accessed. Thus, for a database engine to use MaxCache amount of memory requires every page in the database to be accessed. This system of estimating assumes a long-term steady state for database usage. If you bring the database engine down nightly or weekly, it may be unlikely that the database engine would access every page in the database within the given period of uptime.

If this situation applies to you, you may wish to estimate the average number of distinct pages that your application accesses within the given uptime period, multiply that by the page size, and obtain a more realistic value of MaxCache for your particular uptime scenario.

Note
On Windows-based operating systems, all user processes are limited to 2 GB of memory. If you have calculated a value of MaxCache larger than 2 GB, and your database engine runs on Windows, then you should use the value 2 GB or 2,147,483,648 bytes for MaxCache.

To determine how much total physical memory you need

In addition to the data cache (MaxCache) determined above, the database engine also allocates a separate cache for miscellaneous database management objects. The size of this cache depends on the attributes of the pages in the data cache, and can range from 10% to 30% of the size of the data cache. To be fairly conservative, we will estimate the ManagementCache as 25% of the data cache, or 374,865,920 bytes in our example. Thus, the database engine could consume as much as 1,874,329,600 bytes of memory given our example data files. Let's call this value DBMem. Now you need to evaluate this number in light of the load that is running on the computer where the database engine is located.

  1. Determine portion of physical memory available to database engine.

    The portion of physical memory that you allow the database engine to allocate depends on the load on the machine. If other critical services (such as email server, web server, and so on) are running on the same machine, then you must allow for these other services to allocate the memory they require. If you have a dedicated database server machine, you might allow the database engine to consume 80-90% of physical memory. If you have many other services running on the same machine, you might not want the database engine to take up more than 20% of memory. Thus, the ideal amount of total physical memory for your particular machine is at least TotalMem = DBMem * (1/DbAllocation), where TotalMem is the total amount of physical memory on the machine, and DbAllocation is the portion of memory available to the database engine. You should specify the value of DbAllocation in the Configuration setting Server 4 Performance Tuning 4 Max MicroKernel Memory Usage.

    The Level 2 cache adjusts as needed, but never more than the specified proportion of physical memory. If the database engine encounters heavy contention for memory, then it will use less memory, even when it is below the specified maximum limit.

    The amount of memory actually used by the database engine at any given time always lies between the number of bytes specified in Cache Allocation Size and the portion of total physical memory specified in Max MicroKernel Memory Usage.

    Continuing the example above, assuming that we have other services on the machine and thus we choose to limit the database engine memory to 40% of physical memory, the calculation yields 1,874,329,600 * (1/0.4) = 4,685,824,000 bytes or about 4.37 GB total physical memory on the machine.

    This value is the total amount of memory that we need on the machine in order to be able to allocate enough memory to the database engine to fully cache our specified databases.

 Note
If your database engine runs on Windows and you reduced your calculated value of MaxCache to 2 GB due to the operating system limit, then the performance of your database may benefit from using the Windows system cache in addition to the MicroKernel cache. Unless your cache requirements exceed 2 GB, there is no performance benefit to using the system cache in addition to the MicroKernel cache. By default, Pervasive.SQL runs with the system cache turned off. You can use the Configuration setting Server 4 Performance Tuning 4 System Cache (Windows/Linux engines only) to turn the system cache on.

  2. If you have at least TotalMem memory installed on your server machine, then your memory configuration should now be satisfactory. If your application is highly write-intensive, then you may experience slightly better performance by setting Server 4 Performance Tuning 4 Cache Allocation Size to 50-70% of your calculated MaxCache value. If your application is highly read-intensive, then you may experience the best performance when Cache Allocation Size is set smaller, such as 20% of MaxCache.

Note
Never set Cache Allocation Size larger than the amount of physical memory installed in the computer. Doing so forces the MicroKernel to make use of Virtual Memory on disk, which significantly degrades performance.

  3. If you do not have TotalMem of memory installed, you should consider installing enough memory to reach that amount.
  4. If it is not practical to add enough memory to reach TotalMem, then you may wish to off-load other services to a different computer so that the database engine can use a larger proportion of physical memory. Or, settle for a smaller cache and a somewhat greater level of disk I/O. Many applications will run almost as fast as 100% cached if the database is at least 25-30% cached. The specific performance ratio is dependent on the design and average usage model of the application.

    Under these conditions, you may also consider investing in a fast disk array, such as a RAID 0 stripe array that splits disk writes across multiple volumes simultaneously. Such a configuration can have a significant effect on systems where the disk I/O is limiting the overall application performance.

Minimizing Disk I/O

Reading and writing data to/from disk is much slower than reading and writing to/from memory. Thus, one way to optimize performance is to minimize disk activity.

An important consideration in your attempts to minimize disk I/O is recoverability of data. Disk I/O is a direct trade off against transaction durability and recoverability. The more data you keep in memory without pausing to log changes to disk, the faster the database performs. On the other hand, the more data you keep in memory without pausing to log changes to disk, the more data you lose if the system experiences a failure.

To reduce disk I/O

  1. As discussed in the previous sub-section , Ensuring Adequate Physical Memory and Database Cache, one of the most important considerations is to ensure you have enough database memory cache to avoid frequently swapping data pages between disk and cache. See that section for details.

    One of the best ways to reduce disk I/O is to make sure that the dynamic Level 2 cache is turned on. The Level 2 cache adjusts its size dynamically as application usage changes, storing as much data as possible in memory and thus avoiding disk I/O when cache demands exceed the capacity of the Level 1 fixed cache. By default, the Level 2 cache is turned on. To verify that your database engine is using Level 2 cache, check the Configuration setting Server 4 Performance Tuning 4 Max MicroKernel Memory Usage.

  2. In any networked configuration where the application and the database engine reside on different computers, use of the client cache improves performance under most usage scenarios. By default, the client cache is turned on. To verify that your client is using the client cache, check the Configuration setting Client 4 Performance Tuning 4 Use Cache Engine.
  3. The next step is to consider how much logging you require and what quantity of database operations you are willing to lose in a system failure. The greater the quantity of changes you are willing to lose, the more you can risk in the pursuit of performance.

    Using Archival Logging, Transaction Durability, and Transaction Logging all require log files. By default, archival logging is turned off. Turn it on only if you perform regular backups and you need the capability to restore data up to the moment of a system failure. When you specify the files to be logged, be sure to specify only the files for which you absolutely must have logging. See Chapter 8, Logging, Backup, and Restore, for more information.

    By default, transaction logging is turned on. Turning off transaction logging should improve performance slightly, but does not guarantee multi-file consistency and transaction atomicity. Before turning off transaction logging, check with your application vendor to be sure they allow the application to run without this feature.

    Caution
    The consistency of any multi-file database cannot be guaranteed if transaction logging is disabled.

    By default, transaction durability is turned off. Turn on this feature only if your application requires completed transaction operations to be durable through a system crash. Transaction durability entails the highest performance penalty, and the trade off is the highest safety of your completed transactions.

  4. If you have any logging features turned on, you can specify how much data the engine stores in memory before writing to disk. This feature is important because the changed data builds up over time. The more log data you allow to build up in memory, the less frequent the disk writes are.

    The setting Server 4 Performance Tuning 4 Log Buffer Size specifies the number of bytes of database operations that the engine stores in memory before writing them out to the log files.

    If a system failure occurs, the data in the log buffer is lost.

  5. If you have transaction durability turned on, you can specify the maximum size of the log segments on disk. Specifying a larger log segment size can improve performance slightly, because fewer log segments have to be created and closed over time.

    The setting Server 4 Performance Tuning 4 Transaction Log Size specifies the maximum number of bytes that can be stored in a log segment before closing it and opening a new segment.

  6. If your application usage is weighted heavily in favor of database read operations, you can increase performance by turning on Server 4 Performance Tuning 4 Index Balancing. Over time, index balancing increases the number of nodes on the average index page, allowing read operations to occur faster. However, for insert, update, and delete operations, additional time and disk I/O may be required because the engine balances the index nodes across adjacent pages.
  7. Be sure that tracing is turned off, both in the MicroKernel and/or at the ODBC level. Tracing may cause a significant reduction in performance because it can introduce a large amount of disk I/O.

    To ensure ODBC tracing is turned off, choose Start 4 Programs 4 Pervasive.SQL V8 4 Other Utilities 4 ODBC Administrator and click on the Tracing tab. If tracing is off, you should see a button labeled "Start Tracing Now," and thus you should click Cancel. If tracing is on, click Stop Tracing Now, then click OK.

    To ensure MicroKernel tracing is turned off, use Configuration to inspect the setting Server 4 Debugging 4 Trace Operation. Set the value to Off if it is not already.

Ensuring Adequate Resource Allocation

If your database server platform has adequate memory and CPU power, you should ensure that your database engine can take full advantage of the available hardware resources to service multiple clients and multiple data files most efficiently.

To configure multiple client and file handling

  1. The setting Server 4 Performance Tuning 4 Communications Threads allows you to specify how many threads are available to handle client connections.

    For any network with up to 32 client workstations, you should assign one communications thread for each connected workstation. Above 32 clients, you should use Monitor to evaluate whether the peak usage is hitting the maximum allowed. See Spotting Performance Bottlenecks for more information.

    After you increase the Communications Threads value and restart the database engine, wait until a period of peak usage has occurred, then evaluate the situation again using Monitor.

  2. The setting Server 4 Performance Tuning 4 Number of Input/Output Threads allows you to specify how many threads are available to handle file operations.

    As a guideline, the value of this setting should be about 1/8 the number of files the application has open, on average. For example, if the application has 40 files open most of the time,
    I/O Threads should be set to 5.

    Using Monitor, choose MicroKernel 4 Resource Usage from the menu. In the window that appears, the Files: display shows you current and peak number of files open. You can generate an average reading by recording several Current values over time. Then you can specify an appropriate setting for I/O Threads based on the average value.

Prev
Configuration Utility Tips 		Up
Check for Revisions 		Next
Configuration Reference


Configuration Reference

Configuration Settings Available in Pervasive.SQL V8

This chapter discusses the following topics:

  • Server Configuration Parameters
  • Win32 Client Configuration Parameters
  • Win16 Client Configuration Parameters
  • Linux Client Configuration Parameters
  • Settings and Features that are Not Applicable to Linux Client
Prev
Tuning Performance
Check for Revisions 		Next
Server Configuration Parameters


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:

  • Windows clients: these credentials are stored in the Windows registry. When the Prompt for Client Credentials is set to On, then a pop-up dialag allows you to save the credentials by selecting the Save User name and Password checkbox. Alternatively, you can use the pvnetpass command-line utility to manage stored credentials.
  • Linux clients: credentials are stored in the Pervasive registry by the 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 (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:

  • Emulate Workgroup Engine. Use this value when Samba is used to authenticate user access on the system.
  • Proprietary Authentication (using btpasswd). Use this value when not using Samba and the user does not have an account on the server. This allows a separate password file to be maintained when connecting to the Linux system.
  • Standard Linux Authentication. Use this value when not using Samba but users have accounts on the Linux system.

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:

  • None. By default, system data is not included on file creation. Application developers using the Create operation can override this setting.
  • If needed. System data is added to the file on file creation if the file does not have a unique key.
  • Always. System data is always added on file creation, regardless of whether the file has a unique key.

Note
The System Data setting does not affect existing files. This setting only affects how new files are created.

If you want to use transaction durability with a file that was not created with System Data turned on and does not have a unique key, you must 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.

  • To remove a Btrieve Interface operation from the Selected list, highlight the operation, and click the < button. To remove all of the Btrieve Interface operation codes from the Selected list, click the << button. The operations will move to the Available list.
  • To add a Btrieve Interface operation to the Selected list, highlight the operation in the Available list, and click the > button. To add all of the Btrieve Interface operation codes to the Selected list, click the >> button. The operations will move to the Selected list.
    • Abort Transaction (21)
    • Get Position (22)
    • Begin Transaction (19)
    • Get Previous (7)
    • Clear Owner (30)
    • Get Previous Extended (37)
    • Close (1)
    • Insert (2)
    • Create (14)
    • Insert Extended (40)
    • Create Index (31)
    • Open (0)
    • Delete (4)
    • Reset (28)
    • Drop Index (32)
    • Set Directory (17)
    • End Transaction (20)
    • Set Owner (29)
    • Extend(16)
    • Stat (15)
    • Find Percent (45)
    • Step First (33)
    • Get By Percent (44)
    • Step Last (34)
    • Get Direct/Chunk (23)
    • Step Next (24)
    • Get Directory (18)
    • Step Next Extended (38)
    • Get Equal (5)
    • Step Previous
    • Get First (12)
    • Stop (25)
    • Get Greater (8)
    • Step Previous Extended (39)
    • Get Greater or Equal (9)
    • Unlock (27)
    • Get Last (13)
    • Update (3)
    • Get Less or Equal (11)
    • Update Chunk (53)
    • Get Less Than (10)
    • Version (26)
    • Get Next (6)

    • Get Next Extended (36)

Trace File Location
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:

  • Windows NT/2000: C:\WINNT
  • Windows 9X/ME: C:\WINDOWS
  • NetWare server: SYS:SYSTEM
  • Linux server: /usr/local/psql/etc

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:

  • Windows: C:\PVSW\BIN\MKDE\LOG
  • NetWare: SYS:SYSTEM\MKDE\LOG
  • Linux: /usr/local/psql/log

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.

  • Specify Complete when you want to require the user to provide a valid user name; you can also specify a password, although not required.
  • Specify Pre-Authorized when you want to require the user to enter a valid user name and password.
  • Specify Disabled when you want the user to only have a connection to the NetWare server to access any Btrieve files. If the user is not connected to the server, s/he will receive a Status Code 99, "The Btrieve Requester is unable to access the NetWare Runtime server."

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 		Up
Check for Revisions 		Next
Win32 Client Configuration Parameters


Win32 Client Configuration Parameters

The client configuration options are available in all the different installation setups. These options must be configured separately for each workstation, which includes servers acting as workstations.

Access

Gateway Durability
Name | Type | Range | Default | Units
Gateway Durability | Boolean | On/Off | Off | N/A

This option specifies whether the MicroKernel Router should store in the registry a list of computers that do not have Pervasive.SQL running on them. This decreases the time it takes to find a gateway engine. You must set this option to Off when new engines are added to the workgroup.

Number of Load Retries
Name | Type | Range | Default | Units
Number of Load Retries | Numeric | 0 - 65536 | 5 | N/A

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

Target Engine
Name | Type | Range | Default | Units
Target Engine | SelectOne | See below | On Win9x: Workgroup On Win NT/2000: Try Server, then Workgroup | N/A

This setting applies only to the client running on a Windows NT/2000 server where a database engine is installed. This setting is ignored on Windows 9X/ME. If you are running on Windows9X/ME, setting this value to "Server" is not permitted.

If you have both a Workgroup engine and a Server engine installed on the Windows server, you can use this setting to shorten the initial connection time for the engine that you use the most. If you use the Server engine most often, you can set it to Try Server, then Workgroup so that the client always tries to connect to the local Server engine first.

If you have only a Workgroup engine installed, setting this parameter to Workgroup avoids the wait that occurs when the client tries to open a named pipe to a non-existent local Server engine.

If the client occasionally access both a remote Server engine as well as the local Server engine, you can use this setting to determine which engine the client connects to. In this scenario, the remote Server engine is referred to as the Workgroup.

If the setting Use Local MicroKernel Engine is turned Off, then this setting is ignored.

Use IDS
Name | Type | Range | Default | Units
Use IDS | Boolean | On/Off | Off | N/A

This setting specifies that the MicroKernel Router allows access to a Pervasive.SQL I*net Data server running on a remote server. Make sure this setting is set to On before using any of the IDS configuration options.

Use Local MicroKernel Engine
Name | Type | Range | Default | Units
Use Local MicroKernel | Boolean | On/Off | On | N/A

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
Name | Type | Range | Default | Units
Use Remote MicroKernel | Boolean | On/Off | On | N/A

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.

Prior to Pervasive.SQL 2000i (Service Pack 3), this setting was named "Requester."

Note
We recommend you keep Use Remote MicroKernel Engine set to On for a Microsoft's File and Print Services for NetWare (FPNW) server running Pervasive.SQL. You may receive a Status Code 94, "The application encounter a permission error," if you change this setting to Off when you are running the Btrieve Interface locally on the FPNW server and using a local FPNW drive mapping or local FPNW UNC path.

Cache Engine Debugging

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

Enable Auto Reconnect
Name | Type | Range | Default | Units
Enable Auto Reconnect | Boolean | On/Off | Off | N/A

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
Name | Type | Range | Default | Units
Supported Protocols | Multiselect | N/A | Varies | N/A

This setting specifies the protocols that are used by the Communications Requester. If more than one protocol is specified, the Communications Requester attempts to connect using all available protocols. When the first protocol succeeds, that protocol is used for the remainder of the session. The default value varies depending upon the platform; the available options are:

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

Connection Timeout
Name | Type | Range | Default | Units
Connection Timeout | Numeric | 1 - 2147483647 | 15 | seconds

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

Compress IDS Data
Name | Type | Range | Default | Units
Compress IDS Data | Boolean | On/Off | Off | N/A

This setting determines if the MicroKernel Router uses compression with the IDS server. Using compression may allow the data to be transmitted in fewer TCP/IP packets and may improve performance.

Use Cache Engine
Name | Type | Range | Default | Units
Use Cache Engine | Boolean | On/Off | On | N/A

This setting specifies whether the client cache should be used. If this setting is Off, then the client caches single records in a relatively small fixed-size cache on the client workstation. If this setting is On, then the client uses the client cache engine, if it is loaded in memory. If the client cache engine is not loaded, this setting has no effect.

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. After the client cache engine starts, a tray icon appears, allowing you to control the client cache from the Windows task bar.

Some users 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, simply run it from the Pervasive program group menu before you start any applications that use the database engine.

To run the client cache, choose Start 4 Programs 4 Pervasive.SQL V8 4 Engines 4 Cache Engine.

To stop the client cache, right-click on the client cache tray icon and choose Stop Engines and Exit.

Pervasive.SQL keeps the client cache fully synchronized with the database engine cache and other client cache locations. This behavior is entirely transparent, meaning that you should never need to worry about what records are or are not in any given 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, delete
  • opens and close operations

Security

IDS Password
Name | Type | Range | Default | Units
IDS Password | String | N/A | None | N/A

This is the password used by the MicroKernel Router to log into a Pervasive.SQL I*net Data Server running on a remote server. There is no default value and a password must be set by the system administrator on the I*net Data Server and the Use IDS configuration option must be set to On before using this option.

IDS Username
Name | Type | Range | Default | Units
IDS Username | String | N/A | None | N/A

This is the name used by the MicroKernel Router to log into a Pervasive.SQL I*net Data Server running on a remote server. There is no default value and a user name must be set by the system administrator on the I*net Data Server and the Use IDS configuration option must be set to On before using this option.

Runtime Server Support
Name | Type | Range | Default | Units
Runtime Server Support | String | Yes No user_name:password | Yes | N/A

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 username, enter "user_name:password".

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

Application Characteristics

Embedded Spaces
Name | Type | Range | Default | Units
Embedded Spaces | Boolean | On/Off | Off | N/A

This option instructs the Btrieve Interface to allow embedded spaces in filenames for Btrieve operations.

Splash Screen
Name | Type | Range | Default | Units
Splash Screen | Boolean | On/Off | On | N/A

This setting controls whether or not the Btrieve Interface splash screen displays. The splash screen displays the first time a Btrieve requester is loaded.

Note
The 32-bit Configuration utility enables/disables the splash screen for 32-bit applications and 16-bit applications when thunking is set to On. For 16-bit applications, if thunking is set to Off, use the Client-16-bit Application characteristics options to disable the splash screen.

Configuration Mapping

The following table is a mapping of all the available Client configuration options and their settings.
Table 5-7 Client Configuration Settings
Configuration Option | Parameter Name
Access | Gateway Durability
 | Number of Load Retries
 | Target Engine
 | Use IDS
 | Use Local MicroKernel
 | Use Remote MicroKernel
Communication Protocols | Enable AutoReconnect
 | Supported Protocols
 | TCP/IP Timeout for Communication Requester
Performance Tuning | Compress IDS Data
 | Use Cache Engine
Security | IDS Password
 | IDS Username
 | Runtime Server Support
Application Characteristics | Splash Screen
 | Embedded Spaces

Prev
Server Configuration Parameters 		Up
Check for Revisions 		Next
Win16 Client Configuration Parameters


Win16 Client Configuration Parameters

This section describes the configuration options available for the 16-bit client. These must be changed at each individual client and will be used only when running legacy applications. There is no relational engine access when using 16-bit client applications.

Access

Use Local MicroKernel Engine
Name | Type | Range | Default | Units
Use Local Microkernel Engine | Boolean | On/Off | On | N/A

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
Name | Type | Range | Default | Units
Use Remote MicroKernel Engine | Boolean | On/Off | On | N/A

This setting specifies whether the MicroKernel Router allows access to a MicroKernel server engine running on a remote server. If this value is set to On, and Use Local MicroKernel is set to On, the remote server is tried first.

Application Characteristics

Splash Screen
Name | Type | Range | Default | Units
Splash screen | Boolean | On/Off | On | N/A

This setting controls whether or not the Btrieve Interface splash screen displays. The splash screen displays the first time a Btrieve requester is loaded.

Use IDS
Name | Type | Range | Default | Units
Use IDS | Boolean | On/Off | Off | N/A

This setting specifies that the MicroKernel Router allows access to a Pervasive.SQL I*net Data server running on a remote server. Make sure this setting is set to On before using any of the IDS configuration options.

Use Thunk
Name | Type | Range | Default | Units
Use Thunk | Boolean | On/Off | On | N/A

This setting specifies whether the Win16 client requester uses thunking to access Win32 components. This option must be turned on when on a Win32 platform (Windows NT/9X/2000) accessing Win16 (Btrieve) applications.

Communication Protocols

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

This setting specifies the protocols that are used by the Communications Requester. If more than one protocol is specified, the Communications Requester will attempt to use TCP/IP first. If TCP/IP is not available, it uses SPXII. In the case of Linux servers, the only protocol that can be used is TCP/IP; SPX is will not function. The default value varies depending upon the platform; the available options are:

Table 5-8 Client 16-bit Supported Protocols
  • Microsoft SPX
  • Microsoft NETBIOS
  • Microsoft TCP/IP
  • NWIPX/SPX SPX

TCP/IP Timeout for Communication Requester
Name | Type | Range | Default | Units
TCP/IP Timeout for Communication Requester | Numeric | 1 - 2147483647 | 15 | seconds

This setting specifies the number of seconds the requester should wait for a TCP/IP connect request to succeed before timing out.

Security (NetWare server access only)

Runtime Server Support
Name | Type | Range | Default | Units
Runtime Server Support | String | Yes No user_name:password | Yes | N/A

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 username, enter "user_name:password".

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

Configuration Mapping

The following table is a mapping of all the available 16-bit Client configuration options and their settings.
Table 5-9 16-bit Client Configuration Settings
Configuration Option | Setting Name
Access | Use Local MicroKernel Engine
 | Use Remote MicroKernel Engine
Application Characteristics | Splash Screen
 | Use IDS
 | Use Thunk
Communication Protocol | Supported Protocols
 | TCP/IP Timeout for Communication Requester
Security | Runtime Server Support

Prev
Win32 Client Configuration Parameters 		Up
Check for Revisions 		Next
Linux Client Configuration Parameters


Linux Client Configuration Parameters

On the Windows platform, you configure both Pervasive.SQL clients and servers using the Pervasive Control Center. You can use the Pervasive Center also to remotely connect to and configure a Pervasive.SQL Linux server.

On a Linux client, however, configuration is written to the Pervasive registry using either the pvclientcfg script or the psregedit utility, which allows you to display and modify the Pervasive registry.

Using the pvclientcfg Script

To run the script, enter pvclientcfg at a shell prompt. You must be the root user or a member of the group pvsw to save configuration changes. The script displays the current settings and allows you to change the settings by number.

Using the psregedit Utility

This section describes how to use the psregedit utility.

psregedit Syntax

psregedit

-key KEYNAME [ -r ]
-key KEYNAME -value VALUENAME
-set -key KEYNAME [ -type TYPE ] VALUE
-set -key KEYNAME -value VALUENAME [ -type TYPE ] VALUE
-delete -key KEYNAME
-delete -key KEYNAME -value VALUENAME
-export -key KEYNAME [ -file FILENAME ]
-import [ -file FILENAME ]

Description

You can use either slash (/) or backslash (\) as the delimiter for keys.

Note
You must enclose keys within quotes ("). For example, "PS_HKEY_CONFIG/Software/Pervasive Software". Otherwise, spaces are interpreted as the end of your key.

Specifications

-key KEYNAME
-key KEYNAME -value VALUENAME

Get the key value. If -value is not specified, then the entire key contents are viewed. To view all subkeys, specify -r (for recursive).

-set -key KEYNAME [ -type TYPE ] VALUE
-set -key KEYNAME -value VALUENAME [ -type TYPE ] VALUE

Set the key value. If -value is not specified, the default value will be set. VALUE must be appropriate for the TYPE specified. PS_REG_STR is assumed if -type is not specified.

-delete -key KEYNAME
-delete -key KEYNAME -value VALUENAME

Delete the specified key or value. If -value is not specified, then the entire key and all subkeys will be deleted.

-export -key KEYNAME [ -file FILENAME ]

Export the given key, including all values and subkeys, to standard output or the named file.

-import [ -file FILENAME ]

Import keys and values from either the standard input or the named file.

For all options, the parameters are defined as follows:

KEYNAME := PS_HKEY/Subkey/Path
PS_HKEY := { PS_HKEY_CONFIG | PS_HKEY_CLASSES | PS_HKEY_USER }
VALUENAME := value name or 'default'
TYPE := { PS_REG_STR | PS_REG_UINT32 | PS_REG_UINT64 }

Examples of Configuring the Linux Client

This section provides some examples of configuring the Linux client using psregedit.

To display all your current settings for the Linux client in a scrollable list in the standard output:

psregedit -key PS_HKEY_CONFIG -r | less

To specify that your client allow connections to remote servers:

psregedit -set -key "PS_HKEY_CONFIG/Software/Pervasive Software/Microkernel Router"
-value "Remote" yes

For more information about specific configuration settings, see Pervasive.SQL User's Guide and Configuration Reference for the Linux Client .

Configuration Notes

This section contains important concepts on configuring your Linux client properly.

Case of Setting Values

When checking or editing the values of settings, the Linux client performs a case-insensitive comparison. For example, entering 'Yes' or 'yes' for a setting value is interpreted identically by the Linux client. The names of registry keys are also handled in a case-insenstive manner by the psregedit utility.

Client Performance Affected by "Local" Setting

When the Linux client interface is first activated, it populates its default settings in the Pervasive registry. The client interface does not have knowledge on whether its installation includes a server engine or not (All Pervasive engines also contain the client components). Therefore, it sets the "Local" setting to yes. This can have an impact on the performance of your Linux client.

If the machine on which you are using the client interface does not have a server engine, you should set the Local setting to no. See Use Local MicroKernel Engine for a reference entry for this setting.

File Names with Embedded Spaces

By default, the Linux client interface does not support file names that contain embedded spaces.

For example:

/mymount/usr/gary/file with spaces.mkd

If you want to use file names with embedded spaces, you need to change the "Embedded Spaces" setting. See Embedded Spaces for a reference of this setting.

Configuration Reference for the Linux Client

This section lists all configuration settings for the Linux client.

  • Btrieve Requester Settings
  • Comm Settings
  • MicroKernel Router Settings
  • Diagnostic Configuration

Btrieve Requester Settings

The Btrieve Requester settings for the Linux client can be found under the key:

Key for Btrieve Requester

Use this as the -key for changing settings of this type:

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Btrieve Requester/Version 8/Settings"

Values for Btrieve Requester Settings

The following settings are located under this key, which are denoted by the -value parameter:

Embedded Spaces
Name
Type
Range
Default
Units
Embedded Spaces
PS_REG_STR
yes/no
no
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Btrieve Requester/Version 8/Settings"
-value "Embedded Spaces"

This option instructs the Btrieve Interface to allow embedded spaces in filenames for Btrieve operations.

Comm Settings

The communications settings for the Linux client can be found under the key:

Key for Communication Settings

Use this as the -key for changing settings of this type.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Version 8/Settings"

Values for Communication Settings

The following settings are located under this key, which are denoted by the -value parameter:

Supported Protocols
Name
Type
Range
Default
Units
Supported Protocols
PS_REG_STR
N/A
TCPIP
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Version 8/Settings"
-value "Supported Protocols"

This setting specifies the protocols that are used by the Communications Requester. For the Linux client, the only valid value for this setting is the default: TCP/IP.

Enable AutoReconnect
Name
Type
Range
Default
Units
Enable AutoReconnect
PS_REG_STR
yes/no
no
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Version 8/Settings"
-value "Enable AutoReconnect"

This setting specifies whether you want the client to attempt to auto-reconnect during a network outage. A setting of yes means Auto Reconnect is enabled.

Auto Reconnect is not in effect unless this setting is also enabled in the server configuration.

Note
The Pervasive Linux client supports this auto-reconnect feature, but currently the Linux server does not. Therefore, you can only use the AutoReconnect (PARC) feature from a Linux client connecting to Windows or NetWare servers.

Max Multiple Connections
Name
Type
Range
Default
Units
Max Multiple Connections
PS_REG_UINT32
0-256
0
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Version 8/Settings"
-value "Max Multiple Connections"

This setting controls the maximum number of connections that this client will make to a Pervasive.SQL server using the same Client ID.

When you specify 0, Pervasive.SQL uses internal defaults, which is 16 for the TCP/IP protocol.

Note
The server must be of version 8.0 or above for this setting to be used.

Log Statistics
Name
Type
Range
Default
Units
Log Statistics
PS_REG_STR
Yes/No
No
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Version 8/Settings"
-value "Log Statistics"

This setting enables communications statistics to be recorded.

MicroKernel Router Settings

The MicroKernel Router settings for the Linux client can be found under the following key:

Key for MicroKernel Router

Use this as the -key for changing settings of this type.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
MicroKernel Router/Version 8/Settings"

Values for MicroKernel Router

The following settings are located under this key:

Use Local MicroKernel Engine
Name
Type
Range
Default
Units
Local
PS_REG_STR
yes/no
yes
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
MicroKernel Router/Version 8/Settings"
-value "Local"

This setting determines whether a local application tries to connect to a local engine. If set to no, no attempt is made to connect to a local engine.

Use Remote MicroKernel Engine
Name
Type
Range
Default
Units
Requester
PS_REG_STR
yes/no
yes
N/A

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
MicroKernel Router/Version 8/Settings"
-value "Requester"

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 yes, and Use Local MicroKernel Engine is set to yes, the remote server is tried first.

For information about UNC paths in relation to this setting, see Target Engine and UNC Paths .

Diagnostic Configuration

These settings are only applicable if you are using the Trace requesters introduced with Pervasive.SQL V8. You should only use the trace requesters when debugging an application based on Pervasive.SQL. For more information about the tracing requesters, see What's New in Pervasive.SQL V8.

Key for Diagnostics Settings

Use this as the -key for changing settings of this type.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"

Values for Diagnostics Key

The following settings are available under this key:

Trace Level

Controls the level of detail in the output. It is suggested you set it to "verbose" for maximum output.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"
-value "Trace Level"
Trace File

Set to a specific file name (for example, /usr/local/psql/trace.txt) where you want the output to appear. The file is created as needed.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"
-value "Trace File"
Trace Append

Always set to "yes".

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"
-value "Trace Append"
Trace Modules

Determines which modules write debug output. Set to "all" or to the name of the specific LIBS, such as "psqlnsl" or for multiple libraries, "psqlnsl, psqlmif, psqlupi".

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"
-value "Trace Modules"
Trace Buffer Length

Controls how many bytes of raw hex data is written to the output file when buffers are dumped. Start with the default (32 bytes) and increase if needed.

-key "PS_HKEY_CONFIG/Software/Pervasive Software/
Communications Requester/Diagnostics"
-value "Trace Buffer Length"

Target Engine and UNC Paths

The requester has two settings "Local" and "Requester".

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

  • You must be running an engine on the same computer as the file that you are trying to access
  • You must configure the Microkernel router's "Requester" setting to "yes". See Use Remote MicroKernel Engine for more information.

Note
You cannot send use a UNC path that points to the local Linux machine. However, you can use a path that is in the UNC style such as
//localhost/usr/loca/psql/data/samples/sample.btr

If you do not want an engine on your file server (that is, you want to use the client's local engine), then you will need to mount the remote file system on the client, and modify the path so that it is a "native format" path and not UNC format. For example, the following path is a native Linux format:

/mnt/myremotedata/sample.btr

Prev
Win16 Client Configuration Parameters 		Up
Check for Revisions 		Next
Settings and Features that are Not Applicable to Linux Client


Settings and Features that are Not Applicable to Linux Client

This section lists settings and features that, while available on either the Windows or NetWare platforms, are not available for use from a Linux client.

I*net Data Server

You cannot use a Linux client to connect to an application using the I*net Data Server feature. As such, there is no configuration settings for IDS present in the Linux client. This includes the following settings:

  • Use IDS
  • Compress IDS Data
  • IDS Password
  • IDS Username

TCP/IP Timeout

You configure this as part of your Linux system settings, so the Pervasive setting has no meaning here.

Prev
Linux Client Configuration Parameters 		Up
Check for Revisions 		Next
Setting Up Referential Integrity


Setting Up Referential Integrity

An Introduction to Referential Integrity Structures

Referential Integrity is a system of checks and balances that you can create in your database to ensure that tables with related data remain synchronized.

  • Concepts of Referential Integrity
  • Setting up Primary Keys
  • Setting up Foreign Keys
  • Interactions Between Btrieve and Relational Constraints
Prev
Settings and Features that are Not Applicable to Linux Client
Check for Revisions 		Next
Concepts of Referential Integrity


Concepts of Referential Integrity

Referential Integrity (RI) allows you to modify or prohibit updates, inserts, or deletes based on whether identical field values exist in the same or other tables.

Definitions

A good understanding of RI depends upon a clear understanding of several important terms:

Rule

A rule is a simple statement of cause and effect, carried out by the RI system defined in the database.

Example A

For example, a delete rule defines what happens to records containing a foreign key when a record containing a primary key is deleted: "When the record containing 'Bhargava Building' is deleted, all rows in Table A that reference that record are deleted."

A delete rule can also prohibit the row containing the primary key value from being deleted if there are any foreign key values that reference the given primary key value.

Example B

An update rule defines what happens to a record containing a foreign key when a user attempts to update the record or add a new record: "When a user attempts to insert a new record to Table B, reject the attempt if the building name does not exist in Table C."

Primary key

A primary key is the column or columns upon which a rule depends. Only one primary key is permitted in any table, and the primary key must not allow duplicate values. For an update rule, the primary key is the column or columns against which updated or inserted columns are compared to determine if the updated or inserted record should be allowed.

In Example A above, the column containing "Bhargava Building" is the primary key.

In Example B above, the column in Table C that contains the building name is the primary key.

Foreign key

A foreign key is the column or columns that are compared against a primary key to determine how to proceed.

In Example A above, the column in Table A that may contain the value "Bhargava Building" is the foreign key.

In Example B above, the column in Table B that contains the building name is the foreign key.

Cascade

A cascade rule is a rule in which the database permits the desired operation to occur, then enforces RI by changing other tables or rows to synchronize with the first operation.

For example, if a delete cascade rule is defined, deleting a record in the primary key table causes the database to find and delete all rows throughout the database that have foreign key values the same as the primary key value of the deleted row.

Restrict

A restrict rule is a rule in which the database decides whether or not to permit the desired operation based on existing values in the database.

for example, if an update restrict rule is defined, an attempt to add a row to a table containing a foreign key causes the database engine to compare the value in the foreign key field to the values in the primary key. If there is no primary key row with the same value, the new row is not permitted to be added to the foreign key table.

Understanding Keys and Rules

This section explores the concepts behind primary keys and foreign keys in further detail.

Figure 6-1 Primary and Foreign Keys

Table A |  | Table B
u student_ID | u Name | u stud_ID | u Class
20543 | John | 20543 | ENG-101
20577 | Mary | 20543 | AST-202

In the example shown in Figure 6-1, the column named student_ID in Table A (A.student_ID) is an IDENTITY data type that does not allow two rows to the have the same value. Every student has a unique ID number. We will define student_ID as the primary key of Table A.

We can then define the column named stud_ID in Table B (B.stud_ID) as a foreign key that references A.student_ID. Note that the data type of stud_ID must be a type that can be compared with IDENTITY, such as INTEGER. The data types of primary and foreign keys must be compatible. You can have as many foreign keys as you need in order to enforce your desired referential integrity scheme. Multiple foreign keys can reference the same primary key.

The table with the primary key can be referred to as the parent table, while the table with the foreign key is called the child table. Once the keys are defined, we have a range of behaviors to choose from, as shown in Table 6-1. You can define as many rules as fit your needs, but you can only have one of each type. For example, if you define a delete restrict rule, you cannot define a delete cascade rule on the same keys, because the two behaviors are mutually exclusive.
Table 6-1 Choices for RI Rules
If you want this behavior ... | ... define this rule:
Do not allow a row to be inserted or updated in Table B unless the proposed value of B.stud_ID matches any value in A.student_ID. | Update Restrict
Do not allow a row to be deleted from Table A if any value of B.stud_ID matches that row. | Delete Restrict
If a row is deleted from Table A, delete all rows from Table B in which B.stud_ID matches the value of A.student_ID in the deleted row. | Delete Cascade

Update Restrict

Continuing with the example, setting an update restrict rule ensures that the value of B.stud_ID in any new or updated row must first exist in A.student_ID. It follows, then, that you must have rows in Table A before you can add any rows in Table B. Stated another way, you must create at least one parent row before you can create a child row.

Delete Restrict

In the example, setting a delete restrict rule ensures that a row from Table A cannot be deleted if any rows in Table B reference that row. You cannot delete the row with Name value "John" because John's student ID is referenced in Table B.

Once all rows from Table B that reference John's student ID are deleted, then John's row can be deleted from Table A.

Delete Cascade

In the example, setting a delete cascade rule ensures that both records in Table B are deleted if the row with Name value "John" is deleted.

Prev
Setting Up Referential Integrity 		Up
Check for Revisions 		Next
Setting up Primary Keys


Setting up Primary Keys

You must create primary keys using SQL statements. Pervasive Control Center does not provide this ability in the user interface, unless you wish to modify by hand the SQL statement created by Create Table Wizard before you generate the table.

Creating a Primary Key During Table Creation

You can create a primary key when you create a table, by using the PRIMARY KEY keywords in your CREATE TABLE statement. A primary key can consist of one or more columns. The example below shows the column named id being created then being designated the primary key:

CREATE TABLE mytable (id INTEGER,
                    myname CHAR(20),
                    PRIMARY KEY(id))

The example below shows how to create a primary key using more than one column as the unique key value:

CREATE TABLE mytable (id INTEGER,
                    myname CHAR(20),
                    PRIMARY KEY(id, myname))

Regardless of whether you specify the UNIQUE attribute on the column or columns that you designate as a primary key, the database engine automatically creates an index on the designated columns that does not allow duplicate values or null values in the columns. Null values are never allowed in a key column. Every primary key value must be unique.

For more examples, see CREATE TABLE in SQL Engine Reference.

Adding a Primary Key to an Existing Table

You can add a primary key to an existing table, by using the ALTER TABLE statement with ADD PRIMARY KEY key words. You must create the primary key on a column or columns that do not allow duplicate values or null values.

If necessary, you can modify the column attributes and make the column the primary key at the same time:

ALTER TABLE mytable MODIFY id INTEGER UNIQUE NOT NULL PRIMARY KEY

If you want to add a primary key consisting of more than one column, you must add the key separately:

ALTER TABLE mytable ADD PRIMARY KEY(id, myname)

For more examples, see ALTER TABLE in SQL Engine Reference.

Prev
Concepts of Referential Integrity 		Up
Check for Revisions 		Next
Setting up Foreign Keys


Setting up Foreign Keys

You must create foreign keys using SQL statements. Pervasive Control Center does not provide this ability in the user interface.

When you create a foreign key, you must define the associated rule at the same time. You can define multiple rules on the same key.

Creating a Foreign Key During Table Creation

You can create a foreign key when you create a table, by using the REFERENCES keyword in your column definition. A foreign key can consist of one or more columns. The data types of the column(s) must be the same as the primary key that this foreign key references. The example below shows the column named your_id being created then being designated the foreign key, referencing mytable.id:

CREATE TABLE yourtable (your_id INTEGER REFERENCES mytable(id) ON DELETE CASCADE, yourname CHAR(20))

You can also add the foreign key designation at the end of the statement. You must use this technique if you wish to use multiple columns in the key:

CREATE TABLE yourtable (your_id INTEGER,
            yourname CHAR(20),
            FOREIGN KEY(your_id, yourname) REFERENCES
                mytable(id, myname) ON DELETE CASCADE)

When you create a foreign key, the database engine adds an index on the designated columns.

For more examples, see CREATE TABLE in SQL Engine Reference.

Adding a Foreign Key to an Existing Table

You can add a foreign key to an existing table, by using the ALTER TABLE statement with ADD FOREIGN KEY key words. In the example below, two rules are defined for this foreign key, both a delete rule and an update rule:

ALTER TABLE yourtable ADD FOREIGN KEY (your_id,yourname) REFERENCES mytable(id,myname) ON DELETE CASCADE ON UPDATE RESTRICT

For more examples, see ALTER TABLE in SQL Engine Reference.

Prev
Setting up Primary Keys 		Up
Check for Revisions 		Next
Interactions Between Btrieve and Relational Constraints


Interactions Between Btrieve and Relational Constraints

While Pervasive.SQL is designed to support concurrent access to the same data through both the SQL/ODBC interface and the Btrieve interface, some features of the relational (SQL) database architecture may interfere with Btrieve access to the data. For example, features that are designed to limit relational access, such as Referential Integrity, may also limit Btrieve access in the interest of preserving data integrity.

You should fully understand Integrity Enforcement, Bound Databases, ODBC/SQL Security, Triggers, Referential Integrity and Owner Names before implementing these features on a database that is used by a transactional (Btrieve) application. In most cases you can get "Best of Both Worlds" access to your database, but since Security, Referential Integrity, and Triggers can put constraints on access or operations, some Btrieve operations may be restricted or prevented depending on the implementation.

In some cases using Integrity Enforced, Bound Databases, Security, Triggers, or Referential Integrity may cause Btrieve access to the data and/or file to be restricted or prevented when Btrieve access would violate the bounds and restrictions placed on that data. Triggers and RI mainly limit the ability to manipulate data via the Btrieve API. Security and owner names can limit access and/or the ability to manipulate that data without the proper account, rights, and password. There are many possible combinations of these features, so only the most common ones are listed here.
Table 6-2 Interactions Between Relational Restrictions and Btrieve Access
CONDITIONS |  |  |  |  |  | RESULTS
DDFs Exist? | Integrity Enforced? | Bound Database? | Relational Security Used? | Triggers Used? | RI Used? | Btrieve Access allowed? | SQL/ODBC Access Allowed?
No | - | - | - | - | - | Yes | No
Yes | No | No | No | No | - | Yes | Yes
Yes | No | No (1) | No | Yes (2) | - | Yes (2) | Yes
Yes | Yes | No | No | No | No | Yes | Yes
Yes | Yes | No | Yes | No | No | Yes (3) | Yes (3)
Yes | Yes | No (1) | Yes | No | Yes | Yes (4) | Yes (3) (4)
Yes | Yes | No (1) | Yes | Yes (2) | No | Yes (1) | Yes (3)
Yes | Yes | Yes | No | No | No | Yes | Yes
Yes | Yes | Yes | Yes | No | No | Yes (3) | Yes (3)
Yes | Yes | Yes (1) | Yes | No | Yes | Yes (2) (4) | Yes (3) (4)
Yes | Yes | Yes (1) | Yes | Yes (2) | No | Yes (2) (3) | Yes (3)

(1) Regardless of the Bound Database setting for a database, the database engine automatically stamps a data file as bound if it has a trigger, a foreign key, or a primary key that is referenced by a foreign key. For more information on the meaning of a bound database or file, see Bound Databases .

(2) Adding triggers on a table prevents access to that file from the Btrieve interface, for any operations that would cause the trigger to execute. Because triggers do not react to database operations coming through the Btrieve interface, this lock-out behavior preserves the consistency of the data. See Bound Database versus Integrity Enforced below for more information.

(3) When a database or file is secured, access is allowed as long as the user has permissions (that is, a relational user name and password or a valid Btrieve owner name) to that file. Files that are in a secure database but do not have Btrieve owner names set are accessible to Btrieve users. When relational security is first set up for a file that already has a Btrieve owner name, the Master user must grant relational permissions to users using the file's Btrieve owner name. See Pervasive.SQL Security for more information.

(4) If a table contains referential integrity constraints, and Integrity Enforced is turned on for the given database, both Btrieve and SQL operations that would violate the constraints are disallowed. This mechanism preserves the integrity of the data regardless of the method of access.

Bound Database versus Integrity Enforced

If you do not specify the attribute "Integrity Enforced" for a named database, the database engine does not enforce any referential integrity, triggers, or security rules. If you specify the attribute "Integrity Enforced" for a named database, the MicroKernel enforces the database's defined security, RI, and triggers, regardless of the method you use to access the data. The MicroKernel enforces these rules as follows:

  • Btrieve users are not subject to relational security. If you have owner names on the files, they remain in effect. If you do not have owner names on the files, any Btrieve user can access the data regardless of relational security constraints. Btrieve operations are subject to all the RI and other constraints defined in the database as well as the Trigger restrictions listed below.
  • If constraints exist on a given file, Btrieve access is permitted as follows:

    Table 6-3 Constraints on Btrieve Access - Integrity Enforced
    Constraint on File
    Level of Access Permitted Using Btrieve
    RI constraints defined
    User can access the data and perform any operations within RI constraints.
    INSERT triggers defined
    Read-only, update, and delete operations permitted.
    UPDATE triggers defined
    Read-only, insert, and delete operations permitted.
    DELETE triggers defined
    Read-only, update, and insert operations permitted.

If more than one constraint exists on the bound file, the access level follows the most restrictive constraint or combination of constraints. For example, if a file has both INSERT and UPDATE triggers defined, then Btrieve users have only read-only and delete access.

"Integrity Enforced" is not directly related to "Bound Database." A database can be bound without enforced integrity, or a database can have integrity enforced without being bound.

Bound Databases

If you specify the attribute "Bound" for a named database, the DDFs and data files in that database cannot be associated with any other database. Also, a bound data file cannot be associated with more than one table definition in the database. When you add new tables or DDFs to a bound database, the database engine automatically binds the new objects. This behavior prevents conflicts that could cause unpredictable behavior or data integrity corruption. For example, if you used the same data file for two different table definitions in the same database, you could define RI rules on one table but not on the other. In this case, inserting a row into the table without the RI rules would violate the RI rules on the other table. Binding the data files and DDFs prevents such conflicts.

DDFs and data files can be individually bound. The database engine automatically marks a data file as bound if it has a trigger, has a foreign key, or has a primary key that is referenced by a foreign key. These files cannot be shared with another database or associated with more than one table definition.

Whether a data file is bound has no direct affect on Btrieve access to that data file. However, files that are bound often have other constraints that may limit Btrieve access.

See Also

For information on how to manipulate the "Integrity Enforced" and "Bound Database" settings for a given database, see Pervasive.SQL Database GUI Reference .

Prev
Setting up Foreign Keys 		Up
Check for Revisions 		Next
Pervasive.SQL Security


Pervasive.SQL Security

Concepts and Tasks Related to Btrieve and Relational Security

Pervasive.SQL provides support for Btrieve owner names as well as a full implementation of database security that can be used by either Btrieve or SQL-based applications. This chapter explains the relationship between the two, and how to work with both.

If you are looking for information about securing the database engine and/or administrative access to the database engine, see Chapter 2 of Pervasive.SQL User's Guide.

  • Security Models and Concepts
  • Planning Your Security Scheme
  • Btrieve Security Quick Start
  • Security Tasks
  • Data Encryption
Prev
Interactions Between Btrieve and Relational Constraints
Check for Revisions 		Next
Security Models and Concepts


Security Models and Concepts

This section details the available security models for Btrieve and SQL. Both the Btrieve and SQL interfaces share the same level of granularity in choosing how rights are assigned to users. Both interfaces support database and column-level security. To support Btrieve applications that existed before the SQL security model was applied to Btrieve, the Btrieve interface has additional security policies that can determine how access is granted.

Available Models for Btrieve

This section describes the authentication and authorization models that are available in this release. The term credentials, login credentials, or user credentials refers to a valid username and password pair.

This release of the product supports OS-independent database authentication and authorization capabilities for the transactional (Btrieve) database engine. The original (operating system) authentication model is still available in this release, but now you can instead choose a model in which Btrieve users and privileges are not derived from filesystem users and privileges. One major advantage of the new security model is that now you can allow users access to the database without allowing them operating system access to the data files.

This topic applies only to Btrieve applications and users. Applications that use the SQL Relational Database Engine (SRDE) already have available an implementation of this complete and OS-independent database security model.

Current Btrieve applications can take advantage of the new security models without requiring any changes to the application code.

Classic

Classic security is the Btrieve security model that was provided in previous releases of the product. For Btrieve users, authentication is performed by the operating system, and data access privileges are determined by file system rights for the given user. The only authorization capability provided by the database engine independent of the operating system is Btrieve owner names, which are essentially file access passwords.

Under this security model, any user who is authenticated by the operating system has the same rights to access the data through Btrieve as he or she has to read and/or write the data files through the operating system. Btrieve owner names are an exception to this rule, allowing an additional level of authorization. However, this level of authorization is not related to the user's identity. It is related only to whether the application or the user can supply the owner name for a given file.

For more information on Btrieve owner names, see Advanced Operations Guide.

Mixed

In the Mixed security model, when a database login occurs, the database engine passes the user name and password entered by the user to the operating system authentication service. If the operating system authenticates the user name and password, then the database engine uses the users and rights table for the specified database (the current database if no database is specified) to determine the specific access rights of the given user. Thus, each user's data access privileges must be defined within the database. In turn, the database engine enforces the defined privileges regardless of the given user's filesystem privileges on the data files.

Database authorization for Btrieve applications is provided by extending the SRDE security model so that it also can be used for Btrieve applications. The ability to define users and set permissions is provided through the Groups and Users functionality in PCC, and through SQL statements such as GRANT and REVOKE.

Under the mixed security model, any user names defined in the database must correspond exactly with the same user names defined in the operating system. During a database login, the database engine simply passes the user name and password entered by the user to the operating system authentication module. If the operating system authenticates the credentials, then the database uses its own users and rights table to determine the specific access rights of the given user. You do not need to set up rights for every user. You can define the rights once using the default group PUBLIC, and every valid set of operating system credentials will inherit the rights granted to the PUBLIC group.

For detailed procedures on how to set up a Mixed security environment, see Setting up Mixed or Database Security .

Database

Under the Database security model, the database engine authenticates and authorizes users of Btrieve data files. A user's ability to connect to and access data is unrelated to the user's operating system account identification and filesystem privileges, as long as the user can successfully login to the computer on which his/her application runs.

Database authentication and authorization for Btrieve applications is provided by extending the SRDE security model so that it also can be used for Btrieve applications. The ability to define users and set permissions is provided through the Groups and Users functionality in PCC, and through SQL statements such as GRANT and REVOKE.

Note
To create new databases, a user is still required to have administrator-level privileges in the operating system.

For detailed procedures on how to set up a Database security environment, see Setting up Mixed or Database Security .

Notes on the Mixed and Database Security Models

For each database, a set of users must be defined, and for each user, a set of access privileges must be defined. The simplest case is defining access rights for the user PUBLIC, thus creating a set of rights for all users who are successfully authenticated. In addition, you must specify the filesystem directory or directories that contain the data files that should be considered as members of the given database. The database engine (or operating system in the case of Mixed security) performs user authentication and authorization for each attempt to access any data file within the specified directories. Without this association between databases and directories, when a Btrieve application attempts to open a specific data file, the database engine has no database context from which to determine the applicable set of defined users and permissions.

You can use the Mixed or Database security models only with Btrieve data files that reside in directories that have been defined as belonging to a given database, including the default database DefaultDB described in The Default Database and the Current Database . Data files residing in directories that have not been associated with a database can be accessed only with the Classic security model.

One of the primary advantages of these models is the ability to restrict operating system users' access to the data files, while still allowing full access to the data through the database engine. In contrast, according to the Classic model, any user permitted to add records to the data file must necessarily also have the ability to copy or delete the data file from the operating system.

Note
Since the Workgroup engine performs no operating system authentication, the behavior of the Classic and Mixed security policies using the Workgroup engine are essentially the same. If you with to secure a Btrieve database using the Workgroup engine, you must use the Database security policy.

Setting up Classic Security

Under Classic security, you set up database users and access permissions simply by creating users and assigning file permissions in the operating system. There are no separate actions to take to configure the database engine.

Refer to your operating system documentation for instructions on how to set up user accounts and assign permissions.

Setting up Mixed or Database Security

Migrating to mixed or database security requires that you make a number of choices and plan carefully. In a well-established environment, you may have to plan how your Btrieve files will be grouped together into databases, and schedule the migration so that you do not disrupt your production environment.

For complete information on transitioning from Classic to Mixed or Database security, see Setting Up Btrieve Security . The next section provides a brief overview of the material contained in the Setting Up Btrieve Security .

Summary of Tasks for Security Models

The following table illustrates the basic level of effort required using the different security models. For a more in depth view of the tasks required to migrate to the new security models, see Setting Up Btrieve Security .

Table 7-1 Summary of Security Set-up Tasks
Security Model
Authentication/Authorization
Summary of Behavior and High-Level Setup Tasks
Classic
Operating system/Operating system
  • Give users file permission access to all database files.
  • Add an owner name to Btrieve files to further limit access (optional)
Mixed
Operating system/Database
  • Note that this security model behaves the same as Classic when using the Workgroup engine.
  • Set up users in operating system. Users will be authenticated against this username and password.
  • If you want individual user security, set up like-named users in the database security using the Pervasive Control Center. Although authentication occurred at OS level, database permissions are stored in the database, so the operating system user name and database user name must match.
  • Alternatively, define a set of rights for the group PUBLIC. Each authenticated OS user will have the same rights as PUBLIC. No user can have rights defined that are lower than that of PUBLIC.
  • Define each user's database permissions using Pervasive Control Center or SQL statements.
Database
Database/Database
  • Operating system usernames and passwords are not relevant to the Pervasive.SQL database security, with the exception that the user must be able to log in to the computer.
  • Set up users using the Pervasive Control Center utility or SQL statements.
  • Define the database permissions using Pervasive Control Center or SQL statements.
  • Using the Pervasive Control Center Configuration tool, specify how authentication credentials are passed. This step refers to the new configuration parameters Prompt for Client Credentials and Allow Client-stored Credentials .

For complete information on transitioning from Classic to Mixed or Database security, see Setting Up Btrieve Security .

Available Models for SQL

SQL has always had only one model, which corresponds to the Database model for Btrieve.

Users and Groups

Pervasive security is based on the existence of a default user named "Master" who has full access to the database when security is first turned on. Initially, no password is required for the Master user.

Caution
If you turn on security, be sure to specify a password with a significant length, at least five characters but no more than eight. Do not leave the password field blank because doing so creates a major security risk for your database.

The Master user can create groups and other users and define sets of data access privileges for these groups and users.

If you want to grant the same level of access to all users and avoid having to set up individual groups and users, you can grant the desired level of access to PUBLIC. The default user PUBLIC represents any user connecting with or without a password.

Note
If you wish to use groups, you must set up the groups before creating users. You cannot add a user to a group after you have already created the user.

You can use the Users node in PCC to perform these tasks. You can also use GRANT and REVOKE statements in SQL to perform these tasks. Keep in mind that passwords are case sensitive.

See Pervasive.SQL User's Guide for information on performing these tasks within PCC.

Restrictions

  • A given user cannot be a member of more than one group.
  • All users in a group have exactly the permissions defined for that group. You cannot grant or revoke individual permissions for a user who is a member of a group.
  • Assigning a user to a group overrides and erases any individual permissions that were granted to the user beforehand.
  • You cannot add an existing user to a group. To do so, you must delete the user and re-create the user as a member of the group.
  • You cannot add a group to another group.

Owner Names

An owner name is a password required to gain access to a Btrieve file. There is no relation between an owner name and any system user name or relational database user name. You should think of an owner name as a simple file password.

For information on how to set or clear an owner name, see Setting or Clearing an Owner Name

You can use Maintenance Utility to set or clear an owner name on a file. An owner name can have several attributes, as shown in Table 7-2.
Table 7-2 Owner Name Options
Option | Description
Read-only | Without specifying the password, users can perform data access operations that do not modify the data file.
Read-only encrypted | Without specifying the password, users can perform data access operations that do not modify the data file. When you set this option, the database engine encrypts every record in the file using the owner name as a key. Records added later are also encrypted.
Normal | Without specifying the password, users cannot perform any file access operations.
Normal encrypted | Without specifying the password, users cannot perform any file access operations. Any records inserted or updated are encrypted using the password. When you set this option, the database engine encrypts every record in the file using the owner name as a key. Records added later are also encrypted.

Remarks

When you first set an owner name with encryption on a file, the database engine encrypts the entire file. The larger the file is, the longer this procedure takes.

For information about how owner names interact with relational security, see Owner Names and Security .

Data access operations to an encrypted file are slower than to a normal file. The database engine must decrypt each page as it reads it from disk, and encrypt it again before writing it back to disk.

Caution
Do not forget or lose a file's owner name, especially with encryption turned on. There is no way to find out the owner name, and no way to get access to the data without it.

If you attempt to access a file that has an owner name declared without supplying the owner name, you receive the message, "You are not authorized to perform the operation."

Owner Names and Security

If you have a Btrieve owner name set on a file that is a table in a secure database, the Master user of the database must use the owner name in any GRANT statement to grant privileges on the given table to any user, including the Master user.

After the GRANT statement containing the owner name has been issued for a given user, that user can access the specified table by logging into the database, without specifying the owner name each time.

If a user tries to access a table through ODBC that has a Btrieve owner name, the access will not be allowed unless the Master user has granted privileges on the table to the user, with the correct owner name in the GRANT statement.

If a table has an owner name with the Read-Only attribute, the Master user automatically has SELECT rights on this table without specifically granting himself/herself the SELECT rights with the owner name.

If no owner name is set on a data file, when relational security is enabled on that file, Btrieve access to the file is no longer permitted. You must set an owner name on that file in order to restore Btrieve access for those users who can supply the owner name when accessing the file. This behavior prevents default Btrieve users from circumventing relational security.

Examples

To grant himself/herself full access to a table with an owner name, the Master user must enter the following SQL statement:

GRANT ALL ON table-name owner-name TO Master

To grant SELECT rights on a table named mytable with an owner name of jim56, the Master user must enter the following SQL statement:

GRANT SELECT ON mytable jim56 to bob_smith

Extracting Security Information using SQL

While security information is displayed in PCC using the Users node shown under each named database, you can also obtain security information programmatically using SQL. The statements below show some examples of SQL statements that extract security information from a database. Note that you must login as the Master user or a user with rights to view the system tables.

SELECT "Xu$Name", "Xu$Id" FROM "X$User"

SELECT "X$File"."Xf$Id", MIN("X$File"."Xf$Name"), MIN("X$Rights"."Xr$Column")
    FROM "X$Rights", "X$File" WHERE "X$Rights"."Xr$User"=2 AND "X$Rights"."Xr$Table"="X$File"."Xf$Id"
    GROUP BY "X$File"."Xf$Id"

SELECT "Xr$Rights" FROM "X$Rights" WHERE "Xr$User"=2 AND "Xr$Table"=4 AND "Xr$Column"=0

The first statement lists all the user IDs and the user names associated with them.

The second statement lists the tables where the rights have been set for userID = 2. This restriction is shown in the WHERE clause.

The last statement shows you the table rights for a specific user ID. The segment, "Xr$User"=2, specifies the userID. The segment, "Xr$Table"=4, restricts the table ID to a valid value that was returned by the previous query. The restriction for "Xr$Column" is always set to 0.
Prev
Pervasive.SQL Security 		Up
Check for Revisions 		Next
Planning Your Security Scheme


Planning Your Security Scheme

After you install this product, the default behavior for security is the same as the previous release; that is, the database engine uses Classic or OS-based authentication and authorization. Any user with permission to access a given data file through the operating system will have the same level of permission to access the data records contained within the file, unless you are using Btrieve owner names to restrict access to the data files.

This section describes the steps you must follow to set up the default database, authorized users, and other aspects of the new Btrieve security policies.

Available Options

There are three security options available to you. The features of these options are described below to help you choose which is best for you. Encryption is optional in every configuration.
Table 7-3 Feature Comparison of Security Configurations
Feature | Classic | Mixed | Database
Administrator must set up separate OS and database user accounts for each user |  | ü | ü
Database user accounts are derived directly from OS user accounts | ü | ü |
Users' data access rights are unrelated to users' filesystem rights; administrator must assign data access privileges to each user |  | ü | ü
Users' data access rights are derived directly from OS users' filesystem rights | ü |  |
Supports automatic pop-up dialog for entering database user name and password from any Pervasive-based Windows application |  |  | ü
Database accepts successful OS login as valid database user | ü | ü |
User must log into database separately from logging into computer |  |  | ü

Under Database security, database user accounts are completely unrelated to OS user accounts.

In contrast, under Classic security, a user who succesfully logs into the computer has access to the database contents, at whatever level of filesystem rights that the user has been assigned to the file that contains the data.

Lastly, the Mixed security policy has aspects of both of the other policies. Under this scheme, users login using their OS user names and passwords, but then the users access rights to the data are governed by user permissions set up in the database.

Choosing Your Policy

This section describes some of the major reasons you might choose one security policy over another.

Reasons to Choose Classic

  • You are comfortable with your users having filesystem access to your data files. For example, any user with rights to delete records from the data file can also delete the entire file from your operating system. Note that some government regulations such as HIPAA specifically prohibit this kind of behavior. Consult your legal advisor for issues regarding compliance with government regulations.
  • You want the minimum administrative hassle; you don't want to set up both OS user accounts for each user and at least one database account (PUBLIC account defines permissions for all users).
  • You do not need to have a variety of data access rights that vary from each user's filesystem rights.
  • You don't want your users to have a separate login for the database.

Reasons to Choose Mixed

  • You don't want your users to have a separate login for the database.
  • You want to prevent valid database users from having any rights to the data files on the operating system. For example, you can prevent users who have all rights to in the database from having rights to delete data files from the operating system.
  • You are willing to set up database user accounts that have the same user names as OS user accounts, and you are willing to assign permissions to each database user. Or, all your users have the same level of permissions, and you can address their needs by assigning permissions to one database user account, PUBLIC.

Reasons to Choose Database

  • You want to have a separate login for the database. That is, after logging into the operating system, users must login again to the database. This behavior is useful when some authorized computer users are permitted access to the database and some are not.
  • You want to prevent valid database users from having any rights to the data files on the operating system. For example, you can prevent users who have all rights in the database from having rights to delete data files from the operating system. You can also achieve this goal using the Mixed security policy.
  • You want database user accounts that use different names than the operating system accounts. For example, operating system user "jsmith" might be required to login to the database as "john."

The Simplest Way to Secure your Data Files at the Operating System Level

If your primary concern is simply to implement a Btrieve security scheme such that your database users do not have rights to copy, overwrite, or delete the data files in the operating system, then this section describes an overview of what you need to do.

  1. Install Pervasive.SQL 8.5 database engine.

    As long as you do not use wire encryption, V8 clients are compatible with the V8.5 engine. You are not required to upgrade the clients.

  2. In PCC, use the Maintain Database Names utility to add the data file locations of your Btrieve files into the DefaultDB database.

    You do not need to enter every directory, just the highest level directory that is common to all data files.

  3. Enable security on DefaultDB using either the Database Properties dialog in PCC, or the SET SECURITY statement in SQL.
  4. When logged into DefaultDB as the Master user, grant rights to the PUBLIC user at the database level. For example, if you want to grant all rights to all authenticated users, you would use the statement: GRANT ALL ON "*" TO PUBLIC. This statement will give all users the same rights to the data.

    If you need to grant users varying rights, then you must create group accounts (if applicable) and individual user accounts using the GRANT statement in SQL or using the Users and Groups dialog in PCC.

  5. Use the Maintain Database Names dialog in PCC to set the Btrieve security policy for DefaultDB to Mixed.
  6. Secure the data files in the operating system according to your operating system instructions. You can now deny operating system users from having any rights to the data files, without affecting their ability to access the data through the database engine.

For step-by-step instructions for this procedure, see Btrieve Security Quick Start .

Before you Begin

Setting up Btrieve security is a simple process, but it affords enough flexibility that some preparation is necessary. This section describes the information you should know before you begin to set up Btrieve security.

How Many Databases?

For Mixed or Database security, you must either assign all users the same level of permissions, or create a set of defined users for each database.

In some cases where your Btrieve data files encompass two or more completely unrelated bodies of data, you may want to set up two or more separate databases, each with its own set of authorized users. Generally speaking, however, you want to minimize the number of separate databases so that you do not have to create and maintain multiple sets of defined users. Often, a single database is sufficient. User permissions within the database will allow you to regulate each user's access to the database, so you do not need to create separate databases just to limit certain users' access.

If you determine that you need only one database, you may use the pre-existing database, DefaultDB, as the database associated with your Btrieve files. You may also set up your own named database instead.

Where are the Data Files?

You associate a Btrieve data file with a database by specifying the directory containing the data file as a Data Directory for the given named database. Thus, you need to know the directories containing all the data files that you want to associate with the database. If all the data files reside in a sub-directory tree within a specific directory, all you need to know is the top-level directory pathname. You can even use "C:\" if you wish to include all data files on the hard drive.

What are the User Names?

If you plan to use Mixed security, you must either assign all users the same permissions, or set up user accounts for the users whose rights differ from the default (PUBLIC) permissions. If you are going to set up individual users, you must have a list of the operating system user names that you want to make into database user names. The database user names that you set up must match the operating system user names exactly. You can always add additional user names later, but it is more efficient to create several users at once.

What Security Policy?

Before you set up security, you must know what policy you plan to use. The setup process varies somewhat for each policy. Considerations in choosing a policy are presented in Choosing Your Policy .

Process Overview

This section outlines the high-level procedure used to set up security for a database. Detailed, step-by-step instructions are provided in the section that follows.

  1. Preparation. As specified above in Before you Begin, gather the information you need and make the decisions necessary to get started. How many databases? Where are the Btrieve files located? What are the user names? What security policy will you use?
  2. Select a database to use with your Btrieve files, and populate the database with the data directory specifying the location of your data files. This step is only necessary for Mixed or Database security.

    For details on this step, see To use an existing database, including the pre-defined DefaultDB, with your Btrieve files , or To create a new database for use with your Btrieve files

  3. Turn on security. On the Database Properties dialog, enter a Master user password to enable security.

    For details on this step, see To turn security on for a Database .

  4. Create users and permissions. Using SQL statements or the Groups and Users dialog in PCC, create your user accounts and/or relevant user privileges. This step is only necessary for Mixed or Database security.

    For the fastest, easiest way to grant users access, see To grant the same rights to all users .

  5. Using the Maintain Named Databases dialog, set the Btrieve Security policy for your database to Mixed or Database. Then restart the database engine.

    For details on this step, see To change the security policy for a database .

  6. Secure the data files in the operating system. Users now can access the data without having any rights to access the data files in the operating system. Refer to your operating system documentation for information on securing access to files.
Prev
Security Models and Concepts 		Up
Check for Revisions 		Next
Btrieve Security Quick Start


Btrieve Security Quick Start

This section provides step-by-step instructions on the fastest, easiest way to secure your Btrieve data files in the operating system while still allowing database users to access the data.

When this procedure is complete, you can revoke operating system user rights to the data files without affecting database user rights to access the data through an application.

Note
You must be logged into the computer where the database engine is installed, as an operating system user with administrative rights or as a user who is a member of the Pervasive_Admin security group.

  1. Start Pervasive Control Center (PCC). If you need instructions on starting PCC, see To start Pervasive Control Center .
  2. If the database engine you wish to work with is not registered with PCC, register it now. If you need instructions on how to register a database engine with PCC, see Pervasive.SQL User's Guide.
  3. In PCC, double-click the database engine you wish to work with. Then right-click the Configuration folder underneath the database engine name, and choose Maintain Named Databases.
  4. In the Maintain Named Databases dialog, click on the DefaultDB database to select it. Then click the plus button [image] . Now, in the space provided, enter or select a directory containing your Btrieve files. If your files are spread over many directories, specify a high-level directory that they all have in common. You can specify C:\ if necessary, but realize that doing so will include all Btrieve files on the C:\ drive in DefaultDB. When finished, click OK.

    You do not need to enter every directory, just the lowest level directory that is common to all Btrieve files you want to include in the database.

  5. Now you must enable security on DefaultDB. You can perform this task by issuing a SQL statement or using either the Database Properties dialog in PCC.

    To use the Database Properties dialog, right-click on DefaultDB in the left-hand pane of PCC. From the drop-down menu, choose Properties. In the dialog that appears, click on the Security tab. Enter the password that you wish to use for the Master user, twice as prompted. Click OK.

    To turn on security using a SQL statement, issue the following statement within an ODBC client application (you cannot use SQL Data Manager):

    SET SECURITY = password

    where password is the password you choose for the Master user.

    Now security is turned on, but access is based on OS user rights by default, so your users currently have the same access that they had before. The next step will address this situation.

  6. In SQL Data Manager, grant rights to the PUBLIC user at the database level. For example, if you want to grant read-only rights to all authenticated users, you would use the statement: GRANT SELECT ON * TO PUBLIC. This statement will give all users read-only rights to the data. To give all users read and write access to the data, use the statement: GRANT ALL ON * TO PUBLIC.

    If you need to grant individual users varying rights, then you must create group accounts (if desired) and individual user accounts using the GRANT statement in SQL or using the Users and Groups dialog in PCC. For information on creating groups and users, see Advanced Operations Guide.

  7. Now, return to the left-hand pane of PCC, right-click on Configuration for the database engine you are working with, and choose Maintain Named Databases.

    In the Maintain Named Databases dialog, click on the DefaultDB database to select it. Click on the Btrieve Security policy drop down list and change the value to Mixed. Click OK.

     Caution
    Do not change the Btrieve Security Policy setting until you have completed step 6 as instructed. If you have not created user accounts or granted rights to PUBLIC, changing the security policy will prevent all your users from accessing the data.

    You have now granted login access only to those users who are authenticated by the operating system, and you have specified that the access rights of those users are defined by the permissions you granted to them in the database.

  8. Restart the database engine.

    On NetWare, reboot the server. On Windows server, stop and restart the Pervasive.SQL services. For Workgroup engine, right-click the tray icon and stop the engine, then restart it.

  9. Secure the data files in the operating system according to your operating system instructions. You can now deny operating system users from having any rights to the data files, without affecting their ability to access the data through the database engine.

    Caution
    Be sure to secure the data files in the operating system. If you do not perform this step, the users still can access the files through the operating system with the same level of permissions that they had prior to this procedure. You must revoke the users' operating system privileges to the data files if you want to prevent users from being able to delete or modify the files directly.

Prev
Planning Your Security Scheme 		Up
Check for Revisions 		Next
Security Tasks


Security Tasks

This section explains the basic concepts of Pervasive.SQL security. It is divided into the following topics:

General Tasks

  • To start Pervasive Control Center
  • To log into a database using PCC when you are already logged into that database as another user

Securing a Database Tasks

  • To secure a database using PCC
  • To secure a database using SQL statements
  • To turn security on for a Database
  • To turn security off for a Database

Btrieve Security Policy Tasks

  • To change the security policy for a database
  • To create a new database for use with your Btrieve files
  • To use an existing database, including the pre-defined DefaultDB, with your Btrieve files

User and Group Tasks

  • To create a new user with SQL statements
  • To create a new user with PCC and assign permissions

Assigning Permissions Tasks

  • To assign a user table privilege using SQL statements
  • To assign default permissions for a specific user
  • To assign default permissions for all users
  • To grant the same rights to all users

For encryption tasks, see Data Encryption .

General Tasks

To start Pervasive Control Center

  1. Click Start and select Programs 4 Pervasive.SQL 4 Control Center.
  2. In the left-hand pane of PCC, double-click Pervasive.SQL Engines. In the list of database engines that appears, locate the database engine you wish to access.

Note
If you do not see the database engine you wish to access, you must register it with PCC. To do so, click the Action menu and choose Register New Engine. In the dialog that appears, specify or choose the computer where the desired database engine is located. Click OK when you are finished.

  3. Double-click the icon representing the database engine you wish to access. Continue by selecting one of the procedures detailed below.

To log into a database using PCC when you are already logged into that database as another user

Note
As the Master user, logging in as another user can aid you in testing the more restrictive permissions you have assigned this user.

  1. Click on the machine name in the PCC namespace
  2. Click the F5 button (Refresh). This clears all open connections.
  3. Select the database again and you will be prompted to log in.

Securing a Database Tasks

When turning security on or off, the Master user must have only one connection open and must be the only user connected.

As soon as you turn security on for the first time, only the Master user can access the database. The Master user password, as with all Pervasive.SQL passwords, is case sensitive.

A database can be secured in one of two ways

  • To secure a database using PCC
  • To secure a database using SQL statements
  • To turn security on for a Database
  • To turn security off for a Database

To secure a database using PCC

  • In Pervasive Control Center (PCC), right-click on the database, select Properties, then click on the Security tab. Enter and confirm the password for the Master user in the boxes provided. When you click OK or Apply, security is enabled. For detailed instructions on this procedure, see Pervasive.SQL User's Guide.
For information about how Btrieve owner names interact with relational security, see Owner Names and Security .

To secure a database using SQL statements

  • From an ODBC application connected to the database, issue the SQL statement SET SECURITY= 'password' where password is the text string you want to use as the password for the Master user. For more information on SET SECURITY, refer to SQL Engine Reference.

Note
You cannot use SQL Data Manager in PCC to issue a SET SECURITY statement. Attempting to do so generates an error because both SQL Data Manager and PCC keep an open connection to the database.

To turn security on for a Database

This procedure explains how to turn security on for a given database. You must be logged into the computer as an administrator or as a member of the Pervasive_Admin operating system security group.

Caution
Turning on security will prevent all users from accessing the database unless they login to it using a valid database username and password. Usernames and passwords cannot be set up until security is turned on, so the database will be inaccessible to each user for the period of time until you have set up a user account for that user.

  1. In PCC, right-click on the database you wish to secure, and choose Properties.
  2. In the dialog that appears, click on the Security tab. Enter the password you wish to use for the Master user, and enter it again to confirm. Click OK.
  3. The database is now secure, and you are logged in as the Master user.

    For instructions on creating database user accounts, see User and Group Tasks .

To turn security off for a Database

This procedure explains how to turn security off for a given database. To turn security off, you must be logged into the database as the Master user.

Caution
Turning off security will allow all operating system users to access the database. Turning off security also erases all database user accounts and privileges. If you turn security back on, you must re-create all users and privileges.

  1. In PCC, right-click on the database you wish to make unsecure, and choose Properties.
  2. In the dialog that appears, click on the Security tab. Click the check box labeled Disable security. Click OK. The database no longer enforces security.

Btrieve Security Policy Tasks

To change the security policy for a database

This section describes how to change the security policy for a given database.

Caution
Changing security policy for a database may prevent current users from accessing the database, if security is turned on and the given users do not have equivalent user accounts and rights under the new security policy.

  1. Within PCC, locate the database engine you wish to access. If you do not see an icon named Configuration under your selected database engine, double-click on that database engine to explose the Configuration icon.
  2. Right-click on Configuration and select Maintain Named Databases. Optionally, you may click on Configuration and then click the Action menu and select Maintain Named Databases. You will see the dialog shown in Figure 7-1.

    Click on the database for which you wish to change the security policy, such as DefaultDB.

Figure 7-1 Maintain Named Databases - Changing Security Policy

  3. In the Security Policy box, choose which security policy you wish to use (Mixed or Database). Then click OK.

    Caution
    If your database has security turned on and you change from Classic security policy to Mixed or Database, all users are prevented from accessing the database until you create database user accounts and privileges for them.

  4. If you are prompted to confirm your changes, click OK again.
  5. Restart the database engine for these changes to take effect.

To create a new database for use with your Btrieve files

  1. From the Action menu of PCC, choose New Database.
  2. The Create Database Wizard appears, as shown in Figure 7-2. Enter a name for the database, specify a location for the database definitions, and check Use Advanced Settings. Click Next.

Figure 7-2 Create Database Wizard

  3. In the next screen, shown in Figure 7-3, keep the default values shown unless you are certain you require different values. Click the Create button.

Figure 7-3 Specify DSN Attributes

  4. In the next screen, shown in Figure 7-4, click the plus button [image] . In the dialog that appears, enter or select a directory containing your Btrieve files. If all your files are in sub-directories under one particular directory, you need only add that one top-level directory. Otherwise, repeat this step for each directory you need to add until you have added all the directories containing Btrieve files.

    Caution
    You may be tempted to choose your new Security Policy now, but do not—you will lock out all your users until you define their database rights. You must come back and choose your security policy in a later step, after you have granted database rights to the users.

Figure 7-4 Data File Locations

  5. You should now be back in the screen shown in Figure 7-3. Click Next to display the confirmation screen.
  6. In the confirmation screen, review the information and click Finish, or click Back to change your inputs.

    Now you are ready to turn on security, as detailed in To turn security on for a Database .

To use an existing database, including the pre-defined DefaultDB, with your Btrieve files

  1. Within PCC, locate the database engine you wish to access. If you do not see an icon named Configuration under your selected database engine, double-click on that database engine to explose the Configuration icon.
  2. Right-click on Configuration and select Maintain Named Databases. Optionally, you may click on Configuration and then click the Action menu and select Maintain Named Databases. You will see the dialog shown in Figure 7-5.

    Click on the database you wish to use with your Btrieve files, such as DefaultDB.

Figure 7-5 Maintain Named Databases

  3. Click the Add Data File Location button, circled in Figure 7-5. Enter or select a directory containing your Btrieve files. If all your files are in sub-directories under one particular directory, you need only add that one top-level directory. Otherwise, repeat this step for each directory you need to add until you have added all the directories containing Btrieve files.

    Caution
    You may be tempted to choose your new Security Policy now, but do not—you will lock out all your users until you define their database rights. You must come back and choose your security policy in a later step, after you have granted database rights to the users.

  4. If you are prompted to confirm your changes, click OK again.

    Now you are ready to turn on security, as detailed in To turn security on for a Database .

User and Group Tasks

To create a new user with SQL statements

  1. In PCC, right-click on the database you wish to work with. From the pop-up menu, select Tasks 4 Execute SQL Query to open SQL Data Manager (SQL DM).
  2. In SQL DM (or your selected SQL interface, such as ODBC Test), enter the following query and run it:

    GRANT LOGIN TO myuser mypass

    where myuser is the user name you wish to create, and mypass is the password for that user. For example, to create the user 'john' with password 'jb456', you would enter the following syntax:

    GRANT LOGIN TO john jb456

    You have now created a new database user account. To assign privileges for this user, see Assigning Permissions Tasks .

To create a new user with PCC and assign permissions

  1. Log into your secure database as the Master user.
  2. Right-click on the Users node for a database.
  3. Select New User

Figure 7-6 Creating a New Database User With PCC

  4. If you want this new user to inherit the permissions from a group instead of having individual permissions, you should first define a group. You cannot add a user to a group other than at the time of the user's creation. If you do not assign a group, this new user still inherits the permissions of the PUBLIC group. No user can have permissions that are lower than PUBLIC. Select the checkbox that corresponds to the group and click OK.

Figure 7-7 Entering a New User

  5. If you want the user to have individual permissions, click the Permissions tab when you see Figure 7-7 and specify individual permissions by selecting the checkbox next to the database or table right you want to add.

Figure 7-8 Assigning a User's Permissions

The Database Rights section grants that right to all tables in the database. The lower part of the dialog allows you to specify rights specifically by table. In the example shown in Figure 7-8, the user Joe has Update rights to all the tables, and Insert rights to only the Customer and Employees tables.

The following SQL statements would produce the same results as the selections in Figure 7-8:

GRANT Update on * to Joe#

GRANT Insert on Customers to Joe#

GRANT Insert on Employees to Joe#

  6. It is also important to note that Joe could also inherit rights from the default group PUBLIC that you could not see in Figure 7-8. To see all of a user's potential rights, you need to look at both the user's properties and that of PUBLIC.

Figure 7-9 Rights Assigned to PUBLIC Group

In this case, PUBLIC also has Select rights to all tables, so user 'Joe' has Select and Update rights on all tables, based on his combined individual and PUBLIC rights.

Assigning Permissions Tasks

To assign a user table privilege using SQL statements

  1. In SQL DM or your selected SQL interface, enter the following statement to assign privileges for an existing user:
  2. GRANT privilege ON table to user

To assign default permissions for a specific user

  1. Create a user as described in To create a new user with PCC and assign permissions but do not assign any specific permissions.
  2. The permissions assigned to the group PUBLIC will be enforced for the user.

To assign default permissions for all users

  1. Using PCC, Click the Users node for the secure database.
  2. Right-click PUBLIC and select Properties.
  3. Click the Permissions tab.
  4. Assign the database or table permissions for PUBLIC using the checkboxes as shown in Figure 7-9 . Any right that is not checked is not granted to default new users.

To grant the same rights to all users

To avoid setting up and maintaining individual user accounts, one approach to configuring Btrieve security is to grant the same rights to all authorized users. You must be logged in as Master to perform this procedure.

  1. In PCC, right-click on the database you want to work with (usually DefaultDB). From the pop-up menu, choose Tasks 4 Execute SQL Query to start up SQL Data Manager.

    If prompted to login, enter the user name Master and the master password you created when you turned on security.

  2. In the SQL Data Manager window that appears, enter the following SQL statement:
    To grant this right to all users....
    ... use this syntax:
    read-only
    GRANT SELECT ON * TO PUBLIC
    update-only
    GRANT UPDATE ON * TO PUBLIC
    delete-only
    GRANT DELETE ON * TO PUBLIC
    insert-only
    GRANT INSERT ON * TO PUBLIC
    all of the above
    GRANT ALL ON * TO PUBLIC

    Rights are additive, so you can specify a combination of rights by issuing more than one statement. For example, if you want all users to be able to read and update records only, then you can issue two statements: GRANT SELECT ON * TO PUBLIC and GRANT UPDATE ON * TO PUBLIC.

    These rights are effective immediately upon execution of the statement.

Note
If you are in the process of securing your Btrieve files, you must now change your Btrieve Security policy. For instructions on how to perform this task, see To change the security policy for a database .

Prev
Btrieve Security Quick Start 		Up
Check for Revisions 		Next
Data Encryption


Data Encryption

This release support encrypting the database-related network traffic that occurs when using Pervasive.SQL. This type of encryption is often called wire encryption because it protects the data when it is traveling on the network wire, or on any intervening network infrastructure, including wireless. While the use of wire encryption is not required, it provides additional deterrence against unauthorized access to the data transmitted by your application over a network.

This encryption feature is not directly related to the new security models available in this release. Any of the security models can be used with or without wire encryption turned on.

Configuration Parameters for Wire Encryption

There are two configuration parameters associated with this feature. These parameters must be set at each client machine as well as the server. Within Configuration, they can be located under Server 4 Access. Each machine shares a server and client setting for this feature under the Server setting.

For more information on these settings, see

  • Wire Encryption
  • Wire Encryption Level

Encryption Notes

This release of the product uses a well-known and time-tested public domain encryption algorithm called "Blowfish" to perform the encryption before data passes over the network.

Encryption using a 40-bit key provides the least amount of protection for the data. Encryption using a 56-bit key is more difficult to compromise. Finally, encryption using the 128-bit key is the generally considered very difficult to compromise.

Note
Using encryption slows the network throughput of your data.

Backward Compatibility

Because previous versions of Pervasive.SQL did not support wire encryption, they will be unable to communicate with a client or server from this release that requires encryption. Any client or server that does not support encryption will return an error if it attempts to connect to a client or server that requires encryption.

Setting Up Encryption

Before turning on the encryption settings in your environment, think about your encryption needs first. You can set up your encryption environment in a variety of ways, depending on your situation. There are four general schemes possible:

  • no encryption
  • all communications encrypted
  • encryption to/from specific clients
  • encryption to/from specific servers

No Encryption

First of all, consider whether your data has characteristics that would favor encryption. Is your data confidential or proprietary? Is it protected from the public by federal, state, or local laws? Is it valuable in the hands of unauthorized users? Can it be used to harm your organization? If you answer no to these question and others like them, then your data may not need to be encrypted at all. Under these circumstances, there may be no reason to incur the performance trade-off that encryption entails. If you aren't sure, consult a data security expert.

Assuming your data does need to be protected, you still may not need encryption. If your applications run solely on a LAN, and you are comfortable with the physical security of your network infrastructure, encryption may not be necessary.

Encryption to/from Specific Clients

Now suppose that you have one major customer at a remote site that has a connection to your database. You may wish to use encryption only for the communications that go to/from that remote client. You can achieve this affect by setting Wire Encryption at the remote client to Always and setting the server values accessed by that remote client to If Needed. All your internal clients would be set to Never. Thus, the servers will only use encryption when communicating with the remote client that requires encryption.

Encryption to/from Specific Servers

Now, suppose the situation is reversed and your environment includes one or more remote servers that are accessed by network infrastructure that you do not trust 100%. In this case, you can set those server values to Always, and set the local client values to If Needed. The result is encrypted communications only to those remote servers that require it.

All Communications Encrypted

Finally, if your Pervasive-based applications often run over WAN, VPN, or other external networks that you do not trust 100%, then you may wish to encrypt 100% of your database communications. In this scenario, you would set Wire Encryption to Always at all clients and servers.

Choosing an Encryption Level

Once you have decided which clients and servers require encrypted communications, you must decide what level of deterrence is appropriate for your needs.

While Pervasive Software Inc. cannot offer advice regarding the encryption level that meets your specific needs, we can provide some guidelines to help inform your discussions with an appropriate data security expert. These guidelines do not represent a guarantee or warranty from Pervasive that no third party will be able to intercept and/or decode your encrypted data. As with any encryption scheme, there is no such thing as an "unbreakable" code, only varying levels of difficulty to compromise different types of encryption. Pervasive.SQL's 128-bit encryption would be considered "very difficult" to decode using techniques and equipment available to a highly sophisticated individual hacker.

Low (40-bit) Encryption

Consider using this level of encryption in cases where your data has limited ability to harm your organization or your customers if it falls into the wrong hands. Another reason to consider a Low level of encryption is if you wish simply to prevent a casual observer on your network from being able to read your data as it travels over the wires.

Medium (56-bit) Encryption

Consider using this level of encryption in situations where you believe you need somewhat more protection than against just a casual observer, but you do not believe you require the strongest level of security.

High (128-bit) Encryption

Consider using this level of encryption in situations where your data contains very sensitive information such as credit card numbers, social security numbers, financial account numbers, or other information protected by law. Especially consider this level of encryption if your database is associated with an entity on the network that is well-known to contain sensitive data, such as an Internet shopping web site or an online securities brokerage web site. Consider this level of encryption if your organization has previously suffered attempts to compromise its data security.

Effects of Encryption

Using encryption reduces client/server performance. With encryption turned on, each piece of data must be encoded at the source and decoded at the destination. This process requires additional CPU cycles when compared to the same operations performed without encryption. The level of encryption should not affect the performance. The performance drop in using encryption is roughly the same no matter which of the three encryption levels you choose.

Owner Name Encryption

Pervasive.SQL offers encryption of data files on disk. To require that your data files be encrypted when written to disk, you must set an owner name on each file.

See Owner Names for more information.

Prev
Security Tasks 		Up
Check for Revisions 		Next
Logging, Backup, and Restore


Logging, Backup, and Restore

Understanding Logs, Backups, and Data Restoration

Pervasive.SQL V8 provides several powerful features to ensure data integrity and to support online backups and disaster recovery.

  • Transaction Logging and Durability
  • Understanding Archival Logging and Continuous Operations
  • Using Archival Logging
  • Using Continuous Operations
Prev
Data Encryption
Check for Revisions 		Next
Transaction Logging and Durability


Transaction Logging and Durability

Pervasive.SQL offers two levels of data integrity assurance for database operations that involve transactions: Transaction Logging and Transaction Durability.

This section contains the following sub-topics:

  • Using These Features
  • Feature Comparison
  • Which Feature Should I Use?
  • How Logging Works
  • See Also

Using These Features

Both of these features can be turned on or off in the database engine using the Configuration utility within Pervasive Control Center, or programmatically using the Distributed Tuning Interface.

The default value for Transaction Durability is Off, and the default value for Transaction Logging is On.

Feature Comparison

Both features offer multi-file transaction atomicity, to ensure that the data files remain consistent as a set and that incomplete transactions are never written to any data files.

Atomicity means that, if any given data operation within a transaction cannot successfully complete, then none of the operations within the transaction are allowed to complete. An atomic change does not leave partial or ambiguous effects in the database. Changes to individual files are always atomic whether Transaction Logging and Transaction Durability are on or off. But transactions make it possible to group changes to multiple files into one atomic group. The atomicity of these multi-file transactions are assured by the MicroKernel only when using transactions in your application, and Transaction Logging or Transaction Durability is turned on.

In addition to these benefits, Transaction Durability guarantees that, in the event of a system crash, the data files will contain the full results of any transaction that returned a successful completion status code to the application prior to the crash.

In the interest of higher performance, Transaction Logging does not offer this guarantee. Whereas Transaction Durability ensures that a completed transaction is fully written to the transaction log before the engine returns a successful status code, Transaction Logging returns a successful status code as soon as the logger thread has been signaled to flush the log buffer to disk.

Transaction Logging is a sub-set of Transaction Durability; that is, if Transaction Durability is turned on, then logging takes place and the Transaction Logging setting is ignored by the database engine.

The main differences between Transaction Logging and Transaction Durability are shown in the tables below:
Table 8-1 Transaction Logging vs. Transaction Durability: Benefits
Feature | Guaranteed data consistency and transaction atomicity across multiple files | Guaranteed commit for all completed transactions that have returned a successful status code
Transaction Logging | Yes | No
Transaction Durability | Yes | Yes
Table 8-2 Transaction Logging vs. Transaction Durability: Function
Feature | Timing of log buffer writes to disk
Transaction Logging | The log buffer is written to the log file when the log buffer is full or Initiation Time Limit is reached. A successful status code for each End Transaction operation is returned to the application as soon as the logger thread has been signaled to flush the buffer to disk.
Transaction Durability | The log buffer is written to the transaction log file with each End Transaction operation. A successful status code for each End Transaction operation is not returned to application until the log disk write is successful. For insert or update operations that are not part of a transaction, the log buffer is written to the log file when the log buffer is full or Initiation Time Limit is reached.

Which Feature Should I Use?

For the fastest performance, you want to use the lowest level of logging that meets your transaction safety needs. The best way to determine your appropriate level of logging is to ask your application vendor. If you have multiple applications that use Pervasive.SQL on the same computer, you must use the highest level of logging required by any of the applications.

If you only have one data file, or if none of your applications perform transactions involving multiple data files, you generally do not need to use Transaction Durability or Transaction Logging. Under these circumstances, Pervasive.SQL guarantees the internal consistency of each data file, with or without logging.

Transaction Logging

Turn on Transaction Logging if at least one of your Pervasive.SQL applications performs transactions across multiple data files. Without Transaction Logging, Pervasive.SQL cannot guarantee multi-file atomicity of transactions or multi-file data integrity.

In the event of a system crash, this level of logging does not guarantee that every completed transaction has been written to the data files.

Transaction Durability

Turn on Transaction Durability if at least one of your Pervasive.SQL applications requires that completed transactions across multiple data files be absolutely guaranteed to have been written to the data files under almost any circumstances.

In the event of a system crash, this level of logging guarantees that every transaction that has been successfully completed has been written to the data files.

How Logging Works

Note that these features ensure atomicity of transactions, not of operations. If you are using SQL, a transaction is defined as a set of operations that take place between a BEGIN statement or START TRANSACTION statement, and an END or COMMIT statement. If you are using Btrieve, a transaction is defined as a set of operations that take place between a Start Transaction operation and an End Transaction operation.

All data file inserts and updates are stored in the log buffer. When a transaction is completed (Transaction Durability) or when the buffer gets full or the Initiation Time Limit is reached (Transaction Durability or Transaction Logging), the buffer is flushed to the transaction log file.

In the case of Transaction Logging, when the engine receives the operation ending the transaction and successfully signals the logger thread to flush the log buffer to disk, the engine returns a successful status code to the application that initiated the transaction. In the case of Transaction Durability, the engine does not return the successful status code until the logger thread signals that is has successfully written the buffer to disk.

Transaction log file segments are stored in the location specified in the setting Transaction Log Directory . The log segments are named *.LOG, where the prefix can be 00000001 through FFFFFFFF.

Note
All operations, regardless of whether they take place within a transaction, are written to the log file when Transaction Logging or Transaction Durability is in effect. However, only operations executed within a transaction are guaranteed to be atomic. In the case where a system crash has occurred and the transaction log is being rolled forward, only completed transactions are committed to the data files. All operations without an associated End Transaction operation are rejected, and are not committed to the data files.

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.

You can specify the location of the transaction logs using the configuration setting Server 4 Directories 4 Transaction Log Directory.

If a system failure occurs after the log file has been written but before the "committed" operations are flushed to the data files in a system transaction, the "committed" operations are not lost. When the database engine starts up again after the system failure, it reads the log segments and flushes any "committed" operations to the data files. Log segments are deleted only after the operations are flushed to the data files.

This feature allows individual client transactions to receive a successful status code as soon as possible while at the same time taking advantage of performance gains offered by grouping multiple client transactions together and writing them to the data files sequentially.

If your database server suffers a disk crash of the volume where the data files are stored, and you have to restore the data from an archival log, the engine does not roll forward the transaction log file. The archival log contains all the operations in the transaction log, so there is no need to roll forward the transaction log.

See Also

For further information, see:

Transaction Durability

Transaction Logging

Transaction Log Directory

Prev
Logging, Backup, and Restore 		Up
Check for Revisions 		Next
Understanding Archival Logging and Continuous Operations


Understanding Archival Logging and Continuous Operations

The product offers two mutually exclusive features to support online backups and disaster recovery.
If your situation is like this ... | ... use this feature:
You must keep your database applications running while performing backups. | Continuous operations
You are able to shut down the database engine to perform backups | Archival logging

Archival Logging allows you to keep a log of database operations since your last backup. In case of a system failure, you can restore the data files from backup then roll forward the changes from the log file to return the system to the state it was in prior to the system failure.

Caution
Archival logging does not guarantee that all your data files will be in a consistent state after restoring from an archival log. In the interest of speed, the database engine does not wait for a successful status code from the logging function before emptying the log buffer. Thus, in rare circumstances such as a full disk or a write error in the operating system, updates that were successful in the data files may not be recorded in the archival log. In addition, archival logging does not require you to log all of your files, so a transaction that updates more than one file may not be completely recorded in the archival log if you are only archival logging some of those files. As a result, one file may not be consistent with another. If you use transactions and require multi-file transaction atomicity, see Transaction Logging and Durability .

Continuous Operations allows you to backup database files while the database engine is running and users are connected. After starting Continuous Operations, the database engine closes the active data files and stores all changes in temporary data files (called delta files). While Continuous Operations are in effect, you perform a backup of the data files. The delta files record any changes made to the data files while the backup is taking place. When the backup is complete, you turn off Continuous Operations. The database engine then reads the delta file and applies all the changes to the original data files. The temporary delta file may surpass the size of the original data file if users make extensive changes to the file during continuous operation.

Note
Archival Logging and Continuous Operations are mutually exclusive features and cannot be used at the same time.

Difference Between Archival Logging and Transaction Logging

Transaction Logging is another feature designed to protect the integrity of your data in the event of a system failure, but it is not directly related to Archival Logging. You can have Transaction Logging in effect at the same time as either Archival Logging or Continuous Operations. Transaction Logging uses a short-term log file to ensure that transactions are safely written to disk. The transaction log is reset frequently as completed client transactions are rolled into the physical data files by way of system transactions. In the event of a system failure, when the database engine starts up again, it reads the transaction log and flushes to the data files the transactions that were completed prior to the system failure.

The archival log is written to at the conclusion of each system transaction, so the archival log and the transaction log should remain properly synchronized unless a system failure occurs exactly during the system transaction.

For more information on Transaction Logging, see Transaction Logging and Durability .

What if a File Restore is Needed

In the event of a system crash that requires restoring data files from backup, Archival Logging allows you to restore from backup and then recover database activity up to the moment of the crash.

If you experience a similar crash without Archival Logging (for example if you use Continuous Operations to perform backups), then you will not be able to recover database activity that took place between the last backup and the system crash.
Table 8-3 Data Restore Limits After Crash
If Archival Logging is ... | ... this much data will be unrecoverable after a crash:
On | Unfinished transactions at the moment of failure.
Off | All database operations that have occurred after the last backup of the data files.

The remainder of this chapter describes the options and procedures associated with Archival Logging and Continuous Operations.

Prev
Transaction Logging and Durability 		Up
Check for Revisions 		Next
Using Archival Logging


Using Archival Logging

This section explains the procedures you must follow to set up Archival Logging, make backups, and restore data files. It is divided into the following sub-topics:

  • General Procedures
  • Setting up Archival Logging
  • Roll Forward Command

General Procedures

For Archival Logging to work properly, you must follow a clearly defined procedure to set it up, and another procedure in the event that a restore from backup is necessary.

Caution
If any steps of the procedures are omitted or compromised, you may not be able to restore your data to its pre-crash state.

To use Archival Logging properly

  1. Turn on Archival Logging, if it is not already in effect. See Setting up Archival Logging for the detailed set-up procedure.
  2. Shut down the database engine.
  3. Backup the data files.
  4. After a successful backup, delete all existing archival logs.

    Caution
    Delete the corresponding log files before you resume working with the data files. Synchronizing the backup data files and the corresponding log files is a critical factor of successful recovery.

  5. Restart the database engine.

To restore data files from backup and apply changes from the archival logs

Note
You cannot use this procedure to roll forward the archival logs if you experienced a hard disk crash and your archival logs and data files were both located on the lost hard disk.

  1. When the computer re-starts after the system failure, ensure that the database engine is not running, and ensure no other database engine is accessing the data files you wish to restore.
  2. Restore the data files from backup.
  3. Start the database engine, ensuring that no applications of any kind are connected to the engine.

    Caution
    It is crucial that no database access occurs before the archival logs have been applied to the data files. Make sure no other database engine accesses the files. You must roll forward the archival logs using the same engine that encountered the system failure.

  4. Issue the Roll Forward command as described in Roll Forward Command .
  5. After the Roll Forward completes successfully, stop the database engine and make a new backup of the data files.
  6. After you have successfully backed up the data files, delete the archival log files. You may now re-start the database engine and allow applications to access the data files.

Setting up Archival Logging

Setting up Archival Logging requires two steps:

  • turning on the Archival Logging feature
  • specifying the files to archive and their respective log files

Note
To perform these procedures, you must have full administrative permissions on the machine where the database engine is running or be a member of the Pervasive_Admin group on the machine where the database engine is running.

To turn on Archival Logging

  1. Start up PCC. Click Start and choose Programs 4 Pervasive.SQL V8 4 Control Center.
  2. Double-click Pervasive.SQL Engines. Double-click the engine icon representing the target database engine.

    If you don't see the engine you want to work with, see Pervasive.SQL User's Guide for information on how to register a remote server engine.

  3. Double-click Configuration. Double-click Server. Click Data Integrity.
  4. Right-click Archival Logging Selected Files. From the pop-up menu, click Properties. In the dialog box that appears, click On.
  5. Click OK.

To specify files to archive

You specify the files for which you want the MicroKernel to perform Archival Logging by adding entries to an archival log configuration file you create on the volume that contains the files. To set up the configuration file, follow these steps:

  1. Create the directory \BLOG in a real root directory of the physical drive that contains data files you want to log. (That is, do not use a mapped root directory.) If your files are on multiple volumes, create a \BLOG directory on each volume.

    For example, if you have data files located on C:\ and D:\, and both drives are physical drives located on the same computer as the database engine, then you would create two BLOG directories, as below:

    C:\BLOG\
D:\BLOG\

Note
On Linux, the log directory must be named blog and must be created in the directory specified by the PVSW_ROOT environment variable (by default, /usr/local/psql).

  2. In each \BLOG directory, create an empty BLOG.CFG file. You can use any text editor, such as NotePad, to create the BLOG.CFG file. On Linux, the file must be named blog.cfg (lowercase).
  3. In each BLOG.CFG file, create entries for the data files on that drive for which you want to perform Archival Logging. Use the following format to create each entry:
    \path1\dataFile1[=\path2\logFile1]

path1 | The path to the data file to be logged. The path cannot include a drive letter.
dataFile1 | The name of the data file to be logged.
path2 | The path to the log file. Because the log file and the data file can be on different drives, the path can include a drive letter.
logFile1 | The name of the log file. If you do not specify a name, the default value is the same directory and file name prefix as the data file, but replace the file name suffix with ".log". You may specify a different physical drive, so that the log and the data files are not on the same drive. Each data file being logged requires a different log file.

A single entry cannot contain spaces and must fit completely on one line. Each line can contain up to 256 characters. If you have room, you can place multiple entries on the same line. Entries must be separated by white space. You must terminate the end of the line with a Return character.

 Caution
You must use a different log file for every data file that you wish to log. If you use the same log file for more than one data file, the MicroKernel cannot use that log file in the event that a roll-forward is needed.

If you do not provide a name for a log file, the MicroKernel assigns the original file name plus a.LOG extension to the log file when you first open it. For example, for the file B.BTR, the MicroKernel assigns the name B.LOG to the log file.

 Caution
You are not required to log every file in your database. However, if your database has referential integrity (RI) rules defined, you must log all or none of the files involved in each RI relationship. If you log only a sub-set of the files involved in a given RI relationship, rolling the archival logs forward after a system crash may result in violations of your RI rules.

Examples

The following examples show three sample entries in the BLOG.CFG file on drive C. All three entries produce the same result: activity in the file C:\DATA\B.BTI is logged to the file C:\DATA\B.LOG.

\data\b.bti
\data\b.bti=\data\b.log
\data\b.bti=c:\data\b.log

The next example directs the engine to log activity in the file C:\DATA\B.BTI to the log file D:\DATA\B.LGF. This example shows that archival log files do not have to reside on the same drive as the data file and do not require the .LOG extension. (The .LOG extension is the default.)

\data\b.bti=d:\data\b.lgf

Tip
Writing the log to a different physical drive on the same computer is recommended. If you experience a hard disk crash, having the log files on a different physical disk protects you from losing your log files and your data files at the same time.

The next example shows a BLOG.CFG file that makes the MicroKernel log multiple data files to a different drive (drive D:), assuming this BLOG.CFG file is on drive C:

\data\file1.mkd=d:\backup\
\data\file2.mkd=d:\backup\file2.log
\data\file3.mkd=d:\backup\file3.log

Roll Forward Command

The Btrieve Maintenance utility (GUI or BUTIL command line) provides a command allowing you to roll forward archival log files into the data files. The BUTIL -ROLLFWD command recovers changes made to a data file between the time of the last backup and a system failure. If a system failure occurs, you can restore the backup copy of your data file and then use the BUTIL -ROLLFWD command, which applies all changes stored in the archival log to your restored data files. Do not use this command unless you have restored data files from backup.

Note
You cannot take advantage of the ROLLFWD command unless you both enable the MicroKernel's Archival Logging Selected Files option and back up your files before a system failure occurs.

You can also use the ROLLFWD command to produce an output file of logged operations. The ROLLFWD command can produce the output file either before you roll changes forward or at the same time as the roll forward.

You can roll forward a single file, all data files on a volume, all data files on a drive, or a list of files, volumes, and/or drives.

Using the GUI
  1. From the Start menu, choose Programs 4 Pervasive.SQL V8 4 Other Utilities 4 Maintenance.
  2. Within the Maintenance window, choose Data 4 Roll Forward... The Roll Forward dialog box (Figure 8-1) appears.

Figure 8-1 Roll Forward Dialog

  3. Select the specific operation type: single file, list of files, volume name, or drive letter. When you select either volume name or drive letter, you must insert a back slash (\) or forward slash (/) at the end (for example, \\server\vol1\ or D:\).
  4. You can generate a log file, called a dump file, of all the Btrieve operations required to perform the roll forward tasks.

    By default, this file is not created. Select the Generate Dump File check box to generate a file. You can also specify the following options.

    Table 8-4 Roll Forward GUI Options
    Only Create Dump File
    Indicates that only the dump file is to be created, and the roll forward operation is not to be performed.
    Dump File Name
    Contains the name of the dump file, which must begin with a slash and not contain a drive letter or server/volume name.
    Data Buffer Length
    Indicates the number of data buffer bytes to write to the dump file for each Btrieve operation.
    Key Buffer Length
    Indicates the number of key buffer bytes to write to the dump file for each Btrieve operation.
    Display Numbers as HEX
    If you select this option, the numbers in the dump file output are formatted as hexadecimal. If you do not select this check box, the numbers are displayed in decimal format.
    Verbose
    Includes additional information like user name, network address, and time stamp in the dump file.

Note
If the key buffer or the data buffer is not an input parameter for the particular Btrieve operation, nothing is written to the dump file.

  5. Click Execute to generate the dump file and/or perform the roll forward operation. If the data is valid, the Roll Forward Status dialog box (Figure 8-2) appears.

Figure 8-2 Roll Forward Status Dialog

As files are processed, they are added to the scrolling list box which displays the file name and the Pervasive.SQL status code returned from the roll forward operation.

If an error occurs during processing, the Roll Forward Continue on Error dialog box appears. This dialog box allows you to continue without being prompted again, to continue and be prompted again, or to stop processing files.

Figure 8-3 Roll Forward Continue on Error Dialog

Using the Command Line

This section explains the syntax for the command line usage of Roll Forward.

BUTIL -ROLLFWD <sourceFile | volume | drive | @listFile>
[</L[dumpFile] | /W[dumpFile]> [/T<dataLength>]
[/E<keyLength>] 	[/H] [/V] [/O<ownerList | owner>|*]]
[/A] [/S]

sourceFile

The fully qualified name of a data file for which to roll forward changes. For Windows NT, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.

volume

A volume for which to roll forward changes. End the volume name with a backslash or forward slash, as in SYS:\, //SERVER/SYS/, or \\SERVER\SYS:\.

drive

A drive letter for which to roll forward changes. End the volume name with a backslash (\) or forward slash (/), as in F:\ or F:/.

listFile

The fully qualified name of a text file containing the paths of files, volumes, or drives for which to roll forward changes. Separate these paths with a carriage return/line feed. If the Maintenance utility encounters an error, the utility stops rolling forward the current file, but does not roll back the changes already made. If you specify the /A option, the utility continues rolling forward with the next file.

/LdumpFile

Produces an output file, but does not roll forward.

/WdumpFile

Rolls forward and produces an output file.

dumpFile

The file name of the output file to which the Maintenance utility writes a list of logged operations. The default is \BLOG\BROLL.LST, relative to the root of the physical drive. The file name cannot contain a drive letter or volume name and must start with a forward slash (/) or backslash (\). The Maintenance utility places the file on the same volume as the BLOG.CFG file.

/TdataLength

Specifies the length of the operation's data buffer to write to the output file. If you do not specify this option, the utility does not include data buffer contents in the output file.

/EkeyLength

Specifies the length of the operation's key buffer to write to the output file. If you do not specify this option, the utility does not include key buffer contents in the output file.

/H

Instructs the utility to show numbers in the output file in hexadecimal notation. If you do not specify this option, numbers in the output file are in ASCII format. This option affects the format of the Entry Count, Op Code, Key Number, and Data Length fields.

/V

Instructs the utility to include additional information (such as the user name, network address, and time stamp) in the output file.

/O

Specifies the owner name of the data file, if required. An owner name is required if you request an output file of logged operations and the backup copy of the data file has an owner name for read-only access.

If more than one file has an owner name, the respective owner names must be separated by commas. See  for more information.

/A

Specifies that if you are rolling back more than one file and the Maintenance utility encounters an error, the utility continues rolling forward with the next file.

When you do not specify this option, the utility stops rolling forward if it encounters an error. The utility does not roll back the changes already made.

Note: When you use the /A option, you might want to redirect output to a file, as described in  and

/S (NetWare only)

By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Note
If the key buffer or the data buffer is not an input parameter for the particular Btrieve operation, nothing is written to the dump file.

Examples

Example A The following example recovers changes to the CLASS.MKD file from the default archival log and log location.

butil -rollfwd sys:\pvsw\demodata\class.mkd

Example B This example recovers changes and outputs them to all files on the sys: volume with the following options:

  • use default dump file
  • dump 32 bytes of the data buffer
  • dump 4 bytes of the key buffer
  • dump in hex mode
butil -rollfwd sys:\ /W /H /T32 /E4

Example C The following example does not perform roll forward but only outputs the changes to the files listed in files.txt with the following dump options:

  • use sys:\temp\files.lst as the dump file
  • use verbose mode
  • data files have owner names: own123 and own321
  • do not dump data or key buffer
butil -rollfwd @sys:\temp\files.txt /L\temp\files.lst /V /Oown123,own321

Prev
Understanding Archival Logging and Continuous Operations 		Up
Check for Revisions 		Next
Using Continuous Operations


Using Continuous Operations

Continuous Operations provides the ability to backup data files while database applications are running and users are connected. However, in the event of a hard drive failure, if you use Continuous Operations to make backups, you will lose all changes to your data since the last backup. You cannot use Archival Logging and the Maintenance utility Roll Forward command to restore changes to your data files that occurred after the last backup.

Pervasive.SQL provides two backup commands for Continuous Operations: BUTIL and SQLUTIL. The commands are similar. SQLUTIL supports data source names (DSNs) as a parameter; BUTIL requires file paths. In addition, SQLUTIL runs only on Windows-based platforms and NetWare.

This section is divided into the following sub-topics:

  • Starting and Ending Continuous Operations
  • Backing Up a Database with BUTIL
  • Backing Up a Database with SQLUTIL
  • Restoring Data Files when Using Continuous Operations

Starting and Ending Continuous Operations

This section provides detailed information on the commands: STARTBU and ENDBU .
Table 8-5 Commands to Start and Stop Continuous Operation
Command | Description
STARTBU | Starts continuous operation on files defined for backup (BUTIL). Starts continuous operation on data source names defined for backup (SQLUTIL).
ENDBU | Ends continuous operation on data files defined for backup. (BUTIL). Ends continuous operation on data source names defined for backup (SQLUTIL).

 Note
The temporary delta files created by Continuous Operations mode have the same name as the corresponding data files but use the extension ".^^^" instead. Therefore, do not create multiple data files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your data files. If you do, the MicroKernel returns status 85 and no files will be put in Continuous Operations.

Continuous operation mode does not significantly affect MicroKernel performance; however, using a server to back up files can affect performance.

To protect against data loss using Continuous Operation

  1. Use the -STARTBU command to put your files in continuous operation. See STARTBU for an explanation of the command syntax with BUTIL and for an explanation with SQLUTIL.
  2. Back up your data files.
  3. Use the -ENDBU command to take your files out of continuous operation. See ENDBU for an explanation of the command syntax with BUTIL and for an explanation with SQLUTIL.

Backing Up a Database with BUTIL

This section provides detailed information on backing up a database using the following BUTIL commands: STARTBU and ENDBU .

STARTBU

The BUTIL -STARTBU command places a file or set of files into continuous operation for backup purposes.

Format
BUTIL -STARTBU <sourceFile | @listFile> [/S]

sourceFile

The fully qualified name of the data file (including the drive specification for Windows NT/2000 and volume specification for NetWare) on which to begin continuous operation for backup.

This fully qualifed name must reside on the same machine as the one from which you are running butil. You cannot used mapped drives with the startbu command.

listFile

The name of a text file containing the fully qualified names of files on which to begin continuous operation. Separate these file names with a carriage return/line feed. (Although the utility accepts a blank space separator as well, future versions of Pervasive.SQL may accept blank characters in file names. For compatibility with future versions of Pervasive.SQL, use the carriage return/line feed separator.)

If the Maintenance utility cannot put all of the specified files in continuous operation, the utility does not put any of the files in continuous operation.

/S (NetWare only)

By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Note
This command begins continuous operation only on the files you specify. You cannot use wildcard characters with the STARTBU command.

Examples for Windows Server

Example A The first example starts continuous operation on the COURSE.MKD file.

For Windows Server:

butil -startbu c:\pvsw\demodata\course.mkd

Example B The following example starts continuous operation on all files listed in the STARTLST.FIL file.

butil -startbu @startlst.fil

The STARTLST.FIL file might consist of the following entries:

c:\pvsw\demodata\course.mkd
c:\pvsw\demodata\tuition.mkd
c:\pvsw\demodata\dept.mkd
Examples for NetWare Server

Example A The first example starts continuous operation on the COURSE.MKD file.

butil -startbu sys:\pvsw\demodata\course.mkd

Example B The following example starts continuous operation on all files listed in the STARTLST.FIL file.

butil -startbu @sys:\test\startlst.fil

The STARTLST.FIL file might consist of the following entries:

sys:\pvsw\demodata\course.mkd
sys:\pvsw\demodata\tuition.mkd
sys:\pvsw\demodata\dept.mkd

ENDBU

The ENDBU command ends continuous operation on a data file or set of data files previously defined for backup. Issue this command after using the STARTBU command to begin continuous operation and after performing your backup.

Format
BUTIL -ENDBU </A | sourceFile | @listFile> [/S]

/A

If you specify /A, the utility stops continuous operation on all data files initialized by BUTIL –STARTBU and currently running in continuous operation mode.

sourceFile

The fully qualified name of the data file (including the drive specification for Windows NT/2000 and volume specification for NetWare) for which to end continuous operation.

This fully qualifed name must reside on the same machine as the one from which you are running butil. You cannot used mapped drives with the endbu command.

@listFile

The name of a text file containing a list of data files for which to end continuous operation. The text file must contain the fully qualified file name for each data file, and you must separate these file names with a carriage return/line feed. (Although the utility accepts a blank space separator as well, future versions of Pervasive.SQL may accept blank characters in file names. For compatibility with future versions of Pervasive.SQL, use the carriage return/line feed separator.)

Typically, this list of data files is the same as the list used with the STARTBU command.

/S (NetWare only)

By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
Example for Windows Server

The following example ends continuous operation on the COURSE.MKD file.

butil -endbu c:\pvsw\demodata\course.mkd

However, you can also just enter butil -endbu course.mkd instead of the full path if your current directory is f:\demodata.

Example for NetWare Server

The following example ends continuous operation on the COURSE.MKD file.

butil -endbu sys:\pvsw\demodata\course.mkd

Backing Up a Database with SQLUTIL

SQLUTIL is a command-line utility that runs only on Windows-based platforms and NetWare. You can execute SQLUTIL commands from the command line or through a command file. SQLUTIL works locally on the Pervasive.SQL server or Workgroup product (as an NLM on NetWare or from a command prompt on Windows-based platforms).

This section provides detailed information on backing up a database using the following SQLUTIL commands: STARTBU and ENDBU .

STARTBU

The SQLUTIL -STARTBU command places a file or set of files into continuous operation for backup purposes.

Format
SQLUTIL –STARTBU < datasourceName | @listFile > [ /S ]

datasourceName

The data source name on which to begin continuous operation for backup. This name must match a data source name previously defined using the Pervasive.SQL ODBC DSN Setup utility in the ODBC Data Source Administrator.

@listFile

The name of a text file containing a list of the data source names on which to begin continuous operation. Separate these names with a carriage return/line feed.

If SQLUTIL cannot put all of the files that make up the data source name in continuous operation, the utility does not put any of the files in continuous operation.

/S

By default, the SQL Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
Examples

The following example starts continuous operation on the university data source name:

sqlutil -startbu university

The following example starts continuous operation on all databases listed in the DBBACKUP.TXT file.

sqlutil -startbu @dbbackup.txt

ENDBU

The ENDBU command ends continuous operation on a data source name previously defined for backup. Execute this command after you have issued the STARTBU command and your backup utility has finished running.

Format
SQLUTIL –ENDBU < datasourceName | @listFile > [ /S ]

datasourceName | The data source name for which to end continuous operation.
@listFile | The name of a text file containing the list of data source names for which to end continuous operation. The text file must contain the data source names separated with a carriage return/line feed. Typically, this list of data files is the same as the list used with the STARTBU command.
/S | By default, the SQL Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
Examples

The following example ends continuous operation on the university data source name:

sqlutil -endbu university

The following example ends continuous operation on all databases listed in the DBBACKUP.TXT file.

sqlutil -endbu @dbbackup.txt

Restoring Data Files when Using Continuous Operations

If you are using Continuous Operations for your backup strategy, then you have no recovery log that can be used to recover changes since your last backup. All database changes since your last backup are lost, with the possible exception of any transactions stored in the transaction log. Any such transactions are automatically rolled forward by the database engine when it starts up.

To restore data and normal database operations

  1. Resolve the failure.

    Perform the maintenance required to make the failed computer operational again.

  2. Restore the data files from backup, or restore the hard drive image from backup, as appropriate.
  3. Re-install Pervasive.SQL if it was not restored as part of a disk image.
  4. Re-start the database engine.

    Any database operations performed since the last backup must be performed over again.

Prev
Using Archival Logging 		Up
Check for Revisions 		Next
Server High-Availability Support


Server High-Availability Support

An Introduction to Clustering and Failover Support

The purpose of this chapter is to explain the support for server high availability. This chapter includes the following sections:

  • Server Clustering
  • Microsoft Cluster Service
  • NetWare Cluster Services
  • SFT III for NetWare 4.2
Prev
Using Continuous Operations
Check for Revisions 		Next
Server Clustering


Server Clustering

A server cluster is a group of independent servers working collectively as a single system. Each server runs a collection of software to manage all aspects of the cluster. The purpose of the cluster is to provide high-availability, scalability, and manageability of resources and applications.

Pervasive.SQL V8 supports Microsoft Cluster Service and NetWare Cluster Services. Both services are similar architecturally. They provide for multiple physical servers to access a common, shared disk subsystem that contains one or more file shares or volumes. The services ensure that only one physical server controls the file shares or volumes at a time. Control of the shared disk subsystem is passed automatically from a failed server to the next surviving server in the cluster.

Members of a cluster are referred to as nodes or systems and the terms are use interchangeably. A resource is an item managed by the cluster service, such as a logical disk volume, application, or database. A resource is said to be online on a node when it provides its service on that node. A group is a collection of resources managed as a single unit.

Failure Behavior

If a cluster server fails, the cluster service automatically transfers ownership of resources such as disk drives and IP addresses from the failed server to a surviving server. Similarly, if an application fails, the cluster service restarts the failed application on a surviving server, or disperses the work from the failed node to the remaining nodes.

The shared disk of a cluster appears as a separate server within the cluster because the network name and IP address differ from those of the other nodes. You can think of a cluster as a group of independent computers working together to share data on an area of physical storage. Although the computers share data, only one computer at a time can control the shared disk subsystem.

Note
If a cluster node fails, a Pervasive.SQL client does not automatically reconnect to the Pervasive.SQL engine on the surviving node. Your application must reconnect the client to the Pervasive.SQL database or you must restart the application. This applies even if Enable Auto Reconnect is turned on in the Pervasive Control Center (PCC).

Pervasive.SQL does not maintain the transaction state when a cluster node fails. The transaction states does not transfer to a surviving node. Transactions are automatically rolled back to the state before the transaction began.

Modes

A clustering environment provides two modes of operation, active/passive and active/active. The mode indicates on how many cluster nodes a resource is active at the same time.

Running Pervasive.SQL in the Microsoft clustering environment is an example of active/passive. Pervasive.SQL is active on only one node at a time.

Running Pervasive.SQL in the NetWare clustering environment is an example of both active/passive and active/active. Pervasive.SQL is active on all nodes at the same time, which is active/active. However, only one node at a time controls the shared disk, which is active/passive. Only the Pervasive.SQL engine on the node hosting the shared disk has access to the Pervasive.SQL databases on the shared disk.

Note that the modes have nothing to do with load balancing. Pervasive.SQL does no load balancing in a clustered environment.

Licensing

No special licensing is required to use the Pervasive.SQL Server engine in a clustered environment. Refer to the Pervasive.SQL Standard License Agreement (Server Engine) for details.

Prev
Server High-Availability Support 		Up
Check for Revisions 		Next
Microsoft Cluster Service


Microsoft Cluster Service

Microsoft Cluster Service is supported by the Pervasive.SQL V8 Server engine on the following configurations:

  • Windows 2000 Advanced Server with SP2 or higher
  • Windows NT 4 Server with SP6a or higher

This section assumes that you are familiar with the installation and configuration of Cluster Service and need only the information required to add the Pervasive.SQL V8 services to a Cluster Service group.

If you are not familiar with Cluster Service technology, please refer to the Microsoft documentation for how to install Cluster Service, verify it is working correctly, and perform tasks with it. You may also find the following links beneficial:

  • http://www.microsoft.com/windows2000/technologies/clustering/default.asp
  • http://www.microsoft.com/technet/treeview/default.asp?url=/technet/prodtechnol/WindowsNetServer/proddocs/SCCon_BP.asp
  • http://www.microsoft.com/ntserver/ProductInfo/Enterprise/clustering/ClustArchit.asp.

How to Proceed

This section is organized in the manner in which you should proceed to add the Pervasive.SQL services to a cluster group. That is, this section gives you the following suggested approach:

  • Verify that Cluster Service is functioning correctly
  • Add a cluster group for Pervasive.SQL
  • Install Pervasive.SQL on the cluster nodes
  • Add the Pervasive.SQL resources to the cluster group
  • Configure the engines with Pervasive Control Center
  • Establish the Pervasive.SQL database(s) on the cluster shared disk and verify connection from a Pervasive.SQL client.

Verify Cluster Service Functioning Correctly

It is essential that Cluster Service be functioning correctly before you add the Pervasive.SQL services to a cluster group. Refer to the Microsoft documentation for how to install Cluster Service, verify it is working correctly, and perform tasks with it.

We recommend that you select servers and disk subsystems from the Microsoft hardware compatibility list (HCL) for clusters.

Note
If Cluster Service is not set up properly, you will be unable to get your Pervasive.SQL resources to work properly.

Verify Network Client Communication

Before you add Pervasive.SQL to a cluster environment, we recommend that you verify network client communication with the cluster shared disk. A network client must be able to communicate with a cluster shared disk before and after a failure of a cluster node (failover). The following task lets you verify this.

To verify network client communication and cluster failover

  1. Connect a drive on a client computer to the shared disk subsystem. (This step assumes that you are using a computer on which a Pervasive.SQL requester is, or will be, running.)

    Example:

    From a command prompt on a client computer, execute the following command:

    net use X: \\WIN2K-Cluster\Gdrive

    This example connects drive "X" on a workstation to the "G" drive on the shared disk subsystem "WIN2K-Cluster." "WIN2K-Cluster" is the Network Name. "Gdrive" is the File Share.

  2. Verify that you can execute a command on the connected drive. For example, switch to the drive and display a directory with the dir command:

    x:
    dir

  3. Verify that you can connect to the IP address of the shared disk subsystem. From a command prompt, execute the following command: ping Network Name. For example, ping WIN2K-Cluster.

    If the command returns something like Reply from IP address, then you can connect to the IP address. For example, the following reply shows a successful connection:

    Reply from 172.99.99.35: bytes=32 time<10ms TTL=128

    Check that the IP address in the reply is the correct address of the shared disk subsystem.

  4. In the Cluster Administrator, right-click on the Network Name, then click Initiate Failure. Repeat this action until a failure occurs. The number of times you must repeat the action depends on the threshold setting.

    This fails the node currently controlling the shared disk of the cluster. A surviving node in the cluster becomes active and assumes control of the shared disk.

 Note
Ensure that the failover occurred and that a surviving node is now controlling the shared disk. If you cannot initiate a failure, then your clustering environment may not be set up correctly and you will be unable to get your Pervasive.SQL resources to work properly.

  5. On the client computer used for step 1, verify that you can still execute a command on the connected drive. For example, display a directory with the dir command.

The cluster is functioning correctly if you can execute a command on the shared disk subsystem from a client computer before and after a failure. If you cannot, check the setup of the Cluster Service and the resources.

Add a Cluster Group for Pervasive.SQL

Your next task is to create a cluster group to which you will later add the Pervasive.SQL resources. You create a cluster group to it with the Microsoft Cluster Administrator.

Please refer to the Microsoft Cluster Service documentation for how to add a cluster group. The steps to add the Pervasive.SQL resources to a cluster group are explained in Add Pervasive.SQL Services to Cluster Group .

All resources within a cluster group fail together. That is, if one resource within a group fails on a node, the remaining resources are taken offline. All resources within the group are then transferred to a surviving node and brought back online. For this reason, we suggest that you create a separate cluster group for Pervasive.SQL. This is not mandatory, but is a good administrative method.

At a minimum, ensure that a cluster group for Pervasive.SQL contains the following resources.

  • IP Address. This is the IP address of the shared disk subsystem. The Pervasive.SQL requesters connect to this IP address.
  • Network Name. This is the name of the shared disk subsystem that users see on a network. The name is of your choosing. For example, you may want to name the shared disk subsystem "Pervasive.SQL Cluster" or something to that effect.
  • Physical Disk. This is the disk subsystem that contains the Pervasive.SQL database. The cluster nodes share this disk, but only one node at a time controls the disk.
  • File Share. This is the share point to which users can connect. Your database files reside in one or more directories on the file share.

Failback

In addition to the required minimum resources (IP Address, Network Name, Physical Disk, and File Share), you may want to enable failback for the group. Failback is a feature of clustering that specifies a preferred controlling node within the cluster.

For example, suppose your cluster contains two nodes, Server A, the preferred controlling node, and Server B. If Server A fails, Server B assumes control. When Server A comes back online, control passes back to it automatically. This automatic transfer of control is referred to as failback (clustering automatically "fails back" to the preferred node).

You specify failback on the properties dialog of the group name.

Note
When the cluster node fails back to the preferred server, a Pervasive.SQL client loses connection with the database engine. No automatic reconnection occurs. Your application must reconnect the client to the Pervasive.SQL database or you must restart the application. This applies even if Enable Auto Reconnect is turned on in the PCC.

Pervasive.SQL does not maintain the transaction state when the failback occurs. The transaction state does not transfer to the preferred server. Transactions are automatically rolled back to the state before the transaction began.

Install Pervasive.SQL on the Cluster Nodes

You install Pervasive.SQL V8 Server on each cluster node. Choose identical options for each installations. See Installing Pervasive.SQL with No Previous Installation in Getting Started with Pervasive.SQL (Server edition).

Do not install Pervasive.SQL on the cluster shared disk. The shared disk is where the Pervasive.SQL database(s) reside.

The Pervasive.SQL transactional and relational services typically run under the Local System Account. Depending on the settings for your domain permissions, the Local System Account may lack authority for certain actions pertaining to Pervasive.SQL, such as installing the requesters from a cluster node. Check the domain permissions for your cluster node accounts if you encounter problems installing the Pervasive.SQL products.

After installation, both the transactional and relational services are set to start automatically when the operating system starts. With clustering, however, the Cluster Administrator controls the starting and stopping (bringing online or offline) of the services. Be aware that, once you add the Pervasive.SQL services to a cluster group, the Cluster Administrator changes the service settings from automatic to manual.

If you add both the transactional and relational service to your cluster group, you do not need to take any action concerning the service settings. (Cluster Service sets both to manual.) The transactional service is always required in your cluster. The relational service is optional. If your application(s) requires the relational engine of Pervasive.SQL, you must also add the relational service to the cluster group.

Note, however, that if you add only the transactional service to the cluster then you must change the startup settings for the relational service. (The startup settings established when you installed Pervasive.SQL by running the installation program.) See To change the startup setting for the relational service .

Add Pervasive.SQL Services to Cluster Group

Your next task is to add the Pervasive.SQL services to the cluster group.

To add the Pervasive.SQL transactional service to a cluster group

The transactional service of Pervasive.SQL is always required in a cluster group. Perform this task on only one node in the cluster. All other nodes in your cluster share the information.

  1. Ensure that Pervasive.SQL Server is installed on each cluster node and that the correct administrative permissions are set on each node. See Install Pervasive.SQL on the Cluster Nodes .
  2. In the Microsoft Cluster Administrator, right-click on the desired cluster group name, then click New 4 Resource.
  3. On the New Resources dialog, type in a name for the resource. The name is used only for display purposes within Cluster Administrator. Optionally, type in a description for the resource.
  4. Click the list for Resource type then click Generic Service.
  5. Click the list for Group then click the desired group.
  6. Do not check the option Run this resource in a separate Resource Monitor.

    The information should look something like the following example:

  7. Click Next. The Possible Owners dialog appears.
  8. Specify the nodes that can function as possible owners for the resource. (Add the nodes to the list of possible owners.)
  9. Click Next. The Dependencies dialog appears.
  10. Add the resources that must be brought online first. That is, the resources on which the new resource depends. Add the following dependences to the list of resource dependences:
    • IP Address
    • Network Name
    • File Share

  11. Click Next. The Generic Services Parameters dialog appears.
  12. For Service name, type in Pervasive.SQL (transactional).
  13. Leave the Start parameters blank.
  14. Click the option Use Network Name for computer name.

    The information must be the following:

 Note
Ensure that you check the option Use Network name for computer name. This option allows the Pervasive.SQL transactional engine to open files directly on the shared disk, which improves performance.

  15. Click Next. The Registry Replication dialog appears.
  16. Click Add. The Registry Key dialog appears.
  17. Type in SOFTWARE\Pervasive Software.
  18. Click OK.
  19. Click Finish to add the new resource. A message appears stating that the resource was created successfully.
  20. Click OK.
  21. In the Cluster Administrator, right-click on the Pervasive.SQL resource you just added. Click Properties.
  22. Click the Advanced tab.
  23. Ensure that the Restart option and the Affect the group option are selected.

    Optionally, you may set the Threshold and Period values to your choice.

  24. Click OK (click Apply then OK is the Apply button is enabled).

If your application(s) require only the transactional engine, you do not need to add the relational service to your cluster group. You may skip to To change the startup setting for the relational service .

To add the Pervasive.SQL relational service to a cluster group

If your application(s) requires the relational engine of Pervasive.SQL, you must also add the relational service to your cluster group. If your application(s) require only the transactional engine, you do not need to add the relational service to your cluster group. You may skip to To change the startup setting for the relational service .

  1. Add the Pervasive.SQL transactional service as explained in To add the Pervasive.SQL transactional service to a cluster group . The transactional service is required for the relational service.
  2. In the Cluster Administrator, right-click on the desired cluster group name, then click New 4 Resource.
  3. On the New Resources dialog, type in a name for the resource. The name is used only for display purposes within Cluster Administrator. Optionally, type in a description for the resource.
  4. Click the list for Resource type then click Generic Service.
  5. Click the list for Group then click the desired group.
  6. Do not check the option Run this resource in a separate Resource Monitor.

    The information should look something like the following example:

  7. Click Next. The Possible Owners dialog appears.
  8. Specify the nodes that can function as possible owners for the resource. (Add the nodes to the list of possible owners.)
  9. Click Next. The Dependencies dialog appears.
  10. In the Available resources list, click the Pervasive.SQL transactional resource that you added with the procedure To add the Pervasive.SQL transactional service to a cluster group . For example, if you named the transactional resource "Btrieve," click on "Btrieve."
  11. Click Add. This adds the resource to the list of dependences.

    You do not need to add the resources IP Address, Network Name, and File Share because they are dependencies of the transactional resource.

  12. Click Next. The Generic Services Parameters dialog appears.
  13. For Service name, type in Pervasive.SQL (relational).
  14. Leave the Start parameters blank.
  15. Click the option Use Network Name for computer name.

    The information must be the following:

 Note
Ensure that you check the option Use Network name for computer name. This option allows the Pervasive.SQL relational engine to open files directly on the shared disk, which improves performance.

  16. Click Next. The Registry Replication dialog appears.
  17. Decide how you want to handle DSNs.

    You may specify the key SOFTWARE\ODBC if you want. However, this affects all ODBC data sources and ODBC providers installed on the cluster node. Pervasive.SQL may not be the only ODBC provider installed on the cluster node. If it is the only ODBC provider, this is a fast way to ensure that all Pervasive.SQL data source names (DSNs) identified in your cluster can be used by all cluster nodes.

    If you do not want to specify SOFTWARE\ODBC, then you must set up the individual DSNs on each cluster node.

    Decide on one of the following as your preferred way to handle DSNs.

    1. To specify all ODBC providers, click Add. The Registry Key dialog appears. Type in SOFTWARE\ODBC. Click OK and continue with step 18. All nodes in your cluster now have this key in their registry.
    2. To specify separate DSNs, do not add any key for registry replication. Continue with the remaining steps in this procedure, then perform the steps in To specify DSNs on each cluster node .
  18. Click Finish to add the new resource. A message appears stating that the resource was created successfully.
  19. Click OK.
  20. In the Cluster Administrator, right-click on the Pervasive.SQL resource you just added. Click Properties.
  21. Click the Advanced tab.
  22. Ensure that the Restart option and the Affect the group option are selected.

    Optionally, you may set the Threshold and Period values to your choice.

  23. Click OK (click Apply then OK is the Apply button is enabled).

To change the startup setting for the relational service

This task is required only if you did not add the relational service to your cluster group. (See Install Pervasive.SQL on the Cluster Nodes .) If you added the relational service to your cluster group, skip this task.

  1. Display the Services dialog. For example, on Windows NT, click Start 4 Settings 4 Control Panel, then double-click Services.
  2. In the list, click on the service Pervasive.SQL (relational).
  3. Click Startup.
  4. For Startup Type, click either the Manual option or the Disabled option.
  5. Click OK.
  6. If the service is running, click Stop.
  7. Click Close.

Configure the Engines with PCC

Your next task is to configure the engine by using Pervasive Control Center (PCC). The configuration settings are added to the registry. You need to configure the engine on one node in your cluster, then initiate a failure to migrate the settings to the next node in your cluster.

To configure the engines for clustering

  1. In the PCC name space, right-click on Pervasive.SQL Engines then click Register New Engine.
  2. For computer name, type in the Network Name of the cluster shared disk subsystem.

    Ensure that you specify the Network Name of the cluster shared disk and not the machine name of a cluster node. The following example shows the registration of a new engine on the cluster shared disk named WIN2K-CLUSTER.

  3. Click OK. (Optionally, you can click Test to test the connection, then click OK.)
  4. In the PCC name space, click on Configuration. The server login dialog appears.
  5. Type in the user name and password of an administrator. Click Login.
  6. Expand the Configuration settings, then the Server settings (click the plus signs).
  7. Click on Directories.
  8. Double-click DBNames Configuration Location. Type in a location on the cluster shared drive where you want the dbnames configuration file to reside.

    For example, if the shared disk is drive G: and you want the dbnames configuration file to reside in a directory named "config," type in G:\config.

  9. Click OK.
  10. Double-click Transaction Log Directory. Type in a location on the cluster shared drive where you want the log to reside.
  11. Click OK.
  12. Click on Communication Protocols.
  13. Ensure that TCP/IP Multihomed is ON. If it is not, double-click TCP/IP Multihomed, click On, then click OK.
  14. Click the apply icon in the PCC to apply the configuration changes. The apply icon contains an exclamation mark (!).

    You now need to restart the Pervasive.SQL services to apply the configuration changes. You restart the services with the Cluster Administrator.

  15. In the Cluster Administrator, right-click on the Pervasive.SQL transactional resource. This is the resource you added with the steps To add the Pervasive.SQL transactional service to a cluster group .
  16. Click Take Offline. This takes both the transactional service and the relational service offline. The relational has a dependency on the transactional.
  17. In the Cluster Administrator, again right-click on the Pervasive.SQL transactional resource. Click Bring Online.
  18. Right-click on the Pervasive.SQL relational resource (if you added the relational resource). Click Bring Online.

    The configuration settings are now applied to the Pervasive services. However, the settings are in the registry only on the controlling cluster node. You need to initiate a failure to ensure that the settings are migrated to the registry on the surviving node(s).

  19. In the Cluster Administrator, right-click on the Network Name, then click Initiate Failure. Repeat this action until a failure occurs. The number of times you must repeat the action depends on the threshold setting.

    The next surviving node becomes the new controlling node of the cluster.

    Repeat this step until you have initiated failure to each cluster node. If you prefer, when finished, initiate failure back to the cluster node from which you started (the node for steps 1 through 18). This is not required unless you want that cluster node to be the controlling node.

Note
Ensure that failure occurs or the registry settings will not migrate to the surviving node(s).

To specify DSNs on each cluster node

This task is required only if you did not specify the registry key SOFTWARE\ODBC in step 17 of the task To add the Pervasive.SQL relational service to a cluster group . If you added the registry key SOFTWARE\ODBC, skip this task.

Note that DSNs are stored in the registry as key entries. Cluster Administrator works only with registry keys, not with the individual entries.

You need to create the DSNs on one cluster node, initiate failure, and create the same DSNs on the surviving node. You repeat this until all cluster nodes contain the DSNs.

Note
You must configure the engines by using the PCC before performing this task. See To configure the engines for clustering .

  1. On the controlling cluster node, open the ODBC Administrator.
  2. Click the System DSN tab.
  3. Click Add. The Create New Data Source dialog appears.
  4. In the list, click Pervasive ODBC Engine Interface.
  5. Click Finish. The Pervasive ODBC Engine DSN Setup dialog appears.
  6. Click Create (to specify a database name).
  7. For Database Name, type in the name of the Pervasive.SQL database.
  8. For Directory Location, type in (or browse to) the location on the cluster shared drive where the database files reside. This is the location of the DDF files.
  9. Click OK to return to the Pervasive ODBC Engine DSN Setup dialog.
  10. For Data Source Name, type in a name by which you want to refer to the database.
  11. Click OK.
  12. Repeat steps 1 through 11 for each Pervasive.SQL database involved in clustering.
  13. In the Cluster Administrator, right-click on the Network Name, then click Initiate Failure. Repeat this action until a failure occurs. The number of times you must repeat the action depends on the threshold setting.

    The next surviving node becomes the new controlling node of the cluster. Initiating failure is required because the engine must be running for you to create the DSNs.

  14. Open the ODBC Administrator on the new controlling node.
  15. Click the System DSN tab.
  16. Click Add. The Create New Data Source dialog appears.
  17. In the list, click Pervasive ODBC Engine Interface.
  18. Click Finish. The Pervasive ODBC Engine DSN Setup dialog appears.
  19. In the list for Database Name, click the database name you want.

    The list contains all of the names that you added with steps 1 through 12 because those steps updated dbnames.cfg on the shared disk.

  20. For Data Source Name, type in the appropriate name. That is, the names used in steps 7 and 10 must match the names in steps 19 and 20.
  21. Click OK.
  22. Repeat steps 13 through 21 for each node in the cluster on which you have not set up the DSNs.

Establish Pervasive.SQL Databases on the Cluster Shared Disk

You may establish a Pervasive.SQL database on a cluster shared disk by creating a new database or by copying an existing database.

To create a new database on a shared disk.

Use the Create Database wizard in the PCC to create a database directly on the cluster shared drive. See Adding or Creating a Database in Pervasive.SQL User's Guide.

Since the wizard also sets up the DSN, all cluster nodes are aware of the new DSN if you specified the registry key SOFTWARE\ODBC in step 17 of the task To add the Pervasive.SQL relational service to a cluster group . If you did not add that registry key, then you need to create the DSN on each cluster node. See To specify DSNs on each cluster node .

To copy an existing database to a shared disk

A previously existing database must be copied to the shared drive. You then use the PCC to change the location of the dictionary and data files.

  1. Copy the database directory or directories to the shared drive.
  2. In the PCC name space, right-click on Configuration for the database.
  3. Click Maintain Named Database.
  4. Click on the database in the list of Registered DB Names.
  5. Change the Dictionary Location to the location on the shared drive.
  6. Change the Data File Locations to the location(s) on the shared drive.
  7. Click OK.

To test the transactional connection from a Pervasive.SQL client

  1. Connect a drive to the shared disk subsystem from a computer running a Pervasive.SQL client.

    Example:

    From a command prompt on a client computer, execute the following command:

    net use X: \\WIN2K-Cluster\Gdrive

    This example connects drive "X" on a computer to the "G" drive on shared disk subsystem "WIN2K-Cluster." "WIN2K-Cluster" is the Network Name. "Gdrive" is the File Share.

  2. Copy the sample database DEMODATA (the DEMODATA folder) from the controlling cluster node to the cluster shared disk. (This step is not required if you already have a Pervasive.SQL database on the cluster shared disk. These steps assume that you do not.)

    By default, DEMODATA is located at C:\PVSW\DEMODATA.

  3. At a command prompt on the client workstation, execute the following command (using drive X as an example):

    butil -stat x:\demodata\file.ddf

    If the command executes successfully, the Pervasive.SQL client is communicating with the database on the cluster shared disk. A successful execution returns information such as file version, page size, total number of records, and so forth.

  4. In the Cluster Administrator, right-click on the Network Name, then click Initiate Failure. Repeat this action until a failure occurs. The number of times you must repeat the action depends on the threshold setting.

    This fails the node currently controlling the shared disk of the cluster. A surviving node in the cluster becomes active and assumes control of the shared disk.

  5. After the failure, execute the following command from the client workstation (using drive X as an example):

    butil -stat x:\demodata\file.ddf

    If the command executes successfully, the Pervasive.SQL client is communicating with the database on the cluster shared drive. A successful execution returns information such as file version, page size, total number of records, and so forth.

To test the relational connection from a Pervasive.SQL client

This test is required only if you added the relational service to your cluster group.

  1. Connect a drive to the shared disk subsystem from a computer running the Pervasive.SQL client.

    Example: net use X: \\WIN2K-Cluster\Gdrive

    This example connects drive "X" on a computer to the "G" drive on shared disk subsystem "WIN2K-Cluster." "WIN2K-Cluster" is the Network Name. "Gdrive" is the File Share.

  2. Create a directory on the cluster shared disk named DEMODATA2.
  3. From the controlling cluster node, copy all of the files from the directory of the sample database DEMODATA to the DEMODATA2 directory. By default, DEMODATA is located at C:\PVSW\DEMODATA.
  4. On the controlling cluster node, open the ODBC Administrator. For example, on Windows NT, click Start 4 Settings 4 Control Panel, the double-click ODBC Data Sources.
  5. Click the System DSN tab.
  6. Click Add. The Create New Data Source dialog appears.
  7. In the list, click Pervasive ODBC Engine Interface.
  8. Click Finish. The Pervasive ODBC Engine DSN Setup dialog appears.
  9. Click Create (to specify a database name).
  10. For Database Name, type in DEMODATA2.
  11. For Directory Location, type in (or browse to) DEMODATA2. Include the drive letter. For example, G:\DEMODATA2.
  12. Click OK to return to the Pervasive ODBC Engine DSN Setup dialog.
  13. For Data Source Name, type in DEMODATA2.
  14. Click OK.
  15. On the System DSN tab, click Pervasive ODBC Client Interface.
  16. Click Finish. The Pervasive ODBC Client DSN Setup dialog appears.
  17. Type in the address of the shared disk subsystem (this is the Network Name).
  18. Click Get DSN List.
  19. For the server DSN, click DEMODATA2 in the list.
  20. Type in a name for the client DSN. The information should look similar to the following example:
  21. Click Test. A successful test indicates that the client DSN is communicating with the engine. Click OK to dismiss the Test Connection message box.
  22. Click OK to close the Pervasive ODBC Client DSN Setup dialog.
  23. In the Cluster Administrator, right-click on the Network Name, then click Initiate Failure. Repeat this action until a failure occurs. The number of times you must repeat the action depends on the threshold setting.

    This fails the node currently controlling the shared disk of the cluster. A surviving node in the cluster becomes active and assumes control of the shared disk.

  24. On the controlling cluster node, open the ODBC Administrator.
  25. Click the System DSN tab.
  26. Double-click the client DSN you created in step 20. The Pervasive ODBC Client DSN Setup dialog appears.
  27. Click Test. A successful test indicates that the client DSN is communicating with the engine. Click OK to dismiss the Test Connection message box.
  28. Click OK to close the Pervasive ODBC Client DSN Setup dialog.
Prev
Server Clustering 		Up
Check for Revisions 		Next
NetWare Cluster Services


NetWare Cluster Services

NetWare Cluster Services is supported by the Pervasive.SQL Server engine on the following configurations:

  • NetWare 6.0
  • NetWare 5.1 with Support Pack 2 or later
  • NetWare 5.0 with Support Pack 4

This section assumes that you are familiar with the installation and configuration of Cluster Services and need only the information required to configure Pervasive.SQL for Cluster Services.

If you are not familiar with Cluster Services technology, please refer to the NetWare documentation for how to install Cluster Services, verify it is working correctly, and perform tasks with it.

How to Proceed

This section is organized in the manner in which you should proceed to add Pervasive.SQL to your cluster. That is, this section gives you the following suggested approach:

  • Verify that Cluster Services is functioning correctly
  • Modify the load script if required
  • Configure the engines by using the Pervasive Control Center (PCC) and ensure identical configuration information
  • Establish the Pervasive.SQL databases on the cluster shared disk

Verify Cluster Services is Functioning Correctly

Refer to the Novell documentation for how to install Cluster Services and verify it is working correctly. Also consult the NetWare documentation for how to use ConsoleOne and how to perform tasks with Cluster Services.

During installation of Cluster Services, you create a NetWare cluster object. The Novell documentation details the information required when you create a cluster object. This information is required for any cluster object, including an object for the Pervasive.SQL database engines.

At a minimum, ensure that you know the following when you create a cluster object:

  • Server Names. These are the names of the servers (nodes) that are to be included in the cluster.
  • IP Address. This is the IP address of the shared disk subsystem.
  • Cluster Volume. This is the volume of the disk shared by the cluster nodes.

After you create a cluster object, you may verify that Cluster Services is functioning correctly.

To verify that Cluster Services is functioning correctly

  1. Connect a drive on a client computer to the shared disk subsystem. (This step assumes that you are using a computer on which a Pervasive.SQL requester is, or will be, running.)

    Example:

    From a command prompt on a client workstation, execute the following command:

    net use X: \\nw_cluster_object_server\vol1

    This example connects drive "X" on a workstation to volume 1 of the shared disk.

  2. Verify that you can execute a command on the connected drive. For example, switch to the drive of the shared disk and display a directory with the dir command:

    x:
    dir

  3. Verify that you can connect to the IP address of the shared disk subsystem. From a command prompt, execute the following command: ping shared disk subsystem address. For example, ping 199.99.99.99.

    If the command returns something like Reply from IP address, then you can connect to the IP address. For example, the following reply shows a successful connection:

    Reply from 199.99.99.99: bytes=32 time<10ms TTL=128

    Check that the IP address in the reply is the correct address of the shared disk subsystem.

    The next three steps, 4, 5, and 6, require that you have administrator authority.

  4. In ConsoleOne, click on the cluster object in the left pane, then click View 4 Cluster State. Click the Cluster State tab. You should see something similar to the following.
  5. In the right pane, click on a Location.

    The Cluster Resource Manager dialog appears.

  6. Click on a migration target, then click Migrate. For example, the following image shows NW_Cluster_B as the migration target.

    The migration target becomes active and assumes control of the shared disk. In the ConsoleOne interface, you will see the location change to the migration target and the number of lives (#Lives) increment by one.

  7. On the client workstation used for step 1, verify that you can still execute a command on the connected drive. For example, display a directory with the dir command.

The cluster is functioning correctly if you can execute a command on the shared disk subsystem from a client workstation before and after a migration. If you cannot, check the setup of Cluster Services.

Failback

Optionally, you may want to enable failback for the cluster object. Failback is a feature of clustering that specifies a preferred node within the cluster.

For example, suppose your cluster contains two nodes, Server A, the preferred controlling node, and Server B. If Server A fails, Server B assumes control. When Server A comes back online, control passes back to it automatically. This automatic transfer of control is referred to as failback (clustering automatically "fails back" to the preferred node).

You specify failback on the properties dialog of the volume resource. (Click View 4 Console View to see the volume resources in the right pane of ConsoleOne.) On the Policies tab, set Failback Mode to Auto.

 Note
When the cluster node fails back to the preferred server, a Pervasive.SQL client loses connection with the database engine. No automatic reconnection occurs. Your application must reconnect the client to the Pervasive.SQL database or you must restart the application. This applies even if Enable Auto Reconnect is turned on in the PCC.

Pervasive.SQL does not maintain the transaction state when the failback occurs. The transaction state does not transfer to the preferred server. Transactions are automatically rolled back to the state before the transaction began.

Modify Load Script if Required

The creation of a cluster object creates a default load and unload script. These scripts are necessary to dismount and mount the volume of the shared disk during a failover.

Depending on your applications, you may use the default load and unload scripts as is. If your applications do not access Pervasive.SQL data files with long file names, you may use the default scripts as is. You do not need to add anything specific for Pervasive.SQL.

However, if your applications access data files with long file names, you need to modify the load script only. You may use the default unload script as is.

The reason the load script must be modified is that volumes must be mounted before the Pervasive engines are started if an application accesses data files with long file names. To modify the load script, you must add the commands mgrstop, bstop, bstart, and mgrstart.

You specify the script on the properties dialog of the volume resource. (Click View 4 Console View to see the volume resources in the right pane of ConsoleOne.) Click the Load tab then specify the script.

Table 9-1 shows an example of a modified load script. You add mgrstop and bstop to the top of the script, and bstart and mgrstart to the bottom.

Table 9-1 Example Modified Load Script for Pervasive.SQL Engines
mgrstop
bstop
nss /activate=VOL1
mount VOL1 VOLID=254
trustmig VOL1 watch
NUDP ADD NW_CLUSTER_
SUBSYSTEM 199.99.99.99
add secondary ipaddress 199.99.99.99
bstart
mgrstart

Configure Engines and Ensure Identical Configuration Information

Each cluster node must contain identical configurations for the Pervasive.SQL database engines. This includes the server configuration settings made with the Pervasive Control Center (PCC) and information about all databases created through the PCC (such as data source names).

The easiest way in which to ensure identical configurations is to establish the configuration on one node and then copy the information to the other nodes.

To do this, first register the shared disk subsystem as a new engine to the PCC. (The task To configure an engine shows you how.)

Next, set the following PCC configurations:

  • Transaction durability and transaction logging to OFF. (These settings must be off because only one Pervasive.SQL engine may control the files associated with these settings. In a cluster, the engine is running on all nodes.)
  • Supported protocols to TCP/IP.
  • TCP/IP Multihomed to ON (it is on by default).

Note that these are required. Transaction durability and transaction logging must be set to OFF, the supported protocol must be set to TCP/IP, and TCP/IP Multihomed must be ON. See To configure an engine for the steps to set these configurations.

From the node that is hosting the shared disk, you then copy the following files to all other cluster nodes:

  • SYS:SYSTEM\bti.cfg
  • SYS:ODBC\odbc.ini
  • SYS:SYSTEM\dbnames.cfg

For example, suppose that node NW_CLUSTER_A is hosting the shared disk, which is named NW_CLUSTER_OBJECT_SERVER. Register NW_CLUSTER_OBJECT_SERVER to the PCC and set transaction durability and transaction logging to OFF and supported protocols to TCP/IP. Then copy bti.cfg, odbc.ini, and dbnames.cfg from the SYS volume of NW_CLUSTER_A to the other nodes.

You have a couple of alternatives to copying the bti.cfg, odbc.ini, and dbnames.cfg files to each node. You may register each cluster node in the PCC and set the configuration for each node. Or, you may register the shared disk subsystem, set the configuration, migrate to the next cluster node, set the configuration, and so forth until you have migrated to all cluster nodes.

How you achieve the end result does not matter as long as all nodes are configured identically.

To configure an engine

This task shows how to configure an engine by using the PCC.

  1. In the PCC name space, right-click on Pervasive.SQL Engines then click Register New Engine.
  2. For computer name, type in the name of the shared disk subsystem.

    The following example shows the registration of a new engine on NW_CLUSTER_OBJECT_SERVER.

  3. Click OK. (Optionally, you can click Test to test the connection, then click OK.)
  4. In the PCC name space, click on Configuration for the engine you just registered. The server login dialog appears.
  5. Type in the user name and password of an administrator. Click Login.
  6. Expand the Server settings (click the plus sign).
  7. Click on Data Integrity.
  8. Ensure that Transaction Durability and Transaction Logging are both set to off. If either is on, double-click on the setting name, click Off, then OK.

    You may set Archival Logging Selected Files to on or off as you prefer, but Transaction Durability and Transaction Logging must be set to off. (These settings must be off because only one Pervasive.SQL engine may control the files associated with these settings. In a cluster, the engine is running on all nodes.)

     Caution
    By turning Transaction Durability and Transaction Logging off, you cannot guarantee data consistency and transaction atomicity across multiple files.

  9. Click on Communication Protocols.
  10. Double-click Supported protocols. Ensure that TCP/IP is the only protocol listed in the Selected pane. (Click the > button to add items to the Selected pane. Click the < button to remove items.)
  11. Ensure that TCP/IP Multihomed is set to ON. If it is not, double-click the setting name, click On, then click OK.
  12. Click the apply icon in the PCC to apply the configuration changes. The apply icon contains an exclamation mark (!).

To configure the engines by migration

This task shows how to configure the engines by migration. Perform this task only if you want to configure the engines by the migration method. As an alternative method, you may prefer to configure the node hosting the shared disk, then copy bti.cfg, odbc.ini, and dbnames.cfg to the other nodes.

  1. Complete all of the steps in To configure an engine .

    The next two steps require that you have administrator authority.

  2. In ConsoleOne, click on the cluster object in the left pane, then click View 4 Cluster State. In the right pane, click on Location.

    The Cluster Resource Manager dialog appears.

  3. Click on a migration target, then click Migrate. For example, the following image shows NW_Cluster_B as the migration target.

    The migration target becomes active and assumes control of the shared disk. In the ConsoleOne interface, you will see the location change to the migration target and the number of lives (#Lives) increment by one.

  4. For each node in the cluster, repeat the task To configure an engine and steps 1 through 3 of this task.

    These actions could become tedious if you have numerous nodes in your cluster. For that reason, you may prefer to configure the node hosting the shared disk, then copy bti.cfg, odbc.ini, and dbnames.cfg to the other nodes.

Establish Databases on the Cluster Shared Disk

You may establish a Pervasive.SQL database on a cluster shared disk by copying an existing database or by creating a new database. For example, you may create a database with the PCC directly on the cluster shared disk. If you already have an existing Pervasive.SQL database, you may copy it to the cluster shared disk.

A Previously Existing Database

A previously existing database may be copied to the shared disk. You then use the PCC to change the location of the dictionary and data files.

Copying an Existing Database to a Shared Disk

  1. Copy the database directory or directories to the shared drive.
  2. In the PCC name space, right-click on Configuration for the database.
  3. Click Maintain Named Database.
  4. Click on the database in the list of Registered DB Names.
  5. Change the Dictionary Location to the location on the shared disk.
  6. Change the Data File Locations to the location(s) on the shared disk.
  7. Click OK.

Creating a Database With the PCC

Before using the PCC, you need to create a directory on the shared disk. This will be the location of the database files. After you create the directory, run the Create Database Wizard in the PCC to create a database. Specify the directory on the shared disk as the directory location for the database.

After you create a database, ensure that the DSNs are set for each cluster node. The easiest way to do this is to copy SYS:ODBC\odbc.ini and SYS:SYSTEM\dbnames.cfg from the hosting node to each of the other nodes.

For example, suppose that node NW_CLUSTER_A is hosting the shared disk, which is named NW_CLUSTER_OBJECT_SERVER. You create a directory named CLUSTERDB on VOL1 of the shared disk.

With the Create Database Wizard, you create a new database named Clustertest. For directory, specify the volume and directory name, not a mapped drive letter. Continuing with our example, you would specify the following:

After the database is created, copy odbc.ini and dbnames.cfg from the SYS volume of NW_CLUSTER_A to the other nodes.

As an alternatives to copying the odbc.ini and dbnames.cfg files to each node, you could manually create the DSNs on the remaining nodes. How you achieve the end result does not matter as long as all nodes contain identical information about the database.

To test the transactional connection from a Pervasive.SQL client

  1. Connect a drive on a client workstation with a Pervasive.SQL client to the shared disk subsystem.

    Example:

    From a command prompt on a client workstation, execute the following command:

    net use X: \\nw_cluster_object_server\vol1

    This example connects drive "X" to volume one on the shared disk.

  2. Copy the sample database DEMODATA (the DEMODATA folder) from the controlling cluster node to the cluster shared disk. (This step is not required if you already have a Pervasive.SQL database on the cluster shared disk. These steps assume that you do not.)

    By default, DEMODATA is located at SYS:\PVSW\DEMODATA.

  3. At a command prompt on the client workstation, execute the following command (using drive X as an example):

    butil -stat x:\demodata\file.ddf

    If the command executes successfully, the Pervasive.SQL client is communicating with the database on the cluster shared disk. A successful execution returns information such as file version, page size, total number of records, and so forth.

    The next two steps, 4 and 5, require that you have administrator authority.

  4. In ConsoleOne, click on the cluster object in the left pane, then click View --> Cluster State. In the right pane, click on Location.

    The Cluster Resource Manager dialog appears.

  5. Click on a migration target, then click Migrate. For example, the following image shows NW_Cluster_B as the migration target.

    The migration target becomes active and assumes control of the shared disk. In the ConsoleOne interface, you will see the location change to the migration target and the number of lives (#Lives) increment by one.

  6. After the migration, execute the following command from the client workstation (using drive X as an example):

    butil -stat x:\demodata\file.ddf\file.ddf

    If the command executes successfully, the Pervasive.SQL client is communicating with the database on the cluster shared disk. A successful execution returns information such as file version, page size, total number of records, and so forth.

To test the relational connection from a Pervasive.SQL client

  1. Connect a drive on a client workstation with a Pervasive.SQL client to the shared disk subsystem.

    From a command prompt on a client workstation, execute the following command:

    net use X: \\nw_cluster_object_server\vol1

    This example connects drive "X" to volume one on the shared disk.

  2. Create a directory on the cluster shared disk named DEMODATA2.
  3. From the controlling cluster node, copy all of the files from the directory of the sample database DEMODATA to the DEMODATA2 directory. By default, DEMODATA is located at SYS:\PVSW\DEMODATA.
  4. In the PCC name space, right-click on the Databases node for the server name of the cluster shared disk. Click Create Database to start the Create Database wizard.
  5. Complete the Create Database wizard. For database name, type in DEMODATA2. For directory, type in VOL1:\DEMODATA2. (Capitalization does not matter.)

    The wizard creates the engine DSN for the database. You next use the ODBC Administrator to create the client DSN.

  6. Open the ODBC Administrator. For example, on Windows NT, click Start 4 Settings 4 Control Panel, then double-click ODBC Data Sources. You may also open the ODBC Administrator from within the PCC by clicking Tools 4 ODBC Administrator.
  7. Click the System DSN tab.
  8. Click Add. The Create New Data Source dialog appears.
  9. In the list, click Pervasive ODBC Engine Interface.
  10. Click Finish. The Pervasive ODBC Engine DSN Setup dialog appears.
  11. For Data Source Name, type in DEMODATA2. For Address, type in the server name of the shared disk. The following example shows that the server name of the shared disk is NW_CLUSTER_OBJECT_SERVER.
  12. Click the Get DSN List button.
  13. Select DEMODATA2 in the list.
  14. Click Test. A successful test indicates that the client DSN is communicating with the engine. Click OK to dismiss the Test Connection message box.
  15. Click OK to close the Pervasive ODBC Client DSN Setup dialog.
  16. Click OK to close the ODBC Data Source Administrator dialog.
  17. From the server that is hosting the shared disk, copy SYS:\ODBC\odbc.ini and SYS:\SYSTEM\dbnames.cfg to the other cluster nodes. (Alternatively, you could migrate to each cluster node and create the DEMODATA2 DSN on that node.)

    The next two steps, 18 and 19, require that you have administrator authority.

  18. In ConsoleOne, click on the cluster object in the left pane, then click View --> Cluster State. In the right pane, click on Location.

    The Cluster Resource Manager dialog appears.

  19. Click on a migration target, then click Migrate. For example, the following image shows NW_Cluster_B as the migration target.

    The migration target becomes active and assumes control of the shared disk. In the ConsoleOne interface, you will see the location change to the migration target and the number of lives (#Lives) increment by one.

  20. Open the ODBC Administrator.
  21. Click the System DSN tab.
  22. Double-click the DEMODATA2 DSN. The Pervasive ODBC Client DSN Setup dialog appears.
  23. Click Test. A successful test indicates that the client DSN is communicating with the engine. Click OK to dismiss the Test Connection message box.
  24. Click OK to close the Pervasive ODBC Client DSN Setup dialog.
Prev
Microsoft Cluster Service 		Up
Check for Revisions 		Next
SFT III for NetWare 4.2


SFT III for NetWare 4.2

SFT (System Fault Tolerance) is a means of protecting data by providing ways to automatically recover from hardware failures. SFT provides three levels of protection; each level includes the previous levels. The levels, respectively, are hot fix, disk mirroring, and server mirroring.

Server mirroring involves two identical servers directly connected by a mirrored server link. If the hardware of the primary server fails, a secondary server continues to network services without any network downtime. The secondary server maintains the same memory image and the same disk contents as the primary server. When the secondary server takes over, all files, services, and applications remain available to network clients.

SFT level three (SFT III) is an add-on service to NetWare 4.2. Install and configure SFT III as directed by the Novell documentation. Note the following, however:

  • Novell no longer sells SFT III
  • SFT III requires the IPX/SPX protocol
  • The Novell NetWare Client is required to connect to the SFT III server or the Monitor utility in the PCC does not display information correctly

Pervasive.SQL V8 supports SFT III. You may use the transactional and relational access methods and all Pervasive.SQL interfaces. No special configuration or special licensing of the Pervasive.SQL server engine is required for use with SFT III.

Install Pervasive.SQL V8 only on the mirrored server (the primary). You do not install it on both the primary and the secondary server.

Prev
NetWare Cluster Services 		Up
Check for Revisions 		Next
Workgroup Engine in Depth


Workgroup Engine in Depth

Technical Details and Advanced Procedures for the Workgroup Engine

This chapter explains how to get the most out of your Workgroup engine.

  • Networking
  • Technical Differences Server vs. Workgroup
  • Troubleshooting Workgroup Issues
  • Re-directing Locator Files
Prev
SFT III for NetWare 4.2
Check for Revisions 		Next
Networking


Networking

Both the server and workgroup products are shipped with the same networking components. So you can upgrade a workgroup engine to a server engine. The client side requestors can connect to either type of engine.

NetBIOS

The Pervasive Network Services Layer searches for an engine on the network using NetBIOS as well as the other protocols previously supported; Named Pipe, DNS, and NDS, and NetWare Bindery. The NetBIOS and DNS protocols can be used to contact a workgroup engine. Server engines on Windows advertise themselves with Named Pipes, so NetBIOS is not needed. NetWare servers are advertised using DNS, NDS, and NetWare Bindery.

Even though SPX can be used on Windows 95/98/ME, it cannot be used by itself since these platforms do not use it as a connection protocol, only as a transfer protocol. On Windows, NetBIOS must be bound to SPX/IPX in order to resolve the SPX address.

Once the client requestor has found an IP, SPX or NetBEUI address, it will try to establish a connection to a MicroKernel engine using that transfer protocol.

MicroKernel Router Decision Algorithm

The client side MicroKernel router discovers Gateway ownership of files by following a well-established algorithm.
Table 10-1 Gateway Discovery Priorities
Priority | Procedure
1 | Try to connect to a database engine on the same computer as the data files.
2 | Try to open the data files using the local engine (on the client machine).
3 | Find and connect to the Gateway engine that owns the files.

The first thing the client-side router always tries is to connect to an engine on the same computer as the data. Because of this procedure, it is always more efficient to have an engine running where the data is.

Because the Pervasive Network Services layer uses so many different methods to find and connect to a remote database engine, there may be a time delay on the first attempt to open a file on a file server that does not have a database engine running. If Gateway Durability is turned on, that connection will not be attempted thereafter because the router remembers each machine on which it fails to locate an engine.

If the router cannot connect to an engine on the remote file server, the router then allows the local engine to attempt to open the remote files. The local engine first attempts to create a new locator file and take ownership of the remote directory. If the directory is already owned by another MicroKernel, the local engine returns Status Code 116 to the router.

Finally, the router attempts to discover the Gateway computer. It opens the locator file and reads the name of the Gateway engine. Then it sends the request to that engine. Notice that the router never tries to read a locator file unless it has received Status Code 116 from a MicroKernel first. This behavior means that in order to use the Gateway feature, you must have a local workgroup engine installed. If the attempt to open the remote files with the local engine fails because there is no local engine, the router does not try to read the locator file and no Gateway engine is found.

Prev
Workgroup Engine in Depth 		Up
Check for Revisions 		Next
Technical Differences Server vs. Workgroup


Technical Differences Server vs. Workgroup

There are a few significant differences between a server engine and a Workgroup engine. This section explains the differences.

Platforms

The NetWare and Linux engines are server engines only. Our Windows server engine requires Windows NT or Windows 2000. The Workgroup engine runs on any 32 bit Windows platform.

User Interface

While the Windows server engine runs as a service, the Workgroup engine is started as a regular process that has a tray icon for an interface. It must be put into the startup folder if there is local data to be shared.

Network Connections

The Windows server engine can use Named Pipes for operating system level file security and establishing connections. Since Windows 98/ME does not allow the creation of named pipes, the workgroup engine uses NetBIOS as a connection protocol.

Authentication and Btrieve Security Policies

The server engine enforces file permissions set up in the operating system. The Workgroup engine does not authenticate users on its own. With the Workgroup engine, if you can see the computer on the network, you can get to the data. This relaxed security is intended for small offices where security is not an issue and ease of use is.

A behavior difference between the Server and Workgroup engines with regard to this lack of OS authentication on the part of the Workgroup engine is that the Mixed security policy for Btrieve is the same as the Classic security policy.

Gateway Support

The Windows server engine creates locator files in remote directories where it opens files. This behavior allows it to be a designated gateway for remote files. The workgroup engine creates locator files everywhere it opens files, allowing the workgroup engine to dynamically adjust gateway ownership on a day-to-day basis.

User Counts

The server engines start at 10 concurrent connections and the Workgroup engine starts at 5.

Asynchronous I/O

The server engine for Windows makes use of Asynchronous I/O. This feature can provide a significant performance advantage.

Runs as Service

The server engine for Windows is installed as a Windows Service. The Workgroup engine is not. However, if you wish to run the Workgroup engine as a service on Windows NT/2000, the following Pervasive Knowledge base articles explain how:
Platform | KB Article URL
Windows Server | http://support.pervasive.com/eSupport/publisher.asp?id=60670968-b40a-11d4-b20d-00508b5d6b61
Windows 98/ME | http://support.pervasive.com/eSupport/publisher.asp?id=64b7ab3f-be4f-11d5-b25a-00508b5d6b61

Note that the engine does not have a tray icon when started this way, because at the time of start-up, the "tray" has not been created.

Caution
Running the Workgroup engine as a service is not officially supported by Pervasive Software and has not been officially tested.

Prev
Networking 		Up
Check for Revisions 		Next
Troubleshooting Workgroup Issues


Troubleshooting Workgroup Issues

This section provides a few tips on troubleshooting problems in a Workgroup environment.

Time delay on first connection

If you are regularly experiencing a delay when the first file-open request is issued, see if these techniques help.

If possible, make sure there is an engine running where the data is

Connecting to an engine on the same machine as the data is the client's first priority when deciding where to send a file-open request. In order to make sure a workgroup engine is running, put an engine icon into the startup folder with the command

C:\Pvsw\Bin\W3dbsmgr.exe -SRDE

Another option on Windows 98/ME is to run the engine as a service. For more information, refer to Runs as Service .

If you are running a gateway topology

If you cannot run an engine where the data is, then the time delay during the first connection is a more important issue. Here are a few things you can do.

  1. Reduce the supported protocols in the client settings so that protocols that are not used in your network are not attempted. For example, if you do not have a NetWare MicroKernel on the network, which is true for most workgroup topologies, you can drop SPX/IPX as a supported client protocol.
  2. Use Gateway Durability. Gateway Durability is a client configuration setting that allows you to virtually eliminate the delay in making the first connection in a gateway environment. If Gateway Durability is turned on, it forces the client router to write into the registry the names of computers it finds that do not have an engine running. Once a failure to connect happens, instead of remembering this server name only while the router is running in-process, it saves the name in the registry. The next time the application starts up, it does not try to connect to the engine where the data is. It immediately goes to the next step of determining the identity of the current Gateway.

    You can turn this setting on in PCC. Within PCC, double-click the icon representing the client computer. Double-click Configuration. Double-click Client. Click Access. Right-click on Gateway Durability and set it to On.

 Note
This feature is OFF by default since it fixes the topology. If you add a server engine or a Workgroup engine where the data is, you must turn this setting back to OFF on each of the clients where you turned it ON. Turning the setting off erases the registry of computers without an engine running, so you can turn it back ON immediately and a new list will be generated based on the new topology.

Status Code 116

Status 116 is a MicroKernel Status Code which means that the file is being used by another MicroKernel engine acting as a Gateway. If your application receives a status code 116, it means that the MicroKernel router can read the locator file but cannot contact the engine running on the gateway computer.

The first thing you need to do is find out who the gateway is. You can perform this task with the Gateway Locator utility.

Next, use PSA network tests to try to connect to that computer. PSA can provide valuable information to isolate the problem.

One situation when this could occur is when the two computers are separated by a router such that they can both see the file server but they cannot see each other.

Prev
Technical Differences Server vs. Workgroup 		Up
Check for Revisions 		Next
Re-directing Locator Files


Re-directing Locator Files

This feature of Gateway engine operation guarantees transaction atomicity for multi-directory databases and also makes it easy to change the name of a Gateway engine across multiple data directories.

Limitations of Previous Model

Prior versions of the product supported two modes of Workgroup Gateway operation:

  • a permanent Gateway database engine always serves the data files in a given directory—if the specified database engine is not up, then the data in that directory is not available.
  • with a dynamic Gateway, whichever database engine opens the data files first serves as the Gateway; this architecture is also referred to as a floating Gateway.

This model was useful but had two limitations. First, if you had data in many different directories, and you wanted to change the permanent Gateway to a different engine, you had to use the Gateway Locator Utility to update the Locator File in every data directory (or update all the Locator Files by hand).

Second, if you had a single database consisting of data files in more than one directory, it became possible for two different engines to handle data access within the same database, thus failing to ensure transaction atomicity. This situation could occur if the Gateway Locator files in the two directories pointed to different Gateway engines. For some users this may not be an issue, but transaction durability can only be guaranteed if a single database engine performs all data access operations on a given database. If transaction durability is important, then you must ensure that the same engine services all data files within the same database, regardless of their directory locations.

New Behavior

First, recall that the Pervasive.SQL client uses the following approach to access remote data files:

  • First, attempt to connect to a database engine on the same computer as the data files.
  • Second, if no database engine is available on the remote machine, attempt to use a local engine to take ownership of the remote directory and create a Locator File. If a Gateway Locator File already exists, the local engine is not used.
  • Third, try to use the specified Gateway engine.

It is important to remember that the Gateway configuration only goes into effect when there is no database engine available on the same computer as the data files.

This feature allows a dynamic (floating) Gateway engine while at the same time preserving transaction durability for multi-directory databases on the same volume. This benefit is provided by a new type of Gateway Locator File that points to another Gateway Locator File. The new type is called a Redirecting Locator File. By having Redirecting Locator Files in directories A, B, and C that point to the Locator File in directory D, you can ensure that the Gateway engine specified by the Locator File in directory D services data files in the other directories as well.

Regardless of whether the Locator file in directory D specifies a permanent Gateway or is dynamically created by the first engine to open those files, this architecture ensures that all the specified directories use the same Gateway engine. Likewise, if you decide to change the permanently assigned Gateway engine for several directories, Redirecting Locator Files allow you to do so by changing only one Locator File, rather than all of them. Thus, it is possible to specify that all data files on a given hard drive must use the same Gateway engine, with or without designating a permanent Gateway.

Redirecting Locator File Requirements

The first line of a Redirecting Locator File must start with "=>" and be followed by a path specifying another Locator File, which must be on the same drive. You can use any combination of forward slash and back slash in the path name. All slashes are converted to the type of separator used by the local operating system.

If your specified path ends with a slash, the database engine assumes the default Locator File name (~PVSW~.LOC) and appends it to the path. If the specified path does not end with a slash, the database engine assumes that the path already contains the file name.

The table below lists the ways a Redirecting Locator File path can be specified:
Table 10-2 Redirecting Locator File Path Descriptions
Path | Meaning
=>\path_name | Specifies the path from the root of the drive where the current Locator File is stored.
=>.\path_name | Specifies the path relative to the current directory.
=>..\path_name | Specifies the path relative to the parent directory of the current directory.

You can assign multiple levels of redirection to these Locator Files. For example, you can have the first Locator File pointing to a second Locator File, the second Locator File pointing to a third Locator File, and so on. Each workgroup engine opens each Locator File sequentially, looking for the actual Gateway name. It stops searching once it has found the locator file that does not start with "=>". The engine then assumes this Locator File specifies the Gateway engine.

Creating Redirecting Locator Files

As with any Locator File, a Redirecting Locator File is a plain text file. You can create Redirecting Locator Files by hand or programmatically. A Redirecting Locator File must be flagged as read-only, or it will be overwritten by the first engine to attempt to access the data files in that directory.

To Create a Redirecting Locator File

  1. Open Notepad or a text editor, and open a new text file.
  2. Decide where you are going to save the file when you are finished. You will save the file in the same directory as the data files which you want to redirect to another locator file.

    For example, if you want to ensure that the data files in C:\data are accessed by the same Gateway engine as other data files, then you will want to keep in mind the folder C:\data.

  3. Type in => and the path name of the next Locator File. Continuing the example from the previous step, if you want the current data files in C:\data to be owned by the Gateway engine specified in the Locator File located in c:\moredata, then you would type the following:
    =>..\moredata\ (recommended) or
=>\moredata\ (not recommended)

      In the first case, you are specifying a relative path from the current directory. In the second case, you are specifying an absolute path from the root of the current drive. In this particular example, both cases resolve to the same target directory.

Note
Pervasive strongly recommends that you use relative path names (starting with ./ or ../) in your Redirecting Locator Files, and that you use the same share names on all workstations to access the same data. Following these two recommendations can prevent errors that may occur with network path name resolution over mapped drives.

  4. Save the file as ~PVSW~.LOC in the directory where the data files exist that you want to specify a Gateway engine for.
  5. Close Notepad or the text editor.
  6. Flag the text file as read-only.

    To mark the file as read-only on Windows, you can use the Properties dialog box (right-click on the file icon) in Windows Explorer, or you can use the ATTRIB command in a DOS session or in a program:

    ATTRIB +R ~PVSW~.LOC

To synchronize many data directories on a permanent Gateway

  1. Either by hand or by using the Gateway Locator program, create a read-only (permanent) Locator File that does not redirect. It must specify a Workgroup engine to use as the Gateway.

    For example, your locator file may specify the computer named "workgroup1" as the Gateway engine, and the file may be located in C:\DATA\DB1.

  2. For each of the other data directories that you want to use the Gateway engine specified in the previous step, you need to create a Redirecting Locator File in that directory. Each Redirecting Locator File must point to the file you created in the previous step.

    Continuing the example, each Redirecting Locator File in C:\DATA\DB2 and C:\DATA\DB3 would then contain the following text:

    =>..\DB1\

    This causes any engine reading this file to follow the relative path and search the specified directory C:\DATA\DB1 for another Locator File. In this case, the specified directory contains a Locator File that names "workgroup1" as the Gateway computer.

To synchronize many data directories on a dynamic Gateway

  1. Follow the steps above, only in step #1, ensure that the Locator File is writable, not permanently-assigned.

    In this case, remember that if no engines are accessing any data files in the redirecting hierarchy, then there will be no Locator File in the target directory. This is normal. The dynamic Locator File is created each session by the first engine to access the data, and the file is deleted when the last user session ends. It is permissible to have Redirecting Locator Files that point to a data directory that has no Locator File in it. In this case, the first engine to open those data files creates the Locator File.

Example

Using the example Locator Files shown in Figure 10-1, the Redirecting Locator File on the left forces the database engine to go up one directory, then look in the sub-directory newdir for another Locator File with the default name (~PVSW~.LOC). This Locator File, in turn, specifies that the Workgroup engine on the computer named ntserver1 is the correct Gateway engine. As a result, the database engine on ntserver1 is used to access the data files in the directory mydir.

Figure 10-1 Redirecting Locator File Example

Prev
Troubleshooting Workgroup Issues 		Up
Check for Revisions 		Next
Accessing Data on NetWare using Workgroup Engine


Accessing Data on NetWare using Workgroup Engine

Accessing remote data on a Novell NetWare server using a Workgroup engine running on a Windows workstation presents a special challenge because every NetWare server has some version of Btrieve or Pervasive.SQL server running on it already.

Without taking special steps, any attempt to use a Workgroup engine to access data on a NetWare server may result in one of the following errors:

  • Status Code 116: The file is owned by another Microkernel engine acting as a Gateway
  • Status Code 85: The file is locked
  • Status Code 12: The Microkernel cannot find the specified file.

The Best Choice

The most reliable, lowest maintenance, and fastest way to resolve this issue is to access the data using the server engine running on the NetWare server. Using the existing server engine is likely to save you many headaches in the future. You may need to purchase an additional user count license for the server, because it normally has only 2 permanent user licenses available, and these are used by NetWare itself. Before choosing to use Workgroup engines instead of the server engine, you should carefully evaluate your situation to make certain that you are unable or unwilling to make use of the NetWare server engine.

Using the Workgroup Engine

If you cannot use the server engine given your particular scenario, then the only way to make sure that Workgroup engines can access the remote data files successfully is to write the NetWare server into the Gateway Durability registry key located on all workstations that have Workgroup engines expected to access the remote data. By making each Workgroup engine believe that there is no server engine running on the remote server, you can provide access to the data files on the server. The Registry key information is provided below. You must substitute the actual name of your NetWare server for "myserver":

[HKEY_LOCAL_MACHINE\Software\Pervasive Software\Microkernel Router\Version 8\Settings]
"Gateway Durability"="yes"
"NumServNotRunning"=dword:00000001
"ServNotRunning0"="myserver"

Isn't there Another Way?

Simply turning on the Gateway Durability feature does not achieve the same purpose, because a server engine is in fact running on the NetWare server, so it will not be added to the saved list of computers where no database engine is available.

You cannot solve this problem by creating a permanent gateway locator file in the directory where the data resides. The server engine does not recognize gateway locator files, so it will take ownership of those files if given the chance, and thus prevent any Workgroup engine from acting as a Gateway engine.

In addition, you cannot solve this problem by setting the client configuration setting Use Remote MicroKernel Engine to Off at each workstation. Any Workgroup engine that happens to have this setting turned On will cause problems. If this "On" engine is the first to access the data, it will connect to the NetWare server engine, locking out all other workstations that have this setting turned Off. The other workstations receive status 12 or 116. If this "On" engine is not the first to connect, then the server engine will not be able to open the files, returning status 85 to this "On" engine. Finally, if all workstations have Use Remote MicroKernel Engine set to Off, then none of them will be able to connect to whatever computer is eventually established as the Gateway engine.

Manually editing the Registry is the only sure way to access data on a NetWare server without using the Pervasive.SQL server engine on that computer.

Prev
Re-directing Locator Files 		Up
Check for Revisions 		Next
Monitoring Database Resources


Monitoring Database Resources

Using Monitor to Oversee Database Resources

This chapter includes the following sections:

  • Monitor Utility Overview
  • Setting Monitor Utility Options
  • Monitoring MicroKernel Resources
  • Monitoring SQL Interface Resources
Prev
Accessing Data on NetWare using Workgroup Engine
Check for Revisions 		Next
Monitor Utility Overview


Monitor Utility Overview

The Monitor utility allows you to monitor Pervasive.SQL activities on a server. It provides information that is useful for both database administration and application programming diagnostics. Monitor supports monitoring of the ODBC communications server as well as MicroKernel attributes. Features include:

  • Display users (connected via ODBC Client), client info (host name, IP address, application), data source name, connection info (status, connection time, active/idle period)
  • Auto-refresh of user/connection info

Note
These features require authentication to view remotely.

The following table shows the versions of the Monitor utility and the supported platforms.
Monitor Utility | Supported Platforms
Win32 | Windows NT servers Windows 98/ME and Windows NT clients

Starting the Monitor Utility

The Monitor utility provides a "snapshot" of server activity at a recent point in time. How recent the snapshot is depends on the polling interval. For information on how to set the polling interval, see Setting Monitor Utility Options .

To start Monitor

  1. From the Start menu, click Programs 4 Pervasive.SQL V8 4 Other Utilities 4 Monitor. You can also select the Monitor from the Pervasive Control Center Tools menu.

Figure 11-1 Monitor Utility Main Dialog Box

When you start the Monitor utility, it connects to the local engine by default. However, you can also monitor remote server engine resources by connecting to the remote server.

 Note
If dialog boxes are currently open in the Monitor utility window, you cannot connect to or disconnect from a remote server. Close the open dialog boxes before proceeding.

To connect to a remote server

  1. Choose Connect on the Options menu. The Connect to Remote Server dialog box appears, as shown in Figure 11-2 .

Figure 11-2 Connect to Remote Server Dialog Box

  2. Enter the server name in the Server Name box, along with your user name and password for that server. To be authenticated, you must have full administrator-level rights on the machine where the database engine is running or be a member of the Pervasive_Admin group on the machine where the database engine is running.
  3. To disconnect from a server, choose Disconnect on the Options menu.
Prev
Monitoring Database Resources 		Up
Check for Revisions 		Next
Setting Monitor Utility Options


Setting Monitor Utility Options

To configure the Monitor utility options

  1. Choose Settings from the Options menu. The Monitor Settings dialog box appears, displaying the current settings.

Figure 11-3 Monitor Settings Dialog Box

  2. You can specify the following options:
    Save Settings on Exit
    Select this check box to save all configuration settings when you close the Monitor utility. The Monitor utility saves both the settings in this dialog box and the automatic-refresh option in the various dialog boxes.
    Save Window Layout on Exit
    Select this check box to save the state (open or closed) and screen location of all open windows. When you start the Monitor utility again, these windows are automatically opened and positioned for local file server monitoring. This enables you to easily reproduce your preferred layout.
    NOTE: A user connecting to a remote system must first close all windows which are open.
    Refresh Rate (Seconds)
    Specifies the time interval with which the Monitor utility's display refreshes itself. The refresh rate is measured in seconds. The default setting is 4. You can enter integer numbers only.
    It is important not to set this number too low, or the monitor utility will refresh itself frequently, affecting the performance of your database engine. This is especially true if you are running the Monitor utility local to your engine.
  3. Click OK to save the settings or Cancel to close the dialog box without saving changes.
Prev
Monitor Utility Overview 		Up
Check for Revisions 		Next
Monitoring MicroKernel Resources


Monitoring MicroKernel Resources

This section describes the following options for monitoring the MicroKernel:

  • Setting Screen Refresh Options
  • Viewing Active Files
  • Viewing User Information
  • Viewing MicroKernel Resource Usage

Viewing MicroKernel Communications Statistics Setting Screen Refresh Options

You can refresh the information in the Monitor utility dialog boxes either automatically or manually, as follows.

  • Automatically: select the Automatic Refresh check box. The utility updates the dialog boxes at the Refresh Rate specified in the Monitor options (available via Settings on the Options menu).
  • Manually: Click Refresh.

Viewing Active Files

To view active MicroKernel files

  • Choose Active Files from the MicroKernel menu. The MicroKernel Active Files dialog box appears, as shown in Figure 11-4 . This dialog box shows all the active files for the MicroKernel.

Figure 11-4 MicroKernel Active Files Dialog Box

In the upper left of the dialog box, the Monitor utility displays the Active MicroKernel Files list. This scrollable list contains the complete path of all open files in alphabetic order.

To view more information about a particular file

  • Select the desired file in the list. View the information in the lower left corner of the window.

    In the upper right of the MicroKernel Active Files dialog box, the Monitor utility displays the Selected File's Handles list. This scrollable list contains the active handles (users) associated with the selected file. Each handle is represented by a user name (typically the login ID of the user), or by an index into the engine's client (user) list.

To view more information about a particular user

  • Select the desired user in the Selected File's Handles list.

    Some handles have an agent identifier, a two letter code that specifies the application that initiated the session.

    Table 11-1 lists the agent IDs used by Pervasive.SQL components.

    Table 11-1 Agent IDs

    Agent ID
    Application or Component
    BT
    Maintenance utility for the Btrieve 7.0 (BUTIL)
    DE
    Database Services client
    DC
    Database Services login
    DR
    DOS client Requester
    ML
    MicroKernel logging and roll forward
    NR
    Win32 client Requester
    NX
    Maintenance utility for the Scalable SQL 4.0 (SQLUTIL)
    PU
    Pervasive.SQL utilities
    SC
    Scalable SQL 4.0 login
    SE
    SQL Interface
    WR
    Windows client Requester

    The File Information box displays detailed information about the selected file. The Handle Information box displays detailed information about the selected handle.

File Information

The File Information box displays the following information about each file:
Page Size | Indicates the size in bytes of each page in the file.
Read-Only Flag | Indicates whether the file is flagged as read-only by the operating system.
Record Locks | Indicates whether any of the active handles for the selected file have record locks. Any application can read a locked record, but only the application that placed the lock can modify or delete the record. A record lock exists only as long as the application that opened the file is updating a record. Yes indicates that one or more record locks are applied to the file; No indicates that no records are locked.
Transaction Lock | Indicates whether any of the active handles for the selected file have a transaction lock. A transactional file lock exists only as long as the application that opened the file is processing a transaction.

Handle Information

The Handle Information box displays the following information about each file:
Connection Number
Displays the network connection number of the client. If the client does not have a network connection, this field displays NA (for not applicable).
Task Number
Displays the process-supplied task number for processes originating at the server, or a Windows client. If the process originates at a DOS client, this field contains the communications protocol socket number.
Site
Specifies the location of the user process (local or remote).
Network Address
Identifies the location of the calling process on the network. If the calling process is SPX, then network node/network address is preceded by S: such as S: 65666768 00000000001. If the calling process is TCP/IP, the dotted-decimal notation of the IP number is preceded by T: such as T: 180.150.1.24.
Open Mode
Indicates the method the application uses to open the specified handle of the file. Valid open modes are:
Normal—The application that opened the file has normal shared, read/write access to it.

Accelerated—The application that opened the file has shared read/write access.

Read-only—The application that opened the file has read-only access; it cannot modify the file.

Exclusive—The application that opened the file has exclusive access. Other applications cannot open the file until the calling application closes it.

The Monitor utility also specifies all open modes as non-transactional or shared locking when applicable.
Record Lock Type
Displays the type of record lock(s) currently held by the handle. The possible record lock types are Single, Multiple, and None.

Single-record locks enable a user to lock only one record at a time. Multiple-record locks enable a user to lock more than one record at a time.
Wait State
Indicates whether the user is waiting due to some type of lock on this handle: Waits for Record Lock, Waits for File Lock, or None.
Transaction State
Displays the state of the transaction lock currently held by the handle. The possible transaction types are Exclusive, Concurrent, or None.

Viewing User Information

You can view a list of current users and files, as well as file handles for each user.

To view MicroKernel user information

  • Choose Active Users on the MicroKernel menu. The MicroKernel Active Users dialog box appears, as shown in Figure 11-5.

Figure 11-5 MicroKernel Active Users Dialog Box

In the upper left of the dialog box, the Monitor utility displays the Active MicroKernel Users list. This scrollable list contains the names of active users in alphabetic order. Each user is represented by a user name (typically the login ID of the user) or by an index into the engine's client (user) list.

To receive more information about a particular user

  • Highlight the desired user in the list.

    Each client is represented by either a user name (typically the login ID of the user) or an index into the engine's client (user) list. Table 11-1 lists the agent IDs used by Pervasive.SQL components. SeeUser Information for specific details about the information available.

    In the upper right of the MicroKernel Active Users dialog box, the Monitor utility displays the Selected User's Handles list. This scrollable list contains the active handles (files) associated with the selected user. The MicroKernel creates a handle each time a user opens a file; therefore, a single user can have several handles for the same file.

To view more information about a particular file handle

  • Highlight the desired handle in the list. SeeHandle Information for specific details about the information available.

User Information

The User Information box displays the following detailed information for the selected user handle:
Connection Number | See Connection Number .
Task Number | See Task Number .
Site | See Site .
Network Address | See Network Address .
Locks Used | Indicates the number of locks the user is currently using.
Transaction State | Displays the type of transaction lock the user currently holds. The possible transaction types are Exclusive, Concurrent, or None.
Records Read | Displays the number of records read since the user first opened a file.
Records Inserted | Displays the number of records the user has inserted.
Records Deleted | Displays the number of records the user has deleted.
Records Updated | Displays the number of records the user has updated.
Disk Accesses | Indicates the number of times the user required a disk access. You will not see any information for disk accesses for files that have just been opened.
Cache Accesses | Displays the number of times the user required a cache access.

Handle Information

When you click on a specific file handle, the following information about that handle is displayed in the lower right corner of the window:
Open Mode | See Open Mode .
Record Lock Type | See Record Lock Type .
Wait State | See Wait State .
Transaction State | See Transaction State .

Deleting Current Users

To delete a user

  • Highlight the user name and click Delete Current User button. Deleting the current user removes the user from the list of active users of the MicroKernel and terminates the user's connection to the Communications Server. All open files for the user are closed and all allocated resources are freed.
  • You can also click Delete All Users which deletes all of the current MicroKernel users.

Viewing MicroKernel Resource Usage

To view MicroKernel resource usage

  1. Choose Resource Usage from the MicroKernel menu. The MicroKernel Resource Usage dialog box appears, as shown in Figure 11-6 .

Figure 11-6 MicroKernel Resource Usage Dialog Box

This dialog box allows you to view the total resources in use by the MicroKernel since it was loaded.The MicroKernel Resource Usage dialog box shows the following statistics for each resource:

  • Current – Shows the present value for the field.
  • Peak – Shows the highest value for the field since the MicroKernel was started.
  • Maximum – Shows the highest value allowed for the field.

Note
The maximum values for most of these parameters are controlled dynamically by the engine. The maximum value is shown for backwards compatibility purposes only.
Files
Indicates the number of active files.
Handles
Indicates the number of active handles. The MicroKernel creates a handle each time a user opens a file; therefore, a single user can have several handles for the same file.
Clients
Indicates the number of clients accessing the MicroKernel. A workstation can have multiple clients accessing the engine simultaneously. You set the maximum for this field with the Configuration utility (see Active Clients ).
Worker Threads
Indicates the number of concurrent MicroKernel processes.
Licenses in Use
Indicates the number of connected client licenses in use as defined by your licensing agreement. In this case, the maximum shows the number of users your licensing agreement allows.
Transactions
Indicates the number of transactions. The maximum for this field is unlimited.
Locks
Indicates the number of record locks. The maximum for this field is unlimited.

Viewing MicroKernel Communications Statistics

To view MicroKernel communications statistics

  1. Choose Communications from the MicroKernel menu. The MicroKernel Communications Statistics dialog box appears, as shown in Figure 11-7. This dialog box shows you the network requests, worker threads, and sessions in use by the Communications Server since it was loaded.

Figure 11-7 MicroKernel Communications Statistics Dialog Box

The MicroKernel Communications Statistics dialog box shows the following statistics for several of the communications resources:

  • Current – Shows the most recent value for each field.
  • Peak – Shows the highest value for the field since the Communications Manager was started.
  • Maximum – Shows the highest value allowed for the field.

    You can monitor the activity of the following communications resources in the MicroKernel Communications Statistics dialog box:
    Total Requests Processed
    Indicates the number of requests the Communications Manager has handled from workstations or remote, server-based applications.

    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    SPX Requests Processed
    Indicates the number of SPX requests the Communications Manager has handled from clients or remote, server-based applications.

    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    TCP/IP Requests Processed
    Indicates the number of TCP/IP requests the Communications Manager has handled from clients or remote, server-based applications.

    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    NetBIOS Requests Processed
    Indicates the number of NetBIOS requests the Communications Manager has handled from clients or remote, server-based applications.

    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    Connection Timeouts
    Indicates the number of times the Auto Reconnect feature has timed out when attempting to reconnect to clients.
    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    Connection Recoveries
    Indicates the number of times the AutoReconnect feature has successfully recovered from a connection timeout.
    Total – Indicates the number of requests processed since the Communications server was loaded.

    Delta – Indicates the number of requests since you first invoked the Communications Statistics dialog box. To reset this number to zero, click Reset Delta.
    Communication Threads
    Indicates the number of remote requests that the MicroKernel is currently processing. Local requests are not included in this statistic. For the total number of remote and local threads being processed, see the Resource Usage dialog box. You set the maximum for this field with the Configuration utility (the Communications Threads option ).

    Worker threads are also used to process Monitor utility requests, so you may not see the number of current worker threads drop below one. This is normal.
    Total Remote Sessions
    Indicates the number of remote clients connected to the Communications Manager. The maximum number is dynamic and displays as zero.
    SPX Remote Sessions
    Indicates the number of remote clients connected via SPX to the Communications Manager.
    TCP/IP Remote Sessions
    Indicates the number of remote clients connected via TCP/IP to the Communications Manager.
    NetBIOS Remote Sessions
    Indicates the number of remote clients connected via NetBIOS to the Communications Manager.

Prev
Setting Monitor Utility Options 		Up
Check for Revisions 		Next
Monitoring SQL Interface Resources


Monitoring SQL Interface Resources

This section describes the following options for monitoring the Relational Database Engine:

  • Monitoring Active SQL Connection Manager Sessions
  • Understanding Session Information
  • Refreshing the Active Session List
  • Deleting an Active Session

Monitoring Active SQL Connection Manager Sessions

To view active SQL Connection Manager Sessions:

  1. Choose Active Connections from the SQL menu on Monitor's main screen.
  2. The SQL Connection Manager Active Sessions window appears, as shown below.

Figure 11-8 SQL Connection Manager Active Sessions Dialog Box

Understanding Session Information

The SQL Connection Manager Active Sessions dialog box contains information about connected users, data sources, and applications in use.

The top Active Sessions label displays the number of active SQL Connection Manager sessions. The User Name list box displays the list of connected user names. User Name is set by default to the Windows login ID. If this is unavailable, User Name is set to "unknown".

More information about the selected User Name is displayed in the Session Information group box. By default, it displays the following information about the user:
Client Host Name | This is the client's machine or host name of the selected User Name. If unavailable, this is set to "Unknown."
Network Address | This is the client's IP or SPX address for the selected User Name. If unavailable, this is set to "Unknown."
Client Application | This is the connected application or module. If unavailable, this is set to "Unknown."
Data Source Name | This is the name of the engine DSN referenced by the client application.
Connection Status | This is the connection status for the selected User Name. A possible status may be "Active", "Idle", "Dying", or "Unknown" if status is unavailable.
Active/Idle Period | This refers to the duration of time, in milliseconds, since the connection has been active or idle.
Total Connection Time | This refers to the duration of time, in seconds, since the connection has been established.

Refreshing the Active Session List

  1. Click Refresh Session List or enable the Automatic Refresh checkbox.
  2. To change the Automatic Refresh rate, choose Settings from the Options menu on Monitor's main dialog box. The Monitor Settings dialog box appears, as shown below. The default refresh rate is 4 seconds.

Figure 11-9 Monitor Settings Dialog Box

Deleting an Active Session

  1. Select the session to be deleted by clicking on the desired user name in the User Name list box.
  2. Click Delete Session and the SQL Connection Manager deletes the selected session.

Note
If a large SQL statement is being processed by an active session when you terminate it, the session may be temporarily listed as "Dying." The session should disappear from the display when the engine reaches an appropriate termination point.

Prev
Monitoring MicroKernel Resources 		Up
Check for Revisions 		Next
Testing Btrieve Operations


Testing Btrieve Operations

How to Perform Btrieve Operations with the Function Executor Utility

This chapter discusses the following topics:

  • Function Executor Concepts
  • Function Executor GUI Reference
  • Function Executor Tasks
Prev
Monitoring SQL Interface Resources
Check for Revisions 		Next
Function Executor Concepts


Function Executor Concepts

This section contains the following topics:

  • Overview
  • What Function Executor Can Do
  • Features Unique to the Win32 Function Executor
  • Automatic Mode in 32-bit Function Executor
  • Where to Learn More

Overview

The 16-bit and 32-bit Function Executors run on Win16 and Win32 platforms for the Pervasive.SQL Server and Workgroup products. With these interactive utilities, you can learn how Btrieve operations work. By allowing execution of Btrieve operations one at a time, the Function Executors enable application developers to simulate the operations of a Btrieve application. This simulation can isolate the database calls from the rest of your application, which can help in testing and debugging your program.

The Function Executors are primarily tools for application developers; this chapter assumes a basic knowledge of Btrieve operations. For more information about Btrieve operations, refer to the API Programmer's Reference that is available with the Pervasive.SQL Software Developer's Kit (SDK).

What Function Executor Can Do

  • Perform Btrieve operations while monitoring the contents of memory structures.
  • Allow you to capture a series of Btrieve operations and save them as a history file for later playback
  • Display the Btrieve version for clients, and local and remote engines.
  • Display the Btrieve characteristics of data files and allow you to save those characteristics as a template (description file) or create a new file based on those characteristics. See File Statistics GUI Reference for more information.

Features Unique to the Win32 Function Executor

The Win32 version of the Function Executor includes all the functionality of the Win16 utility as well as some additional features. Many ways of performing familiar Win16 operations are different in the Win32 version. These include the features listed below.

  • Editor Status Bar
  • Statistics
  • Get and GetExt
  • Transaction Toolbar
  • Login Dialog
  • History Log
  • Viewing as Any Data Type

Editor Status Bar

The status bar contains these elements:

The last/current status code is shown in the editor window's status bar at the bottom of the window for the open file, and appears red if the last status was not zero.

Placing the mouse cursor over the status code shows a description of the status and what operation caused it. You can also click on the display in red in order to display the full help for the status code. See To get help for a status code for more information.
When your cursor is in the input area on the main window of the Function Executor, the status bar displays the offset within the buffer: the hex, the decimal, and the ASCII value of the byte you are presently on.
The status bar also indicates how many operations have been performed when there are multiple items in the queue. Normally this displays 1 of 1, but if you are executing multiple operations, it will display the count as the operations are executed.
The status bar also displays when you are in a transaction.

Statistics

Clicking on the File Statistics icon displays a dialog box listing the currently-open file's statistics. You can print these statistics to a text file or save them to a description file usable by BUTIL -CREATE (you may also create a new blank file with the same characteristics.) Previously, these items had to be manually picked out of the data buffer after executing a Btrieve operation 15.

Get and GetExt

From the Get menu, you can retrieve the First, Next, Previous, and Last records in the table. The GetExt menu includes the Goto Percent, Get Position, and Find Percent commands.

The Get and GetExt commands are available from both the menu bar and toolbar. The toolbar offers Step (Physical) and Get (Logical), allowing you to move either through the natural order of the file (Physical) or in a specific order (Logical).

Goto Percent allows you to choose whether to jump to a point within the physical layout of the file, or down any key path, limited to the keys defined in the file. You can also set lock biases using the option buttons in the Locks group box.

Find Percentage is the opposite of Goto Percent. It tells you how far into the data you are, depending on whether you are stepping through the file logically or physically.

Transaction Toolbar

The Transaction toolbar lets you start, stop, and abort transactions. You can set all aspects of the Transaction API through this toolbar, and the operation is executed immediately. The Transaction status also appears on the main window status bar, since it affects all open files for the client ID.

Login Dialog

The Login dialog allows you to perform the Btrieve login operation via a GUI interface.

See the following topics for more information about the Login dialog:

  • Login GUI Reference
  • Login Tasks
  • Pervasive.SQL Databases
  • Pervasive.SQL Security

History Log

When you perform operations using the Function Executor utility, they are recorded in a History log. You can use this log to perform the operations contained therein, or save the history as a file that you can later reload and step through.

See the following topics for more information about the History log:

  • History GUI Reference
  • History Tasks

Viewing as Any Data Type

When a file is open, you can right-click on any position in the buffer and select Show As. A dialog appears in which you can view the bytes at the chosen buffer position as any data type.

Table 12-1 lists controls available only in the Win32 version of the Function Executor.
Table 12-1 Win32-Only Function Executor Controls
Control | Description
Repeat | Allows you to repeat commands.
Create | Allows you to create a new file.
File Statistics | Gives information from the BSTAT function. You can print these statistics.
MDI | The Multiple Document Interface permits the opening of multiple files.
Reset | Reset Client ID
Stop | Btrieve Stop
Version | Btrieve Version

Automatic Mode in 32-bit Function Executor

For each open file (see Application Window (32-Bit) ), you have the option of performing Btrieve operations with or without the assistance of Function EXECUTOR. You do not need to make any configuration changes to use one method or the other. Whether you use automatic mode or manual mode depends on which GUI elements you use as shown in Figure 12-1.

Figure 12-1 Automatic Mode vs. Manual Mode

 Note
Selections from the menus (see Application Window (32-Bit) ) also are part of the automatic mode.

When you click a button in the automatic area, the following assistance is provided by the utility:

  • Data buffers are set automatically to prevent Status code 22.
  • Assumptions are made about certain operations. For example, if you select continuous operations from the menu, Function Executor assumes that it should put the file in focus under continuous operations; it does not require that the Data Buffer

Where to Learn More

The Function Executor is a valuable tool for program developers, but it assumes you have a working knowledge of Btrieve fundamentals. You should have knowledge of the following before attempting to understand all the features of this utility:

  • Btrieve Fundamentals in Pervasive.SQL Programmer's Guide

    http://www.pervasive.com/library/index.asp?_pub=GDE&_topic=BTRIEVE_FUNDAMENTALS

  • Btrieve Operations reference in API Programmer's Reference

    http://www.pervasive.com/library/index.asp?_pub=API

  • For information about security models for Btrieve:

    Pervasive.SQL Security

Prev
Testing Btrieve Operations 		Up
Check for Revisions 		Next
Function Executor GUI Reference


Function Executor GUI Reference

This section describes the objects on the Function Executor graphical user interface (GUI).

  • Application Window (32-Bit)
  • Application Window (32-Bit)
  • Main Window (16-Bit)

The following GUI features are only present in the 32-bit version.

  • Login GUI Reference
  • Open File Dialog GUI Reference
  • Create a File Dialog GUI Reference
  • Create a File Dialog GUI Reference (Advanced)
  • Transactions GUI Reference
  • File Statistics GUI Reference
  • History GUI Reference

Application Window (32-Bit)

Click on an area of the image to learn more.

GUI Object
Description
Related Information
File menu
Allows you to perform the following commands and Btrieve operations:
  • Login
  • Logout
  • Open
  • Close
  • New
  • Print Setup
  • Set Owner
  • Clear Owner
  • Start Continuous Operations
  • End Continuous Operations
  • Reset
  • Stop
  • Exit
  • Performing Operations Tasks
  • Opening a File Tasks
  • Login Tasks
Get menu
Allows you to perform the following Btrieve operations:
  • Get First
  • Get Next
  • Get Previous
  • Get Last
  • Get Greater Than
  • Get Greater or Equal
  • Get Less
  • Get Less or Equal
Performing Operations Tasks
GetExt menu
Allows you to perform the following Btrieve operations:
  • Goto Percent
  • Get Position
  • Find Percent
Performing Operations Tasks
Step menu
Allows you to perform the following Btrieve operations:
  • Step First
  • Step Next
  • Step Previous
  • Step Last
Performing Operations Tasks
Updates menu
Allows you to perform the following Btrieve operations:
  • Insert
  • Update
  • Delete
You can also release locks using this menu.
Performing Operations Tasks
View menu
Allows you to display GUI elements:
  • Toolbars (main and transactions)
  • History window
  • File statistics window
  • Engine version using the Btrieve Version operations
  • History Tasks
  • File Statistics Tasks
Tools menu
Allows you to perform the following Btrieve operations:
  • Get Directory
  • Set Directory

Window menu
Allows you to perform windowing operations:
  • Cascade windows
  • Tile windows
  • Select from a list of open windows

Help menu
Allows you to select from a list of help resources for this utility.
To get help for a status code
Open button
Displays the Open File dialog so that you can select a Btrieve file to open.
Opening a File Tasks
Create button
Displays the Create New File dialog so that you can create a new Btrieve file.
Creating a Btrieve File Tasks
Reset button
Resets the current client connection (Btrieve operation 28) and closes all files opened with that client ID.

Stop button
Terminates transactional services (Btrieve operation 25) and closes all open files.

Statistics button
Displays a dialog box listing the currently opened file's statistics. You can print these statistics to a text file or save them to a description file usable by BUTIL -CREATE
File Statistics Tasks
Version button
Displays information about the version of Pervasive.SQL (using Btrieve operation 26) that you are running. If no file is open, you will see information about the requester DLLs and any local MicroKernel engine. If you open a file on a remote server, you will see information about the server and requester DLLs.

Status Codes Help button
If no file is open, displays Status Codes help file.
If file is open and a status code is active, displays help for that particular status code.

Show help button
Toggles whether a pop-up dialog displays when a non-zero status code is received.

Show history button
Toggles whether the History window is displayed.
  • To display the History window
  • History GUI Reference
  • History Log
Operation count
Indicates the current operation number.
This is used when you set the Repeat to a value greater than one.
Performing Operations Tasks
Transaction state
Indicates the current state of any transactions. Can be:
  • Blank, if no transaction is in effect
  • Concurrent
  • Exclusive
  • Performing Operations Tasks
  • Transactions GUI Reference

Main Window (32-Bit)

A main window displays for every open file. Click on an area of the image to learn more.

GUI Object
Description
Related Information
Title Bar
Lists the full path of the open data file.
To open a data file with the Win32 Function Executor:
Data Buffer
Specifies a data value. For read and write operations, the Data Buffer contains records. For other operations, the Data Buffer contains file specifications, filtering conditions, and other information the MicroKernel needs for processing the operation. This control corresponds with the Data Buffer parameter.

Key Buffer
Specify the path for the data file for which you want to perform a Btrieve operation.

Step vs. Get
Toggles between Step and Get operations

Get/Step First
Performs the Get or Step Next operation
Performing Operations Tasks
Get/Step Prev
Performs the Get or Step Previous operation
Performing Operations Tasks
Get/Step Next
Performs the Get or Step Next operation
Performing Operations Tasks
Get/Step Last
Performs the Get or Step Last operation
Performing Operations Tasks
Get Equal
Performs the Get Equal operation
Performing Operations Tasks
Get Less Than
Performs the Get Less Than operation
Performing Operations Tasks
Get Greater Than
Performs the Get Greater Than operation
Performing Operations Tasks
Get Less or Equal Than
Performs the Get Less or Equal Than Operation
Performing Operations Tasks
Get Greater or Equal Than
Performs the Get Greater or Equal Than Operation
Performing Operations Tasks
Get/Find Percent
Performs the Get or Find Percent operations
Performing Operations Tasks
Insert
Performs the Insert operation
Performing Operations Tasks
Update
Performs the Update operation
Performing Operations Tasks
Delete
Performs the Delete operation
Performing Operations Tasks
Cancel
Cancels the recent changes

Unlock
Releases any locks.

Set or Goto Bookmark
Sets or positions at a previously defined bookmark.

Key Num
For most Get operations, specifies a key number, or index path, to follow for the current operation. For other operations, specifies such information as file open mode, encryption, or logical disk drive. This control corresponds with the Key Number parameter.

Key Only
Specifies to get key only, not data.

Repeat
Repeats the operation the number of times you specify.

Locks
Specifies the locking behavior you want in for the current operation.

Op Code
Specifies the current operation code plus its bias (if any). The default is 0. If you are familiar with Btrieve operation codes, you can enter the desired code. Otherwise, use the List box to specify an operation. This control corresponds with the Operation Code parameter.
Performing Operations Tasks
Execute button
Performs the currently specified operation.
Performing Operations Tasks
Operations list
Lists all Btrieve operations and their codes. The default is Open (0). You can move quickly through the list by entering the first letter of the operation you want to perform.
Performing Operations Tasks
DataLen
Specifies the length (in bytes) of the Data Buffer. The default is 1024. For every operation that requires a data buffer, you must specify a buffer length. On many operations, the MicroKernel returns a value to the Data Length. Generally, you should always specify a Data Length before you execute an operation. This control corresponds with the Data Buffer Length parameter.
Performing Operations Tasks
Status Code Indicator
Displays a numeric status code returned by the MicroKernel and a brief message explaining the result of a Btrieve operation.
For detailed information about these status codes and messages, refer to the Status Codes and Messages manual.
To get help for a status code
Continuous Operations Indicator
Displays the following on the bottom row of the file window if the file is in Continuous Operations mode (operation 42).
  • Using Continuous Operations

Main Window (16-Bit)

Click on an area of the image to learn more.

Table 12-2 lists the controls available in the Win16 version of the Function Executor. Some of the controls correspond to Btrieve operation parameters.

Table 12-2 Win16 Function Executor Controls

GUI Element
Description
Related Information
File
Lists the full path of all open data files and displays the current open file. You can move among open files, but you cannot open a file using this box. To open a file, refer to .
This control corresponds with the Position Block parameter. Because each file name represents a position block, a file name can appear more than once in the list if the file has been opened more than once.
  • To start the Win16 Function Executor utility
  • To open a data file with the Win16 Function Executor:
Transaction
Indicates whether the current operation occurs inside a transaction and the type of transaction, as follows:

Exclusive – Exclusive transaction.
Concurrent – Concurrent transaction.
Conc+ModLk – Concurrent transaction with Modify Lock (+500) bias.
Performing Operations Tasks
Operation

Current
Specifies the current operation code plus its bias (if any). The default is 0. If you are familiar with Btrieve operation codes, you can enter the desired code. Otherwise, use the List box to specify an operation. This control corresponds with the Operation Code parameter.
Performing Operations Tasks
Last
Displays the code of the last operation that was executed on the current file.
Performing Operations Tasks
List
Lists all Btrieve operations and their codes. The default is Open (0). You can move quickly through the list by entering the first letter of the operation you want to perform.
To open a data file with the Win16 Function Executor:
Get Key Bias (+50)
Instructs the MicroKernel to return only a key value, not a data record, on the current Get operation.

Modify Lock Bias (+500)
Instructs the MicroKernel to set a no-wait lock bias on an insert, update, or delete operation executed within a concurrent transaction.

Read Lock Bias
Adds one of five biases to the current operation, as follows. For files in exclusive transactions, the MicroKernel ignores any lock bias values you specify explicitly.

No Lock – Performs no locking. (Default)
Single Wait (+100) – Attempts to lock a single record; if the record is already locked, it waits until the record is free.
Single No Wait (+200) – Attempts to lock a single record and returns control if the record is already locked.
Multiple Wait (+300) – Attempts to lock multiple records in the same file; if the records are already locked, it waits until the records are free.
Multiple No Wait (+400) – Attempts to lock multiple records in the same file and returns control if the records are already locked.

Key

Number
For most Get operations, specifies a key number, or index path, to follow for the current operation. For other operations, specifies such information as file open mode, encryption, or logical disk drive. This control corresponds with the Key Number parameter.

Buffer
Specify the path for the data file for which you want to perform a Btrieve operation.

Position
Indicates the position of the cursor within the Key buffer.

Hex Display
Click this check box to view the data in Hex format.

Clear
Click this button to clear the buffer field so that you can enter another data file.

Data

Length
Specifies the length (in bytes) of the Data Buffer. The default is 1024. For every operation that requires a data buffer, you must specify a buffer length. On many operations, the MicroKernel returns a value to the Data Length. Generally, you should always specify a Data Length before you execute an operation. This control corresponds with the Data Buffer Length parameter.

Buffer
Specifies a data value. For read and write operations, the Data Buffer contains records. For other operations, the Data Buffer contains file specifications, filtering conditions, and other information the MicroKernel needs for processing the operation. This control corresponds with the Data Buffer parameter.

Position
Indicates the position of the cursor within the Key or Data Buffer.

Hex Display
Click this check box to view the data in Hex format.

Clear
Click this button to clear the buffer field so that you can enter another data file.

Status
Displays a numeric status code returned by the MicroKernel and a brief message explaining the result of a Btrieve operation. For detailed information about these status codes and messages, refer to the Status Codes and Messages manual.

Execute
Performs the currently specified operation.
Performing Operations Tasks

Note
The Win16 version of the utility performs wait lock simulation. Win16 applications cannot go into a wait loop. If you ask for a record lock using a Wait Bias and the record is locked by someone else, the engine returns Status Code 84 or 85 immediately to the application.

The Win16 Function Executor utility retries the operation until it gets the record or you click Abort which is displayed in the lower right corner of the Main window.

Login GUI Reference

This dialog allows you to perform the Btrieve login operation using a graphical interface to specify the database URI. Click on an area of the image to learn about this dialog.

GUI Object | Description | Related Information
Server | Specifies the server where the database you wish to login to resides. | Login Tasks
Database | Specifies the database on the server to which you want to authenticate. | Login Tasks
User Name | The user name you want to authenticate against the database. | Login Tasks
Password | The password for the user name. | Login Tasks
Client ID | If you want this login to apply to a specific client ID, click Use and specify the range. Otherwise, leave as-is. | Login Tasks
URI String | As you enter information in the forms, the URI resulting from your selections is shown in this area. | Login Tasks
Login button | Click Login to attempt the Btrieve login information using the URI specified. | Login Tasks

Open File Dialog GUI Reference

This dialog allows you to open a file with a graphical interface. Click on an area of the image to learn about this dialog.

GUI Object | Description | Related Information
Filename | Specifies the server where the database you wish to login to resides. | Opening a File Tasks
Owner name | Specifies the database on the server to which you want to authenticate. | Opening a File Tasks
Mode | The user name you want to authenticate against the database. | Opening a File Tasks
Client ID | If you want this login to apply to a specific client ID, click Use and specify the range. Otherwise, leave as-is. | Opening a File Tasks
Sharing | As you enter information in the forms, the URI resulting from your selections is shown in this area. | Opening a File Tasks
Open button | Click Login to attempt the Btrieve login information using the URI specified. | Opening a File Tasks

Create a File Dialog GUI Reference

This dialog allows you to open a file with a graphical interface. Click on an area of the image to learn about this dialog.

GUI Object | Description | Related Information
Filename | Specifies the server where the database you wish to login to resides. | Creating a Btrieve File Tasks
Owner name | Specifies the database on the server to which you want to authenticate. | Creating a Btrieve File Tasks
Mode | The user name you want to authenticate against the database. | Creating a Btrieve File Tasks
Client ID | If you want this login to apply to a specific client ID, click Use and specify the range. Otherwise, leave as-is. | Creating a Btrieve File Tasks
Sharing | As you enter information in the forms, the URI resulting from your selections is shown in this area. | Creating a Btrieve File Tasks
Open button | Click Login to attempt the Btrieve login information using the URI specified. | Creating a Btrieve File Tasks

Create a File Dialog GUI Reference (Advanced)

This dialog allows you to open a file with a graphical interface. Click on an area of the image to learn about this dialog.

GUI Object | Description | Related Information
Filename | Specifies the server where the database you wish to login to resides. | Creating a Btrieve File Tasks
Owner name | Specifies the database on the server to which you want to authenticate. | Creating a Btrieve File Tasks
Mode | The user name you want to authenticate against the database. | Creating a Btrieve File Tasks
Client ID | If you want this login to apply to a specific client ID, click Use and specify the range. Otherwise, leave as-is. | Creating a Btrieve File Tasks
Sharing | As you enter information in the forms, the URI resulting from your selections is shown in this area. | Creating a Btrieve File Tasks
Open button | Click Login to attempt the Btrieve login information using the URI specified. | Creating a Btrieve File Tasks

Transactions GUI Reference

This dialog allows you to control transactions during your Function Executor session. Click on an area of the image to learn about this dialog.

GUI Object | Description | Related Information
Main application window | Main features of the program. | See Application Window (32-Bit)
Transaction type | Specifies whether you want an exclusive or concurrent transaction. |
Lock information | Specifies the type of locking you want in the transaction. |
Start transaction button | Starts a transaction. |
Commit transaction button | Commits the active transaction. |
Abort transaction button | Cancels the active transaction and rolls back any changes made. |
File area | This area contains one or more open files. | See Main Window (32-Bit)
Transaction indicator | Indicates whether you are currently in a transaction. If you are in a transaction, this display will show either Concurrent or Exclusive. |

File Statistics GUI Reference

This dialog allows you to see all the operations you have performed. Click on an area of the image to learn about this dialog.

GUI Object
Description
Related Information
File information
Displays statistical information about the file.
File Statistics Tasks
Flags
Allows you to view the flags set for this file. Any flag that is set will have a checkmark next to its listing in the dialog.
File Statistics Tasks
Keys
Allows you to view the keys defined in this file.
File Statistics Tasks
Key legend
Describes the single letter values that indicate Key attributes for the file.
  • D = DUP (Duplicatable)
  • M = MOD (Modifiable)
  • R = REPEAT_DUPS_KEY (repeating duplicates key)
  • A= NUL (All segment Null key)
  • L = MANUAL_KEY (any segment null key)
  • < = DESC_KEY (descending key value)
  • I = NOCASE_KEY (case-insensitive key)
  • Key Attributes in Pervasive.SQL Programmer's Guide, which is part of the Pervasive.SQL Software Developer's Kit (SDK).
Print button
Allows you to print the file statistics. Set up the printer using the File menu.
File Statistics Tasks
Disk button
Allows you to save the current file statistics to a description file, which you can later use to make a new file with the same characteristics.
File Statistics Tasks
Exclamation point (create new file)
Allows you to create a new file based on these file statistics.
File Statistics Tasks

History GUI Reference

This dialog allows you to see all the operations you have performed. Click on an area of the image to learn about this dialog.

GUI Object
Description
Related Information
File menu
Allows you to perform the following operations:
  • Import a history file
  • Export a history file
  • Close the history window

Settings menu
Allows you to specify the visual attributes of the History window.
  • Save on Exit - specifies whether you want your customization of the History window to be saved between sessions.
  • Defaults - Resets the History window to default settings. This removes any settings you specified.
  • Docked - Toggles the state of the History window between a separate window and one that is attached to the Application Window (32-Bit) .
  • Stay On Top- toggles the state of the History window between one that can lose focus and one that cannot.
  • To toggle the docking status of the History window
  • To toggle the Always On Top status of the History window
  • To reset the History window to default settings
Execute command
Loads the History Playback window

List of operations
Lists operations that you have recently performed. Each operation is logged with the following information:
  • FileID
  • Operation name or number depending on the status of the OpCodeNames checkbox.
  • Status code when that operation was performed
  • Number of times that operation was performed.
  • Key number set for the operation.
  • Contents of the key buffer.
  • Contents of the data buffer.
  • History Tasks
  • History GUI Reference
Logging
Toggles the inclusion of future operations in the history list.

OpCode Names
Toggles the display in the Operation column between operation code names (such as B_OPEN) and operation code numbers (such as 0 for B_OPEN)

Prev
Function Executor Concepts 		Up
Check for Revisions 		Next
Function Executor Tasks


Function Executor Tasks

The Function Executor tasks are grouped into the following categories:

  • Starting Function Executor Tasks
  • Performing Operations Tasks
  • Opening a File Tasks
  • Creating a Btrieve File Tasks
  • Login Tasks
  • File Statistics Tasks
  • History Tasks

Starting Function Executor Tasks

  • To start the Win32 Function Executor utility:
  • To start the Win16 Function Executor utility

To start the Win32 Function Executor utility:

  1. Click Start 4 Programs 4 Pervasive.SQL V8 4 Other Utilities 4 Function Executor.
    • Alternatively, you can access the Function Executor from within the Pervasive Control Center. Click on Tools and select Function Executor.
  2. The main window (Figure 12-2) appears.

Figure 12-2 32-bit Function Executor Main Window

To start the Win16 Function Executor utility

  1. Find the \bin directory where Pervasive.SQL is installed.
  2. Run wbexec.exe.
  3. The main window (Figure 12-3) appears.

Figure 12-3 16-bit Function Executor Main Window

Performing Operations Tasks

Because Btrieve provides many operations, this chapter cannot explain them all. The following sections discuss some common operations as well as some new ways of performing them with the Win32 Function Executor.

Note
In the Win16 Function Executor, to perform an operation, specify values for the appropriate controls and click Execute. In the Win32 Function Executor, selecting options from all menus performs the intended operation immediately. It does not fill in the grid and wait for you to execute the command as the Win16 Function Executor does. Also, closing the form in the Win32 Function Executor closes each open file. This is new; the Win16 Function Executor forces you to do the close operation manually.

General Operations-Related Tasks

  • To get help for a status code

For other tasks, see these sections:

  • Opening a File Tasks
  • Creating a Btrieve File Tasks
  • Login Tasks
  • File Statistics Tasks
  • History Tasks

To get help for a status code

  1. When a status code is received using the 32-bit Function Executor, it is displayed on the status bar of the open file.

    Move your mouse so it hovers over the status code that is displayed in red.

Figure 12-4 Status Code Received

  2. If you click on the status code indicator, the full documentation for the status code is displayed as shown in Figure 12-5.

Figure 12-5 Status Code Documentation

Opening a File Tasks

To open a data file with the Win16 Function Executor:

  1. Select Open (0) from the List box or enter 0 in the Current box.
  2. Enter the path of a data file in the Key buffer.
  3. [Optional] Enter the owner name into the Data buffer.
  4. [Optional] Enter the Open Mode into the key number.
  5. Click Execute or press Enter.

To open a data file with the Win32 Function Executor:

  1. From the File menu, select Open. The following dialog box appears:

Figure 12-6 Open Btrieve File Dialog Box

.

 Note
Client ID: If you have Use disabled, the Function Executor will use a BTRV() function call. If Use is enabled, it will use a BTRVID() function call for each operation you execute on this file. With Auto enabled, the Function Executor will generate a client ID for you. If you have Auto disabled, then you may enter values manually.

  2. Click Browse.
  3. Double-click on the desired filename.
Other Ways to Open a File with Win32 Function Executor

1) You can drag a file from Windows Explorer or from an operating system folder view into the Open dialog. This step fills in the filename for you.

2) You can drag one or more files into the main window.

3) After opening one file (so you have the editor window available), you can use the OpCode 0 to open another file. The file will appear in a new window.

4) You can run Function Executor from the DOS command line and specify a list of filenames to open. For example, you could use the following command line to open two files from the DEMODATA sample database:

WBExec32 person.mkd billing.mkd

You can even use wildcard characters, as in the example:

WBExec32 *.mkd

Running this command allows you to associate file extensions (types) with Function Executor. For example, you can associate MKD, BTR, DAT, or any other extension with Function Executor. Thus, when you double-click the file in Explorer, it automatically opens the file with Function Executor.

Creating a Btrieve File Tasks

There are two options in creating a Btrieve file with the Win32 Function Executor. If a file is already open, you can clone it; otherwise you can start from scratch.

Method 1: Using a current file as a template
  1. From the File menu, select New. The following dialog box will appear:

Figure 12-7 Modify File Definition Dialog Box

  2. You can manipulate keys from this dialog as well. You can Add, Create, or Insert Segments from the Key menu. You can also save the new file as a description for use with BUtil create. Select Save As Desc and indicate the name and location where you would like the file saved.
  3. To create the file, click Create. This will open the file and display a message indicating success.
Method 2: Creating a new file from scratch
  1. Click the Create icon on the main toolbar; or, if no file is open yet, you may click File and then New, as before.
  2. If a file is already open on screen, a drop down box will appear. Choose Create New File from Scratch.
  3. The same dialog as before will appear, but it will be blank - allowing you to input brand new values.
  4. Start by adding a new Key using the Key menu - or press Ctrl-A.
  5. Fill in the attributes for the key in the lower section of the dialog.
  6. Continue adding or removing new keys and segments as desired, using the menus or right-clicking on the key in the list.
  7. Now click the Create button to execute the B_Create (14) operation. This will automatically open the file on screen as well.

Login Tasks

These procedures will be completed in a later release.

File Statistics Tasks

These procedures will be completed in a later release.

History Tasks

The following tasks are related to the History feature:

  • To display the History window
  • To toggle the docking status of the History window
  • To toggle the Always On Top status of the History window
  • To reset the History window to default settings

To display the History window

  1. Click View4History or click the History button.

To toggle the docking status of the History window

  1. If the History window is not visible, display it. (see To display the History window).
  2. In the history items window, right-click on the display and check or uncheck the Docked selection as shown in the following figure:

Figure 12-8 Undocking the History window

  3. When docked, the History window is connected to the application window as shown in Figure 12-8. When not docked, the History window is a distinct window. When undocked, the History window has menu items that duplicate the commands seen from the right-click menu in Figure 12-8.

To toggle the Always On Top status of the History window

  1. If the History window is not visible, display it. (see To display the History window).
  2. This feature only applies to the History window when it is in the undocked state. (see To toggle the docking status of the History window)
  3. In the history items window, right-click on the display and check or uncheck the Stays On Top selection.

To reset the History window to default settings

  1. If the History window is not visible, display it. (see To display the History window).
  2. In the history items window, right-click on the display and select Settings 4 Defaults.

Prev
Function Executor GUI Reference 		Up
Check for Revisions 		Next
Adding Relational Access to Btrieve Files


Adding Relational Access to Btrieve Files

How to Create Table Definitions for Existing Btrieve Files

This chapter explains how to make an existing Btrieve data file available to relational (SQL or ODBC) applications.

If you have an existing application that uses the transactional Btrieve interface to access data, and you would like to be able to access the same data using Pervasive Data Exchange, Microsoft ODBC Bridge for ADO, Microsoft Access, or other ODBC-based applications, then this chapter provides the information you need.

This chapter consists of the following sections:

  • How to Use this Chapter
  • Creating a Database
  • Associating a Data File with a Database
  • Building a Table Definition
Prev
Function Executor Tasks
Check for Revisions 		Next
How to Use this Chapter


How to Use this Chapter

Although this chapter is broken into several sections, it is designed to be read from front to back sequentially.

Note
Depending on the complexity of your application, this chapter may require that you have substantial knowledge of the internal record structure of your Btrieve data file.

Before you Begin

Make Sure it's Necessary

Before you follow the instructions provided in the remainder of this chapter, you must determine whether your data file is already enabled for ODBC/relational access.

To determine whether your data file is ODBC-enabled

  1. Inspect the folder or directory where your Btrieve file is currently located. If you see files named FIELD.DDF, FILE.DDF, and INDEX.DDF in this folder, then most likely your data file can already be accessed with ODBC.

Note
While most applications keep the DDFs in the same directory as the data files, storing them in the same location is not required. You may wish to search the same physical volume as the data files for one of the above mentioned DDF files, to be sure that you do not have DDF files available.

If this is the case, then you need only set up access to the database. Follow the instructions provided in Chapter 2 of Pervasive.SQL User's Guide.

Decide on Your Goal

Next, you must decide what you want to do. Do you want to build a brand new Pervasive.SQL database around an existing Btrieve file (or files), or do you want to add an existing Btrieve file as a new table in an existing Pervasive.SQL database?
If you want to do this ... | ... follow these instructions:
Create a brand new database around my Btrieve file | Creating a Database
Add your Btrieve file to an existing database | Associating a Data File with a Database

Prev
Adding Relational Access to Btrieve Files 		Up
Check for Revisions 		Next
Creating a Database


Creating a Database

This section explains how to create a new database for one or more existing Btrieve files.

If you wish to add a Btrieve data file to an existing relational database, please skip to the next section of this chapter, Associating a Data File with a Database.

To create a new database

  1. Follow the detailed instructions in Pervasive.SQL User's Guide Chapter 2, "Setting Up Database Access."

    During the above-mentioned procedure, you will be asked to specify the location of the database. You should specify the location of the existing Btrieve file(s) around which you wish to build a database.

  2. After creating the database, there are three DDF files in the same directory as your Btrieve files. These newly created DDFs are empty. You must now populate the DDFs with table definitions for your existing Btrieve files. The steps that follow will show you how to perform this task. Proceed to the next section of this chapter, Associating a Data File with a Database.
Prev
How to Use this Chapter 		Up
Check for Revisions 		Next
Associating a Data File with a Database


Associating a Data File with a Database

To add a Btrieve data file to a Pervasive.SQL database, you must associate the data file with a table definition in the database.

Tip
Moving your Btrieve file to the same directory as the other data files in the database can make database maintenance tasks easier. Do not move the file unless you can re-configure your existing Btrieve applications to be aware of the file's new location.

To create a table definition for a data file

  1. If you do not have Pervasive Control Center (PCC) open, start it now by choosing Start 4 Programs 4 Pervasive.SQL V8 4 Control Center.
  2. Double-click Pervasive.SQL Engines to show a list of engines registered with PCC. Next, double-click the icon representing your target engine, to show a list of the databases serviced by that engine.
  3. Right click on the database to which you want to add the Btrieve file. Choose New 4 Table. This step brings up the Create Table Wizard.

Figure 13-1 Create Table Wizard—Advanced Settings

  4. In the Create Table Wizard, enter the name you want to assign to the new table and click Use advanced settings, as shown in Figure 13-1, Create Table Wizard—Advanced Settings. The table name must be no more than 20 characters. It does not have to correspond to the data file name, although that is a good idea to help you remember which file corresponds to which table definition. Click Next.

Figure 13-2 Create Table Wizard—Specify Btrieve File

  5. In the next window, specify the Btrieve file for which you are creating a table definition. If you don't want to type the path, you may click ... to select the file. See Figure 13-2 Create Table Wizard—Specify Btrieve File. In the example screen, we are creating a table definition for the file person.mkd.
  6. Click Next to display "Columns and Indexes found in the Btrieve file" window, as shown in Figure 13-3.

    Your table name is now associated with the data file, but the table definition is still empty, except for any index definitions that were found. Do not exit the Create Table Wizard. Continue to the next section of this chapter, Building a Table Definition, for detailed instructions on using the remaining screens of the wizard to build a table definition for the specified data file.

Prev
Creating a Database 		Up
Check for Revisions 		Next
Building a Table Definition


Building a Table Definition

The table definition you have created is "empty"—it does not contain any information about the structure of the data file. You must now populate the table definition with specific information about the record structure of the data file. The Create Table Wizard guides you through this task by detecting certain structures within the data file, and helping you define the remaining field characteristics.

This section uses the Btrieve file PERSON.MKD as an example. This file is provided in the product as part of the "demodata" sample database.

Determining background information

Records in a Btrieve file can consist of any mixture of fixed-length and variable-length fields. In the physical file on disk, all the fixed-length fields and the pointer values for the variable-length fields are stored together. This is called the fixed-length portion of the record. The data contained in the variable-length fields is stored at the end of the fixed-length portion of the record, as a single large block of data.

You can determine whether the data file has at least one variable-length field by obtaining the file statistics on the Btrieve file using the Btrieve Maintenance Utility. Pervasive Software offers both a command-line and graphical version of the Btrieve Maintenance Utility. For the examples in this section, we chose to use the command-line Btrieve Maintenance Utility (BUTIL).

The following is an excerpt of the output produced by running the command BUTIL -stat on the PERSON.MKD file.

Total Number of Records = 1500
Record Length = 333
Data Compression = No
Variable Records = Yes
   Variable-Tail Allocation Tables = No
   Blank Truncation = No
Free Space Threshold = 5%
...

From this output, we can determine that at least one variable-length field is defined. From the Record Length specified, we can also determine the size of the fixed length portion of the record. You will use this information later.

Naming Known Fields

Btrieve files contain some information about field lengths and data types, indexes, and overall record length that must match the corresponding table definition. The Create Table Wizard analyzes this information to come up with definitions of the indexed fields in the file, as shown in Figure 13-3.

To name the indexed columns

  1. Continuing the Create Table Wizard steps from the previous section, the next window displays the columns and indexes that the wizard was able to discover in the file. See Figure 13-3 Create Table Wizard—Columns and Indexes Detected.

Note
In most cases, not all columns are displayed. The wizard can only detect columns that have indexes defined on them. This is the only method the wizard can use to gain information about the internal record structure of the file. As explained in the following steps, you must supply most of the information about the record structure.

Figure 13-3 Create Table Wizard—Columns and Indexes Detected

Name the columns appropriately according to your knowledge of the record structure. The maximum length for a column name is 20 characters. Click Next when you are finished.

 Note
If you are inspecting a Btrieve file that was created with Pervasive.SQL 2000 or later, each column that is allowed to have NULL values is preceded by a one-byte space that contains a NULL indicator value. You should not explicitly define these spaces as columns, however, you must allow for this extra byte when specifying the column offset. You should count this space as part of the column.

Note
If you use Btrieve Maintenance Utility to display field data about a Btrieve file, you must mentally subtract one (1) from the position values shown in Btrieve Maintenance Utility output to generate comparable offset values, as shown in the Create Table Wizard. This is because byte position one (1) in the record, as shown in Btrieve Maintenance Utility, corresponds to an offset of zero (0), as shown in the Create Table Wizard.

Caution If there are any field overlaps in your indexed columns, you cannot create a valid table definition for your Btrieve file without modifying the file. For example, in the sample definition, you would have a field overlap if there were an indexed field at offset 5 with length of 1 or more. This would overlap the bytes in the ID field, and possibly the First_Name field as well.

If you have overlapping field definitions and you want to have relational access to the data, then you must:
(1) remove any indexes from your Btrieve file that refer to overlapping fields, and
(2) modify your Btrieve application program logic to reflect the newly changed index definitions.

Typically you must separate the overlapping fields into multiple fields that do not overlap, and define an index (or segmented index) on these fields.

Defining Remaining Columns

To define the non-indexed columns

  1. The next screen is shown in Figure 13-4 Create Table Wizard—Specify Columns. This window shows you both the indexed columns as well as the gaps in the record structure that exist between the known columns. These gaps are named "unnamed_X" and their data type is currently "unknown."

Figure 13-4 Create Table Wizard—Specify Columns

The task now is to define the structure of the data in these undefined areas. Each area may contain one or more fields.

  2. In order to determine how to define these areas, you can inspect the actual contents of an undefined area by selecting the area and clicking the Split button:

Figure 13-5 Create Table Wizard—Split Columns

  3. The next window to appear is the Split Column window. This window allows you to view the data in an undefined area and determine where it should be split into separate fields.

    By default, the window shows hex codes for each byte of data in several rows of the data file. Click Ascii view to switch to a view that shows the hex codes as ASCII characters.

  4. Visually inspect the data in the Split Column window to determine where fields begin and end.
  5. Click in zero or more Split At checkboxes to specify where the additional columns should begin. Keep in mind it is possible that the space is all one field, so you may not click any checkboxes. See Figure 13-5 for an example. The first field appears to be zip code information, while the next field appears to be country information.

    If you know that you are defining columns that are nullable, split the columns by checking the box immediately prior to where the data starts. In the example shown, box 13 is checked because it is the null indicator position for the nullable "Country" information that begins in the next byte.

    Later, when you go back to the main window, remember to check the Null box for this field. Doing so creates the null indicator byte corresponding to box 13, and specifies that the actual data starts at the next position, as is correct.

    Click OK when you are ready to execute the split and go back to the main window.

  6. You may need to visit the Split Column window several times. You can also use the Merge button [image] to undo a split, if you split a column in the wrong place. You merge two or more adjacent columns into a single field by selecting the ones you want to merge and clicking the Merge button.
  7. Return to the main window and specify different data types if necessary, to achieve the desired display of column data in the main window.

    Remember, nullable fields have a one-byte null indicator at the beginning of the field. When you click Null to make a field nullable, the field's start position increases by one (allowing for the null indicator byte) and the field's length decreases by one byte (because the next field must still begin at the appropriate location). If you find that you have a number of fields that are off by one byte, check that you have the Null attribute set correctly for all the columns in question.

    Non-character columns may be difficult to interpret accurately. Columns of type BIT and LOGICAL may require a detailed knowledge of the record structure to define them properly.

    If you create a column of type BIT, eight columns are created automatically, one for each bit in the byte selected. If you do not have eight bit columns to be defined, simply select the extra columns and click the Delete button:

Note
If you are working through the fields sequentially from front to back and you reach a point where the Wizard won't allow you to define the columns correctly, you can try a couple other approaches:
1) Work through the remaining fields from back to front.
2) Define all the non-indexed fields in a gap area with a single use of the Split Column window. Do not define a few of the columns, return to the main window, then split again.

When you are satisfied that your entire column structure is correct, click Next in the main window.

Variable length fields

Variable-length fields require special mention. These must be specified as a blob data type, with a size of 8 bytes. The 8 bytes are actually a pointer value into an offset location in the variable-length portion of the record that comes after the fixed-length columns.

Summary of Sample

The table below summarizes the full contents of the PERSON.MKD example file, as deduced by the Create Table Wizard:
Table 13-1 Complete Field Definition for PERSON.MKD file
Field Name | Position | Size | Data Type
Student_ID | 1 | 8 | Unsigned
FirstName | 10 | 16 | Zstring
LastName | 27 | 26 | Zstring
PermStreet | 54 | 31 | Zstring
PermCity | 86 | 31 | Zstring
PermState | 118 | 3 | Zstring
Perm_Zip | 122 | 11 | Zstring
Perm_Country | 134 | 21 | Zstring
Street | 156 | 31 | Zstring
City | 188 | 31 | Zstring
State | 220 | 3 | Zstring
Zip | 224 | 11 | Zstring
Phone | 236 | 6 | Numeric
EmergencyPhone | 243 | 20 | Character
Unlisted | 263 | 1 | Bit
BirthDate | 265 | 4 | Date
EmailAddress | 270 | 31 | Zstring
Sex | 301 | 1 | Logical
Citizenship | 303 | 21 | Zstring
Survey | 324 | 1 | Bit
Smoker | 324 | 1 | Bit
Married | 324 | 1 | Bit
Children | 324 | 1 | Bit
Disability | 324 | 1 | Bit
Scholarship | 324 | 1 | Bit
Comment | 326 | 8 | blob

Generating a Table Definition

This section explains how to complete the task of creating a table definition, once you have finished creating definitions for all the columns in your Btrieve file.

To complete the task of creating a table definition

  1. After you complete all the field definitions and click Next, a new screen appears listing the SQL statement that creates the table structure you have defined. See Figure 13-6. Click Save... to save the SQL statement to a text file.

Figure 13-6 Create Table Wizard—Save SQL Script

It is recommended that you save the statement in case you need to reconstruct the table definition later, or in case you want to make minor changes to the table definition and then re-create it.

Click Next.

Figure 13-7 Create Table Wizard—Finish

  2. In the next screen, you must confirm whether you want the table definition to be created, as shown in Figure 13-7. Click Finish.

Verifying a Table Definition

You should verify the table definition after generating it. The verification process performs two tasks:

  • Verifies that the index definitions in the table match the index definitions in the Btrieve file.
  • Verifies that the field definitions match what you expect for your data.

To verify the database definition

In PCC, right-click the database to which you have just added the table definition, then choose Tasks 4 Check Database. The Check Database Wizard guides you through the steps to check your database definitions.

Conclusion

As you can see, creating a table definition for an existing Btrieve file can be a time-consuming, highly detailed task. However, when the task is complete, the result is a Btrieve file that can be accessed concurrently by both ODBC-based applications and Btrieve applications.

Prev
Associating a Data File with a Database 		Up
Check for Revisions 		Next
Manipulating Btrieve Data Files with Maintenance


Manipulating Btrieve Data Files with Maintenance

Handling Btrieve Files with the Maintenance Utility

This chapter discusses the following topics:

  • Maintenance Utilities Overview
  • Btrieve Interactive Maintenance Utility
  • Btrieve Command-Line Maintenance Utility (BUTIL)
Prev
Building a Table Definition
Check for Revisions 		Next
Maintenance Utilities Overview


Maintenance Utilities Overview

Pervasive.SQL provides both an interactive Maintenance utility and a command-line Maintenance utility. Both Maintenance utilities perform the following common file and data manipulations:

  • Create new data files based on file and key specifications you define.
  • Provide file and key specifications for existing data files.
  • Set and clear owner names for data files.
  • Create and drop indexes on data files.
  • Import and export ASCII sequential data.
  • Copy data between Pervasive.SQL data files.
  • Recover changes made to a file between the time of the last backup and a system failure.

While both utilities provide the same core functionality, minor differences exist. For example, the interactive Maintenance utility allows you to create description files based on file and key specifications you define. The command-line Maintenance utility allows you to start and stop continuous operation on a file or set of files locally on the server.

Before you use either Maintenance utility, you should be familiar with Btrieve fundamentals, such as files, records, keys, and segments. For information about these topics, refer to the Pervasive.SQL Programmer's Guide.

Note
The Pervasive.SQL product provides two categories of maintenance utilities: Btrieve and SQL. The SQL Maintenance Utility supports data source names (DSNs), which are used for relational access through ODBC. See Backing Up a Database with SQLUTIL for a discussion of the SQL Maintenance Utility.

Prev
Manipulating Btrieve Data Files with Maintenance 		Up
Check for Revisions 		Next
Btrieve Interactive Maintenance Utility


Btrieve Interactive Maintenance Utility

The Interactive Maintenance utility runs on Win16 (client/server only), and Win32 (Pervasive.SQL client/server and Workgroup products). Use this utility if you prefer a graphical interface or if you want to create a description file. This section contains the following major topics:

  • File Information Editor
  • Owner Names
  • Statistics Report
  • Indexes
  • Data

Each major topic contains tasks specific to that topic.

Extended File Support

The size of a MicroKernel data file can be larger than the operating system file size limit. When you export data from an extended MicroKernel file to an unformatted file, the size of the unformatted file can exceed the MicroKernel file size limit because of the differences in the physical format.

When you are exporting large files, the Interactive Maintenance utility detects that the unformatted file has exceeded the operating system file size limit (2 GB) and starts creating extension files. This process is transparent. Extension files and the original unformatted file must reside on the same volume. The extension file uses a naming scheme in which the file names are similar to the base file name. In contrast to native MKDE extension files which use a caret "^" to indicate extension file status, the unformatted extension files use a tilde "~" to avoid overwriting any existing extended MKDE files with the same base file name. The first export extension file is the same base file name with ".~01" extension. The second extension file is ".~02," and so on. These extensions are appended in hexadecimal format.

While the naming convention supports up to 255 extension files, the current maximum number of extension files is 32, thus supporting files as large as 64 GB.

Additionally, when you import data from an unformatted file, the utility detects whether the file has extensions and loads the data from the extension file.

Long File Names and Embedded Spaces Support

Long file name support, including support for embedded spaces is available in all supported operating system environments. All references to files can contain embedded spaces and be longer than 8 bytes.

Older versions of Btrieve allowed spaces to be added at the end of a file name in path-based operations such as Open and Create. This is still the default behavior. Existing applications will not break. However, if you want to take advantage of file and directory names with embedded spaces, use the Configuration utility to change the Embedded Spaces setting for the Btrieve Requester to "Yes." In the registry, you can locate this setting under:

HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive Software\BtrieveRequester\Version 8.0\Settings\Embedded Spaces.

Even when you turn the option "Off," an application that accesses a file having a name with embedded spaces can enclose that name in double quotes while making the BTRV/BTRVID/BTRCALL/BTRCALLID call to open or create the file.

Note
On NetWare, long file name support is available only in the MicroKernel and not in any of the other NLM utilities such as BUTIL.NLM. This means that Btrieve data files may be accessed using long names but long names cannot be used for any other kind of files. For example, in the NLM command:

BUTIL -CREATE <outputFile> <descriptionFile>

The <outputFile> being a Btrieve data file manipulated by the MKDE can have a long name but the <descriptionFile> must have only a short name as BUTIL.NLM does not understand long names.

The Btrieve Maintenance Utility Interface

You start the Btrieve Maintenance Utility by clicking Start 4 Programs 4 Pervasive.SQL V8 4 Other Utilities 4 Maintenance. The utility's main window displays as illustrated in Figure 14-1.

Figure 14-1 Btrieve Maintenance Utility Main Window

Menu Options

The interactive Maintenance utility provides the following menus:
Options | Allows you to display the File Information Editor, set and clear owner names, generate statistics reports, and exit the utility.
Index | Allows you to create and drop indexes.
Data | Allows you to load data from ASCII files, save data to ASCII files, copy records between data files, and perform a roll forward operation to recover changes made to a data file between the time of the last backup and a system failure.
Help | Provides access to the Maintenance utility help system.

Getting Help

To access the Maintenance utility help system, choose a command from the Help menu, as follows:
Getting Help | Explains how to use the Maintenance utility help system.
Index | Provides a list of Maintenance utility help topics.
Help on Help | Explains how to use the help system.
About | Displays copyright information and the version number. It also provides the version number of the MicroKernel Database Engine and Btrieve client Requester, if they are loaded.

In addition, you can display help for a particular dialog box by clicking the Help button contained in that dialog box.

Prev
Maintenance Utilities Overview 		Up
Check for Revisions 		Next
File Information Editor


File Information Editor

This section provides general information about the File Information Editor with which you can create new files based on file and key specifications you construct. Because this Editor allows you to load information based on an existing file, it is also useful for viewing file and key specifications on existing data files. You can also create a new file based on the file and key specifications of an existing file (similar to CLONE in the command-line Maintenance utility ).

You open the File Information Editor by clicking Options 4 Show Information Editor.

Figure 14-2 File Information Editor

File Information Editor Dialog Elements

At the top of the Editor, the following buttons appear:
Load Information | Loads information based on an existing file. When you load information, you are not editing the existing file. Instead, you are loading a copy of the information about that file.
Create File | Creates a new file based on current information in the dialog box.
Set to Defaults | Sets the controls to default values.
Description Comments | If you are creating a description file, allows you to enter notes about the file.
Show 6.x Attributes | Displays controls specific to 6.x and later files, which are unavailable when you load information based on a pre-6.0 file. (This button is unavailable unless you load information based on a pre-6.x file.)
Help | Displays help for the File Information Editor dialog box.

The Data File Info box, also at the top of the File Information Editor, contains the following controls:
Owner Name | Provides a text box you can use to specify the owner name, if applicable, for an existing file.
Version | Earliest version of the MicroKernel that can read all the attributes of the file. For example, if you created a file using the 6.15 MicroKernel but did not use any attributes specific to 6.15, the Maintenance utility displays 6.0 as the version number. See File Version Notes for additional information about file format versions.
Total Records | Total number of records in the file.

The File Specification box is in the middle of the File Information Editor. Table 14-1 describes the controls in this box.
Table 14-1 File Specification Controls
Control | Description | Range | Default
Record Length | Specifies the logical data record length (in bytes) of the fixed-length records in a file. | 4–4,088 | 100
Page Size | Specifies the physical page size (in bytes) for the file. Must be a multiple of 512 bytes. | 512–4,096 | 4,096
# Keys | Indicates the number of distinct keys (as opposed to key segments) currently defined in the Editor. Reflects the number of keys in the Key list. | 0–119 | 0
# Segments | Indicates the number of key segments currently defined in the Editor. Reflects the number of segments in the Segment list. | 0–119 | 0
Available Linked Keys | Specifies how many 8-byte place holders you want to reserve for future linked-duplicatable keys. If you are loading information based on an existing data file, this value reflects the number of place holders currently available in that file. (The number of originally reserved place holders is not stored in the file.) | 0–119 | 3
Key-Only | Indicates whether the file is key-only. Not applicable if you turn Data Compression on, if you turn Variable Records on, or if you define more than one key for the file. | On or Off | Off
Balanced Indexing | Specifies that the file uses the balanced indexing method of managing key pages. | On or Off | Off
Pre-allocation | Specifies that the file uses preallocated pages. | On or Off | Off
# Pages | Specifies the number of pages you want preallocated when you create the file. Applicable only if Pre-allocation is turned on. If you are loading information based on an existing data file, this value reflects the number of unused, preallocated pages left in that file. (The number of originally preallocated pages is not stored in the file.) | 1–65,535 | 0
Data Compression | Specifies that the file uses data compression. Not applicable for key-only files or files that use blank truncation. | On or Off | Off
Variable Records | Specifies that the file can contain variable-length records. | On or Off | Off
Blank Truncation | Specifies whether the file uses blank truncation on variable records to conserve disk space. Applicable only if Variable Records is turned on. | On or Off | Off
Include VATs | Specifies whether the file supports Variable-tail Allocation Tables for faster access to data in very long records. Applicable only if Variable Records is turned on. | On or Off | Off
% Free Space | Specifies the amount of unused space a file's variable pages must have available before the MicroKernel creates a new variable page. Applicable only if Data Compression or Variable Records are turned on. | 5, 10, 20, or 30 | 5

At the bottom middle of the dialog box, the Key list shows the key numbers defined in a file. (For 6.x and later files, these key numbers do not have to be consecutive; they can have gaps between them.) The Maintenance utility displays the highlighted key's specifications in the Key box at the bottom left of the dialog box.

Also at the bottom middle of the dialog box, the Segment list shows the key segment numbers defined for the key highlighted in the Key list. The Maintenance utility displays the highlighted segment's specifications in the Segment box at the bottom right of the dialog box.

In addition, the following buttons appear under the Key and Segment lists:
Insert | Defines a new key or segment.
Delete | Removes the highlighted key or segment specification.
Compress | Renumbers the keys consecutively. You can use this button to remove gaps that result from deleting a key specification.

 Note
Because these buttons control key specifications for a file you want to create, you cannot use them to operate on keys in an existing file. If you want to create or drop an index on an existing file, refer to

At the bottom left in the dialog box is the Key group box. Table 14-2 describes the controls in this area. These controls are specific to the designated key (that is, the key highlighted in the Key list), not just to the current key segment. When you change the setting for one of these controls, the change affects all segments of the specified key.
Table 14-2 Key Specification Controls
Control | Description | Default
Duplicates | Specifies that the key can have duplicate values. | On
Modifiable | Specifies that the key value can be modified after creation. Allowing modification of key values does not affect performance. Key pages are only updated if the actual key value changes, not if non-key fields in a particular record are changed. | On
Repeating Duplicates | Specifies that the MicroKernel uses the repeating-duplicatable method of storing duplicate key values. | Off
Sparse Key (Null Key) | A sparse key contains fewer key values than the number of record in the file. To specify which key values are excluded from the index, see the next two controls. Applicable only to keys that contain nullable segments. | Off
All Segments (Null) | Specifies that if all key segments in the record contain a null value, the MicroKernel does not include that record in the index. Applicable only if Sparse Key (Null Key) is turned on. Equivalent to key flag 0x0008. Whether a segment is evaluated as null is determined solely by the null indicator segment for that field; the contents of the field are not evaluated. | Off
Any Segment (Manual) | Specifies that if one or more key segments contains a null value, the MicroKernel does not include that record in the index. Applicable only if Sparse Key (Null Key) is turned on. Equivalent to key flag 0x0200. Whether a segment is evaluated as null is determined solely by the null indicator segment for that field; the contents of the field are not evaluated. | Off
ACS Information | Allows you to specify an alternate collating sequence (ACS) for the key. Applicable only if the Use ACS check box is selected for a segment of the key. | Off
Unique Values | Indicates the number of unique key values in the file. Applicable only if you are loading information based on an existing data file. | N/A

At the bottom right in the dialog box is the Key Segment group box. Table 14-3 describes the controls in this area. These controls are specific to the designated key segment (that is, the segment highlighted in the Segment list),
Table 14-3 Key Segment Specification Controls
Control | Description | Default
Data Type | Specifies a data type for the key segment. The NULL data type indicates that the index is one byte Null indicator segment. It must be in a multi-segment key and it must precede another key segment that is not a NULL type. The number used in the Btrieve API for this key type is 255. | String
Position | Specifies by number the relative starting position of the beginning of this key segment in the record. The value cannot exceed the record length. | 1
Length | Specifies the length (in bytes) of the key segment. This value cannot exceed the limit dictated by the data type for the segment. The total of key position and key length cannot exceed the record length. | 10
Null Value | Specifies the null character value (in hexadecimal) for the key segment. Applicable only if the Null Key check box is selected for the key. | Binary zero
Case Insensitive | Specifies whether the segment is sensitive to case. Applicable only for STRING, LSTRING, and ZSTRING data types or for keys that do not use an ACS. | On
Descending | Specifies that the MicroKernel sort the key segment values in descending order (that is, from highest to lowest). | Off
Use ACS | Specifies that the segment uses the alternate collating sequence defined for the key. Applicable only for string, lstring and zstring data types that are case sensitive. | Off
Null Value Discrete Ordering | NULL Value Discrete Ordering is used for the null indicator segment (NIS) to determine whether the MKDE should treat the NIS as a boolean value, where any non-zero value is considered NULL, or as a one byte integer, where zero is considered non-null and all other values are considered different types of null. In this case they are sorted as discrete values. The Btrieve API uses the NO_CASE flag, 0x0400, to indicate discrete ordering should be performed, because that flag was previously unused for integer values. | Off

Information Editor Tasks

You perform the following tasks with the File Information Editor:

  • Load information from an existing data file
  • Create a new file
  • Compact a Btrieve file
  • Show or hide 6.x data
  • Specify a key's alternate collating sequence

Loading Information from an Existing Data File

When you load information from an existing file, you are not editing the existing file. Instead, you are loading a copy of the information about that file. Generally, you want to load a data file before performing other tasks with the File Information Editor, but this is not mandatory.

To load information from an existing data file into the File Information Editor

  1. Click Load Information at the top of the File Information Editor. The Select File dialog box appears (Figure 14-3).

Figure 14-3 Select File Dialog Box

  2. Specify the name and path of the file for which you want to load information. (By default, data files have the .mkd extension.)

    The Maintenance utility first attempts to open the specified file as a data file. If the file requires an owner name, the utility prompts you for one. (Because owner names are optional, the file you open may not require an owner name.) If the specified file is not a data file, the utility then attempts to open the file as a description file.

Creating a New File

You can create a new file based on the current information in the File Information Editor or on new information you provide.

To create a new file based on the current information in the File Information Editor

  1. Click Create File at the top of the File Information Editor dialog box. The Create File dialog box (Figure 14-4) appears.

Figure 14-4 Create File Dialog Box

  2. Specify the controls in the Create File dialog box, which are described in Table 14-4.

    Table 14-4 Create File Dialog Controls
    Control
    Description
    Default
    File Name
    Specifies a name and path for the file. By default, data files have the .mkd extension.
    N/A
    File Type
    Specifies the type of file to create. If you are creating a description file, you can use the Index Only option, which creates a description file you can use with the BUTIL utility to add an index to an existing data file. (For more information, refer to .)
    MicroKernel-compatible
    System Data
    Determines whether the utility includes system data in the file. If you choose Use Engine Setting, the utility uses the setting for the configuration option described . If you choose No System Data, the utility does not create system data, regardless of the engine configuration. If you choose Force System Data, the utility creates system data, regardless of the engine configuration.

    This is applicable only if the file type is MicroKernel-compatible.
    Use Engine Setting

Adding Comments to a Description File

The comments are written to the top of the description file when you create the description file. For example, the comment, "This is my file," appears at the top of the description files as /* This is my file */. If you add additional comments after creating the description file, you need to create the file again to include the additional comments.

To add comments to a description file

  1. Click Description Comments. The Description File Comments dialog box (Figure 14-5) appears.

Figure 14-5 Description File Comments Dialog Box

  2. Enter a block of comments up to 5,120 characters long.
  3. Click OK when you are finished entering comments.

Compacting Btrieve Data Files

You can compact a Btrieve data file to remove unused space in it, which typically decreases the file's size. You can also perform this procedure using the command-line Maintenance utility .

To compact a Btrieve file

  1. Click Load Information in the File Information Editor and select the file you want to compact.
  2. Click Create File, give the file a new name (which creates a clone) in the Create File dialog box, and click OK.
  3. From the Data menu on the main window, select Save. In the Save Data dialog box, enter the name of the original file in the From MicroKernel File box and then specify a name for the output file (for example, <original file>.out) in the To Sequential File box.
  4. Click Execute. The Save Data dialog box displays the results of the save. Click Close.
  5. From the Data menu, select Load. In the Load Data dialog box, enter the name of the sequential data file you just saved in the From Sequential File box. Then enter the name of the clone file you created in Step 2 in the To MicroKernel File box.
  6. Click Execute. The Loading Data dialog box displays the results of the load. Click Close.

    You can now compare the size of the original file to the clone file to verify the reduction in size.

Showing and Hiding 6.x Data

When you load a pre-6.0 file, all the controls in the File Information Editor that are specific to 6.x and later are unavailable unless you click the Show 6.x Data button. For example, one feature that is specific to 6.x and later is the use of variable-tail allocation tables, or VATs.

This button is useful for users working in environments that use both pre-6.0 and 6.x and later MicroKernels. By hiding the 6.x-specific controls, you can avoid unintentionally creating a 6.x file. (Pre-6.0 MicroKernels cannot access 6.x files.)

To display the 6.x-specific controls

  • Click Show 6.x Data.

    The Show 6.x Data button is unavailable unless you are working with pre-6.0 files.

Specifying a Key's Alternate Collating Sequence

You can use an alternate collating sequence (ACS) to sort string keys (types STRING, LSTRING, and ZSTRING) differently from the standard ASCII collating sequence. By using one or more ACSs, you can sort keys as follows:

  • By your own user-defined sorting order, which may require a sorting sequence that mixes alphanumeric characters (A-Z, a-z, and 0-9) with non-alphanumeric characters (such as #).
  • By an international sorting rule (ISR) that accommodates language-specific collations, including multi-byte collating elements, diacritics, and character expansions and contractions.

Files can have a different ACS for each key in the file, but only one ACS per key. Therefore, if the key is segmented, each segment must use either the key's specified ACS or no ACS at all. For a file in which a key has an ACS designated for some segments but not for others, Btrieve sorts only the segments that specify the ACS.

The ISR tables are provided with Pervasive.SQL and are based on ISO-standard locale tables. ISR tables are stored in the COLLATE.CFG file, which is a Pervasive.SQL system file. This means that multiple data files can share a single ISR.

To specify a key's alternate collating sequence

  1. Click ACS Information.

    The Maintenance utility displays the Specify ACS Information dialog box (Figure 14-6).

Figure 14-6 Specify ACS Information Dialog Box

  2. You can specify either a country ID and code page, an ACS file name, or an International Sorting Rule (ISR) as follows:

Table 14-5 ACS Information Controls
Control | Description | Default
ACS Country/Code
Country ID | An Intel-format number that identifies your country. Refer to your operating system's documentation for specific information. | -1
Code Page | An Intel-format number that identifies the code page you want to use. Refer to your operating system's documentation for specific information. | -1
ACS File | Specifies the fully qualified file name of the alternate collating sequence file. | N/A
International Sorting Rule | When you click this radio button you can specify a specific ISR table for sorting international data. Pervasive.SQL provides a set of pre-generated ISR tables, which are listed in the Pervasive.SQL Programmer's Guide. |

  3. When you specify a country ID and code page ID, the MicroKernel stores the locale-specific collating sequence in the data file. Moreover, the MicroKernel can insert new key values correctly, even if the locale changes.
  4. When you specify an ACS file name for a data file, the MicroKernel copies the contents of the ACS file into the data file. (That is, the data file does not contain the file name of the ACS file.) The ACS identifies itself using an eight-digit name (such as UPPER). Subsequently, when you view the ACS information for a data file, the Maintenance utility displays this eight-digit name, not the file name of the original ACS.
  5. When you specify an ACS file name for a description file, the Maintenance utility copies the actual path and file name of the ACS file into the description file. Subsequently, when you view the ACS information for a description file, the Maintenance utility attempts to locate the specified ACS file.

    To specify an ACS that sorts string values using an ISO-defined, language-specific collating sequence, you must specify an ISR table name. The Table Name field is limited to 16 characters. For more information on ISRs, refer to the Pervasive.SQL Programmer's Guide, available with the Pervasive.SQL Software Developer's Kit (SDK).

Prev
Btrieve Interactive Maintenance Utility 		Up
Check for Revisions 		Next
Owner Names


Owner Names

The MicroKernel allows you to restrict access to files by specifying an owner name. Because owner names are optional, the files you use with the utility may or may not require an owner name. Owner names are case-sensitive.

Conceptually, owner names are like passwords. They are not the same as user or group names, which you can set in the PCC. For example, an owner name of "Master" is not the same as the default user Master.

For more information on owner names, see Owner Names .

With relational access, an ODBC error results if you attempt to manipulate a table that is restricted by an owner name. (For example in the PCC, if you double-click the table name or attempt to delete the table.) You can use the GRANT statement to grant access to a particular user or group, and then manipulate the table via relational access through ODBC. The Master user must supply the GRANT statement with the correct owner name.

Owner Names Tasks

You perform the following tasks pertaining to owner names:

  • Set or clear an owner name

Setting or Clearing an Owner Name

You set an owner name to restrict access to a file. You clear an owner name to remove the access restriction.

To set or clear an owner name

  1. Click Options 4 Set - Clear Owner from the menu on the main window. The Set - Clear Owner Name dialog box appears (Figure 14-7).

Figure 14-7 Set/Clear Owner Name Dialog Box

  2. In the MicroKernel File box, specify the file for which you want to set or clear an owner name. Then, to clear the owner name, click Clear Owner and specify the file's owner name in the Current Owner box.
  3. To set the owner name, click Set Owner and specify the file's new owner name in the New Owner box. Select the Permit read-only access without an owner name check box to allow anyone to read-only access to the records.

    Select the Encrypt data in file check box to ensure that unauthorized users do not examine your data using a debugger or a file dump utility. Only select this option if data security is important to your environment as this requires additional processing time.

Prev
File Information Editor 		Up
Check for Revisions 		Next
Statistics Report


Statistics Report

Generating a statistics report is a good way to determine whether a file can be logged by the MicroKernel's transaction durability feature. The report shows whether the file has system data and if a key is unique. (A unique key lacks the "D" flag, which indicates that duplicates are allowed.) The statistics report provides metadata about the file. This information can be used when you troubleshoot problems or to help you create similar files.

Statistics Report Tasks

You perform the following tasks pertaining to owner names:

  • Create a statistics report

To create a statistics report for an existing data file

  1. Click Options 4 Create Stat Report from the menu on the main window. The Maintenance utility displays the Statistics Report dialog box (Figure 14-8).

Figure 14-8 Statistics Report Dialog Box

  2. Specify a data file to use and a report file name. If you want to view the report when it is created, select the View Report check box.

    If you choose to view the report, the Maintenance utility displays the View File window as shown in Figure 14-9.

Figure 14-9 Statistics Report Example

The informational headings in a status report correspond to the controls in the File Information Editor, which is described in .

The legend at the bottom of the statistics report explains the symbols used in the key/segment portion of the report. This information includes items such as the number of keys and key segments, the position of the key in the file, and the length of the key:

Legend:

< = Descending Order
D = Duplicates Allowed
I = Case Insensitive
M = Modifiable
R = Repeat Duplicate
A = Any Segment (Manual)
L = All Segments (Null)
* = The values in this column are hexadecimal.
?? = Unknown
-- = Not Specified

Prev
Owner Names 		Up
Check for Revisions 		Next
Indexes


Indexes

An index is a structure that sorts all the key values for a specific key. Btrieve access permits overlapping indexes (an index that includes a partial column). Relational access through ODBC does not permit overlapping indexes. (You can create an overlapping index with the File Information Editor, which you can display by clicking the Goto Editor button.)

Index Tasks

You perform the following tasks pertaining to indexes:

  • Create an index
  • Drop an index

Creating Indexes

You cannot create an index for a file unless the file has at least one key defined. You can create a key with the File Information Editor .

To create an index

  1. Click Index 4 Create from the main menu, which opens the Create Index dialog box (Figure 14-10).

Figure 14-10 Create Index Dialog Box

  2. Complete the following data boxes in the Create Index dialog box.

Index Type
Specify whether to create an internal or external index. Internal indexes are dynamically maintained as part of the data file. External indexes are separate files you generate as needed.

An external index file is a standard data file that contains records sorted by the key you specify. Each record consists of the following:
  • A 4-byte address identifying the physical position of the record in the original data file
  • A key value
Data File
Specify the name of the data file for which you want to create the index.
External Index File
Specify the name of the file to generate for an external index. Not applicable for internal indexes.
Key Specification Number in Information Editor to Use
Lists the key numbers defined in the File Information Editor. If the file contains a system-defined log key (also called system data) but the key has been dropped, this list includes SYSKEY, which you can select to re-add the system-defined log key to the file.
Existing Key Numbers in Data File
Click Refresh Lists to display the key number defined for the file. If the file contains a system-defined log key, this list includes SYSKEY.
Key Number to Use For Create
Click Refresh Lists to display the key numbers available (that is, not defined for the file). Highlight the key number you want to use when creating the index.

  3. You can click Go To Editor to display the File Information Editor dialog box, which shows more complete information about the key. You can click Refresh Lists to read key information from the data file and refresh the Existing Key Numbers in Data File and Key Number to Use For Create lists. You must click Refresh Lists before you can create an index.
  4. When you have completed the Create Index dialog box, click Execute to create the index. The amount of time required to create the index depends on how much data the file contains.

Dropping Indexes

Ensure that you understand the access performed by an application program before dropping an index. Certain functions fail (such as GET NEXT) if a required index is missing. This can result in an application program not functioning correctly.

To drop an index

  1. Click Index 4 Drop from the main menu The Drop Index dialog box appears (Figure 14-11).

Figure 14-11 Drop Index Dialog Box

  2. Complete the following data boxes in the Drop Index dialog box.

MicroKernel File | Specify the name of the data file from which you want to drop the index.
Existing Key Numbers | Click Refresh List to display the key number defined for the file. Highlight the number of the key whose index you want to drop. If the file contains a system-defined log key, this list includes SYSKEY, which you can select to drop the system-defined log key from the file.
Renumber Keys | Renumbers the keys consecutively. Click this button to remove gaps that result from deleting an index.

  3. Click Refresh List to get the key information from the file you have specified.
Prev
Statistics Report 		Up
Check for Revisions 		Next
Data


Data

The commands in the Data menu allow you to import, export, and copy records in data files. You can also recover data after a system failure with the Roll Forward feature. See Roll Forward Command for a discussion of Roll Forward.

Importing and Exporting ASCII File Format

When you save data, records in the ASCII file have the following format. You can use an ASCII text editor to create files that you can load, as long as they adhere to these specifications. Note that most text editors do not support editing binary data.

  • The first field is a left-adjusted integer (in ASCII) that specifies the length of the record. (When calculating this value, ignore the carriage return/line feed that terminates each line.) The value in this first field matches the record length specified in the data file.
    • For files with fixed-length records, the length you specify should equal the record length of the data file.
    • For files with variable-length records, the length you specify must be at least as long as the fixed-record length of the data file.
  • A separator (a comma or a blank) follows the length field.
  • The record data follows the separator. The length of the data is the exact number of bytes specified by the length field. If you are creating an import ASCII file using a text editor, pad each record with blank spaces as necessary to fill the record to the appropriate length.
  • A carriage return/line feed (0D0A hexadecimal) terminates each line. The Maintenance utility does not insert the carriage return/line feed into the data file.
  • The last line in the file must be the end-of-file character (CTRL+Z or 1A hexadecimal). Most text editors automatically insert this character at the end of a file.

Figure 14-12 shows the correct format for records in the input ASCII file. For this example, the data file has a defined record length of 40 bytes.

Figure 14-12 Format for Records in Input Sequential Files

Data Tasks

You can perform the following data tasks with the Maintenance utility:

  • To import ASCII data
  • To export ASCII records
  • To copy records between MicroKernel data files
  • To recover (Roll Forward) changes made to a data file between the time of the last backup and a system failure, see the Logging, Backup, and Restore chapter .

Importing Records From an ASCII File

You can use the Maintenance utility to import records from an ASCII file to a standard data file. This operation does not perform any conversions on the data. You can create an import file using a text editor or the Maintenance utility (see ).

To import ASCII data

  1. Click Data 4 Load from the main menu. The Load dialog box appears (Figure 14-13).

Figure 14-13 Load Dialog Box

The ASCII file you specify must adhere to the specifications explained in . The record length of the standard data file you specify must be compatible with the records in the ASCII file.

  2. Click Execute to import the records.

    While importing data, the Maintenance utility shows the number of records being imported, the percentage of records imported, and a status message. You can continue working in the Maintenance utility (for example, you can open another Load dialog box).

Exporting Records to an ASCII File

You can use the Maintenance utility to export records from a data file to an ASCII file.

To export ASCII records

  1. Click Data 4 Save from the main menu. The Save Data dialog box appears (Figure 14-14).

Figure 14-14 Save Data Dialog Box

  2. In the Save Data dialog box, specify the following options.
    From MicroKernel File
    Specifies the name of the existing MicroKernel-compatible file you want to save.
    To Sequential File
    Specifies the name of the sequential file to create.
    Use An Index
    Uses a specified index when sorting the records for export. By default, the Maintenance utility does not use an index, meaning that records are exported according to their physical position in the data file.

    Internal Index #:
    Uses the specified key number. Click Refresh Index List to update the available indexes if you change file in the From MicroKernel File box.

    External Index File:
    Uses the specified external index. (To create an external index, refer to .)
    Direction
    Forward: This is the default setting and indicates the utility recovers the file from the beginning.

    Backward: This option recovers data from the end of the file.

    Forward and Backward: This option reads the file forward until it fails. Then it starts at the end of the file and reads the file backward until it reaches the record that failed previously or encounters another failure.

    Backward and Forward: Indicates the utility reads the file backward until it fails. Then it starts at the beginning of the file and reads the file forward until it reaches the record that failed previously or encounters another failure.
  3. Click Execute to export the data. The Maintenance utility creates the specified ASCII file using the format described in . You can then edit the ASCII file and use the Load command to import the edited text to another standard data file, as described in .

Copying Records Between Data Files

You can use the Maintenance utility to copy data from one Microkernel data file to another. The record lengths for both data files you specify must be the same.

To copy records between MicroKernel data files

  1. Click Data 4 Copy from the main menu. The Copy Data dialog box appears (Figure 14-15).

Figure 14-15 Copy Data Dialog Box

  2. Enter the name of the file you want to copy in the From MicroKernel File box and then specify the path where you want to copy the file in the To MicroKernel File box.

    The record lengths for both data files you specify must be the same.

Recovering (Roll Forward) Changes to a Data File

See the Logging, Backup, and Restore chapter .

Prev
Indexes 		Up
Check for Revisions 		Next
Btrieve Command-Line Maintenance Utility (BUTIL)


Btrieve Command-Line Maintenance Utility (BUTIL)

Use this utility if you prefer a command-line interface or if you want to start or stop continuous operation. The Btrieve Maintenance utility is also available in a command-line format that runs on the server (as an NLM on NetWare or from a DOS command prompt on Windows NT) or locally on DOS, and Win32 clients. You can execute Maintenance utility commands from the command line or through a command file you create. Before you perform commands in the Btrieve Maintenance utility, also referred to as BUTIL, it is important you understand some concepts and elements addressed in the Commands

The Btrieve Command-Line Maintenance utility performs the following common file and data manipulations:

  • Importing and Exporting Data
  • Creating and Modifying Data Files
  • Viewing Data File Statistics
  • Displaying Btrieve Interface Module Version
  • Unloading the Btrieve Interface and Requester (DOS only)
  • Performing Continuous Operations

Return Codes

When BUTIL finishes executing, it returns an exit code or DOS "errorlevel" return code to the operating system. The return codes are as follows:
Table 14-6 BUTIL.EXE Return Codes
Code | Meaning
SUCCESS_E = 0 | Requested operation succeeded.
PARTIAL_E = 1 | Requested operation completed, but with errors.
INCOMPLETE_E = 2 | Requested operation did not complete.
USAGE_E = 3 | Syntax error in input, display usage screen and exit.

Commands

Table 14-7 lists the commands that you can use with the Command-line Maintenance Utility.
Table 14-7 Command-Line Maintenance Utility Commands
Command | Description
CLONE | Creates a new, empty data file using an existing file's specifications.
CLROWNER | Clears the owner name of a data file.
COPY | Copies the contents of one data file to another.
CREATE | Creates a data file.
DROP | Drops an index.
ENDBU | Ends continuous operation on data files defined for backup in Win32 and NLM versions only.
INDEX | Creates an external index file.
LOAD | Loads the contents of an unformatted file into a data file.
RECOVER | Reads data sequentially from a data file and writes the results to an unformatted file. (The DOS version does not support ROLLFWD.) Use this command if you have a damaged file.
ROLLFWD | Recovers changes made to a data file between the time of the last backup and a system failure.
SAVE | Reads data along a key path and writes the results to a sequential file.
SETOWNER | Assigns an owner name to a data file.
SINDEX | Creates an index.
STARTBU | Starts continuous operation on files defined for backup in Win32 and NLM versions only.
STAT | Reports statistics about file attributes and current sizes of data files.
STOP (DOS only) | Unloads the Btrieve Interface and requester.
VER | Displays the version of the MicroKernel Database Engine and Btrieve Interface Module that is loaded at the server.

Viewing Command Usage Syntax

To view a summary of each command usage, enter the following command at the file server:

butil

Note
Unless otherwise shown, all command syntax is lowercase on UNIX platforms. Windows-based platforms are case insensitive. NetWare can be configured to be case sensitive or insensitive, but for purposes of discussion, this section assumes case insensitive.

The utility displays usage syntax for each command as illustrated in
Table .

Table 14-8 Maintenance Utility Command Syntax on NetWare

BUTIL -CLONE outputFile sourceFile [/O<owner | *>] [/S]

BUTIL -CLROWNER sourceFile /O<owner | *> [/S]

BUTIL @commandFile [commandOutputFile]

BUTIL -COPY sourceFile outputFile
[/O< owner1 | *> [/O<owner2 | *>]] [/S]

BUTIL -CREATE outputFile descriptionFile [< Y | N >] [/S]

BUTIL -DROP sourceFile < keyNumber | SYSKEY >
[/O<owner | *>] [/S]

BUTIL -ENDBU < /A | sourceFile | @listFile > [/S]

BUTIL -INDEX sourceFile indexFile descriptionFile
[ /O<owner | *>] [/S]

BUTIL -LOAD unformattedFile outputFile [/O<owner |*>] [/S]

BUTIL -RECOVER sourceFile unformattedFile [/O<owner |*>] [/S]

BUTIL -ROLLFWD <sourceFile | volume | drive | @listFile>
[</L[dumpFile] | /W[dumpFile]> [/T<dataLength>]
[/E<keyLength>] [/H] [/V] [/O<ownerList | owner> | *]]
[/A] [/S]

BUTIL -SAVE sourceFile unformattedFile
[Y indexFile | N <keyNumber | -1>] [/O<owner1 | *>
[/O<owner2 | *>]] [/S]

BUTIL -SETOWNER sourceFile /O<owner | *> level [/S]

BUTIL -SINDEX sourceFile <descriptionFile | SYSKEY> [keyNumber] [/O<owner | *>] [/S]

BUTIL -STARTBU <sourceFile | @listFile> [/S]

BUTIL -STAT <sourceFile> [/O<owner | *>] [/S]

BUTIL -VER [/S]

Note
The /S option applies only to the NetWare version of the command-line utility. Also, on NetWare you always have to specify the full path of the file name such as sys:\pvsw\demodata\tuition.mkd.

Command Format

The format for the Maintenance utility command line is as follows:

BUTIL [-command [parameter ...]] | @commandFile

–command | A Maintenance utility command, such as COPY. You must precede the command with a dash (–), and you must enter a space before the dash. Table 14-7 lists the commands.
parameter | Information that the command may require. Discussions of the individual commands provide details when applicable.
@commandFile | Fully qualified file name of a command file.

Command Files

You can use a command file to do the following:

  • Execute a command that is too long to fit on the command line.
  • Execute a command that you use often (by entering the command once in the command file and then executing the command file as often as you want).
  • Execute a command and write the output to a file, using the following command format:
    BUTIL @commandFile [commandOutputFile]

      For each command executed, the resulting output file shows the command followed by its results. All messages appear on the server console screen, as well.
  • Execute multiple commands sequentially.

Command files contain the same information as that required on the command line.

Rules for Command Files

Observe the following rules when creating a Maintenance utility command file:

  • You cannot split a single parameter across two lines.

You must end each command with <end> or [end]. You must also end each command with an <end> when trying to execute multiple commands. The <end> or [end] must be lowercase.

Command File Example

The following is an example command file, COPYCRS.CMD. The file calls the BUTIL - CLONE command to create the NEWCRS.MKD file by cloning the COURSE.MKD file, and the -CREATE command to create the NEWFILE.DTA file by using the description provided in the NEWFILES.DES description file.

-clone newcrs.mkd course.mkd <end>
-create newfile.dta newfiles.des <end>

The following command uses the COPYPATS.CMD file and writes the output to the COPYPATS.OUT file:

butil @copypats.cmd copypats.out

Description Files

Description files are ASCII text files that contain descriptions of file and key specifications that the Maintenance utility can use to create data files and indexes. Some users employ description files as a vehicle for archiving information about the data files they have created. For more information about the description file format, see Appendix A Description Files.

Extended File Support

The size of the MicroKernel data file can be larger than the operating system file size limit. When you export data from an extended MicroKernel file to an unformatted file, the size of the unformatted file can exceed the MicroKernel file size limit because of the differences in the physical format.

When you are exporting large files, the Interactive Maintenance utility detects that the unformatted file has exceeded the operating system file size limit (2 GB) and starts creating extension files. This process is transparent. Extension files and the original unformatted file must reside on the same volume. The extension file uses a naming scheme in which the file names are similar to the base file name. In contrast to native MKDE extension files which use a caret "^" to indicate extension file status, the unformatted extension files use a tilde "~" to avoid overwriting any existing extended MKDE files with the same base file name. The first export extension file is the same base file name with ".~01" extension. The second extension file is ".~02," and so on. These extensions are appended in hexadecimal format.

While the naming convention supports up to 255 extension files, the current maximum number of extension files is 32, thus supporting files as large as 64 GB.

To SAVE or RECOVER huge files to unformatted files, see the respective command. Also, when you import data from an unformatted file, the utility detects if the file has extensions and loads the data from the extension file.

Owner Names

The MicroKernel allows you to restrict access to files by specifying an owner name. Because owner names are optional, the files you use with the utility may or may not require an owner name. If the file requires an owner name, you must specify it using the /O option. You can specify one of the following:

  • Single owner name.
  • List of up to eight owner names. Separate the owner names with commas.
  • Asterisk (*). The utility prompts you for the owner name. With the ROLLFWD command, the utility prompts you for a list of owner names separated by commas.

Owner names are case-sensitive. If you enter owner names on the command line, the utility discards leading blanks. If you specify an asterisk, the utility does not discard leading blanks.

Redirecting Error Messages

Be sure that you specify a fully qualified file name (including a drive letter or UNC path) when redirecting error messages.

To redirect error messages to a file on a Windows NT or UNIX server

  • Use the following command format.
    BUTIL -command commandParameters > filePath

To redirect error messages to a file on a NetWare server

  • Use the following command format.
    LOAD BUTIL -command commandParameters (CLIB_OPT)
/>filepath

ASCII File Format

See in the Interactive Maintenance utility section.

Rules for Specifying File Names on Different Platforms

When you run BUTIL on a Windows-based platform or a UNIX-based platform, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.

Prev
Data 		Up
Check for Revisions 		Next
Importing and Exporting Data


Importing and Exporting Data

This section provides detailed information on importing and exporting data using the following BUTIL commands: COPY , LOAD , RECOVER , and SAVE.
Table 14-9 Commands to Import and Export Data
Command | Description
COPY | Copies the contents of one data file to another.
LOAD | Loads the contents of a sequential file into a data file.
RECOVER | Reads data sequentially from a data file and writes the results to a sequential file.
SAVE | Reads data along a key path and writes the results to a sequential file.

COPY

The COPY command copies the contents of one MicroKernel file to another. COPY retrieves each record in the input data file and inserts it into the output data file. The record size must be the same in both files. After copying the records, COPY displays the total number of records inserted into the new data file.

Note
COPY performs in a single step the same function as a RECOVER command followed by a LOAD command.

Using the COPY command, you can create a data file that contains data from an old file, but has new key characteristics.

To copy a MicroKernel data file

  1. Use the CREATE command to create an empty data file with the desired key characteristics (key position, key length, or duplicate key values).

    or

    Use CLONE to create an empty data file using the characteristics of an existing file.

  2. Use the COPY command to copy the contents of the existing data file into the newly created data file.

Format

BUTIL -COPY sourceFile outputFile [/O< owner1 | *>
[/O<owner2 | *>]] [/S]

sourceFile | The fully qualified name of the data file from which to transfer records. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
outputFile | The fully qualified name of the data file into which to insert records. The output data file can contain data or be empty. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner1 | The owner name of the source data file, if required. If only the output data file requires an owner name, specify /O followed by a blank for owner1 (as illustrated in the example).
/Oowner2 | The owner name of the output data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following command copies the records in COURSE.MKD to NEWCRS.MKD. The COURSE.MKD input file does not require an owner name, but the NEWCRS.MKD output file uses the owner name Pam.

butil -copy course.mkd newcrs.mkd /O /OPam

If you omit the first /O from this example, the utility assumes that the owner name Pam belongs to the input data file, not the output data file.

LOAD

The LOAD command inserts records from an input ASCII file into a file. The input ASCII file can be a single file or an extended file (the base file plus several extension files). LOAD performs no conversion on the data in the input ASCII file. After the utility transfers the records to the data file, it displays the total number of records loaded.

Note
The LOAD command opens the output file in Accelerated mode; during a LOAD operation, the MicroKernel does not log the file. If you are using archival logging, back up your data files again after using the LOAD command.

Extended files: If the utility finds the next extension file, it continues the load process. Do not delete any extension file created earlier by the SAVE and RECOVER commands. If the file has three extensions and the user deletes the second one, LOAD stops loading records after processing the first extension file.

If SAVE or RECOVER created three extension files and a fourth one exists from a previous SAVE or RECOVER, LOAD reads the records from the fourth extension and inserts them into the MicroKernel file. If a fourth file exists, then you need to delete it before starting the LOAD process.

Before running the LOAD command, you must create the input ASCII file and the data file. You can create the input ASCII file using a standard text editor or an application; the input ASCII file must have the required file format (as explained in ). You can create the data file using either the CREATE or the CLONE command.

Format

BUTIL -LOAD unformattedFile outputFile [/O<owner |*>] [/S]

unformattedFile | The fully qualified name of the ASCII file containing the records to load into a data file. For Windows NT, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
outputFile | The fully qualified name of the data file into which to insert the records. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner | The owner name for the data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following example loads sequential records from the COURSE.TXT file into the COURSE.MKD file. The owner name of the COURSE.MKD file is Sandy.

butil -load course.txt course.mkd /OSandy

RECOVER

The RECOVER command extracts data from a MicroKernel file and places it in an ASCII file that has the same format as the input ASCII file that the LOAD command uses. This is often useful for extracting some or all of the data from a damaged MicroKernel file. The RECOVER command may be able to retrieve many, if not all, of the file's records. You can then use the LOAD command to insert the recovered records into a new, undamaged MicroKernel file.

Note
The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.

Format

BUTIL -RECOVER sourceFile unformattedFile [/O<owner |*>] [/S]
[/Q] [/J] [/I]

sourceFile | The fully qualified name of the data file from which to recover data. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
unformattedFile | The fully qualified name of the ASCII file where the utility should store the recovered records.
/Oowner | The owner name for the data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
/Q | Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message. The utility also checks whether the MicroKernel file to be recovered is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension file. If one of those files exists, the utility returns an error message.
/J | Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using STEP LAST and PREVIOUS operations. The default is forward reading, using STEP FIRST and NEXT operations.
/I | Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure. If you specify /J first, the utility reads backwards and then reads forward.

For each record in the source file, if the RECOVER command receives a variable page error (Status Code 54), it places all the data it can obtain from the current record in the unformatted file and continues the recovery process.

The utility produces the following messages:

  • informs you about the name of the last extension file created
  • checks if the next extension file exists, and if so, tells you to delete it
  • if you move the extended unformatted files to a different location, you are prompted to move the base file and all of its extension files

Example

The following example extracts records from the COURSE.MKD file and writes them into the COURSE.TXT file.

butil -recover course.mkd course.txt

SAVE

The SAVE command retrieves records from a MicroKernel file using a specified index path and places them in an ASCII file that is compatible with the required format for the LOAD command. You can then edit the ASCII file and use the LOAD command to store the edited data in another data file. (See for more information about the ASCII file format.)

SAVE generates a single record in the output ASCII file for each record in the input data file. Upon completion, SAVE displays the total number of records saved.

Note
The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.

Format

BUTIL -SAVE sourceFile unformattedFile [Y indexFile | N <keyNumber | -1>] [/O<owner1 | *> [/O<owner2 | *>]] [/S] [/Q] [/J] [/I]

sourceFile | The fully qualified name of the data file containing the records to save. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
unformattedFile | The fully qualified name of the ASCII file where you want the utility to store the records.
indexFile | The fully qualified name of an external index file by which to save records if you do not want to save records using the default of the lowest key number.
keyNumber | The key number (other than 0) by which to save records if you do not want to save records using the default of the lowest key number.
-1 | The specification for saving the records in physical order using the Btrieve Step operations.
/Oowner1 | The owner name for the source file, if required. If only the index file requires an owner name, specify /O followed by a blank for owner1.
/Oowner2 | The owner name for the index file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
/Q | Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message. The utility also checks whether the MicroKernel file to be saved is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension files. If one of those files exists, the utility returns an error message.
/J | Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using GET LAST and PREVIOUS operations. The default is forward reading, using GET FIRST and NEXT operations.
/I | Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure. If you specify /J first, the utility reads backwards and then reads forward.

The utility produces the following messages:

  • informs you about the name of the last extension file created
  • checks if the next extension file exists, and if so, tells you to delete it
  • if you move the extended unformatted files to a different location, you are prompted to move the base file and all of its extension files

Examples

The following two examples illustrate how to use the SAVE command to retrieve records from a data file.

This example uses a NEWCRS.IDX external index file to retrieve records from the COURSE.MKD file and store them in an unformatted text file called COURSE.TXT:

butil save course.mkd course.txt newcrs.idx

The following example retrieves records from the COURSE.MKD file using key number 3 and stores them in an unformatted text file called COURSE.TXT:

butil -save course.mkd course.txt n 3
Prev
Btrieve Command-Line Maintenance Utility (BUTIL) 		Up
Check for Revisions 		Next
Creating and Modifying Data Files


Creating and Modifying Data Files

This section includes detailed information on creating and modifying data files using the following BUTIL commands: CLONE , CLROWNER , CREATE , DROP , INDEX , SETOWNER , and SINDEX. This section also includes information about removing unused space in a Btrieve data file, which is discussed in
Table 14-10 Commands to Create and Modify Data Files
Command | Description
CLONE | Creates a new, empty data file using an existing file's specifications.
CLROWNER | Clears the owner name of a data file.
CREATE | Creates a data file.
DROP | Drops an index.
INDEX | Creates an external index file.
SETOWNER | Assigns an owner name to a data file.
SINDEX | Creates an index.

CLONE

The CLONE command creates a new, empty file with the same file specifications as an existing file (including any supplemental indexes, but excluding the owner name). The new data file includes all the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file.

The CLONE command ignores all MicroKernel configuration options that affect file statistics (such as ) except file version. The CLONE command creates a new file using the MicroKernel file version you specify with the Create File Version option.

Format

BUTIL -CLONE outputFile sourceFile [/O<owner | *>] [/S]

outputFile | The fully qualified file name to use for the new, empty data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
sourceFile | The fully qualified file name of the existing data file to replicate.When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner | The owner name, if any, for the source data file. The new data file does not have an owner name. See for more information.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Remarks

Btrieve 6.0 and later allows a maximum of 23 key segments in a data file with a page size of 1,024 bytes. Therefore, the CLONE command sets the page size in the new data file to 2,048 bytes if the existing data file contains 24 key segments and has a page size of 1,024 bytes. This occurs if the existing data file has a format earlier than 6.0 and the MicroKernel was not loaded with the option set to 5.x or 6.x.

If you are cloning a pre-7.x file, ensure that the MicroKernel is configured to create the file format version that you want the new file to be. For example, if you want to clone a 6.15 file in 8.x format, ensure that the MicroKernel File Format Version option is set to 8.x.

Note
If your source file is in 8.x format and it does not contain system data, your output file will not contain system data, regardless of the MicroKernel configuration. To add system data to an existing file, refer to Getting Started With Pervasive.SQL.

If you are trying to recover from receiving Status Code 30 (The file specified is not a MicroKernel file) and you suspect that the header page of the source file might be damaged, try creating the new MicroKernel file using the CREATE command with a description file.

Example

The following command creates the NEWCRS.MKD file by cloning the COURSE.MKD file.

butil -clone newcrs.mkd course.mkd

CLROWNER

The CLROWNER command clears the owner name of a MicroKernel file.

Format
BUTIL -CLROWNER sourceFile </O<owner | *> [/S]

sourceFile | The fully qualified file name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner | The owner name to clear. See for more information.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following command clears the owner name for the TUITION.MKD file. The owner name for the file is Sandy.

butil -clrowner tuition.mkd /OSandy

CREATE

The CREATE command generates an empty MicroKernel file using the characteristics you specify in a description file. Before you can use the CREATE command, you must create a description file to specify the new key characteristics. For more information, see Appendix A Description Files.

Format

BUTIL -CREATE outputFile descriptionFile [< Y | N >] [/S]

outputFile | The fully qualified file name of the MicroKernel file to create. If the file name is the name of an existing MicroKernel file, this command creates a new, empty file in place of the existing file. Any data that was stored in the existing file is lost and cannot be recovered. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
descriptionFile | The fully qualified name of the description file containing the specifications for the new MicroKernel file.
Y|N | Indicates whether to replace an existing file. If you specify N but a MicroKernel file with the same name exists, the utility returns an error message. The default is Y.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following command creates a file named COURSE.MKD using the description provided in the CREATE.DES description file.

butil -create course.mkd create.des

Sample Description File for the CREATE Command

The sample description file shown in Figure 14-16 creates a MicroKernel formatted file. The file is specified to have a page size of 512 bytes and 2 keys. The fixed-length portion of each record in the file is set to 98 bytes. The file specifies variable-length records with no blank truncation, data compression, and variable-tail allocation tables (VATs). The free space threshold is set to 20 percent. Allocation is set to 100 pages. The MicroKernel preallocates 100 pages, or 51,200 bytes, when it creates the file.

Figure 14-16 Sample Description File for the CREATE Command

Key 0 is a segmented key with two duplicatable, nonmodifiable string segments and a null value of 20 hexadecimal (space) specified for both segments. Key 0 uses the collating sequence UPPER.ALT.

Key 1 is a numeric, nonsegmented key that does not allow duplicates but permits modification. It is sorted in descending order.

DROP

The DROP command removes an index from a file and adjusts the key numbers of any remaining indexes, subtracting 1 from each subsequent key number. If you do not want to renumber the keys, you can add 128 to the key number you specify to be dropped. This renumbering feature is available only for 6.0 and later files.

Format

BUTIL -DROP sourceFile < keyNumber | SYSKEY >
[/O<owner | *>] [/S]

sourceFile | The fully qualified name of the file from which you are dropping the index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
keyNumber | The number of the key to remove. To preserve the original key numbers, add a 128 bias to the key number you specify.
SYSKEY | Instructs the utility to drop the system-defined log key (also called system data). Dropping the system-defined log key does not delete values from the records; the MicroKernel still assigns unique system-defined log key values to newly inserted records.
 | However, the MicroKernel cannot perform logging for a file from which the system-defined log key is dropped, if no user-defined unique keys exist. For this reason, you should use this option only if you suspect that the system-defined log key is corrupt and you intend to re-add it. The SINDEX command allows you to re-use the system-defined log key once you have dropped it.
/Oowner | The owner name for the file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Examples

In both of the following examples, COURSE.MKD has three keys. The original keys in the file are numbered 0, 1, and 2.

In the first example, the BUTIL -DROP command drops key number 1 from the COURSE.MKD file and renumbers the remaining key numbers as 0 and 1.

butil -drop course.mkd 1

In the following example, the BUTIL –DROP command drops key number 1, but does not renumber the keys. The key numbers remain 0 and 2.

butil -drop course.mkd 129

INDEX

The INDEX command builds an external index file for an existing MicroKernel file, based on a field not previously specified as a key in the existing file. Before you can use the INDEX command, you must create a description file to specify the new key characteristics. For more information about description files, see Appendix A Description Files.

The records in the new file consist of the following:

  • The 4byte address of each record in the existing data file.
  • The new key value on which to sort.

Note
If the key length you specify in the description file is 10 bytes, the record length of the external index file is 14 bytes (10 plus the 4byte address).

Format

BUTIL -INDEX sourceFile indexFile descriptionFile [ /O<owner | *>]
[/S]

sourceFile | The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
indexFile | The fully qualified name of the index file in which the MicroKernel should store the external index.
descriptionFile | The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
/Oowner | The owner name for the data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Remarks

The INDEX command creates the external index file and then displays the number of records that were indexed. To retrieve the data file's records using the external index file, use the SAVE command.

Sample Description File for the INDEX Command

The description file shown in the following illustration defines a new key with one segment. The key begins at byte 30 of the record and is 10 bytes long. It enables duplicates, is modifiable, is a STRING type, and uses no alternate collating sequence.

Figure 14-17 Sample Description File for INDEX Command

Example

The following command creates an external index file called NEWCRS.IDX using a data file called COURSE.MKD. The COURSE.MKD file does not require an owner name. The description file containing the definition for the new key is called NEWCRS.DES.

butil -index course.mkd newcrs.idx newcrs.des

SETOWNER

The SETOWNER command sets an owner name for a MicroKernel file.

Format

BUTIL -SETOWNER sourceFile /O<owner | *> level [/S]

sourceFile | The fully qualified name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner | The owner name to be set
level | The type of access restriction for the data file. The possible values for this parameter are as follows
 | 0: Requires an owner name for any access mode (no data encryption)
 | 1: Permits read access without an owner name (no data encryption)
 | 2: Requires an owner name for any access mode (with data encryption)
 | 3: Permits read access without an owner name (with data encryption)
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following example creates an owner for the COURSE.MKD file. The owner name is Sandy, and the restriction level is 1.

butil -setowner course.mkd /OSandy 1

SINDEX

The SINDEX command creates an additional index for an existing MicroKernel file. By default, the key number of the new index is one higher than the previous highest key number for the data file, or you can instruct the MicroKernel to use a specific key number. An exception is if a DROP command previously removed an index without renumbering the remaining keys, thus producing an unused key number; in this case, the new index receives the first unused number.

You can instruct the MicroKernel to use a specific key number for the new index with the key number option. The key number you specify must be a valid key number that is not yet used in the file. If you specify an invalid key number, you receive Status Code 6.

If you do not use the SYSKEY option with this command, you must create a description file that defines key specifications for the index before you can use the SINDEX command. For more information about description files, see Appendix A Description Files.

Format

BUTIL -SINDEX sourceFile <descriptionFile | SYSKEY> [keyNumber]
[/O<owner | *>] [/S]

sourceFile | The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
descriptionFile | The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
SYSKEY | Instructs the utility to re-add the system key on a file in which the system key was dropped.
/Oowner | The owner name for the data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Examples

The following example adds an index to the COURSE.MKD file. The name of the description file is NEWIDX.DES.

butil -sindex course.mkd newidx.des

The following example adds the system-defined key to the COURSE.MKD file. The system-defined key was dropped.

butil -sindex course.mkd syskey

Compacting Btrieve Data Files

You can use several commands in the BUTIL (CLONE, RECOVER, and LOAD, respectively) to remove unused space in a data file to decrease its size.

To compact a Btrieve data file

  1. Rename your data file and then use the CLONE option to create a blank data file using the original file name.
  2. Use RECOVER to save the data from the clone file to an unformatted text file in sequential order.
  3. Use LOAD to load the recovered data into the clone.

    Every record containing data will load into the newly created data file without blank records.

 Note
You can also perform this operation in the Btrieve Interactive Maintenance utility.

Prev
Importing and Exporting Data 		Up
Check for Revisions 		Next
Viewing Data File Statistics


Viewing Data File Statistics

This section includes information about generating a report that contains a data file's characteristics and statistics using STAT.

STAT

The STAT command generates a report that contains defined characteristics of a data file and statistics about the file's contents. Using the STAT command is a good way to determine if a file can be logged by the MicroKernel's transaction durability feature. The STAT command reports indexes the same whether they were created by the Create Supplemental Index operation (in Btrieve 6.0 and later) or the Create operation.

Format

BUTIL -STAT <sourceFile> [/O<owner | *>] [/S]

sourceFile | The fully qualified name of the data file for which to report statistics. For Windows NT, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/Oowner | The owner name for the data file, if required.
/S (NetWare only) | By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the/S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Example

The following example reports file statistics for the PATIENTS.DTA file. The data file does not have an owner name.

butil -stat patients.dta

However for NetWare, you must specify the full path such as:

butil -stat sys:\pvsw\demodata\patients.dta.

The following example shows the resulting report:

**************************************************
File Statistics for PATIENTS.DTA

File Version = 8.00
Page Size = 2048
Page Preallocation = No
Key Only = No
Extended = No

Total Number of Records = 16
Record Length = 104
Data Compression = No
Variable Records = No

Available Linked Duplicate Keys = 0
Balanced Key = No
Log Key = 1
 System Data = No
Total Number of Keys = 3
Total Number of Segments = 4

Key  Segment Position Length  Type  Flags
Null Values*  Unique  ACS Values
0    1       21       20      String MD
--            16       0
0    2        7       12      String MD
--            16       0
1    1        1        6      String M
--            16       0
2    1       83       10      String MD
--            7        0

Alternate Collating Sequence (ACS) List:
 0 UPPER

Legend:
 < = Descending Order
 D = Duplicates Allowed
 I = Case Insensitive
 M = Modifiable
 R = Repeat Duplicate
 A = Any Segment (Manual)
 L = All Segments (Null)
 * = The values in this column are hexadecimal.
?? = Unknown
-- = Not Specified

This example shows that the file called PATIENTS.DTA is an 8.0 file. (The version number indicates the earliest Btrieve version that can read the file format.) The file has a page size of 2,048 bytes and has no preallocated pages. This is not a key-only file, nor is it an extended file.

Sixteen records have been inserted into the file. The file was defined with a record length of 104 bytes, does not use data compression, and does not allow variable-length records.

There are no linked duplicate keys available in the file. The file does not use balanced indexing. The MicroKernel performs logging using Key 1, and the file contains no system-defined data. The file has three keys comprised of four key segments.

Note
Indexes created with SINDEX are designated with the letter R by default unless you specified the Reserved Duplicate Pointer element.

The STAT report also provides information about specific keys. For example, the report shows that Key 0 allows duplicates, is modifiable, and consists of two segments:

  • The first segment starts in position 21, is 20 characters long, allows duplicates, is modifiable, and will be sorted as a STRING type. The dashes indicate that a null value was not defined. The Unique Values column indicates that 16 unique values were inserted for this segment. This segment uses the UPPER.ALT alternate collating sequence file.
  • The second segment starts in position 7, is 12 characters long, allows duplicates, is modifiable, and will be sorted as a STRING type. Sixteen unique values were inserted for this segment. This segment uses the UPPER.ALT alternate collating sequence file.

Key 1 is the key the MicroKernel uses in logging this file. Key 1 consists of one segment. It starts in position 1, is six characters long, does not allow duplicates, is modifiable, and will be sorted as a STRING type. Sixteen unique values were inserted for this key. This key uses the UPPER.ALT alternate collating sequence file.

Key 2 consists of one segment. It starts in position 83, is 10 characters long, allows duplicates, is modifiable, and will be sorted as a STRING type. Seven unique key values were inserted for this key. This key uses the UPPER.ALT alternate collating sequence file.

File Version Notes

When reporting the file format version for a file, the MicroKernel reports the earliest engine version that can read the specified file. For example, you may have a file that was created in Btrieve 5.x format, but it may be reported as a version 3.x file because it does not use any 4.x or 5.x features. Starting with the 6.x format, the file itself contains a version stamp. Prior to 6.x, the only way to determine the file format version of a file is by inspecting the features that it uses. For version 5.x or earlier files, the table below shows the features which, if used, determine the version that is reported for the file:
Table 14-11 Version 5.x and Earlier File Format Features
This file format version is reported ... | ... if one or more of these features are in use:
5.x | Compressed records Key only file
4.x | Extended key types Variable length records Index added with CreateIndex operation
3.x | None of the above

Prev
Creating and Modifying Data Files 		Up
Check for Revisions 		Next
Displaying Btrieve Interface Module Version


Displaying Btrieve Interface Module Version

This section includes detailed information about displaying the version of the Btrieve Interface module using the VER command.

VER

The VER command returns the version number of both the MicroKernel and the Btrieve Access Module.

Format

BUTIL -VER [/S]

/S (NetWare only)

By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Remarks

When you run the VER command, the utility displays messages similar to the following:

The Btrieve Requester version is 8.00.
The Btrieve Version is 8.00.
Prev
Viewing Data File Statistics 		Up
Check for Revisions 		Next
Unloading the Btrieve Interface and Requester (DOS only)


Unloading the Btrieve Interface and Requester (DOS only)

STOP

Use the STOP command to unload the Btrieve Interface and, if applicable, the requester.

Format

butil -stop
Prev
Displaying Btrieve Interface Module Version 		Up
Check for Revisions 		Next
Performing Continuous Operations


Performing Continuous Operations

The commands pertaining to continuous operations, startbu and endbu, are discussed in the chapter Logging, Backup, and Restore .

Prev
Unloading the Btrieve Interface and Requester (DOS only) 		Up
Check for Revisions 		Next
Converting Data Files


Converting Data Files

Maintaining Pervasive.SQL File Compatibility

Pervasive.SQL includes tools that convert Pervasive.SQL files to take advantage of features in the latest versions of the Pervasive.SQL engines. This chapter describes those tools, why you might need to use them and how to do so. This chapter includes the following sections:

Rebuild utility (GUI and Command-line):

  • Rebuild Utility Concepts
  • Rebuild Utility GUI Reference
  • Rebuild Utility Tasks

Null Conversion Wizard:

  • Null Conversion
Prev
Performing Continuous Operations
Check for Revisions 		Next
Rebuild Utility Concepts


Rebuild Utility Concepts

The Rebuild utility allows you to perform the following operations on MicroKernel files (data files and dictionary files):

  • convert older file formats to a newer Pervasive.SQL format
  • convert newer file formats to a format not older than a 6.x format
  • rebuild a file using the same file format (provided the format is 6.x, 7.x, or 8.x)
  • add file indexes
  • change file page size
  • rebuild files to include system data and key or system data without key
  • specify a location and name of the log file used by Rebuild

If your database uses dictionary files (DDFs), you must rebuild them as well as the data files.

Read further in this section to understand the conceptual aspects of rebuilding data files.

  • Platforms Supported
  • File Formats
  • Command Line Parameters
  • Temporary Files
  • Optimizing the Rebuild Process
  • Log File

For information on using the Rebuild utility, see one of these sections:

  • Rebuild Utility GUI Reference
  • Rebuild Utility Tasks
  • CLI Tasks

Platforms Supported

Rebuild comes in two forms: a GUI version for 32-bit versions of Windows, and command-line versions for Linux, NetWare, and Windows. See Rebuild Utility GUI Reference and CLI Tasks .

Linux CLI Rebuild

Rebuild runs as a program, rbldcli, on Linux. By default, the program is located at /usr/local/psql/bin.

NetWare CLI Rebuild

Rebuild runs as an NLM, BREBUILD.NLM, on NetWare. By default, BREBUILD.NLM is located at SYS:\SYSTEM.

Note
When rebuilding a data file larger than 10MB, BREBUILD.NLM can hog CPU on the NetWare platform. Perform rebuild tasks directly at the file server console when server usage is low.

Windows CLI Rebuild

Rebuild runs as a program, rbldcli.exe, on Windows. By default, the program is located at \PVSW\BIN.

File Formats

The current database engines remain compatible with some older file formats, but you may want to convert files to the current format to take advantage of current features. The following table lists the primary reasons for converting from an older to a newer format.
Table 15-1 Rebuild Utility Conversions
Original File Format | Converted File Format | Reason for Conversion
8.x | 8.x | Remove deleted record space from a file, change the page size, or add system data.
Pre-8.x | 8.x | Take advantage of write (insert, update, delete) performance improvements offered by Turbo Write Accelerator.
7.x | 7.x | Original file does not have a system key.
Pre-7.x | 7.x | Take advantage of 7.x features and improve general performance.
Pre-6.0 | 6.x | Take advantage of 6.x features and improve general performance. Use this option only if you are still running the 7.x engine with other 6.x engines.

The file format that results from using the command-line Rebuild depends on the -f parameter. If you omit the -f parameter, Rebuild uses the value set for the MicroKernel's Create File Version configuration option. For example, if the Create File Version value is 8.x, then running the Rebuild utility on version 7.x files converts them to 8.x format. See Create File Version and "-f" parameter .

It is suggested that you back up all the data files you plan to convert before running Rebuild. This is particularly true if you are rebuilding files to the same location as the source files (in which case the rebuilt files replace the source files). Having backup copies allows you to restore the original files if you so desire. To ensure that the backup is successful, you may perform one or more of the following operations:

  • Close all data files before running the backup utility.
  • Use continuous operations (only during the backup).

Note
You cannot run Rebuild on a file that is in continuous operation mode.

Command Line Parameters

The parameter option specifies the parameter(s) used with the utility. You may use the parameters in any order. Precede each parameter with a hyphen (-). Do not place a space after the hyphen or after the single-letter parameter and the parameter value.

Note
On Linux platforms only, the parameters are case sensitive.

Parameter is defined as follows:
-c
Instructs Rebuild to continue with the next file if an error occurs. The utility notifies you of non-MicroKernel data files or errors with MicroKernel files, but continues rebuilding data files. The errors are written to the log file. See Log File .

Tip: This parameter is particularly useful if you specify wildcard characters (*.*) for a mixed set of files. Mixed set means a combination of MicroKernel files and non-MicroKernel files. Rebuild reports an error for each non-MicroKernel file (or any errors on MicroKernel files), but continues processing.
-d
If you specify -d, Rebuild converts pre-6.0 supplemental indexes (which allow duplicates) to 6.x, 7.x, or 8.x indexes with linked-duplicatable keys.

If you omit this parameter, Rebuild preserves the indexes as repeating-duplicatable keys.

If you access your data files only through Btrieve and your files have a relatively large number of duplicate keys, you can use the -d parameter to enhance the performance of the Get Next and Get Previous operations.
-m<0 | 2>
The "m" parameter stands for "method." Rebuild selects a processing method whether you specify this parameter or not. If you omit this parameter, Rebuild does the following:
  • uses -m2 as the default method if sufficient available memory exists
  • uses an alternative method,-m0, if the amount of available memory is not sufficient.

See Amount of Memory for how the amount of memory affects the method chosen.
0
Clones and copies the file without dropping and replacing indexes. This method is slower than the -m2 method. It is available in case you do not want to rebuild your indexes.

A file built with the -m0 creates a file where each key page is about 55% to 65% full. The file is more optimized for writing and less for reading. If you can afford the extra rebuild time, which can be considerable depending on the situation, you might want to rebuild a file optimized for writing.

See also Optimizing the Rebuild Process .
2
Clones the file, drops the indexes, copies the records into the new file, and rebuilds the indexes. This method is faster and creates smaller files than the -m0 method.

The -m2 method may create a new file in which the records are in a different physical order than in the original file.

A file built with the -m2 method has key pages that are 100% full. This allows the file to be optimized for reading.
-p<D | P | bytes>
Optimizes page size for disk storage or processing, or specifies a specific page size to use for the rebuilt file.

If you omit this parameter, Rebuild uses the page size from the source file. If the source page size does not work for the current database engine, Rebuild changes the page size and displays an informative message explaining the change. (For example, older file formats, such as 5.x, supported a page size of 1024 with 24 keys. File format 8.x supports only 23 keys for a page size of 1024, so Rebuild would select a different page size if building an 8.x file.)

See also Index Page Size .
D
Optimizes page size for disk storage. For a discussion of optimal page size for disk storage, Choosing a Page Size in Pervasive.SQL Programmer's Guide, which is part of the Pervasive.SQL Software Developer's Kit (SDK).
P
Optimizes for processing (that is, for your application accessing its data). For -pP, Rebuild uses a page size of 4096 bytes.
bytes
Specifies the page size (in bytes) for the new file. The only valid values are 512, 1024, 1536, 2048, 2560, 3072, 3584, and 4096 (multiples of 512 up to 4096).
-bdirectoryname
Specifies an alternate location for the rebuilt file (which may also be a location on a different server). The default location is the directory where the data file is located. You must specify a location that already exists. Rebuild does not create a directory for you.

You may use either a fully qualified path or a relative path. Do not use wildcard characters in directoryname.

On your local server, the MicroKernel Database Engine and the Message Router must be loaded. On a remote server, the MicroKernel Database Engine and communications components must be loaded.

If you omit this parameter, the rebuilt file replaces the original data file. A copy of the original file is not retained.

If you specify this parameter, the rebuilt file is placed in the specified location and the original file is retained. An exception to this is if the specified location already contains data files with the same names. Rebuild fails if the alternate location you specify contains files with the same names as the source files. For example, suppose you want to rebuild mydata.mkd, which is in a directory named folder1. You want to place the rebuilt file into a directory named folder2. If mydata.mkd also exists in folder2 (perhaps unknown to you), Rebuild fails and informs you to check the log file.

Note: Ensure that you have create file permission for the location you specify (or for the location of the source file if you omit the parameter).
-knumber
Specifies the key number that Rebuild reads from the source file and uses to sort the rebuilt file. If you omit this parameter, Rebuild reads the source file in physical order and creates the rebuilt file in physical order.

See also Optimizing the Rebuild Process .
-s[D | K]
Retains in the rebuilt file the existing system data and key from the source file. If you omit this parameter, Rebuilt does not include the system data and key in the rebuilt file.

See also System Data .
D
Rebuilds the file to include system data. The system data is not indexed. See also System Data .
K
Rebuilds the file to include system data and key. The system data is indexed. See also System Data .
-lfile
Specifies a file name, and optionally a path location, for the Rebuild log file. The default file name is rbldcli.log on Windows and Linux. On NetWare, the default file name is brebuild.log. The default location is the current working directory on Windows and Linux. On NetWare, the default location is SYS:\SYSTEM.
The following conditions apply:
  • The path location must already exist. Rebuild does not create the path location.
  • If you specify a path location without a file name, Rebuild ignores this parameter and uses the default file name and location.
  • If you specify a file name without a path location, Rebuild uses the default location.
  • You must have read and write file permission for the location you specify. Rebuild uses the default location if it cannot create the log file because of file permission.

See also Log File .
-f<6 | 7 | 8>
Specifies a file format for the rebuilt file. File formats supported are versions 6.x, 7.x, and 8.x. The following example rebuilds a file to the 7.x format:

rbldcli -f7 c:\pvsw\demodata\class.mkd

If you omit this parameter, Rebuild uses the value set for the MicroKernel's "Create File Version" configuration option. See Create File Version .

Note1: If you specify a file format newer than the version supported by the current database engine, Rebuild uses the highest supported file format of that engine. Rebuild reports no error or message for this. For example, if the database engine is Pervasive.SQL 2000i and you specify a file format of 8.x (-f8), the file is rebuilt to 7.x. File format 7.x is the highest one supported by the Pervasive.SQL 2000i engine.

Note2: Rebuild does not convert data types in indexes. If you rebuild a file to an older file format for use with an older database engine, ensure that the engine supports the data types used. You must manually adjust data types as required by your application and by the database engine.

Example1. Your data file contains index fields that use the WZSTRING data type. If you rebuild the data file to a 6.x file format, the WZSTRING data type is not converted. You would be unable to use the data file with a Btrieve 6.15 engine. That engine does not support the WZSTRING data type.

Example 2. Your data file contains true NULLs. You rebuild the data file to a 7.x file format. The true NULLs are not converted. You would be unable to use the data file with the Pervasive.SQL 7 engine. That engine does not support true NULLs.

File and @command_file are defined as follows:
file
Specifies the file(s) to convert. If the source file is not in the current working directory, include the location, either as a fully qualified path or as a relative path. You may use the asterisk (*) wildcard character in the file name to specify multiple files.

Note: If the original file contains an owner name, Rebuild applies the owner name and level to the rebuilt file.
@command_file
Specifies a command file for Rebuild to execute. You may include multiple entries in one command file. Each entry in the command file contains the command line parameters (if any) and the set of files to convert, followed by <end> or [end].

When specifying the files to convert, use full directory names. You may use the asterisk (*) wildcard character in the file names.

The following is an example of a Rebuild command file:

–c sys:\mydir\*.* <end>
–c –p1024 dta:\dir\*.* <end>
–m0 –k0 sys:\ssql\*.* <end>

Temporary Files

On Windows, Rebuild creates temporary files in the directory specified by the TMP system environment variable. By default on NetWare and Linux, Rebuild creates temporary files in the output directory (or in the source directory if the -b parameter is not used). Therefore, you need enough disk space in the temporary file directory (while the Rebuild utility is running) to potentially accommodate both the original file and the new file. You can specify a different directory for storing these files by using the Output Directory option in the Rebuild GUI version or by using the -b parameter with the CLI versions.

Normally, Rebuild deletes temporary files when the conversion is complete. However, if a power failure or other serious interruption occurs, Rebuild may not delete the temporary files. If this occurs, delete the following types of temporary files:
Platform | Temporary File Names
Linux | _rbldxxxxxx, where xxxxxx is six random letters. Caution: Ensure that you do not delete the Rebuild executable, rbldcli.
NetWare | _T-xxxxx.TMP, where xxxxx is five random characters
Windows | _rbldx, where x is a number.

Optimizing the Rebuild Process

Rebuild makes Btrieve calls to the MicroKernel. Therefore, the MicroKernel configuration settings and the amount of random access memory (RAM) in your computer affect the performance of the rebuild process. This is particularly evident in the amount of time required to rebuild large data files.

In general, building indexes requires much more time than building data pages. If you have a data file with many indexes, it requires more time to rebuild than would the same file with fewer indexes.

The following items can affect the rebuild processing time:

  • CPU Speed and Disk Speed
  • Amount of Memory
  • Sort Buffer Size
  • Max MicroKernel Memory Usage
  • Cache Allocation Size
  • Index Page Size
  • Number of Indexes

CPU Speed and Disk Speed

The speed of the central processing unit (CPU) and access speed of the physical storage disk can affect processing time during a rebuild. In general, the faster the speed for both of these, the faster the rebuild process. Disk speed is more critical for rebuilding files that are too large to fit entirely in memory.

Tip
Large files, such as 3 or 4 GB or more, may take several hours to convert. If you have more than one database engine available, you may wish to share the rebuild processing among a number of machine CPUs. For example, you could copy some of your files to each machine that has a database engine installed, then copy the files back after the rebuild process.

Amount of Memory

Rebuild is capable of rebuilding a file using two different methods, a default method and an alternative method. See -m<0 | 2> parameter . The method chosen depends on the amount of memory available. For the default method (-m2), Rebuild takes the following steps provided available memory exists.

  1. Creates a new, empty data file with the same record structure and indexes as defined in the source file.
  2. Drops all the indexes from the new file.
  3. Copies all the data into the new file, without indexes.
  4. Adds the indexes, using the following process.
    1. For a particular key in the source file, reads as many key values as possible into a memory buffer using the Extended Step operation.
    2. Sorts the values in the memory buffer and writes the sorted values to a temporary file.
    3. Repeats steps a and b, processing the key value from every record.

      The temporary file now contains several key value sets, each of which has been individually sorted.

  5. Merges the sets into index pages, filling each page to capacity. Each index page is added to the data file at the end, extending the file length.
  6. Repeats steps 4 and 5 for each remaining key.

If any failure occurs during this process, such as a failure to open or write the temporary file, Rebuild starts over and uses the alternative method to build the file.

Rebuild uses an alternative method (-m0) when insufficient memory exists to use the default method, or if the default method encounters processing errors.

  1. Creates a new, empty data file with the same record structure and indexes as defined in the source file.
  2. Drops all the indexes from the new file.
  3. Copies all the data into the new file, without indexes.
  4. Adds the indexes, using the following process.
    1. For a particular key in the source file, reads one record at a time using the Step Next operation.
    2. Extracts the key value from the record and inserts it into the appropriate place in the index. This necessitates splitting key pages when they get full.
    3. Repeats steps a and b, processing the key value from every record.
  5. Repeats step 4 for each remaining key.

The alternative method is typically much slower than the default method. If you have large data files with many indexes, the difference between the two methods can amount to many hours or even days. The only way to ensure that Rebuild uses the default method is to have enough available memory. In a NetWare environment, the available memory must also not be highly fragmented. Several Configuration settings affect the amount of available memory.

Formulas For Estimating Memory Requirements

The following formulas estimate the optimal and minimum amount of contiguous free memory required to rebuild file indexes using the fast method. The optimal memory amount is enough memory to store all merge blocks in RAM. The minimum amount of memory is enough to store one merge block in RAM.

Key Length = total size of all segments of largest key in the file.
Key Overhead = 8 if key type is not linked duplicate. 12 if key type is linked duplicate.
Record Count = number of records in the file.

Optimal Memory Bytes = (((Key Length + Key Overhead) * Record Count) + 65536) / 0.6

Minimum Memory Bytes = Optimal Memory Bytes / 30

For example, if your file has 8 million records, and the longest key is 20 bytes (not linked duplicate), the preferred amount of memory is 373.5 MB, or ((( 20 + 8 ) * 8,000,000 ) + 65536 ) / 0.6 = 373,442,560 bytes.

The optimal amount of contiguous free memory is 373.5 MB. If you have at least this much free memory available, the Rebuild process takes place entirely in RAM. Because of the 60% allocation limit, the optimal amount of memory is actually the amount required to be free when the rebuild process starts, not the amount that the rebuild process actually uses. Multiply this optimal amount by 0.6 to determine the maximum amount Rebuild actually uses.

The minimum amount of memory is 1/30th of the optimal amount, 12,448,086 bytes, or 12.45 MB.

The divisor 30 is used because the database engine keeps track of no more than 30 merge blocks at once, but only one merge block is required to be in memory at any time. The divisor 0.6 is used because the engine allocates no more than 60% of available physical memory for rebuild processing.

If you do not have the minimum amount of memory available, Rebuild uses the alternative method to rebuild your data file.

Finally, the memory block allocated must meet two additional criteria: blocks required and allocated block size.

Blocks required must be less than or equal to 30, where:

Blocks Required = Round Up (Optimal Memory Bytes / Allocated Block)

Allocated block size must be greater than or equal to:

((2 * Max Keys + 1) * (Key Length + Key Overhead)) * Blocks Required

Assuming a 512-byte page size, and a block of 12.45 MB successfully allocated, the value for blocks required is:

Blocks Required = 373,500,000 / 12,450,000 = 30

The first criteria is met.

The value for allocated block size is:

Max Keys = (512-12) / 28 = 18
(((2 * 18) + 1) * (20 + 8)) * 9 = 9324

Is Allocated Block (12.5 million bytes) larger than 9324 bytes? Yes, so the second criteria is met. The index keys will be written to a temporary file in 12.45 MB pieces, sorted in memory, and then written to the index.

Sort Buffer Size

This setting specifies the maximum amount of memory that the MicroKernel dynamically allocates and de-allocates for sorting purposes during run-time creation of indexes. See Sort Buffer Size .

If the setting is zero (the default), Rebuild calculates a value for optimal memory bytes and allocates memory based on that value. If the memory allocation succeeds, the size of the block allocated must be at least as large as the value defined for minimum memory bytes. See Formulas For Estimating Memory Requirements .

If the setting is a non-zero value, and the value is smaller than the calculated minimum memory bytes, Rebuild uses the value to allocate memory.

Finally, Rebuild compares the amount of memory that it should allocate with 60% of the amount that is actually available. It then attempts to allocate the smaller of the two. If the memory allocation fails, Rebuild keeps attempting to allocate 80% of the last attempted amount. If the memory allocation fails completely (which means the amount of memory is less than the minimum memory bytes), Rebuild uses the alternative method to rebuild the file.

Max MicroKernel Memory Usage

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). See Max MicroKernel Memory Usage .

If you have large files to rebuild, temporarily set Max MicroKernel Memory Usage to a lower percentage than its default setting. Reset it to your preferred percentage after you complete your rebuilding.

Cache Allocation Size

This setting specifies the size of the Level 1 cache that the MicroKernel allocates; the MicroKernel uses this cache when accessing any data files. See Cache Allocation Size .

This setting determines how much memory is available to the MicroKernel for accessing data files, not for use when indexes are built.

Increasing Cache Allocation to a high value does not help indexes build faster. In fact, it may slow the process by taking up crucial memory that is now unavailable to Rebuild. When rebuilding large files, decrease the cache value to a low value, such as 20% of your current value but not less than 5 MB. This leaves as much memory as possible available for index rebuilding.

Index Page Size

The page size in your file also affects the speed of index building. If Rebuild uses the alternative method, smaller key pages dramatically increase the time required to build indexes. Key page size has a lesser effect on building indexes if Rebuild uses the default method.

Rebuild can optimize page size for application performance or for disk storage.

To optimize for performance (your application accessing its data), Rebuild uses a page size of 4096 bytes. This results in larger page sizes on physical storage and slower rebuilding times.

For a discussion of optimizing page size for disk storage, see Choosing a Page Size in Pervasive.SQL Programmer's Guide, which is part of the Pervasive.SQL Software Developer's Kit (SDK).

Assume that your application has 8 million records, a 20-byte key, and uses a page size of 512 bytes. The MicroKernel places between 8 and 18 key values in each index page. This lessens the amount of physical storage required for each page. However, indexing 8 million records creates a B-tree about seven levels deep, with most of the key pages at the seventh level. Performance will be slower.

If you use a page size of 4096 bytes, the MicroKernel places between 72 and 145 key values in each index page. This B-tree is only about four levels deep and requires many fewer pages to be examined when Rebuild inserts each new key value. Performance is increased but so is the requirement for the amount of physical storage.

Number of Indexes

The number of indexes also affects the speed of index building. Generally, the larger the number of indexes, the longer the rebuild process takes. The time required to build the indexes increases exponentially with increasing depth of the B-tree.

Log File

Information from a rebuild process is appended to an ASCII log file. By default, the log file is placed in the current working directory except on NetWare. On NetWare, the default location for the log file is SYS:\SYSTEM. The default file name is rbldcli.log on Windows and Linux. On NetWare, the default file name is brebuild.log.

You may specify a location and name for the log file. See -lfile parameter .

You may examine the log file using a text editor. The information written to the log file includes the following:

  • Start time of the rebuild process
  • Parameters specified on the command line
  • Status code and error description (if an error occurs)
  • File being processed
  • Information about the processing (such as page size changes)
  • Total records processed
  • Total indexes rebuilt (if the -m2 processing method is used)
  • End time of the rebuild process
  • Status of the process (for example, if the file rebuilt successfully)

Prev
Converting Data Files 		Up
Check for Revisions 		Next
Rebuild Utility GUI Reference


Rebuild Utility GUI Reference

This section describes the objects on the Rebuild utility graphical user interface (GUI).

File Options Screen

This screen allows you to add files to the rebuild list.

Figure 15-1 Rebuild Utility File Selection

GUI Object | Description | Related Information
Selected files | The files listed for rebuilding according to your selections using the Add button. | To select files for rebuilding
Add button | Adds a file to the list of files to be rebuilt. | To select files for rebuilding
Remove button | Removes the selected file in the list. | To select files for rebuilding
Clear button | Clears the entire list of selected files. | To select files for rebuilding

Rebuild Options Screen

This screen allows you to select the options for rebuilding files.

Figure 15-2 Rebuild Utility File Options

GUI Object
Description
Related Information
System Data
Specify whether you want Rebuild to create a System Data key in the file.
System data is necessary for transaction durability logging.
Specifies whether the file is rebuilt with System Data or System and Key Data. The MicroKernel cannot perform logging for a file without system data when no user-defined unique key exists.
To specify rebuild options
Continue on Error
Determines whether the Rebuild utility continues if it encounters an error during the rebuild process. If you select Yes, the utility continues with the next file even if an error occurs. The utility notifies you of non-MicroKernel data files or other errors but continues rebuilding data files. If you select No, the utility halts the rebuild if it encounters an error.

This option is useful if you have specified wildcard characters for the rebuilt files.
To specify rebuild options
Save Settings on Exit
Saves the current values in this dialog box for use in subsequent Rebuild sessions.
To specify rebuild options
Key Number
Specifies the key by which the utility reads when rebuilding a file. If you specify NONE for this option, the utility clones the files, drops the indexes, copies the records into the new files, and rebuilds the indexes. Because this method is faster and creates smaller files than specifying a key number, use it whenever possible.

This method may create a new file in which the records are in a different physical order than in the original file.

If you specify a key number, the utility clones and copies the files without dropping and replacing indexes. While this method is slower than specifying NONE, it is available in case you do not want to rebuild your indexes.
  • To specify rebuild options
  • Key Attributes in Pervasive.SQL Programmer's Guide, which is part of the Pervasive.SQL Software Developer's Kit (SDK).
Page Size
Specifies the page size (in bytes) of the new files. Choose either EXISTING, 512, 1024, 2048, 3072, or 4096. If you select EXISTING, the utility uses the existing page size. The utility changes the page size if the original size does not work.

For example, assume you have a v5.x file with a page size of 1,024 and 24 keys. Because Btrieve 6.0 and later supports only 23 keys for a page size of 1,024, the utility automatically selects a new page size for the file and writes an informative message to the status file.
  • To specify rebuild options
  • Choosing a Page Size in Pervasive.SQL Programmer's Guide, which is part of the Pervasive.SQL Software Developer's Kit (SDK)
File Format
Previous, the Rebuild utility built the file version based on the Create File Version configuration setting.
This Rebuild utility allows you to specify the file version type independent of that setting.
Choose 6x, 7x, or 8x for the file version of the rebuilt file.
To specify rebuild options
Output Path
Specifies an alternate location for the rebuilt files. (The default location is the current directory.) You must specify a directory that already exists.

This option lets you rebuild large files on a different server. The MicroKernel and its communications components must be loaded on the server that contains the rebuilt files. Do not use wildcard characters in the path.

If the Output Directory location is different than the original file's location, the original file is not deleted during the rebuild. If the output directory is the same as the original file, the original file is deleted upon completion of the rebuild.
DefaultDB w/ DB security: Cannot rebuild outside DB's file locations in Maintain Named Databases
To specify rebuild options
Log File
Specifies a location for the rebuild log file. (The default location is the current working directory.) Do not use wildcard characters in the path.
  • To specify rebuild options
  • Log File

Rebuild Progress Screen

This screen allows you to see the rebuild progress and to view the log file.

Figure 15-3 Rebuild Utility File Options

GUI Object | Description | Related Information
Message area | Displays the information about the file being rebuilt, or a summary of the operations if rebuilding has completed. | Log File
View Log File | Allows you to see information about the rebuild process for each file. Click View Log File to display the rebuild log using your default text viewer. | Log File

Prev
Rebuild Utility Concepts 		Up
Check for Revisions 		Next
Rebuild Utility Tasks


Rebuild Utility Tasks

The following Rebuild tasks are available:

  • GUI Rebuild: GUI Tasks
  • Command-line Rebuild: CLI Tasks

GUI Tasks

  • To start the GUI Rebuild utility
  • To obtain help for the Rebuild utility
  • To select files for rebuilding
  • To specify rebuild options
  • To start the rebuild process

To start the GUI Rebuild utility

There are two ways to start the GUI Rebuild utility:

  • On a Windows machine, select Tools, then Rebuild from the Pervasive Control Center menu.
  • From the Windows Start menu, select Programs, then Pervasive.SQL V8, then Other Utilities, then Rebuild.

To obtain help for the Rebuild utility

You can access this help file by clicking Help in any dialog box.

To select files for rebuilding

  1. After you click Next at the Rebuild welcome screen, the Select Files dialog box appears (Figure 15-4.)

Figure 15-4 Select Files Dialog Box

  2. Click Add and select the file you want to rebuild. You can select more than one file to rebuild at a time. Click OK when you have finished adding files to rebuild.

    The Rebuild utility deletes the original file after rebuilding it if the file is being rebuilt in the same directory. If the new file is in a different directory, the original file is not deleted.

    Click Next and continue with Step 3.

To specify rebuild options

  3. Before you rebuild the file(s), you may want to specify settings. The Settings dialog box displays as illustrated in Figure 15-5.

Figure 15-5 Settings Dialog Box

You can change the configuration options for the Rebuild utility before you rebuild your selected file or files. These options are defined in Rebuild Options Screen .

When you are ready, see To start the rebuild process .

To start the rebuild process

  4. Click Next to begin the rebuild process, which converts all of the listed files.

    When the process completes, a message dialog box informs of the success or failure of the conversion and prompts you to view the results.

Figure 15-6 Start Rebuild Dialog Box

  5. Click Finish when you have finished converting files.
  6. To display the results, click View Log File The REBUILD.LOG file is displayed as illustrated in Figure 15-7.

Figure 15-7 Rebuild Log Display

The Rebuild utility writes to the status file for every file it attempts to convert. The log file (REBUILD.LOG by default) is an ASCII text file that is placed by default in the directory in which you run the Rebuild utility from.

You can examine the log file by selecting the View Status File command from the Run menu. The rebuild settings are listed for every file. If you disabled the Continue on Error setting, the status file contains the information up to the point of the error. If the rebuild was not successful, the status file contains error messages explaining why the rebuild failed.

CLI Tasks

The following command line Rebuild utility tasks are available.

  • To run Rebuild on Linux
  • To run Rebuild on NetWare
  • To run the Rebuild on Windows
  • To learn about the command line parameters for the CLI Rebuild utility, see Command Line Parameters
  • To see your progress while rebuilding files

To run Rebuild on Linux

  1. Ensure that the account under which you are logged in has permission to run Pervasive.SQL utilities.

    By default, you must be logged in as user psql to run utilities. User psql has no password and can be accessed only through the root account by using the su command. To use utilities from accounts other than psql, you must first make modifications to your .bash_profile. See "Pervasive.SQL Account Management on Linux" in Getting Started With Pervasive.SQL (Server edition).

  2. Change directory to /usr/local/psql/bin directory.
  3. Type one of the following commands at the prompt:
    rbldcli [–parameter ...] file
or
rbldcli @command_file

Parameter, file, and @command_file are defined in Command Line Parameters .

Example Usage

The following example continues on error, sets a page size of 4096 bytes, and places the rebuilt files in a different directory on the server.

rbldcli -c -p4096 -b/usr/local/psql/tmp /usr/local/psql/data/DEMODATA/*.mkd

To run Rebuild on NetWare

  1. Run RCONSOLE from a workstation, or go to the server's console.
  2. Type one of the following commands at the prompt:
    LOAD BREBUILD [–parameter ...] file
or
LOAD BREBUILD @command_file

Parameter, file, and @command_file are defined in Command Line Parameters .

Example Usage

The following example continues on error, sets a page size of 4096 bytes, and places the rebuilt files in a different directory on the server.

LOAD BREBUILD –c –p4096 –bsys:\newfiles sys:\oldfiles\*.mkd

To run the Rebuild on Windows

  1. Open a command prompt on the machine where Pervasive.SQL is installed. (Depending on your operating system, click Start 4 Programs 4 Command Prompt or Start 4 Programs 4 Accessories 4 Command Prompt.)
  2. Optionally, change directory to PVSW\BIN. (This is not required if PVSW\BIN is in the Path system variable.)
  3. Type one of the following commands at the prompt:
    rbldcli [–parameter ...] file
or
rbldcli @command_file

Parameter, file, and @command_file are defined in Command Line Parameters .

Example Usage

The following example continues on error, sets a page size of 4096 bytes, and places the rebuilt files in a different directory on the server.

rbldcli -c -p4096 -bc:\dbtemp c:\datafiles\*.mkd

To see your progress while rebuilding files

Rebuild reports on the screen the number of records processed per file, incrementing 50 records at a time. In addition, Rebuild writes information to an ASCII log file. See Log File .

Prev
Rebuild Utility GUI Reference 		Up
Check for Revisions 		Next
Null Conversion


Null Conversion

The Null Conversion Utility adds or removes support for nullable columns in Pervasive.SQL tables. The utility allows users to:

  • Convert legacy tables into Pervasive.SQL V8 format
  • Change not-nullable columns to nullable
  • Change nullable columns to not-nullable

In Pervasive.SQL V8, null values are added as an extra byte to the default record. If you set this extra byte as any value other than zero, it is designated as null. This extra byte can be used to define the index. If a field is not defined as nullable, no extra bytes are added.

Note
There are a maximum number of segments allowed per file. In Pervasive.SQL V8, true null columns contain two segments per index. Therefore, it is important to keep in mind that defining null values doubles the number of segments used. See the Pervasive.SQL Programmer's Guide for more information about maximum Btrieve segment sizes.

Note
In a case where a user converts an existing table with legacy nulls and the null values differ from the defaults, the Null Conversion utility will allow the user to specify which value(s) should be considered null for each column.

Caution
Do not run this utility on data files that are accessed by older Btrieve applications. Doing so can make the data unusable to the older application unless the underlying application code is changed.

The Null Conversion utility is implemented as a wizard with the Pervasive.SQL Control Center framework.

To convert a table's nullable fields:

  1. Open on the Databases namespace node under a machine in the Control Center namespace tree.
  2. Right-click on the desired database in the namespace.
  3. Select Tasks, then Null Conversion in the shortcut menu.
  4. The wizard presents a dialog box in which the user can specify which tables in the database are to undergo null conversion.

Figure 15-8 Null Conversion Wizard Dialog Box

Click the check box under the Convert column for those tables that are to be converted. Click Next when done.

  5. Next, the wizard presents a dialog box allowing the indication of which fields are currently nullable. These values may be changed at this time.

Figure 15-9 Null Conversion Wizard - Specify Columns for Conversion Dialog Box

 Note
Some data types are not nullable, such as BIT and AUTOINC.

  6. Before changes are committed to the database the following dialog box displays the actions that are to be taken.

Figure 15-10 Null Conversion Wizard - Completing Dialog Box

To stop the operation, click Cancel. To continue, click Convert.

  7. Finally, the Null Conversion Wizard indicates that the selected tables were converted successfully (not shown).
Prev
Rebuild Utility Tasks 		Up
Check for Revisions 		Next
Description Files


Description Files

Using Description Files to Store Btrieve File Information

A description file is an ASCII text file that contains descriptions of file and key specifications that the Maintenance utility can use to create data files and indexes. Some users employ description files as a vehicle for archiving information about the data files they have created. Description files are not the same as DDFs, or Data Dictionary Files, which are used with the SQL Interface and the ODBC Interface.

Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space). Each element in a description file corresponds to a particular characteristic of a data file or key specification.

Note
Before using description files, you should be familiar with Btrieve fundamentals, such as data compression and index balancing. For information about these topics, refer to the Pervasive.SQL Programmer's Guide.

This appendix discusses the following topics:

Prev
Null Conversion
Check for Revisions 		Next
Rules for Description Files


Rules for Description Files

Use the following rules when creating a description file.

  • Enter elements in either uppercase or lowercase.
  • Separate elements from each other with a separator (blank space, tab, or carriage return/line feed), as in the following example:
    record=4000
key=24
  • Specify the description file elements in the proper order. Table A-1 presents the elements in the appropriate order.
  • Address all element dependencies. For example, if you specify nullkey=allsegs in your description file, you must also specify a value for the value= element.
  • Define as many keys as you specify with the Key Count element. For example, if you specify key=12, you must define 12 keys in the description file.
  • For a key that consists of multiple segments, you must define the following elements for each key segment:
    • Key Position
    • Key Length
    • Duplicate Key Values
    • Modifiable Key Values
    • Key Type

      The Descending Sort Order element is optional for each segment.

  • If any key in the file uses an ACS, you must specify an ACS file name, a country ID and code page ID, or an ISR table name. You can include this information as either the last element of the key (applies to current key only) or the last element in the description file (applies to entire data file).
    • You can specify only one ACS per key, and you must provide an ACS file name, country ID and code page ID, or an ISR table name. Different keys in the same file can use different types of ACSs; for example, Key 0 can use an ACS file name, and Key 1 can use a country ID and code page ID.
    • Different segments of the same key cannot have different ACSs.
    • If you specify an ACS at the end of a description file, it is used as the default ACS. That is, if you specify alternate=y for a given key but do not include an ACS file name, country ID and code page ID, or an ISR table name for that key, the MicroKernel uses the ACS file name, country ID and code page ID, or ISR table name specified at the end of the file.
    • If you are creating a new key and you specify alternate=y but you omit the ACS file name, country ID and code page ID, or ISR table name, the MicroKernel does not create the key.
  • If a Description File element is optional, you can omit it.
  • Make sure the description file contains no text formatting characters. Some word processors embed formatting characters in a text file.
Prev
Description Files 		Up
Check for Revisions 		Next
Description File Examples


Description File Examples

The sample description files shown in this section describe a data file. This data file has a page size of 512 bytes and 2 keys. The fixed-length portion of the record is 98 bytes long. The file allows variable-length records but does not use blank truncation.

The file uses data compression, allows for Variable-tail Allocation Tables (VATs), and has the free space threshold set to 20 percent. The MicroKernel Database Engine preallocates 100 pages, or 51,200 bytes, when it creates the file. The file has two keys: Key 0 and Key 1. Key 0 is a segmented key with two segments.

In Figure A-1 , both keys use the same ACS file name (UPPER.ALT). In Figure A-2 , both keys use the same country ID (–1) and code page ID (–1). In Figure A-3 , Key 0 and Key 1 use different ACS file names (LOWER.ALT and UPPER.ALT, respectively). In Figure A-4 , the file has no keys except the system-defined key used for logging.

Figure A-1 Sample Description File Using Alternate Collating Sequence File Name

Figure A-2 Sample Description File Using Alternate Collating Sequence ID

Figure A-3 Sample Description File Using Alternate Collating Sequence File Name
on a Key Segment

Figure A-4 Sample Description File Using System-Defined Key for Logging

Prev
Rules for Description Files 		Up
Check for Revisions 		Next
Description File Elements


Description File Elements

Description file elements must appear in a particular order. Table A-1 lists the description file elements in the appropriate order. For each element, the table specifies the required format and the range of acceptable values.

  • An asterisk (*) indicates that the element is optional.
  • A pound sign (#) indicates that it is not applicable in the current MicroKernel version but is retained for backward compatibility with previous MicroKernel versions.
  • A percent sign (%) indicates that the element is applicable only to the current MicroKernel version.

    Table A-1 Summary of Description File Elements

    Element
    Keyword and Format
    Range
    Comments
    File Specification Information

    Comment Block*
    /*. . . . . . . . . . . . */
    5,120 bytes
    None.
    Record Length
    record=nnnn
    4 – 4,088
    None.
    Variable-Length Records
    variable=<y|n>
    N/A
    Not applicable to key-only files.
    Reserved Duplicate Pointer*
    dupkey=<nnn>
    0–119
    Applicable only to files for which you plan to add linked-duplicatable keys.
    Blank Truncation*
    truncate=<y|n>
    N/A
    Not applicable for files that use data compression.
    Data Compression*
    compress=<y|n>
    N/A
    Not applicable to key-only files.
    Key Count
    key=nnn
    0 –119
    Specify 0 to create a data-only file.
    Page Size
    page=nnnn
    512– 4,096
    Must be a multiple of 512.
    Page Preallocation*
    allocation=nnnnn
    1– 65,535
    None.
    Replace Existing File*#
    replace=<y|n>
    N/A
    None.
    Include Data*
    data=<y|n>
    N/A
    Specify n to create a key-only file. Cannot create a key-only file that both allows duplicates and uses a system-defined key.
    Free Space Threshold*
    fthreshold=<5|10|20|30>
    N/A
    Applicable only for files that have variable-length records. The default is 5.
    Variable-Tail Allocation Tables (VATs)
    huge=<y|n> #
    vats=<y|n>
    N/A
    Applicable only for files that have variable-length records.
    Balanced Index*
    balance=<y|n>
    N/A
    None.
    Use Key Number *
    usekeynum=<y|n>
    N/A
    Used with the Key Number element.
    1Use System Data*%
    sysdataonrecord=
    <n|loggable>
    N/A
    If no element specified, MicroKernel configuration is used. If creating a key-only file, MicroKernel configuration is used and this element is ignored. Also, you cannot create a key-only file that both allows duplicates and uses a system-defined key.
    Key Specification Information

    Key Number *
    keynum=nnn
    0–118
    Must be unique to the file, specified in ascending order, and valid for the file's Page Size. Applicable only when creating a file.
    Key Position
    position=nnnn
    1– 4,088
    Cannot exceed the Record Length.
    Key Length
    length=nnn
    key type limit
    Cannot exceed the limit dictated by the Key Type. For binary keys, the key length must be an even number. The total of the Key Position and Key Length cannot exceed the file's Record Length.
    Duplicate Key Values
    duplicates=<y|n>
    N/A
    Cannot create a key-only file that allows duplicates and uses a system-defined key.
    Modifiable Key Values
    modifiable=<y|n>
    N/A
    None.
    Key Type
    type=
    validMKDEKeyType
    N/A
    Can enter the entire word (as in float) or just the first three letters (as in flo).
    Descending Sort Order*
    descending=<y|n>
    N/A
    None.
    Alternate Collating Sequence
    alternate=<y|n>
    N/A
    Applicable only for case sensitive STRING, LSTRING, WSTRING, WZSTRING, or ZSTRING keys. When creating an additional index for an existing file, if you want the index to use an ACS other than the first one in the data file, use with caseinsensitive=y.
    Case-Insensitive Key*
    caseinsensitive=<y|n>
    N/A
    Applicable only for STRING, LSTRING, or ZSTRING keys that do not use an ACS.
    Repeating Duplicates*
    repeatdup=<y|n>
    N/A
    If creating a key-only file, use repeating duplicates. If using this element, you must use duplicates=y.
    Null Segments*
    nullkey=<allsegs | n | anyseg |>
    N/A
    None.
    Null Key Value
    value=nn
    1-byte hex
    Used with the Null Segments element.
    Segmented Key
    segment=<y|n>
    N/A
    None.
    Alternate Collating Sequence File Name/ID
    name=sequenceFile or countryid=nnn and codepageid=nnn
    isr=table name (%)
    valid path or values valid to operating system or
    –1
    Used with the Alternate Collating Sequence element.
    1
    When the MicroKernel adds a system key, the resulting records may be too large to fit in the file's existing page size. In such cases, the MicroKernel automatically increases the file's page size to the next accommodating size.

Prev
Description File Examples 		Up
Check for Revisions 		Next