Copyright: Getting Started with Pervasive.SQL: part # 100-003415-001. Built 08/11/98 11:16:49


About This Manual

This manual contains information about installing the Btrieve data management system and the SQL relational database system, together called Pervasive.SQL. Btrieve is a complete navigational database management system designed for high-performance data handling and improved programming productivity. Scalable SQL is a relational, embeddable, and scalable database system.

This manual also contains information about common installation pitfalls, general network protocol information, and Btrieve components.

For information about configuring Pervasive.SQL engines, see Pervasive.SQL User’s Guide.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Who Should Read This Manual

Read this manual if you are installing the Pervasive.SQL 7 Workstation product.

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. Please complete the User Comments form that appears on our Web site and fill in part number 100-003415-001.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Manual Organization

This book is arranged in the order of the main installation sequence. You complete the installation by following the chapters in order. Getting Started With Pervasive.SQL is divided into the following sections:

•	Chapter 1—“Welcome to Pervasive.SQL”

This chapter describes the components and documentation that come with Pervasive.SQL.

•	Chapter 2—“Installing the Pervasive Workstation Engine”

This chapter describes installing the Pervasive.SQL on Windows NT or Windows 9X.

•	Chapter 3—“Running the Pervasive Workstation Engines”

This chapter describes how to start and stop Pervasive Database Engines.

•	Chapter 4—“Troubleshooting Installation Problems”

This chapter outlines some common problems that can occur when installing and how to resolve them. It also provides information on Pervasive.SQL tools that aid in diagnosing problems. This chapter gives contact information for Pervasive.SQL support for the case that you do not find the answer to your problem.

This manual also contains an index.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Conventions

Unless otherwise noted, command syntax, code, and code 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.
[ ]	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  [path | @path].
< >	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 path.
...	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.
Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Welcome to Pervasive.SQL

Thank you for purchasing Pervasive.SQL. We hope that you will enjoy using this fast and reliable database product.

This chapter contains the following topics:

•	“Components of Pervasive.SQL”

•	“Documentation Included with Pervasive.SQL”

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Components of Pervasive.SQL

Pervasive.SQL consists of the following components:

•	Btrieve engine

•	Scalable SQL engine

•	ODBC 2.5

•	Utilities that help you troubleshoot configuration problems (SmartScout, InstallScout), enhance performance and set configuration options (Setup), and maintain databases (Maintenance, Rebuild, and DDF Ease).

•	Requesters that allow you to access a server-based Pervasive.SQL product from a Windows 9X/NT, OS/2, Windows 3.x, or DOS client.

 Note: The Pervasive.SQL server engine and the Monitor utility are not included in the Workstation edition of Pervasive.SQL.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Documentation Included with Pervasive.SQL

The following hardcopy documentation comes with Pervasive.SQL 7 Workstation: Getting Started with Pervasive.SQL, and Pervasive Products and Services. All manuals are provided in Windows Help format with the Pervasive.SQL 7 product.

You can order additional hardcopy editions of any of the manuals except What’s New through the Pervasive Software Sales Team.

The following documentation is common to the Btrieve and Scalable SQL interfaces.

•	This book, Getting Started with Pervasive.SQL (Workstation Edition), helps you to get Btrieve and the Scalable SQL running with installation, setup, and troubleshooting information.

•	Pervasive Products and Services provides an outline of how to work with Pervasive Software and describes the database and product architecture.

•	Pervasive.SQL User’s Guide gives information on how to configure Btrieve and Scalable SQL using the Setup utility, and documents the Rebuild, Maintenance, Monitor, and Function Executor utilities.

•	ODBC Interface Reference documents the open database connectivity feature.

•	Status Codes and Messages documents all the possible status codes and numbered messages that can be received when using Pervasive software.

•	What’s New documents the updates to Pervasive.SQL for Btrieve 7.0 and Scalable SQL 4.0.

In addition, you receive the following publication which is specific to Scalable SQL.

•	SQL Language Reference

 Note: Some manuals make reference to documentation (such as the Pervasive.SQL Programmer’s Guide) that is part of the Pervasive.SQL SDK package.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Installing the Pervasive Workstation Engine

This chapter contains procedures on successfully installing and running Pervasive.SQL. The chapter contains the following sections:

•	“Preparing for Installation”

•	“Installing the Pervasive.SQL Workstation Engine on Windows 9X/NT”

•	“Common Questions After Installation”

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Preparing for Installation

This section contains information with which you need to be familiar in order to successfully install Pervasive.SQL.

Before installing Pervasive.SQL, review this section for any information relevant to your operation. You should also read the README.TXT file on the distribution media.

System Requirements

You must have the following to install Pervasive.SQL:

Workstation

•	The Pervasive.SQL 7 Workstation Install is a 32-bit only install that only operates under Windows 9X or Windows NT 4.0.

•	At least 16 MB of free memory (32 MB is recommended).

•	At least 28 MB of free disk space for the engine components in C:\WINDOWS\SYSTEM.

•	Up to an additional 60 MB for the following client components, assuming you choose to install all components:

•	Pervasive.SQL documentation in Windows Help format.

•	Pervasive configuration tools and utilities, such as Setup, Rebuild, Maintenance, SmartScout, DDF Ease, SQLScope, and Function Executor.

Platform Notes for Windows Environments

Observe the following rules when installing on this platform:

•	Do not run the installation program from Windows Explorer or Network Neighborhood.

•	If you run with Advanced Power Management, disable it while installing Pervasive.SQL.

The power management can cause a Pervasive.SQL installation to fail if the machine is suspended during the install. In Windows NT, you control the advanced power management via the Power icon on the Control Panel.

Installing Over Existing Pervasive Products

•	You can install the workstation engine on a machine that already contains a server version of Pervasive.SQL, Btrieve 6.15, or Scalable SQL 4.0.

