Pervasive.SQL DOS Application Support October 2003 READDOS.TXT ===================================================================== Contents ======== 1. Overview 2. Running DOS applications on Windows NT/2000/XP - Using or Disabling Win32 DOS Box Support on Windows NT/2000/XP - Using DOS TCP/IP Support (BREQTCP) - Using DOS SPX Support (BREQUEST/BREQNT) 3. Running DOS applications on Windows 98/ME - Using or Disabling Win32 DOS Box Support on Windows 98/ME - Using DOS TCP/IP Support (BREQTCP) - Using DOS SPX Support (BREQUEST/BREQNT) 4. Running DOS applications on DOS - Using DOS TCP/IP Support (BREQTCP) - Using DOS SPX Support (BREQUEST/BREQNT) 5. Verifying the DOS configuration 6. Running BREQ*.EXEs with faster connection Appendix A: DOS TCP/IP Technical Information ===================================================================== 1. Overview =========== Pervasive.SQL supports DOS Btrieve applications in several different ways. This, however, depends on the current configuration and environment of the workstation. The following choices are available: - Win32 DOS Box support: Allows a DOS application to run in a DOS box on a Windows NT-based or Windows 98 workstation. This enables direct communication to the Windows 32-bit workstation components rather than to the database engine. This configuration can be used with either a local Pervasive.SQL Workgroup engine or a remote Pervasive.SQL Server engine. The TCP/IP or SPX protocol supported for client/server access depends on the configuration of the Windows 32-bit components. - DOS TCP/IP requester (BREQTCP): Allows a DOS application to run in any Windows DOS box or on a DOS workstation, and communicate to a remote Pervasive.SQL Server engine via the TCP/IP protocol. - DOS SPX requester (BREQUEST or BREQNT): Allows a DOS application to run in any Windows DOS box or on a DOS workstation, and communicate to a remote Pervasive.SQL Server engine via the SPX protocol. There are different reasons for using these different options, including: - Pervasive.SQL Workgroup products only support the Win32 DOS Box configuration. - DOS operating system requires the DOS TCP/IP or SPX requesters when accessing a remote Server engine. - A particular environment may have only one of the supported protocols available. Windows 98/NT/2000/XP ===================== The preferred Requester for Windows 98/NT is BTRBOX. You can use this Requester even for legacy DOS applications. NOTE: Use the BREQUEST/BREQNT/BREQTCP Requesters ONLY if you experience a problem with BTRBOX. DOS Workstations ================ The Requesters for non-Win32 boxes are: * BREQUEST * BREQNT * BREQTCP * Please check the Pervasive Knowledge Base for information relating to choices and configurations available for running a DOS application on a Windows 98/ME or Windows NT/2000 workstation communicating with a Pervasive.SQL server. The following sections document the steps for running DOS applications on Windows NT/2000/XP, Windows 98/ME, and DOS. ===================================================================== 2. Running DOS applications on Windows NT/2000/XP ================================================= To run a Pervasive application on a Windows NT/2000/XP workstation or locally on a Windows NT/2000/XP server, you should always install the Windows client components. Note, these are installed on the Windows NT/2000/XP server by default. You can find the Windows client installation on the Pervasive.SQL CD in the \CLIENTS\WIN directory. Typically, the client installation programs are also installed automatically on your Pervasive.SQL server in the \PVSW\CLIENTS\WIN directory. After the Windows client component installation, you will have everything you need to run a DOS, Windows 16-bit, or Windows 32-bit application. The default DOS application support installed is the Win32 DOS Box configuration. Using or Disabling Win32 DOS Box Support ------------------------------------- Under Windows NT/2000/XP, the DOS Box Install configures the drivers to be completely transparent. Thus, you are able to immediately open a command prompt and run a DOS Btrieve application. The Config.NT file, located in the WINNT\SYSTEM32 directory, contains the command that enables DOS application support. This file is similar to the old Config.SYS in DOS. Windows NT/2000/XP loads it for each DOS session opened. In here, the Install places the following path to load the Win32 DOS Box driver: DEVICE = C:\PVSW\BIN\BTRDRVR.SYS To disable the Win32 DOS box support to use the DOS TCP/IP or SPX requester, you must follow these steps: 1. Remove the files BTRDRVR.SYS and BTRVDD.DLL from your system. These are installed by default in the \PVSW\BIN directory. 2. Edit the Config.NT file (using Notepad) in the folder WINNT\SYSTEM32. Delete or invalidate the line: DEVICE=C:\PVSW\BIN\BTRDRVR.SYS Note: Each configuration (Win32 DOS Box, DOS TCP/IP and DOS SPX Support) is mutually exclusive. You must disable the existing configuration before configuring your machine for a new configuration. Using DOS TCP/IP Support (BREQTCP) ---------------------------------- To use the DOS TCP/IP requester on a Windows NT/2000/XP workstation, you must first disable the Win32 DOS Box support as described above, and then enable the DOS TCP/IP requester configuration. To enable BREQTCP support on Windows NT/2000/XP, follow these steps: 1. Copy the following six files into your %SystemRoot%\SYSTEM directory. %SystemRoot% refers to your Windows directory, typically C:\WINNT. You can determine the value for %SystemRoot% by opening a DOS box and entering the SET command. BREQTCP.EXE BREQTCP.MSG JSBDOSWS.EXE JSBDOSWS.DLL MSOCKLIB.RC VSLDOS.INI 2. Click Start->Settings->Control Panel. 3. Double-click System and click the Environment tab. 4. Add the following environment variable: VSL=%SystemRoot%\SYSTEM Note: There must NOT be a trailing semicolon in this statement. Once the DOS TCP/IP requester is setup, follow these steps to run a DOS application: 1. Start a DOS session. 2. Run JSBDOSWS.EXE 3. Load BREQTCP.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application. 4. Run your application. Note: The commands to load JSBDOSWS and BREQTCP can be put in your autoexec.NT file. You can load JSBDOSWS with the Load High command. To stop a DOS application, unload the requester components: 1. Enter the command BREQTCP /u in the DOS box 2. Enter the command JSBDOSWS /u in the DOS box 3. Close the DOS box. Using DOS SPX Support (BREQUEST/BREQNT) --------------------------------------- There are two DOS SPX Btrieve requesters: * BREQNT.EXE is the "dual mode" requester that can be used by a DOS application to communicate to either a Windows NT/2000/XP or a NetWare server. * BREQUEST.EXE is a NetWare-only version of the DOS SPX requester. This exists for historical purposes before Windows NT/2000/XP support was available, and is still provided because it requires smaller memory than BREQNT. If you are accessing Pervasive.SQL on a NetWare server and if you are running low on DOS conventional memory, you may need to use BREQUEST. If you are accessing a Windows NT/2000/XP server, you must use BREQNT. In order to use the DOS SPX requester on a Windows NT/2000/XP workstation, you must first disable the Win32 DOS Box support as described above. There are no special steps required to enable the DOS SPX requester configuration. A DOS application can be run with the SPX protocol to a remote Server engine by following these steps: 1. Start a DOS session. 2. Load BREQNT.EXE or BREQUEST.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application. 3. Run your application. To stop a DOS application, unload the requester by entering the command BREQUEST /u or BREQTCP /u in the DOS box before closing it. ===================================================================== 3. Running DOS applications on Windows 98/ME =============================================== To run a Pervasive application on a Windows 98/ME workstation, you must always install the Windows client components. These are found on the Pervasive.SQL CD in the \CLIENTS\WIN directory. Typically, the client installation programs are also installed on your Pervasive.SQL server in the \PVSW\CLIENTS\WIN directory by default. After the Windows client component installation, you will have everything you need to run a DOS, Windows 16-bit, or Windows 32-bit application. The default DOS application support installed is the Win32 DOS Box configuration. Using or Disabling Win32 DOS Box Support on Windows 98/ME --------------------------------------------------------- NOTE: Legacy DOS applications must use the BTRBOX configuration on Windows 98/ME. In fact, it is the only supported configuration with the Workgroup engine product. However, with client/server products, you can run DOS applications with either the BTRBOX configuration, or the legacy 16-bit DOS requesters. If the DOS application is being run on a DOS operating system, then the legacy 16-bit DOS requesters MUST be used. BTRBOX works on Windows32 operating systems only. Installation Instructions ========================= To run a DOS application with the Win32 DOS Box configuration follow these steps: 1. Start BTRBOX95: * Select the BtrBox95 icon to launch from the Start\Programs\Pervasive.SQL V8\Other Utilities menu. * Load from the \PVSW\BIN directory. A minimized dialog appears indicating active support. You must leave this dialog running. Closure of this dialog will unload BTRBOX95. You will only need to run BTRBOX once -- you may have multiple DOS sessions open using a single instance of the driver. 2. Start a DOS session. 3. Load BDOSSTUB.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application. 4. Run your application. NOTE: You MUST reboot after the initial installation of the Windows client components for the Win32 DOS Box support to function. A device driver (VxD) is registered and will not load until reboot. The proper order to stop a DOS application is as follows: 1. Stop the DOS application. 2. Close the DOS box. 3. Stop BTRBOX95. If you do not follow this order, BTRBOX95 or the database engine may not unload properly. In situations where stopping and restarting all clients is recommended, you should perform all three steps above. Simply stopping and starting your client applications is not sufficient. To disable the Win32 DOS box support in order to use the DOS TCP/IP or SPX requester, you must follow these steps: 1. Remove the files BTRBOX95.EXE, BDOSSTUB.EXE, and BTRBOX95.VXD from your system. These are installed by default in the \PVSW\BIN directory. 2. Using REGEDIT, remove the following key from your registry: HKEY_LOCAL_MACHINE\ System\ Current Control Set\ Services\ VXD\ BtrBox95 Note: Each configuration (Win32 DOS Box, DOS TCP/IP and DOS SPX Support) is mutually exclusive. You must disable the existing configuration before configuring your machine for a new configuration. NOTE: Editing your registry is dangerous and can cause you to reinstall your entire computer. If you do not feel comfortable doing this, please obtain the services of a qualified technician. Pervasive Software can accept no responsibility for a damaged Registry. Using DOS TCP/IP Support (BREQTCP) ---------------------------------- To use the DOS TCP/IP requester on a Windows 98/ME workstation you must first disable the Win32 DOS Box support as described above, and then enable the DOS TCP/IP requester configuration using the following steps: 1. Ensure you have the following five files in your PVSW\BIN directory. These files are installed as part of the clients\win installation. Make sure PVSW\BIN is included in your path. BREQTCP.EXE BREQTCP.MSG JSBDOSWS.VXD MSOCKLIB.RC VSLDOS.INI 2. Use a text editor such as Notepad to edit your AUTOEXEC.BAT file located in your root directory. Make sure the following line is in the file: SET VSL=C:\PVSW\BIN 3. Edit your SYSTEM.INI file with a text editor such as Notepad. SYSTEM.INI is a Windows system file that is located in your Windows directory (for example, C:\WINDOWS). In the section [386enh], ensure the following line exists DEVICE=JSBDOSWS.VXD 4. Restart Windows 98/ME to register your changes. Once the DOS TCP/IP requester is setup, follow these steps to run a DOS application: 1. Start a DOS session. 2. Load BREQTCP.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application. 3. Run your application. To stop a DOS application, enter the command BREQTCP /u in the DOS box to unload the requester. Using DOS SPX Support (BREQUEST/BREQNT) --------------------------------------- There are two DOS SPX Btrieve requesters. BREQNT.EXE is the "dual mode" requester used by a DOS application to communicate to either a Windows NT/2000 or a NetWare server. BREQUEST.EXE is a NetWare-only version of the DOS SPX requester. This exists for historical purposes before Windows NT support was available, and is still provided because it requires smaller memory than BREQNT. If you are accessing Pervasive.SQL on a NetWare server and if you are running low on DOS conventional memory, you may need to use BREQUEST. If you are accessing a Windows NT/2000 server, you must use BREQNT. To use the DOS SPX requester on a Windows 98/ME workstation, you must first disable the Win32 DOS Box support as described above. There are no special steps required to enable the DOS SPX requester configuration. A DOS application can be run with the SPX protocol to a remote server engine by following these steps: 1. Start a DOS session. 2. Load BREQNT.EXE or BREQUEST.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application. 3. Run your application. To stop a DOS application, unload the requester by entering the command BREQUEST /u or BREQTCP /u in the DOS box before closing it. ===================================================================== 4. Running DOS applications on DOS ================================== DOS Btrieve application support on DOS workstations is only available through the DOS TCP/IP or DOS SPX requesters. Both allow a DOS application to communicate to a Windows NT/2000/XP or NetWare server running the client/server version of Pervasive.SQL. Using DOS TCP/IP Support (BREQTCP) ---------------------------------- To use the DOS TCP/IP requester on a DOS workstation, you must have one of the following TCP/IP stacks: - Microsoft LAN Manager - Novell LAN Workplace - FTP Software 2.2 or greater You can enable the DOS TCP/IP requester configuration using the following steps: 1. Copy the following files to the target directory where you installed the Pervasive.SQL DOS client software. These files can be found in the CLIENTS\DOS directory on your Pervasive.SQL CD or in the PVSW\CLIENTS\DOS directory of a Pervasive.SQL server. BREQTCP.EXE BREQTCP.MSG M3OPEN.EXE MNOVLWP.EXE MFTP22.EXE MSOCKLIB.RC VSLDOS.* 2. Rename your VSLDOS file to VSLDOS.INI in your target directory. If your TCP stack is Rename this file to VSLDOS.INI ---------------------- ------------------------------ Microsoft LAN Manager VSLDOS.M3 Novell LAN Workplace VSLDOS.LWP FTP Software VSLDOS.FTP 3. Edit AUTOEXEC.BAT file located in the root directory. Add the following line to the file: SET VSL=[jsb-location] where [jsb-location] is the fully-qualified path of the directory where you placed the VSLDOS.INI file. For example, C:\PVSW\BIN for DOS. 4. Restart the computer to register the AUTOEXEC.BAT changes. Once the DOS TCP/IP requester is setup, follow these steps to run a DOS application: 1. Make sure your TCP/IP components are loaded, as described by your TCP/IP stack provider. 2. Run the JSB executable appropriate for your TCP stack: - M3OPEN.EXE (Microsoft) - MNOVLWP.EXE (Novell) - MFTP22.EXE (FTP) 3. Load BREQTCP.EXE. 4. Run your application. ** VENDOR-SPECIFIC NOTES ** MICROSOFT LAN MANAGER --------------------- 1. Ensure that the NUMSOCKETS parameter in the [SOCKETS] section of TCPUTILS.INI is set to the maximum concurrent number of connections required. 2. SOCKETS.EXE is a Terminate and Stay Resident (TSR) program that allows applications to use the Microsoft LAN Manager TCP/IP stack. SOCKETS.EXE must be located in the same directory as the other Microsoft LAN Manager TCP/IP executable. NOVELL LAN WORKPLACE -------------------- Using Novell's LAN Workplace for DOS with BREQTCP.EXE requires that the environment variable EXCELAN be set to the Novell base directory. For example, if you installed LAN Workplace in the C:\NET directory, do a SET EXCELAN=C:\NET prior to loading MNOVLWP.EXE and BREQTCP.EXE. FTP SOFTWARE ------------ 1. Ensure that you allocate enough TCP and packet buffers for your application within the FTP kernel. For example, 'kernel-name' -t 16 -p 20 allocates 16 TCP connections and 20 packet buffers. 2. Once the maximum number of connections is reached, it may prove difficult to effect any connection thereafter until all, or almost all, connections have been closed. You are therefore recommended to set the maximum number of connections to a high number. To stop a DOS application, unload the requester components by entering the command BREQTCP /u at the DOS prompt, followed by [JSB executable] /U, where [JSB executable] is either M3OPEN.EXE, MNOVLWP.EXE, or MFTP22.EXE. If running in a Windows DOS box, unload the requester components before closing the DOS box. Using DOS SPX Support (BREQUEST/BREQNT) --------------------------------------- There are two DOS SPX Btrieve requesters. BREQNT.EXE is the "dual mode" requester that can be used by a DOS application to communicate to either a Windows NT/2000/XP or a NetWare server. BREQUEST.EXE is a NetWare-only version of the DOS SPX requester. This exists for historical purposes before Windows NT support was available, and is still provided because it has a smaller memory requirement than BREQNT. If you are accessing Pervasive.SQL on a NetWare server and if you are running low on DOS conventional memory, you may need to use BREQUEST. If you are accessing a Windows NT server, you must use BREQNT. A DOS application can be run with the SPX protocol to a remote server engine by following these steps: 1. At a DOS prompt, load BREQNT.EXE or BREQUEST.EXE from the \PVSW\BIN directory. This needs to be loaded in each DOS session running a Btrieve application in a Windows environment. 2. Run your application. To stop a DOS application, unload the requester by entering the command BREQUEST /u or BREQTCP /u in the DOS box before closing it. ===================================================================== 5. Verifying the DOS Configuration ================================== To verify that the install completed successfully, you need a pure DOS Btrieve application. One of the simplest application ships with the Server engines. You will find BUTIL.EXE in the PVSW\CLIENTS\DOS directory. Running this command by itself will show a list of available commands. Do this one time to ensure the copyright information says Butil for DOS, not Windows NT. You will then want to access a Btrieve file. You can use the BUTIL -STAT command to do this. If the command completes successfully, your DOS support is functioning as designed. Try a command like this: BUTIL -STAT f:\pvsw\samples\sample.btr Here, "f:" is a drive letter mapped to your server and "f:\pvsw\samples\sample.btr" is the path and filename of an existing Btrieve data file. A successful completion will return information about the data file. Otherwise, you will see a status code indicating the problem. Pervasive Technical Support can help you resolve any problems. ===================================================================== 6. Running BREQ*.EXEs with faster connection =========================================== For Pervasive.SQL 2000i SP3 new functionality was added to BREQUEST.EXE, BREQNT.EXE and BREQTCP.EXE to allow them to access newer Novell NetWare Client APIs to obtain information about the user's rights to files being Opened or Created. This reduced the time required to Open or Create a file by about 2 seconds However on some DOS machines, these improved executables have problems. Possible problems include Status 20 (the Microkernel or Btrieve Router is inactive), Status 91 (application encountered a server error), Status 94 (application encountered a permission error) and most severely EMM386 error #12 and EMM386 GPFs. If these problems are experienced with the installed executables, the problems might be fixed by upgrading the Novell NetWare Client to those Novell shipped with NetWare 5.0 or later. If you still experience problems, starting with Pervasive.SQL V8, versions of the BREQ*.EXE executables that do not include the newer Netware API calls are available in the \CLIENTS\DOS\ALT directory on the Pervasive.SQL CD. ===================================================================== Appendix A: DOS TCP/IP Technical Information ============================================ BREQTCP.EXE is a DOS executable that runs on various DOS and Windows platforms. It is built using JSB Corporation's Virtual Socket Library (VSL). VSL implements an API based on the Berkeley 4.3 sockets standard that enables development of platform-independent and transport-independent network applications. For information about JSB Corporation, visit their site at http://www.jsb.com. COMPONENTS OF THE BTRIEVE TCP/IP REQUESTER ------------------------------------------ - DOS TCP/IP Requesters - BREQTCP.EXE, BREQTCP.MSG - VSL DOS components - M3OPEN.EXE, MNOVLWP.EXE, MFTP22.EXE - VSL Windows 98/ME Components - JSBDOSWS.VXD - VSL Windows NT/2000/XP Components - JSBDOSWS.EXE, JSBDOSWS.DLL - VSL Platform specific configuration files - VSLDOS.INI, VSLDOS.M3, VSLDOS.LWP, VSLDOS.FTP - VSL Multiplatform resource file - MSOCKLIB.RC SYSTEM REQUIREMENTS FOR BTRIEVE TCP/IP REQUESTER ------------------------------------------------ Server software requirements - Pervasive.SQL - TCP/IP configured correctly at server You must have one of the following client operating systems: - Windows NT 4.0 or greater - Windows 98/ME - DOS 5.0 or greater For DOS, you must have one of the following TCP/IP stacks: - Microsoft LAN Manager - Novell LAN Workplace - FTP Software 2.2 or greater Conventional memory required to load with defaults -------------------------------------------------- - Windows NT/2000/XP - BREQTCP.EXE 81984 - JSBDOSWS.EXE 30400 (Upper memory) - Windows 98/ME - BREQTCP.EXE 85792 - JSBDOSWS.VXD 0 (No conventional memory used) - DOS 5.0 or greater - BREQTCP.EXE 81456 - M3OPEN.EXE 43280 (Microsoft LAN Manager) - MNOVLWP.EXE 66880 (Novell LAN Workplace) - MFTP22.EXE 69424 (FTP Software PC/TCP) ACCESSING NETWARE SERVERS ------------------------- You must have your Pervasive.SQL Server IP address configured properly on your clients for Pervasive.SQL to function. There are two ways to do this. To configure your clients to use the server's IP address, do one of the following: a. 1. In Windows, click Start and point to Control Panel. 2. Select Network. 3. Select TCP/IP and click Properties. 4. Click the DNS tab. 5. Enable DNS and enter the appropriate server information. b. Enter your Server IP address/name in the \ETC\HOSTS file. c. Verify correct configuration using the TCP/IP 'ping' to ping the server by name. *Note that BREQTCP will return Btrieve status 20 if it is unable to resolve the server name into an IP address, or if the IP address is incorrect or unreachable. KNOWN ISSUES ------------ This section contains notes on technical issues. 1. Multiple DOS Boxes When running BREQTCP on Windows 98/ME, only one DOS box is supported. Unloading BREQTCP is not sufficient to release the JSB VxD. The DOS box must be closed before another DOS box can load BREQTCP. On Windows NT/2000/XP, there is no restriction on the number of DOS boxes that can be invoked. 2. Use of DOS Requesters on the Windows NT/2000/XP platform There are some configuration requirements when you use the DOS Requester (BREQTCP, BREQNT or BREQUEST) with Windows NT/2000/XP. *To run a DOS application using the DOS requester in a Windows NT/2000/XP DOS box to access a NetWare server, NW16.EXE must be loaded prior to loading BREQTCP. Pervasive Software recommends you load it from AUTOEXEC.NT. If the NWLink IPX/SPX compatible transport is installed, these files are located in the WINNT\SYSTEM32 directory. *DOS applications are not supported through the DOS Requester when running on the Windows NT/2000/XP server where the data files you are trying to access reside. You must use the Win32 DOS Box Support as installed by Pervasive.SQL to access local files. 3. IP Address caching in Windows 98/ME After adding a target IP address for a NetWare server in the local Windows 98/ME hosts file, BREQTCP must be unloaded and reloaded. After correcting a target IP address for a NetWare server in the local Windows 98/ME hosts file, the Windows 98/ME system may need to be restarted to restart the JSB VxD. BREQTCP caches both valid and invalid IP addresses while the JSB VSL VxD caches valid IP addresses. The result is that modifications to the hosts file will not affect BREQTCP and may not affect the JSB VSL VxD depending upon prior attempts cached. This can be confusing when you are trying to modify a target IP address in the local host's file or on a DNS server. Note that the Windows 98/ME 'ping' utility does not exhibit this behavior, so ping may work while BREQTCP requires that Windows 98/ME be restarted. 4. Diagnosing BREQTCP.EXE initialization failures You may receive the following error message when loading BREQTCP: BREQTCP-10: The function InitSocketLibrary returned an error. If you see this message, you can determine the cause by using this checklist: a) Verify that the JSB VSL components appropriate to your workstation are loaded. Refer to the "Using DOS TCP/IP Support (BREQTCP)" section for your operating system for instructions on loading the JSB VSL components. b) Verify that you set the VSL environment variable to the directory where you placed the VSLDOS.INI file. c) Verify that the VSLDOS.INI you are using is correct. You should copy the appropriate VSL platform specific configuration file into your installation directory and renamed it VSLDOS.INI. It is not necessary to modify the VSLDOS.INI file. Refer to the "Using DOS TCP/IP Support (BREQTCP)" section for your operating system to find the correct version of the configuration file for your platform. d) On Windows 98/ME, ensure another DOS box using BREQTCP is open. This is the multiple DOS box condition described above. 5. Status 20, 91, 94, EMM386 error #12 or EMM386 general protection fault See Section 6, "Running BREQ* EXEs with faster connection," for an explanation of why these errors may occur and the corrective action. ===================================================================== (c) Copyright 2003 Pervasive Software Inc. All rights reserved. ======================= End of READDOS.TXT ==========================