home *** CD-ROM | disk | FTP | other *** search
- Filename: README.BTR
- Product: NetWare Btrieve v6.1 for NetWare v3.12
- Date: June 1993
-
- This Readme document pertains to NetWare Btrieve v6.1 for
- NetWare v3.12. It provides installation and upgrade
- information and descriptions of the NetWare Btrieve v6.1
- program files for NetWare v3.12.
-
-
- ================================================================
- 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 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
- Associated Documents
-
-
- ================================================================
- 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
- Developer's 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 Btrieve 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 Developer's Program (PDP).
-
- - Find Percentage and Get By Percentage -- Window-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 Requester is a new
- component of NetWare Btrieve v6.1 for NetWare v3.12.
- This 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.
-
- 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 MS 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 a 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"
- for more information about all-segment and any-segment
- null keys. The "Btrieve Programmer's Manual" is
- included in the NetWare Btrieve v6.1 Developer's Kit
- Supplement, which must be purchased separately.
-
- 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 can be grouped into the
- following categories:
-
- - Files related to server operations
- - Files related to DOS workstation operations
- - Files related to MS 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 server operations:
-
- BREBUILD.NLM Rebuild utility that lets you convert
- existing Btrieve v5.x files to Btrieve
- v6.x format.
-
- BROUTER.NLM NLM that allows server-based Btrieve
- applications to access Btrieve databases
- on remote servers.
-
- BSETUP.NLM Btrieve installation and configuration
- utility.
-
- BSETUP.HLP Help file for BSETUP.NLM.
-
- BSPXCOM.NLM SPX communications agent.
-
- BSPXSTUB.NLM NLM that allows you to use the Btrieve
- Monitor utility (BTRMON.NLM) when
- BSPXCOM.NLM is not loaded.
-
- 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.ORG BTRIEVE NLM to which you can apply any
- future patches.
-
- BTRMON.NLM Btrieve Monitor utility that lets you
- monitor the activity of Btrieve files,
- users, and communications resources.
-
- 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.
-
- 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.
-
-
- - Files related to DOS workstation operations:
-
- BREQUEST.EXE Btrieve Requester for DOS.
-
- 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 MS Windows workstation operations:
-
- WBROLL.EXE Roll Forward utility for the MS 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 MS Windows.
-
- WBTRVRES.DLL Resource file for the Btrieve MS Windows
- Requester.
-
- WNDBCNVT.EXE MS Windows Conversion utility that converts
- the client-based Btrieve DLL (WBTRCALL.DLL)
- to WBTRLOCL.DLL.
-
- NOVDB.INI Btrieve initialization file for the Btrieve
- MS 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.
-
-
- ================================================================
- Associated Documents
- ====================
-
- 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 Developer's Program
- (PDP). For information about the Btrieve v6.x file format
- and Btrieve operations, refer to this manual.
-
-