•	You can also install the Workstation engine on a machine that already has Pervasive.SQL client requester components installed. All communication components required to make a connection to a remote Pervasive.SQL server are installed with the Workstation engine. If you are trying to access a database that is located on your local machine, the Workstation engine will be used. If you access a database on a remote machine that contains a Pervasive.SQL server, the server engine will be used. There are two settings that control which engine is used. These settings are controlled using the Setup utility under the MicroKernel Router and Scalable SQL Requester components. They are:

•	Requester (Yes/No)

•	Local Access (Yes/No)

See the User’s Guide for more information on the Setup utility and changing settings.

•	If you install Pervasive.SQL over an existing Btrieve 6.15 or 6.30 Workstation or Server installation, the older Btrieve components will no longer be used. All features and functions from the 6.15 engine are supported in the Pervasive.SQL 7 Workstation engine.

Installation Tips

•	If the installation program detects that a long pause occurs in the installation, a status screen displays that asks if you wish to continue waiting or if you think the installation stopped responding.

If this occurs, you might need to switch tasks to bring the main installation window back into focus in the foreground. Use the Alt-Tab key combination to rotate among your running tasks.

•	If you run multiple installations on the same machine, specify different directories so that Install can preserve your ability to uninstall each separate installation. Install displays the following dialog if you try to install multiple times to the same directory.

•	In all cases, if you install more than one engine from the same workstation, then you should choose distinct directories into which to install the non-system (non-shared) components. This is to prevent the second engine install from overwriting files and/or program icons from previous installs, or from interfering with the workings of the uninstalls for engines previously installed.

•	If you run multiple installations from the same server, specify different folder names for the Start Menu items so that Install can preserve your ability to uninstall each separate installation. Install displays the following dialog if you try to use the same folder name twice.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Installing the Pervasive.SQL Workstation Engine on Windows 9X/NT

Follow this procedure to install the Workstation engine at your workstation.

To install Pervasive.SQL on Windows 9X or NT:

1.	 Launch the installation program from your Windows machine.

a.	Insert the Pervasive.SQL CD in the CD-ROM drive of your Windows machine.

b.	If the installation does not start automatically, click Start, select Run, and type drive:setup where drive is the drive letter of your CD-ROM device. The following dialog box displays.

Figure 2-1
Pervasive.SQL Setup Welcome Screen

Click Next to proceed with the installation.

2.	 Choose your Setup Type.

There are two choices for the installation: Typical and Custom:

•	Typical is what most users should use to install Pervasive.SQL (60 MB). It installs the following components: both Btrieve and Scalable SQL services and client utilities, ODBC, and documentation.

•	Custom install allows you control over some setup options and components.

Table 2-1 shows what components are included in the Typical path. The custom path allows you to configure options such as the name of the Pervasive folder.

Table 2-1
Pervasive.SQL Typical Setup - Workstation Engine

Component	Typical Install
Disk Space Required	60 MB
Workstation Engine (Btrieve and SQL)
Utilities
Documentation
Windows Requesters (Btrieve and SQL)
ODBC Client (Win32)
DOS Clients (Btrieve and SQL)
Pervasive.SQL Programming Interfaces Use Custom setup type to install this component.
Figure 2-2
Pervasive.SQL Setup Type

If you choose Typical, continue with the next step. For Custom installs, skip now to “Custom Installation Path” . At the end of both these section, you will return to this section to continue the installation.

3.	 Pick your client installation directory.

The utilities and documentation are written by default to C:\PVSW. You can specify a different location for the client-side software during the installation as shown in the following window. The database engine and other shared components are written to the WINDOWS\SYSTEM directory.

Figure 2-3
Choosing Client Directory of Pervasive.SQL

The utilities by default are placed in the C:\PVSW directory. If you wish to change this, click Browse under Destination directory and select the correct directory. Click Next to install the Pervasive.SQL files.

 Note: Please wait while the Btrieve and Scalable SQL system files are  copied to your machine.

 Note: Please wait while the client utilities, programming interfaces (if custom install), and program icons are installed to your server.

4.	 Wait while Setup finishes installing files .

Pervasive.SQL installation finishes by copying additional files. If you installed using the Typical path, the Win32, Win16, ODBC, and DOS requesters are copied to your machine.

5.	 Test your new Pervasive workstation engine with InstallScout

InstallScout can will now test the newly installed Pervasive engines for how they access and write database files. When these tests are completed, you can be assured that your Pervasive engine is performing correctly. Later, if you use the Requester software to access a server engine, InstallScout will test the connectivity of your workstation with this server.

Click Next to begin the test.

Figure 2-4
Start of InstallScout Software Functionality Tests

6.	 Read the README file for important information.

When the installation is finished, you choose whether to view the README file. Read this file for any important product information it may contain.

 Note: The install program modifies the PATH and PERVASIVE_PATH environment variables at the end of the installation process. These settings control how your Windows operating system finds Pervasive components. These environment variables are stored in the Control Panel under the Environment icon.

7.	 Your Pervasive.SQL installation is complete. Congratulations!

You should now restart your computer to finish registering the updates to your system. After your computer restarts, you are ready to run the Pervasive database engine.

Figure 2-5
Successful Installation

Continue reading this manual for other new-user information on Pervasive.SQL. Skip to “Common Questions After Installation” “Common Questions After Installation” on page 2-13

Custom Installation Path

This section describes the detail of the custom installation path.

 Note: If you already installed using the Typical setup type, skip to “Common Questions After Installation” .

1.	 Choose your client directory.

The utilities and documentation are written by default to C:\PVSW. You can specify a different location for the client components during the installation as shown in the following window.

Figure 2-6
Choose Your Custom Client Directory

2.	 Choose your client components.

