Filename: BTR61.TXT Product: NetWare Btrieve v6.1 Upgrade Date: June 1993 This Readme document pertains to the NetWare Btrieve v6.1 Upgrade. It provides installation and upgrade information and descriptions of the NetWare Btrieve v6.1 program files. =============================================================================== Disclaimer ========== Novell, Inc. makes no representations or warranties with respect to any NetWare software, and specifically disclaims any express or implied warranties of merchantability, title, or fitness for a particular purpose. Distribution of any NetWare software is forbidden without the express written consent of Novell, Inc. Further, Novell reserves the right to discontinue distribution of any NetWare software. Novell is not responsible for lost profits or revenue, loss of use of the software, loss of data, costs of re-creating lost data, the cost of any substitute equipment or program, or claims by any party other than you. Novell strongly recommends a backup be made before any software is installed. Technical Support for this software may be provided at the discretion of Novell. =============================================================================== Contents ======== Btrieve v6.x in the NetWare Environment Installation Procedure Btrieve v6.x Upgrade Information Btrieve v6.x File Format Btrieve v6.x Operations Btrieve v6.x Utilities Btrieve v6.x Requesters Btrieve v6.x Status Codes Btrieve v6.x Program Files Btrieve Documentation Documentation Updates Printing Btrieve Documentation Associated Documents =============================================================================== Btrieve v6.x in the NetWare Environment ======================================= The NetWare v3.11 or v4.0 operating system provides a nonpreemptive, multitasking environment. NetWare Loadable Modules (NLMs) reside in server memory with the NetWare operating system. IMPORTANT: In a NetWare v4.0 environment, NetWare Btrieve v6.1 runs at the highest privilege level (domain 0), with direct access to the NetWare operating system. You cannot run NetWare Btrieve v6.1 in protected mode (domain 1, 2, or 3). You can run NetWare Btrieve v6.1 in a NetWare v3.11 or v4.0 environment. The list of NetWare products with which you can run NetWare Btrieve v6.1 will be updated as the products become available and are tested. =============================================================================== Installation Procedure ====================== To upgrade your existing NetWare Btrieve program files in a NetWare v3.11 or v4.0 environment, follow the installation procedure outlined in the following table. An "X" in either of the first two columns indicates that the step applies to that NetWare environment. NOTE: The following installation procedure replaces the NetWare INSTALL procedure documented in Chapter 3 in the "Btrieve Installation and Operation" manual. Upon completion of this installation procedure, refer to "Configuring Btrieve" in Chapter 3 in the "Btrieve Installation and Operation" manual. NetWare NetWare v3.11 v4.0 Installation Procedure ------- ------- ----------------------------------------------- From the NetWare Btrieve v6.1 Upgrade source media: X 1. Copy the AFTER311.NLM, CLIB.NLM, and NWSNUT.NLM files to the \SYSTEM directory on the NetWare server. NOTE: NetWare v4.0 includes these files, therefore, you do not need to copy them. X X 2. Copy all the .NLM files and corresponding .HLP files in the \SYSTEM directory to the \SYSTEM directory (or to the appropriate subdirectory for your configuration) on the NetWare server. X X 3. Copy the BSTART.NCF and BSTOP.NCF files in the \SYSTEM directory to the \SYSTEM directory (or to the appropriate subdirectory for your configuration) on the NetWare server. X X 4. Copy all the program files in the \PUBLIC directory to the \PUBLIC directory (or to the appropriate subdirectory for your configuration) on the NetWare server. X NOTE: Copy the NWLOCALE.DLL file in the \PUBLIC\OS2 or \PUBLIC\WIN directory to the appropriate subdirectory on the NetWare server or on the hard drive of the client workstation. NetWare v4.0 includes these files, therefore, you do not need to copy them. X 5. Copy the .MSG files in the \SYSTEM and \PUBLIC directories to the appropriate language subdirectory in \SYSTEM\NLS on the NetWare server. X X 6. Use the Btrieve Setup utility to configure Btrieve according to your application's requirements. For more information about the Setup utility, see Chapter 3, "Installing and Configuring Btrieve" in the "Btrieve Installation and Operation" manual. =============================================================================== Btrieve v6.x Upgrade Information ================================ For a description of the enhancements to NetWare Btrieve v6.1, refer to Chapter 1 of the "Btrieve Installation and Operation" manual. Before you start NetWare Btrieve v6.1, read the following sections in this document. - Btrieve v6.x File Format -- Addresses some of the differences between the Btrieve v6.1, v6.0, and v5.x file formats. - Btrieve v6.x Operations -- Highlights the new Btrieve v6.1 chunk operations and the restrictions that apply when using Btrieve v6.0 to operate on records larger than 64 KB. - Btrieve v6.x Utilities -- Provides important notes on Btrieve's logging feature. - Btrieve v6.x Requesters -- Highlights the new Btrieve v6.1 configuration options for the DOS and OS/2 Requesters. - Btrieve v6.x Status Codes -- Discusses error conditions specific to different versions of Btrieve. Btrieve v6.x File Format ------------------------ When creating files, Btrieve v6.x uses a new file format that allows faster data access than possible with versions of Btrieve prior to v6.0. This new file format, first introduced in Btrieve v6.0, has been slightly modified in Btrieve v6.1. For more information on the Btrieve v6.x file format, refer to the "Btrieve Programmer's Manual" included in the NetWare Btrieve v6.1 Developer's Kit Supplement, which is available through the Professional Developers' Program (PDP). When working with Btrieve files created with different versions of Btrieve, consider the following. - New file features supported by Btrieve v6.1 include: multiple alternate collating sequences (ACSs), locale-specific ACSs, Variable-tail Allocation Tables (VATs), and the ability to mark a file as using index balancing. Btrieve v6.1 returns a file version of 6.1 if the file specified in a Stat operation or BUTIL -STAT command was created with multiple ACSs, locale-specific ACSs, VATs, or the index balancing option. NOTE: Files created with any of these features are created in the Btrieve v6.1 file format. If Btrieve v6.1 creates a file without any of these features, it creates the file in the Btrieve v6.0 file format by default. You can override the v6.0 default and create Btrieve v5.x files by using the Setup utility. Refer to Chapter 3, "Installing and Configuring Btrieve" in the "Btrieve Installation and Operation" manual for more information on the Setup utility. - Btrieve v6.0 operates on a file created by Btrieve v6.1, unless the file uses multiple ACSs, locale-specific ACSs, VATs, or the balanced index flag. That is, Btrieve v6.0 cannot open a file that uses the Btrieve v6.1 file format. NOTE: Btrieve v6.0 returns a Status Code 30 (The file specified is not a Btrieve file) when you attempt to open a file created in the Btrieve v6.1 file format. (This is generally true whenever you use an earlier Btrieve version to open a file that has a more recent Btrieve file format.) - Btrieve v6.x can open files that were created with earlier versions of Btrieve. For example, Btrieve v6.0 can open files created with Btrieve v5.x, and Btrieve v6.1 can open files created with Btrieve v5.x or v6.0. Additionally, Btrieve v6.x can write to files using the existing file format. In other words, Btrieve v6.x writes to v5.x files using the v5.x file format and writes to v6.x files using the v6.x file format. NOTE: When Btrieve v6.x opens files from earlier versions, it does not convert them automatically to the v6.x file format. For example, if you use Btrieve v6.1 to open a v6.0 file, Btrieve v6.1 does not convert the v6.0 file to a v6.1 file format. However, if an application uses Btrieve v6.10a on a v6.0 file and creates an index which uses a second ACS or a locale-specific ACS, the file format will be upgraded to a version 6.1, thus preventing the file from being opened by an earlier Btrieve version, which would not recognize these features. If your database contains files created with versions of Btrieve prior to v6.x, you may want to upgrade them to take advantage of the Btrieve v6.x features. The Btrieve Rebuild utility converts Btrieve data files to the v6.x file format. Refer to Chapter 3, "Installing and Configuring Btrieve" in the "Btrieve Installation and Operation" manual for information on how to rebuild your existing Btrieve files. - Btrieve v5.x cannot open files that have a v6.x file format. NOTE: If you are using Btrieve v6.x and you need backward compatibility with Btrieve v5.x, use the Btrieve Setup option Create Btrieve Files in Pre v6.x Format. This option allows you to create files with Btrieve v6.x and use them with Btrieve v5.x. (Keep in mind, however, that many of the Btrieve v6.x features require the Btrieve v6.x file format.) Refer to Chapter 3, "Installing and Configuring Btrieve" in the "Btrieve Installation and Operation" manual for more information on the Setup utility. - Btrieve v6.1 supports a longer STS data type than NetWare SQL. NOTE: Make sure that the length of the STS data type does not exceed 15 bytes if you plan to use the Btrieve v6.1 files with NetWare SQL. - Btrieve v6.1 allows the creation of an STS data type index in files using the Btrieve v6.0 file format. IMPORTANT: If you use Btrieve v6.00d or an earlier Btrieve version to access a file with an STS data type index, a server abend may occur. Btrieve v6.x Operations ----------------------- Btrieve v6.1 supports the following new Btrieve operations. For more information about these new operations, refer to the "Btrieve Programmer's Manual" included in the NetWare Btrieve v6.1 Developer's Kit Supplement, which is available through the Professional Developers' Program (PDP). - Find Percentage and Get By Percentage -- Windows-oriented applications can use these new operations for implementing scroll bars. - Get Direct/Chunk and Update Chunk -- Btrieve v6.1 allows applications to operate on portions of a record, called "chunks," rather than on the entire record. Through the new Get Direct/Chunk and Update Chunk operations, Btrieve v6.1 supports records larger than 64 KB. NOTE: Applications can use the new chunk operations to build records larger than 64 KB in files that use the Btrieve v6.0 file format. When Btrieve v6.0 operates on files containing records larger than 64 KB, however, the following restrictions apply. - If you use an Update Chunk operation in a file that uses the Btrieve v6.0 file format, one of the file's Free Space Lists may be left in a state that can cause Btrieve v6.00d or an earlier Btrieve version to overwrite its own cache; a server abend may occur. - Btrieve v6.0 does not recognize the Get Direct/Chunk or Update Chunk operations, and therefore can only perform operations that update or retrieve entire records. Those "entire record" operations can only retrieve or update up to 64 KB of a record because the operations' data buffer length parameter, which specifies the amount of data to update or retrieve, can contain a maximum value of 64 KB. - If you use an Update Chunk operation to create a record larger than 64 KB in a file that uses the Btrieve v6.0 file format, Btrieve v6.0 (which can only use operations to update or retrieve entire records) cannot retrieve more than the first 64 KB of the record. Btrieve v6.0 returns a Status Code 22 (The data buffer parameter is too short) or a Status Code 97 (The communications buffer is too small) to indicate that there is more data to be retrieved. - Because Btrieve v6.0 does not recognize the Update Chunk operation, you cannot use Btrieve v6.0 to modify a record that is larger than 64 KB and still have the resulting record be larger than 64 KB. You can use the Update operation to shorten such a record. The length of the resulting record of a successful Update operation is defined by the operation's data buffer length parameter, which has a maximum value of 64 KB. Btrieve v6.x Utilities ---------------------- Btrieve Monitor utility (BTRMON.NLM) -- The Btrieve v6.x Monitor utility (BTRMON.NLM) replaces the Btrieve v5.x Console utility (BCONSOLE.NLM). IMPORTANT: NLM applications that call Btrieve must issue a Btrieve Reset before unloading. Failure to do so may lead to a server abend when you try to use the Btrieve Monitor utility to monitor the NLM application's activity. Rebuild utility (BREBUILD.NLM) -- This new Btrieve v6.x utility allows you to upgrade files created with versions of Btrieve prior to v6.x. Use this utility to upgrade your files to take advantage of the Btrieve v6.x features. For more information about rebuilding your existing files, refer to "Rebuilding Existing Btrieve Files" in Chapter 3 of the "Btrieve Installation and Operation" manual. NOTE: Before running the Rebuild utility (either from the command line or through the Setup utility), you must start Btrieve v6.x. Roll Forward utilities (BROLLFWD.EXE, PBROLL.EXE, and WBROLL.EXE) -- When using Btrieve's logging feature and the Roll Forward utility, consider the following: - Btrieve does not allow a log file to contain log entries created by different versions of Btrieve. That is, all entries in a log file must be logged under the same version of Btrieve. Otherwise, Btrieve displays a system error message on the server console and ignores logging for the Btrieve file. - If you need to restart Btrieve, specify the same index balancing setting that was used when you first loaded Btrieve (after a backup) and performed logging. Otherwise, you may receive a Status Code 43 (The specified record is invalid) when you run the Roll Forward utility. - If you need to run the Roll Forward utility (for example, after a system crash), load the same version of Btrieve and specify the same index balancing setting that was used during logging. Otherwise, you may receive a Status Code 43 (The specified record is invalid). NOTE: If you want to switch to a different version of Btrieve or you want to change the index balancing setting, first create a backup of the Btrieve files to be logged and then delete the corresponding log files. - If you attempt to create a log file for a Btrieve file that contains records larger than 57 KB, you may receive a Status Code 43 (The specified record is invalid) when you run the Roll Forward utility. The Btrieve v6.1 BROLLFWD.EXE file replaces the Btrieve v6.0 DBROLL.EXE. Btrieve v6.x Requesters ----------------------- Btrieve Requester for UnixWare -- This new Requester provides UnixWare clients with access to Btrieve data residing on a NetWare Btrieve server. For detailed information about this Requester, refer to the separate Readme document, BTRUNIX.DOC, that is included in this upgrade. Btrieve Requester for DOS -- This Requester has three new configuration options. For detailed information about this Requester, refer to Chapter 4 in the "Btrieve Installation and Operation" manual. - NetWare Runtime Server Support (/C) -- Enables or disables NetWare Runtime support. - DOS Session Load (/L) -- Allows you to load another instance of the Btrieve DOS Requester even if it is already loaded. This option is useful if you want to run Windows applications using the Btrieve DOS Requester while running DOS VM applications that are also using the Requester. - Real-Time Data Compression (/O) -- Helps reduce network traffic by reducing the number of packets required to complete a request to Btrieve. Btrieve Requester for OS/2 -- This Requester also provides Runtime Server support. For detailed information about the Btrieve OS/2 Requester, refer to Chapter 4 in the "Btrieve Installation and Operation" manual. Btrieve v6.x Status Codes ------------------------- Status Code 11 (The specified filename is invalid) -- If you receive this status code when you open a Btrieve file using the Btrieve OS/2 Requester (BTRCALLS.DLL), make sure that you are using the latest NetWare OS/2 Requester. Status Code 30 (The file specified is not a Btrieve file) -- Btrieve v6.0 returns this status code when you attempt to open a file that has the Btrieve v6.1 file format. (This is generally true whenever you use an earlier Btrieve version to open a file that has a more recent file format.) Status Code 43 (The specified record address is invalid) -- The Btrieve Roll Forward utility receives this status code when the address acquired from the Free Space List of the Btrieve file during an Insert operation at roll forward time is different from the one received at logging time. The synchronization problem with Free Space Lists occurs when you use different versions of Btrieve or the same Btrieve version but with a different index balancing setting. The following is a summary of the specific conditions for which Status Code 43 can be returned: - During logging, you loaded Btrieve multiple times and did not specify the same index balancing setting each time. - You inserted or updated a record larger than 57 KB. - At roll forward time, you loaded a different version of Btrieve or the same Btrieve version but with a different index balancing setting from what you used at logging time. To correct the synchronization problem with Free Space Lists, load the proper version of Btrieve with the proper index balancing setting. Status Code 44 (The specified key path is invalid) -- Btrieve v6.1 returns this code for some situations, in which earlier versions of Btrieve returned Status Code 82 (The application lost positioning). These situations can occur when you define the key attribute to be manual or null (all-segment and any-segment). If you have an existing Btrieve application that checked for Status Code 82, you may want to rewrite the application to check for Status Code 44 as well. Refer to Chapter 2 in the "Btrieve Programmer's Manual" (included in the NetWare Btrieve v6.1 Developer's Kit Supplement) for more information about all-segment and any-segment null keys. Status Code 102 (Insufficient stack space is available) -- Btrieve v6.1 requires 3 KB of stack space. If your NLM application receives this status code, try increasing the size of your stack space. You may need more than 3 KB of stack space if you are accessing files defined by NetWare SQL as being under referential integrity (RI) constraints. Because Btrieve uses recursion when enforcing the constraints, you will need 3 KB of stack space at the deepest level of recursion. ================================================================================ Btrieve v6.x Program Files ========================== The NetWare Btrieve v6.1 program files included in this upgrade can be grouped into the following categories: - Files related to the NetWare v3.11 environment - Files related to server operations - Files related to DOS workstation operations - Files related to Windows workstation operations - Files related to OS/2 workstation operations - Files related to UnixWare workstation operations The following lists describe the NetWare Btrieve v6.1 program files in each category. - Files related to the NetWare v3.11 environment: AFTER311.NLM NLM that NetWare Btrieve v6.1 requires in a NetWare v3.11 environment. CLIB.NLM C Library for the NetWare v3.11 environment. NWLOCALE.DLL National Language Support DLL for the NetWare v3.11 environment. The /PUBLIC/WIN and /PUBLIC/OS2 directories each contain a different NWLOCALE.DLL. NWSNUT.NLM Graphics User Interface (GUI) NLM for the NetWare v3.11 environment. - Files related to server operations: BDIRECT.NLM Directory Services utility that allows you to install or remove a Btrieve server object in a NetWare v4.0 environment. BDIRECT.MSG Message file for BDIRECT.NLM (for the NetWare v4.0 environment). BDROUTER.NLM NLM that provides Directory Services support in a NetWare v4.0 environment. BDROUTER.MSG Message file for BDROUTER.NLM (for the NetWare v4.0 environment). BREBUILD.NLM Rebuild utility that lets you convert existing Btrieve v5.x files to Btrieve v6.x format. BREBUILD.MSG Message file for BREBUILD.NLM. BROUTER.NLM NLM that allows server-based Btrieve applications to access Btrieve databases on remote servers. BROUTER.MSG Message file for BROUTER.NLM. BSETUP.NLM Btrieve installation and configuration utility. BSETUP.MSG Message file for BSETUP.NLM. BSETUP.HLP Help file for BSETUP.NLM. BSPXCOM.NLM SPX communications agent. BSPXCOM.MSG Message file for BSPXCOM.NLM. BSPXSTUB.NLM NLM that allows you to use the Btrieve Monitor utility (BTRMON.NLM) when BSPXCOM.NLM is not loaded. BSPXSTUB.MSG Message file for BSPXSTUB.NLM. BSTART.NCF Batch file executed to start Btrieve. This file also loads BSPXCOM.NLM and BROUTER.NLM (if Btrieve is configured to do so). BSTOP.NCF Batch file executed to stop Btrieve. This file also unloads BSPXCOM.NLM and BROUTER.NLM (if loaded). BTRIEVE.NLM Btrieve Record Manager (database engine). BTRIEVE.MSG Message file for BTRIEVE.NLM. BTRMON.NLM Btrieve Monitor utility that lets you monitor the activity of Btrieve files, users, and communications resources. BTRMON.MSG Message file for BTRMON.NLM. BTRMON.HLP Help file for BTRMON.NLM. BUTIL.NLM Btrieve Maintenance utility, which is a command line utility that allows you to create, manipulate, and recover Btrieve data files. BUTIL.MSG Message file for BUTIL.NLM. RSPXSTUB.NLM Module that resolves external references for the Btrieve Monitor utility (BTRMON.NLM) when BSPXCOM.NLM is not loaded. If you want to use the Btrieve Monitor utility to monitor outgoing requests generated by the Btrieve Message Router (BROUTER.NLM) to another server and you do not want to load BSPXCOM.NLM, load RSPXSTUB.NLM instead of BSPXSTUB.NLM at the server. RSPXSTUB.MSG Message file for RSPXSTUB.NLM. - Files related to DOS workstation operations: BREQUEST.EXE Btrieve Requester for DOS. BREQUEST.MSG Message file for BREQUEST.EXE. BREQUTIL.EXE Btrieve Requester utility that allows you to stop the Requester and to obtain the Requester's version number at a DOS workstation. BREQUTIL.MSG Message file for BREQUTIL.EXE. BROLLFWD.EXE Roll Forward utility for the DOS operating environment. This utility recovers changes made to a Btrieve file between the time of the last backup and a system failure. BROLLFWD.MSG Message file for BROLLFWD.EXE. - Files related to Windows workstation operations: WBROLL.EXE Roll Forward utility for the Windows operating environment. This utility recovers changes made to a Btrieve file between the time of the last backup and a system failure. WBROLLRS.DLL Resource file for WBROLL.EXE. WBTRCALL.DLL Btrieve Requester for Windows. WBTRVRES.DLL Resource file for the Btrieve Windows Requester. WNDBCNVT.EXE Windows Conversion utility that converts the client-based Btrieve DLL (WBTRCALL.DLL) to WBTRLOCL.DLL. NOVDB.INI Btrieve initialization file for the Btrieve Windows Requester. - Files related to OS/2 workstation operations: PBROLL.EXE Roll Forward utility for the OS/2 operating environment. This utility recovers changes made to a Btrieve file between the time of the last backup and a system failure. PBTRVRES.DLL Resource file for PBROLL.EXE. BTRCALLS.DLL Btrieve Requester for OS/2. NDBCOMM.DLL Communications handler for the Btrieve Requester for OS/2. NDBCNVT.EXE OS/2 Conversion utility that converts the client-based Btrieve DLL (BTRCALLS.DLL) to BTRLOCL.DLL. - Files related to UnixWare workstation operations: LIBBTRV.A Archive Btrieve Interface Library. LIBCOMM.A Archive Communications Interface Library. LIBBTRV.SO Shared-object Btrieve Interface Library. LIBCOMM.SO Shared-object Communications Interface Library. UNXCBTRV.O C interface object file. BTRUNIX.DOC Readme document that describes the Btrieve Requester for UnixWare. =============================================================================== Btrieve Documentation ===================== The NetWare Btrieve v6.1 Upgrade includes the "Btrieve Installation and Operation" manual. The following section describes the updates to this manual. Currently, you can print this manual using the set of Postscript files included BTR61M.EXE. For printing instructions, see the "Printing Btrieve Documentation" section. NOTE: Btrieve documentation in printed form will be available at a later date. Information on how to order the printed Btrieve documentation will be forthcoming. Documentation Updates --------------------- The following documentation updates apply to the "Btrieve Installation and Operation" manual included in this upgrade. Chapter 3, "Installing and Configuring Btrieve" -- Replace the installation procedure in the "Using the NetWare INSTALL Utility" section with the information presented in the "Installation Procedure" section of this Readme document. Chapter 4, "Configuring and Using the Requesters" -- In the "Loading the Windows Requester" section, change the name of the Windows import library to WBTRCALL.LIB. Printing Btrieve Documentation ------------------------------ The Postscript files that compose the "Btrieve Installation and Operation" manual can be obtained in the the self extracting zip file, BTR61M.EXE. You can print the "Btrieve Installation and Operation" manual in Postscript format, using a printer that can print Postscript files. Associated Documents -------------------- For information about the Btrieve v6.x file format and Btrieve operations, refer to the "Btrieve Programmer's Manual." This manual is a component of the NetWare Btrieve v6.1 Developer's Kit Supplement, which is available through the Professional Developers' Program (PDP). **End of BTR61.TXT**