Now select the components that you wish to install. Click on an open square to select an item and click again to deselect an item.

The column on the left lists the major categories: client programs, documentation, programming interfaces, and client installs. When you select one of these categories by clicking on them, the column on the right shows the subitems available under that category.

Select each of the major categories and decide which items you wish to install. When you are finished, click Next.

Figure 2-7
Choose Your Components to Install

3.	 Choose the folder in which to place menu items.

You specify the folder in which the Start Menu items will be placed. Pervasive Install suggests a name for the folder, which you can accept by clicking Next.

If you have previously done an install from this workstation, Install recommends that you do not use the same folder name so that your ability to cleanly uninstall the software in the future is preserved.

Figure 2-8
Choosing Your Start Menu Folder

4.	 Your custom installation choices are complete. Now installation begins.

Install now has enough information to start the installation process. A dialog displays that lists the options you selected. If you want to change any of your selections, click Back.

If the displayed selections are correct, click Next to continue.

 Note: Please wait while the Btrieve and Scalable SQL engine files are copied to your machine.

Figure 2-9
Your Custom Installation Selections

Now the custom path rejoins the Typical and Compact installation paths. See the step entitled “Wait while Setup finishes installing files.” .

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Common Questions After Installation

This section contains information that you should read after running the installation program.

How Do I Convert My Files From Previous Pervasive Products?

•	Users of Previous Btrieve Versions: Use the Rebuild utility to convert your existing pre-v6.0 or v6.x files to v6.x or v7.x format. For more information, refer to User’s Guide.

•	Users of Previous Scalable SQL Versions: Use the Conversion utility to convert your existing 3.x Scalable SQL databases to the 4.x format. For more information, refer to User’s Guide.

•	Use the View Conversion utility to convert 3.x views to 4.x format. DDFs created with previous Btrieve versions are rebuilt to convert pre-6.0 or 6.x files to 7.x format.

How Do I Read the Online Documentation?

Pervasive provides documentation in the Windows Help format. Therefore, you do not need any additional tools in order to view the content. To read a manual, you need only select its name from the Start Menu under the Pervasive.SQL Doc group.

How Do I Run DOS Programs with the Workstation Engine?

DOS programs are supported in the Workstation engine with the use of technology from Artefact. To run a DOS program, first start the item BTRBOX95 located in the Start Menu. Then run your DOS program. You can run multiple DOS applications in multiple windows after loading BTRBOX95 once. Please see README.TXT for detailed information.

Windows virtual device driver DOS box support for Btrieve software was developed by Artefact Network Support and  Pervasive Software Distribution and Competence Center in the Netherlands, pursuant to an assignment from Pervasive Software Inc.

What Files Were Installed As Part of Pervasive.SQL?

Once installed, the Pervasive.SQL system files reside in the following directory structure.

\WINNT\SYSTEM32 or \WINDOWS\SYSTEM		Btrieve and Scalable SQL files (engine and requesters).
\PVSW
	\BIN		Pervasive.SQL configuration tools and utilities
	\DEMODATA		Contains a sample SQL database.
	\DOC		User documentation in Windows Help format
	\SAMPLES		Contains the sample database SAMPLE.BTR and  UPPER.ALT, a sample Alternate Collating Sequence.
Where Do I Go From Here?

Continue with your Pervasive.SQL installation by learning how to start and stop the Pervasive engines as described in Chapter 3, “Running the Pervasive Workstation Engines”.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Running the Pervasive Workstation Engines

This chapter outlines how to start and stop the Pervasive engines for both the Btrieve and Scalable SQL components of Pervasive.SQL. You may want to start or stop the engines when you change configuration.

 Note: This chapter is only intended for users of the Workstation database engines. If you are running a Pervasive.SQL server engine, see the appropriate chapter in Getting Started with Pervasive.SQL (server edition).

This chapter contains the following topics:

•	“Starting and Stopping Pervasive.SQL Workstation Engines”

•	“Questions and Answers about the Workstation Engine”

•	“Using a Pervasive Server Engine in Conjunction with your Workstation Engine”

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Starting and Stopping Pervasive.SQL Workstation Engines

To start and stop the Pervasive Workstation engine, follow these instructions.

 Note: Users of Previous Btrieve Versions: If you have any v6.15 or earlier log (.LOG) files you want to roll forward, you must do so before you load the v7.0 MicroKernel, which uses a different logging scheme. You must use both the v6.15 or earlier engine and its accompanying Roll Forward utility. Refer to your Btrieve v6.15 or earlier documentation for information about logging and instructions on how to roll forward files.

To Start the Pervasive Workstation engine:

1.	Click the Start menu, point to Programs and select Pervasive SQL 7.

2.	Select the Pervasive.SQL Workstation Engine icon.

By default, the MicroKernel allocates resources and is ready to service local appliation database requests.

To Stop the Pervasive Workstation engine:

1.	On the Windows taskbar, right-click the Pervasive Database icon.

If you are unsure which icon represents Pervasive Database, move the mouse pointer over the icons on the taskbar to display their identities.

2.	Select Stop Engines and Exit.

 Note: You will receive a warning message when trying to stop the engine if any of the following is true:

•	There are active clients (Btrieve or SQL).

•	No activity took place since the engine loaded.

•	10 seconds has not elapsed since the last operation took place.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Questions and Answers about the Workstation Engine

What is the best way to start the Pervasive Engine?

The database engines will be autoloaded when your application starts and makes its first database call. It will auto-unload when your applications ends normally and performs either a stop or reset.

You can also manually start your Pervasive.SQL engine by double-clicking the Workstation engine icon in your Pervasive folder to start the engine.

How do I know if the Pervasive Engine is Loaded?

When the Workstation engine is loaded, an icon is displayed in the right side of your Windows task bar. Right-click on this icon to stop the engine.

Can I load the Pervasive Engine from the Startup Folder of Windows?

Yes, you can add a shortcut to the Pervasive Workstation Engine program icon to the Startup folder of Windows.

How do I make the Pervasive Engine available to both DOS and Windows programs? Can I load it from AUTOEXEC.BAT?

Pervasive.SQL 7 supports Btrieve DOS applications running on a 32-bit Windows machine. Essentially, virtual device drivers allow Btrieve applications to thunk to the 32-bit components. With one Workstation engine running on one machine, you can run multiple Btrieve DOS applications, each within its own DOS box. you need only one BtrBox95 (Windows 9X only) to do this.

Windows virtual device driver DOS box support for Btrieve software was developed by Artefact Network Support and  Pervasive Software Distribution and Competence Center in the Netherlands, pursuant to an assignment from Pervasive Software Inc.

Will the Pervasive v7 Workstation Engine conflict with older versions of Pervasive Software?

Pervasive.SQL 7 Workstation does not support mixed operation with previous Pervasive Database products on a computer. After installing Pervasive.SQL 7 Workstation, existing Pervasive Database components will no longer be used.

The Pervasive.SQL 7 Workstation Engine is compatible with all features of the Btrieve v6.15 Engine features and functions, including the Btrieve API and data file formats (v4.x, v5.x, v6.x). Applications designed to work using the Btrieve v6.15 server or workstation engines will run on the Pervasive.SQL 7 Workstation engine.

For more information, see “Installing Over Existing Pervasive Products” in the Installation chapter.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Using a Pervasive Server Engine in Conjunction with your Workstation Engine

You can use your workstation engine to access files on a remote server through a mapped drive on either a Windows NT or NetWare server. Map the drive and use the letter assigned by the network as part of the Universal Naming Convention (UNC) path.

You can also use the requester software provided with your workstation engine to connect to other server engines on a remote machine as described in the following sections.

Using a Workstation Engine to Access Local Files and a Remote Server Engine to Access Non-Local files

If you want to use your local engine for local file access and a remote server for access to files being serviced by the remote Pervasive server, set:

Scalable SQL Requester

•	Local Usage: Yes

•	Remote Usage: Yes

MicroKernel Router

•	Local: Yes

•	Requester: Yes

Running a Workstation Engine and a Server Engine on the Same Machine

If you want to run both a Workstation engine and  a server on a Windows NT machine, you need to set the following:

Scalable SQL Requester

Change this setting to one of the following:

•	Local Target engine

•	Local Server only

Local Target Engine

Change this setting to one of the following:

•	Try Local Server, then Workstation

•	Local Server only

•	Workstation only

 Note: See the Pervasive.SQL User’s Guide for more information on changing settings using the Setup utility.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Troubleshooting Installation Problems

This chapter contains information that is useful in preventing installation problems and in resolving conflicts running Pervasive.SQL.

Pervasive provides several features and tools in Pervasive.SQL that help to prevent configuration and installation problems.

Some of these utilities are installed and run as part of the installation process and all can be run later to evaluate configuration and registry settings and to troubleshoot problems. They are shown in Table 4-1.

This chapter contains the following sections:

•	“Pervasive.SQL Installation Troubleshooting”

•	“Diagnosing Communications and Component Problems with SmartScout”

•	“How to Get Additional Help”

Table 4-1
Pervasive Tools that Assist in Installation
and Problem Determination

Feature/Component	Function	For More Information
InstallScout	To ensure that your system meets  network communication  requirements before installation and  that  your new software is performing  correctly after installation.	See the InstallScout Help file  (INSSCT.HLP).
SmartScout	A troubleshooting utility that analyzes  components, runs system tests, and  allows you to display registry and .INI  file settings.	See “Diagnosing  Communications and  Component Problems with  SmartScout”
Smart Components	Smart Components is a new internal  design in Pervasive.SQL 7.0 that  ensures that Pervasive software  components always load with  compatible components.	Refer to the Pervasive.SQL  User’s Guide.
Knowledge Base	Provides information about many  Pervasive software configurations  and common environments.	Search the Pervasive  Knowledge base at:  www.pervasive.com
Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Pervasive.SQL Installation Troubleshooting

This section outlines problems you may encounter during the installation or when first using the product.

The Btrieve or Scalable SQL Windows NT Service will not start.

The Pervasive MicroKernel and SQL engine on Windows NT run as services. Normally, these services are started automatically during the installation process. If the service will not start, usually this is caused by another older Btrieve or Scalable SQL engine that is running in the background, especially if that engine is not registered as a service.

I made configuration changes using the Setup utility and they do not seem to be in effect.

After making changes to engine configuration components, you must stop and restart the MicroKernel for the changes to take effect. For information on how to start and stop the MicroKernel, see “Starting and Stopping Pervasive.SQL Engines” .

I was running an application. Now I get a Status Code 95 (Invalid Session).

This can happen if you made changes to your configuration settings and had to restart the MicroKernel. Once you stop the MicroKernel, any applications that were running at the time lose their session with the MicroKernel. You must stop all those utilities and restart them in order to reestablish communication. See the Status Codes and Messages manual for more cases in which this status code can be returned.

I cannot use the SPX protocol with a Win16 client to connect to a NetWare server.

In order to connect using SPX, the Win16 client needs two Novell system DLLs which may be missing on your system. Check for the existence of NWCALLS.DLL and NWIPXSPX.DLL and replace them if they are missing. You can get the files from Novell’s web site (http://www.novell.com).

I installed another Btrieve application and now my system is unusable.

Pervasive.SQL uses a new system called Smart Components to avoid component mismatches and older programs overwriting newer components. To provide an interface for legacy applications, though, some component names are still capable of being overwritten. If this happens, you can restore the overwritten DLLs using a backup directory that is automatically created when you install Btrieve.

To restore the compatibility DLLs:

1.	Assuming you installed to the default client directory of C:\PVSW, open the directory C:\WINDOWS\SYSTEM\BTCOMPAT.BCK.

2.	Copy the files located inside this directory to your Btrieve requester’s system directory. For example, C:\WINDOWS\SYSTEM for a Windows 95 machine or C:\WINNT\SYSTEM32 for a Windows NT machine.

 Note: You only need to perform this procedure if your Pervasive.SQL engine was made inoperable by installing an incompatible or outdated application.

I want to verify that I have the correct NLMs loaded in NetWare.

After the server installation is complete, verify the server setup by running the Modules command from the console and confirm the version numbers of the NWMKDE.NLM, BTRIEVE.NLM, and the NWBSRVCM.NLM (7.00).

How do I verify that my DOS components are functioning?

Since InstallScout does not verify Btrieve DOS, Pervasive provides a DOS version of BUTIL.EXE in C:\PVSW\BIN\DOS for purposes of verification.  To verify using the DOS version of BUTIL, enter the following at a DOS prompt:

cd \pvsw\bin\dos

butil -stat ..\..\samples\sample.btr

In addition,  use of the bdosstub.exe is needed for some applications using Windows 95 DOS Box for Btrieve if you encounter status 20s, indicating the requester is not loaded.  Some applications built with Turbo Pascal have this problem, which can be avoided by loading the bdosstub.exe TSR before starting the DOS application.

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


Diagnosing Communications and Component Problems with SmartScout

The Pervasive Software SmartScout utility includes both Win32 and Win16 versions. This utility is designed to assist in component management, module conflict resolution, and communication troubleshooting for Pervasive products. The program performs the following functions:

•	Gathers pertinent configuration information about the machine and networking environment.

•	Searches memory for loaded Pervasive and network communications modules, and displays that information.

•	Searches the operating system's search path for Pervasive and network communications components, and displays that information.

The System tests function of the SmartScout utility performs the following:

•	Using 32-bit or 16-bit versions, SmartScout’s system tests performs many of the same functions as the Pervasive communications components with respect to IPX/SPX and TCP/IP in evaluating the system's ability to connect to Pervasive server engines.

•	Using Win32 or Win16 versions, performs stress tests of the SPX and TCP/IP transports to assist in diagnosing communications problems.

Files included in this release

Version	Component	Function
Win32	SSCOUT32.EXE	the SmartScout executable
Win32	CMDIAG32.DLL	the communications diagnostics module
Win32	WDBNMT32.DLL	named databases module
Win32	PSAPI.DLL	a DLL required for Microsoft NT
Win16	SSCOUT.EXE	the SmartScout executable
Win16	CMDIAG16.DLL	the communications diagnostic module
Win16	WDBMNT16.DLL	named databases module
Win16	NWLOCALE.DLL	resource module
How to Start SmartScout

To run SmartScout, follow these steps:

1.	Start SmartScout by doing one of the following:

•	Double clicking its icon in Windows Explorer (95/NT) or File Manager (Windows 3.x).

•	Entering sscout32.exe (Win32) or sscout.exe (Win16) from the command line in a Win32 DOS box (Windows 95 and Windows NT only)

•	Select Run from the Start menu (Windows 95 and NT) or from the File menu (Windows 3.x), and enter sscout32.exe (Win32) or sscout.exe (Win16) and press Enter.

2.	The SmartScout main window then opens, as shown in Figure 4-1.

Figure 4-1
SmartScout Main Window

Obtaining Information from SmartScout

After initializing, the utility displays a single window with three tabs that divide the program into its functional areas. The three tabs are as follows:

Workstation

Clicking on the Workstation tab (shown in Figure 4-1) provides information on the environment and operating system identified. It also allows you to edit Pervasive configurations in INI files and view entries in the Registry.

The following information is on this page:

Item	Function
Operating System	Displays the operating system for this machine.
Version	Displays the version of the operating system
Free Memory	Displays the available free memory on the  machine.
Windows directory	Displays the path to the WINDOWS directory.
Windows System  directory	Displays the path to the Windows system  directory where many DLLs reside.
In the Pervasive Products Setup Information box, you can view setup information displayed in both .INI files and the registry (for Windows 95/NT). If information is available, the check box located next to the information is selected as shown in the following example:

:

The four configuration areas are:

Configuration Area	Function
BTI.INI	The BTI.INI file contains configuration  information. If available, click Edit to  change the file.
Btrieve section in WIN.INI	The Btrieve section in WIN.INI  contains configuration information. If  available, click Edit to change this file.  This is no longer used in  Pervasive.SQL 7.0.
Btrieve Technologies Registry entries	This button controls whether to view  Windows 95 and NT registry  information if it is found. Click View to  see the information. If you need to edit  the information, use the Registry  Editor provided by Microsoft. This is  no longer used in Pervasive.SQL 7.0.
Pervasive Software Registry entries	This button controls whether to view  Windows 95 and NT registry  information if it is found. Click View to  see the information. If you need to edit  the information, use the Registry  Editor provided by Microsoft.
When you click View on one of the Registry information entries, the following window appears:

Figure 4-2
SmartScout - Registry Information

Components

Clicking on the Components tab (shown in Figure 4-3) displays a grid containing information on components found in memory and in the machine's path.

The Win32 version includes a Loaded column and displays Yes or No to indicate whether a Win32 DLL is loaded. Asterisks are displayed to indicate Win16 DLLs because their load status cannot be determined. To obtain information on Win16 DLLs, use the Win16 SmartScout.

The Win16 version includes a Usage column that displays a number greater than 0 for all modules actually loaded in memory at the time of the scan. An asterisk displays in the column for Win32 DLLs, since this information is not available through the Win16 version of SmartScout. To obtain information on Win32 DLLs, use the Win32 SmartScout.

The other columns provide information, including size and date, which is useful in determining component versions. You can rearrange the columns by dragging the column headers to a new location.

Figure 4-3
SmartScout - Component Information

System Tests

Clicking on the System Tests tab provides an interface to the Communications Diagnostics module, CMDIAG16.DLL (16-bit version) and CMDIAG32.DLL (32-bit version). The user can select the engine (Btrieve or Scalable SQL) and protocol (TCP/IP or SPX) to test, and the type of test to be performed.

The fields on this panel are:

Field	Function
Engine to test	Select the engine you wish to test. You can choose Btrieve or Scalable SQL.
Protocol	You can choose one of the following. Some items may not appear in this box,  depending on the SmartScout version (32 or 16-bit): All available, which tests all protocols installed on system. First available, which tests the first protocol established. TCP/IP SPX
Testing level	Most users need only run the Basic Tests. If you suspect a communications  problem, select Communications Stress Tests. The stress tests run multiple  communications calls to the client requester and are executed during the Basic  Tests procedure (see “Step 5: Send data to and receive data from target engine.”   ). They run until canceled by the user as shown in Figure 4-6.
Target name	Enter a path to the server you want to test. The default is the directory where the  executable is installed. You can use mapped drives and UNC network names to  specify the path. For Scalable SQL, a Named Database can be chosen instead of the path. To do  this, select the Named Database check box and choose a database name from the  list as shown in Figure 4-4.
Test output	This window shows the output from the tests. This output can be saved to a file or  printed by clicking Report.
Figure 4-4
SmartScout - System Tests Tab

Running Systems Tests

The SmartScout 32-bit and 16-bit system tests perform the same operations that the Btrieve, Scalable SQL and ODBC client requesters perform to communicate with their respective server engines, while giving information on the success or failure of each of the operations. To start the test, click Run Tests.

SmartScout Communication Test Steps

1.	Establish the client environment.

2.	Determine the full target name.

3.	Resolve full target name into a network address.

4.	Establish a connection to the target server.

5.	Send data to/receive data from target server.

6.	Terminate the established connection.

While processing each of the steps, SmartScout displays messages labeled as either Information, Warning or Fatal Error. Information messages list general operational characteristics. For example, when SmartScout determines that the Novell IPX/SPX DLL is installed and available on the client machine, the following is displayed:

Information : Novell IPX/SPX is available.

Warning messages list errors that prevent SmartScout from continuing down a particular code path. Warnings in and of themselves do not indicate a complete failure of the communication test, but rather that SmartScout's options for completing the test may be limited in some way. For example, if SmartScout is unable to load WINSOCK.DLL (which is needed for TCP/IP support), the following is displayed:

Warning : Could not load winsock.dll.

Warning : TCP/IP is not available.

 Note: In this example, the unavailability of TCP/IP may not prevent SmartScout from completing the communication test, because it may be able to use SPX to communicate with the target server.

Fatal Error messages indicate that SmartScout is unable to continue processing the test. Fatal Error messages describe situations where a Btrieve, Scalable SQL or ODBC application would generally receive a non-zero status code when trying to communicate with the particular target server under the same operational characteristics. Fatal Error messages are displayed only after one or more Warning messages indicating the basic cause of the failure.

As a final example, consider that the client machine is configured as indicated in the previous examples with SPX available but TCP/IP unavailable. Furthermore, assume that the target server has only TCP/IP available and not SPX. In this situation, SmartScout would display (among others) the following messages:

Warning : Unable to connect via TCP/IP.

Warning : Unable to connect via SPX.

Fatal error : Unable to establish a connection to the
target server.

The following figure shows the System Tests window with some messages displayed. To remove the test results from the window, click Clear List.

Figure 4-5
SmartScout - System Tests Messages

System Test Steps

As stated previously in “Running Systems Tests” , SmartScout groups the operations it performs into six major steps. Each one of these steps attempts to accomplish one specific task that is required for the successful completion of the remaining steps. Failure to complete any individual step results in a Fatal Error message that terminates the test.

The following describes each of the steps in more detail.

Step 1: Establish the client environment.

Here SmartScout loads each of the system DLLs it may need to process the test. Specifically, SmartScout attempts to load the following:

DLL	Version	Function
WSOCK32.DLL	Win32	Provides TCP/IP and SPX support, as well as some name-to- address resolution capabilities.
KERNEL32.DLL	Win32	Provides Microsoft Networking support to connect to engines  running on Windows NT servers.
CALWIN32.DLL	Win32	Provides Novell API support to connect to engines running on  NetWare servers.
WDBMNT32.DLL	Win32	Provides Scalable SQL database name to Windows NT server  name mapping.
WINSOCK.DLL	Win16	Provides 16-bit TCP/IP support.
NWIPXSPX.DLL	Win16	Provides Novell SPX support. This is a Novell system file.
NETAPI.DLL	Win16	Provides Microsoft Networking support to connect to engines  running on Windows NT servers.
NWCALLS.DLL	Win16	Provides Novell API support to connect to engines running on  NetWare servers. This is a Novell system file.
WDBMNT16.DLL	Win16	Provides Scalable SQL database name to Windows NT server  name mapping.
Step 2: Determine full target name.

In this step, SmartScout takes the supplied Target or Database Name and calls one or more of the system DLLs it loaded in Step 1 to determine the name of the NetWare or Windows NT server corresponding to the target. For file and directory names in the 16-bit version, SmartScout calls NWCALLS.DLL and/or NETAPI.DLL. For Database Names, SmartScout calls WDBMNT16.DLL. For file and directory names in the Win32 version, SmartScout calls CALWIN32.DLL and/or KERNEL32.DLL. For Database Names, SmartScout calls WDBMNT32.DLL.

 Note: It is possible to specify the Target as a fully qualified UNC or NetWare name. In that case, SmartScout does not call any system DLLs, but rather extracts the server name directly from the Target.

Step 3: Resolve full target name into a network address.

In this step, SmartScout takes the full target name parsed in Step 2 and calls one or more of the system DLLs to resolve the name into a network address.

Win32 version	For server engines running on a NetWare server,  SmartScout will attempt to call NWCALLS.DLL or  CALWIN32.DLL, depending on which is available. If  NWCALLS.DLL or CALWIN32.DLL is not available,  SmartScout falls back to using the built in Microsoft  Networking capability of KERNEL32.DLL and  WSOCK32.DLL.  For server engines running on a Windows NT server,   CMDIAG32.DLL must be able to call KERNEL32.DLL to  obtain a TCP/IP address of the target server.
Win16 version	For server engines running on a NetWare server,  SmartScout must be able to call NWCALLS.DLL. For  server engines running on a Windows NT server,  SmartScout generally must be able to call NETAPI.DLL,  although in some situations where both NetWare and  Windows NT are present, SmartScout may be able to use  NWCALLS.DLL to obtain the network address.
Step 4: Establish a connection to the target engine.

At this point, SmartScout has resolved the input Target or Database Name into a network address, and now attempts to connect to the target engine using one or more transport protocols as constrained by the test parameters and transports it was able to load in Step 1.

Step 5: Send data to and receive data from target engine.

Now that SmartScout has successfully established a connection to the target engine using one or more transport protocols, it sends a Btrieve or Scalable SQL Version request to the engine and displays the result. If the Version request was successful and the user specified a Communications Stress Test, SmartScout begins sending and receiving Btrieve or Scalable SQL loopback requests. These requests are replied to by the Btrieve or Scalable SQL server communication module and are not actually processed by the server engine. SmartScout displays a message box giving a running total of the number of requests processed, and continues until you click Cancel, as shown in Figure 4-6.

Figure 4-6
SmartScout - System Stress Test

Step 6: Terminate the established connection.

As a final step, SmartScout gracefully closes any server connection established in Step 4.

 Note: You may get Warning or Fatal Error messages that include various status codes or other information. You may receive an unknown error code from a function call involved in the communication process. If you are unsure how to resolve your problem based on the results of running SmartScout, please contact Pervasive Customer Support.

To obtain a report on the System tests, click Report. You can choose whether you want the results to be outputted to a printer or to a file as shown in Figure 4-7.

To exit SmartScout, click Done.

Figure 4-7
SmartScout - Report Generation

SmartScout produces a report similar to the following:

Pervasive Software System Qualification UtilityApril 17, 1997  11:41 AM

---- Results of Component Search ----

#  Module       Usage     Size    Date   Location

1  netware.drv2,656 08/03/96 c:\winnt\system32\

2  ntbticom.dll     0

3  nwcalls.dll      1   147,616 10/20/94 c:\winnt\system\

4  nwgdi.drv        0

5  nwipxspx.dll     0    41,456 10/18/94 c:\winnt\system\

6  nwlocale.dll     1    38,576 11/02/93 k:\utils\roundup\test\

7   "               0    38,576 11/02/93 c:\winnt\system\

8   "               0    38,576 11/02/93 c:\ssql40\win\bin\

9   "               0    38,576 11/02/93 d:\bti\win\bin\

10 nwnet.dll        0

11 nwpsrv.dll       0

12 tli_win.dll      0

13 tli_spx.dll      0

14 vnetware.386     0

15 vipx.386         0

16 w32bticm.dll     0 42,496 02/13/97 c:\winnt\system32\

17  "               0    42,496 01/16/97 c:\ssql40\win\bin\

18  "               0    42,496 02/13/97 c:\ssql40\bin\

19 w32mkde.exe      0   320,512 10/07/96 c:\winnt\system\

20 wbt32res.dll     0     4,290 10/10/96 d:\bti\win\bin\

21 wbticomm.dll     0    41,980 01/16/97 c:\ssql40\win\bin\

22 wbtr32.exe       0   315,336 10/10/96 d:\bti\win\bin\

23 wbtrcall.dll     1    43,472 02/04/97 c:\winnt\system\

24  "               0    43,472 02/04/97 d:\bti\win\bin\

25  "               0    13,131 05/13/93 \\aus-rd\sys\public\

26 wbtrlocl.dll     0    17,762 10/10/96 d:\bti\win\bin\

27 wbtrthnk.dll     1     5,824 07/15/96 c:\winnt\system\

28 wbtrv32.dll      0    68,096 02/12/97 c:\winnt\system\

29  "               0    68,096 02/04/97 c:\winnt\system32\

30 wbtrvres.dll     0     4,272 01/16/97 c:\winnt\system\

31  "               0     4,272 01/16/97 c:\ssql40\win\bin\

32  "               0     4,192 04/19/95 d:\bti\win\bin\

33 wdbnames.dll     0   256,208 03/04/97 c:\ssql40\win\bin\

34  "               0   256,076 02/06/97 d:\bti\win\bin\

35 wdbmnt16.dll     1   256,076 04/10/97 k:\utils\roundup\test\

36 winbtint.dll     0   427,472 03/04/97 c:\winnt\system\

37 winbtstp.dll     0    17,952 03/04/97 c:\winnt\system\

38 winsock.dll      0     2,880 08/03/96 c:\winnt\system32\

39 wodbc16.dll      0    69,152 03/04/97 c:\ssql40\win\bin\

40  "               0    69,152 01/25/97 d:\bti\win\bin\

41 wodbc32.dll      0    88,576 03/04/97 c:\winnt\system32\

42 wxql32.dll       0   859,049 03/04/97 c:\ssql40\win\bin\

43  "               0   859,049 01/23/97 d:\bti\win\bin\

44 wxqlcall.dll     0    68,848 01/16/97 c:\ssql40\win\bin\

45 wxqlfmt.dll      0   408,342 03/04/97 c:\ssql40\win\bin\

46  "               0   407,366 02/06/97 d:\bti\win\bin\

47 wxqllocl.dll     0    37,684 03/04/97 c:\ssql40\win\bin\

48  "               0    37,684 01/23/97 d:\bti\win\bin\

49 wxqlres.dll      0     5,878 03/04/97 c:\ssql40\win\bin\

50  "               0     5,862 02/06/97 d:\bti\win\bin\

---- Results of Communications Testing ---------

Test started on Thu Apr 17 11:40:33 1997

Engine to test : Scalable SQL

Transport : All Available

Test level : Basic Test

Target name : @PQUALNT

-----

Step 1 : Establish the workstation environment.

--Information : Winsock TCP/IP is available

--Information : Novell IPX/SPX is available

--Information : Microsoft Networking API is available

--Information : NetWare API is available

--Information : Access to Scalable SQL for Windows NT database names is
available

Step 2 : Determine full target name.

--Information : Input target name is @PQUALNT

--Information : Scalable SQL database name

--Information : Target server is a Windows NT server

--Information : Target server name BTI-JSH

--Information : Fully qualified name BTI-JSH

Step 3 : Resolve full target name into a network address.

--Information : Calling NetWare API to resolve server name BTI-JSH (0x0400)

--Warning : NWReadPropertyValue returned 0x89fc

--Information : Calling Named Pipe to resolve server name BTI-JSH

--Information : Target engine SPX address : 30883088:000000000001:805B

--Information : Target engine TCP address : 192.168.2.145 port 0A04

Step 4 : Establish a connection to the target engine.

--Information : Waiting for TCP/IP connection establishment

--Information : TCP/IP connection established (0x0003)

--Information : SPX connection established (0x6c92)

Step 5 : Send data to/receive data from target server.

--Information : Making Scalable SQL Version call with TCP/IP.

--Information : Scalable SQL Version is 4.0 NTSV.

--Information : Making Scalable SQL Version call with SPX.

--Information : Scalable SQL Version is 4.0 NTSV.

Step 6 : Terminate the established connection.

--Information : TCP/IP connection terminated successfully.

--Information : SPX connection terminated successfully.

-----

Test completed on Thu Apr 17 11:40:34 1997-----

-----

Test started on Thu Apr 17 11:40:43 1997

Engine to test : Scalable SQL

Transport : All Available

Test level : Communications Stress Test

Target name : @PQUALNT

-----

Step 1 : Establish the workstation environment.

--Information : Winsock TCP/IP is available

--Information : Novell IPX/SPX is available

--Information : Microsoft Networking API is available

--Information : NetWare API is available

--Information : Access to Scalable SQL for Windows NT database names is
available

Step 2 : Determine full target name.

--Information : Input target name is @PQUALNT

--Information : Scalable SQL database name

--Information : Target server is a Windows NT server

--Information : Target server name BTI-JSH

--Information : Fully qualified name BTI-JSH

Step 3 : Resolve full target name into a network address.

--Information : Calling NetWare API to resolve server name BTI-JSH (0x0400)

--Warning : NWReadPropertyValue returned 0x89fc

--Information : Calling Named Pipe to resolve server name BTI-JSH

--Information : Target engine SPX address : 30883088:000000000001:805B

--Information : Target engine TCP address : 192.168.2.145 port 0A04

Step 4 : Establish a connection to the target engine.

--Information : Waiting for TCP/IP connection establishment

--Information : TCP/IP connection established (0x0005)

--Information : SPX connection established (0x6c94)

Step 5 : Send data to/receive data from target server.

--Information : Making Scalable SQL Version call with TCP/IP.

--Information : Scalable SQL Version is 4.0 NTSV.

--Information : Beginning TCP/IP Stress Test

--Information : TCP/IP Stress test aborted by user

--Information : Total TCP/IP requests processed :      117

--Information : Making Scalable SQL Version call with SPX.

--Information : Scalable SQL Version is 4.0 NTSV.

--Information : Beginning SPX Stress Test

--Information : SPX Stress test aborted by user

--Information : Total SPX requests processed :      344

Step 6 : Terminate the established connection.

--Information : TCP/IP connection terminated successfully.

--Information : SPX connection terminated successfully.

-----

Test completed on Thu Apr 17 11:41:14 1997-----

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.


How to Get Additional Help

Pervasive Software wants your installation experience to be a pleasant one. If you encounter problems during the installation that are not covered in this manual, please contact Pervasive Software in one of the following ways and we will do everything to ensure that your problem is addressed.

For general questions, common problem resolution, client/server issues, your first line of support should be the Pervasive Software Knowledge Base, a web-based searchable index of all Pervasive technical information. This is located at http://www.pervasive.com/support.

For developer-related issues, visit the following web sites:

•	Pervasive Developer Relations Web Site at http://www.pervasive.com/developer

•	PervasiveDevWire:  Free developer-oriented e-mail news service at http://www.smithware.com/contact/DevWire.html

If your installation is not successful, or you encounter problems not documented in the Btrieve manuals or on the Knowledge Base, contact Pervasive Software Customer Support in one of the following ways:

•	Via e-mail at techsupport@pervasive.com or the Support request form located at the Support section of http://www.pervasive.com

•	Via telephone at 512-794-1719

•	Via fax at 512-794-1778

Send comments to docs@pervasive.com.  Copyright © 1998 Pervasive Software Inc.  All rights reserved.